Skip to content

[Guide] Update instructions for OS settings configuration profiles #48503

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
melpike wants to merge 1 commit into
base: docs-v4.90.0
Choose a base branch
from
Open

[Guide] Update instructions for OS settings configuration profiles #48503

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions articles/custom-os-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,15 @@ Fleet UI:

2. Choose which fleet you want to add a configuration profile to by selecting the desired fleet in the fleets dropdown in the upper left corner. Fleets are available in Fleet Premium.

3. Select **Add profile** and choose your configuration profile.
3. Select **Add profile** and choose your configuration profile and target, then select **Add profile** in the modal.

4. To edit the OS setting, first remove the old configuration profile and then add the new one.
Once the profile is saved, you can edit the profile's targets or replace the configuration file. Hover over the profile row and select the **pencil/edit button** to edit the following:

- Targets (all hosts or custom). For custom targets, you can edit the labels (include and/or exclude).
- Configuration profile. In the edit modal, hover over the uploaded file and select the **pencil/edit button** to upload a replacement file.
> The replacement file must match the original:
> - **DDM profiles:** same declaration identifier and file name
> - **v1 .mobileconfig profiles:** same `PayloadIdentifier` and `PayloadDisplayName`

Fleet API: Use the [Create configuration profile endpoint](https://fleetdm.com/docs/rest-api/rest-api#create-configuration-profile) in the Fleet API.

Expand All @@ -47,6 +53,7 @@ How to deliver user-scoped configuration profiles:
#### macOS

1. If you use iMazing Profile Creator, open your configuration profile in iMazing, select the **General** tab and update the **Payoad Scope** to **User**.

2. If you edit your configuration profiles in a text editor, open the configuraiton profile in your text editor, find or add the `PayloadScope` key, and set the value to `User`. Here's an example `.mobileconfig` snippet:

```
Expand All @@ -65,18 +72,21 @@ How to deliver user-scoped configuration profiles:
#### Windows

1. Head to the [Windows configuration profiles (CSPs) documentation](https://learn.microsoft.com/en-us/windows/client-management/mdm/policy-configuration-service-provider) to verify that all the settings in your Windows profile support the user scope. For example, the [SCEP setting](https://learn.microsoft.com/en-us/windows/client-management/mdm/clientcertificateinstall-csp#devicescep) supports both the device and user scope.

2. To make your Windows configuration profiles user scoped, replace `./Device` with `./User` in all `<LocURI>` elements.

#### Upgrading from below 4.71.0

Fleet added support for user-scoped macOS configuration profiles in Fleet 4.71.0. If you're upgrading Fleet from a version below 4.71.0, here's how to prepare your already enrolled hosts for macOS user-scoped configuration profiles:

1. If the host automatically enrolled to Fleet (via ADE), you don't need to take action. Fleet added support for the user-scoped configuration profiles on these hosts.

2. To deliver user-scoped profiles to hosts that manually enrolled and turned on MDM, first turn off MDM and ask end user to [turn on MDM](https://fleetdm.com/guides/mdm-migration#migrate-hosts:~:text=If%20the%20host%20is%20not%20assigned%20to%20Fleet%20in%20ABM%20(manual%20enrollment)%2C%20the%20end%20user%20will%20be%20given%20the%20option%20to%20download%20the%20MDM%20enrollment%20profile%20on%20their%20My%20device%20page.) through the **My device** page.

Edit user-scoped configuration profiles that are already installed on hosts:

1. Check for profiles with `PayloadScope` set to `User`. Already deployed profiles with `PayloadScope` set to `User` won’t be re-installed on hosts automatically.

2. To change them to the user-scope, update the `PayloadIdentifier`, re-add the profile to Fleet, and delete the old profile. This will uninstall the device-scope profile and install the profile in the user scope. If you're using [GitOps](https://fleetdm.com/docs/configuration/yaml-files), just update the `PayloadIdentifier` and run GitOps.

In versions older than 4.71.0, Fleet always delivered configuration profiles to the device scope (even when the profile's `PayloadScope` was set to `User`)
Expand All @@ -89,7 +99,9 @@ In the Fleet UI, head to the **Controls > OS settings** tab.

To see the status of a specific setting, hover over the setting's row in the **Configuration profiles** table and select the information (**i**) icon.

Currently, when editing a profile using Fleet's GitOps workflow, it can take 30 seconds for the profile's status to update to "Pending."
When editing a profile via Fleet's GitOps workflow, it may take up to 30 seconds for the profile's status to update to "Pending."

Editing a profile's labels sets the status to "Pending" for newly targeted hosts.

### Verified

Expand Down
Loading