From c45ff9f02971533921a5ab9996df5c287d332b0c Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Fri, 29 May 2026 18:37:53 -0400 Subject: [PATCH] Preview of v4.86.0 doc changes (merge conflicts resolved) (#42428) --- articles/apple-mdm-setup.md | 43 ++- ...nnect-end-user-to-wifi-with-certificate.md | 47 +++- ...ify-on-macOS-with-configuration-profile.md | 6 + articles/enroll-hosts.md | 19 +- ...s-ipad-hosts-with-managed-apple-account.md | 22 +- articles/fleet-variables.md | 46 +++ .../foreign-vitals-map-idp-users-to-hosts.md | 2 +- articles/install-app-store-apps.md | 25 +- articles/lock-wipe-hosts.md | 2 + articles/role-based-access.md | 2 +- ...s-in-scripts-and-configuration-profiles.md | 16 +- articles/setup-experience.md | 12 + articles/windows-linux-setup-experience.md | 91 +++++- docs/Configuration/agent-configuration.md | 36 +++ .../fleet-server-configuration.md | 67 +++++ docs/Configuration/yaml-files.md | 131 +++++---- docs/Contributing/reference/audit-logs.md | 109 +++++++- docs/REST API/rest-api.md | 263 +++++++++++++++--- website/config/routes.js | 5 +- 19 files changed, 819 insertions(+), 125 deletions(-) create mode 100644 articles/fleet-variables.md diff --git a/articles/apple-mdm-setup.md b/articles/apple-mdm-setup.md index 1e66135df9..ead1261877 100644 --- a/articles/apple-mdm-setup.md +++ b/articles/apple-mdm-setup.md @@ -38,7 +38,21 @@ How to connect Fleet to APNs: > Available in Fleet Premium -Connect Fleet to your AB to allow automatic enrollment for company-owned and [Account-driven User Enrollment](https://fleetdm.com/guides/enroll-personal-byod-ios-ipad-hosts-with-managed-apple-account) for personal (BYOD) macOS, iOS, and iPadOS hosts. +Connect Fleet to your ABM to allow automatic enrollment for company-owned and [Account-driven User Enrollment](https://fleetdm.com/guides/enroll-personal-byod-ios-ipad-hosts-with-managed-apple-account) for personal (BYOD) macOS, iOS, and iPadOS hosts. + +### Re-enrolling AB hosts + +When an AB host re-enrolls in Fleet (e.g., after a wipe or OS reinstall), Fleet automatically: + - Cancels pending MDM commands, script runs, and software installs + - Clears completed commands, scripts, and software from the previous enrollment + - Resets host labels + +This means you **do not need to delete** an ABM host from Fleet before +re-enrolling it. Fleet handles clearing stale state automatically. + +> This automatic state clearing does not apply to hosts undergoing ABM MDM migration. During migration, the host's existing state (labels, pending activity) is preserved to ensure a seamless transition from your previous MDM solution. + +### To connect Fleet to ABM, you have to add an ABM token to Fleet. To add an ABM token: 1. In Fleet, navigate to the **Settings > Integrations > MDM** page. 2. Under **Apple Business (AB)**, select **Add AB**. @@ -75,7 +89,30 @@ When one of your uploaded AB tokens has expired or is within 30 days of expiring > If no default fleet is set for a host platform (macOS, iOS, or iPadOS), then newly enrolled hosts of that platform will be placed in "Unassigned". -> A host can be transferred to a new (not default) fleet before it enrolls. In the Fleet UI, you can do this under **Settings** > **Fleets**. + > A host can be transferred to a new (not default) fleet before it enrolls. In the Fleet UI, you can do this under **Settings** > **Fleets**. + +### Default automatic enrollment profile + +When macOS, iOS, or iPadOS hosts automatically enroll through Apple Business, Fleet sends an automatic enrollment (ADE) profile to Apple that controls how the Setup Assistant behaves. If no custom profile is uploaded for a fleet, Fleet uses a built-in default profile. + +The default profile sets options such as whether enrollment is mandatory, which Setup Assistant panes are skipped, and whether the MDM profile is removable. See the [Setup Assistant pane options](https://fleetdm.com/learn-more-about/apple-setup-assistant). + +#### Where to view the default profile + +- **Fleet UI:** Navigate to **Controls > Setup experience > Setup Assistant**. When no custom profile is uploaded, you can select **Download** to download the default profile JSON that your Fleet instance is currently using. +- **API:** `GET /api/v1/fleet/enrollment_profiles/automatic/default` + +#### Stored once, never auto-refreshed + +The default profile is stored once per Fleet instance — at the time of your first automatic enrollment registration with Apple — and is **not** refreshed by Fleet upgrades, by adding or removing AB tokens, or by any other normal operation. This means that even if a newer version of Fleet ships updated default values, existing Fleet instances will continue using the default profile that was originally stored. + +#### Updating to Fleet's latest defaults + +There is no in-product "reset to latest default" action today. If you want your Fleet instance to use newer default values introduced in a later Fleet release: + +1. Check the latest defaults by reviewing the [REST API documentation](https://fleetdm.com/docs/rest-api/rest-api#get-fleet-default-mdm-setup-enrollment-profile) or by checking a freshly created Fleet instance. +2. Create a custom enrollment profile JSON containing the desired values. See the [Setup Assistant section of the setup experience guide](https://fleetdm.com/guides/setup-experience#setup-assistant) for instructions on creating and uploading a custom profile. +3. Upload it via the Fleet UI (**Controls > Setup experience > Setup Assistant > Add profile**) or the [API](https://fleetdm.com/docs/rest-api/rest-api#update-custom-mdm-setup-enrollment-profile). ## Turn on MDM on a host @@ -219,6 +256,8 @@ To view an AB issue: 2. Select a host and click on the MDM status to view details. +> For AB hosts, you do not need to delete the host from Fleet before re-enrolling. Fleet automatically clears pending and completed commands, scripts, software installs, and labels when the host re-enrolls. See [Re-enrolling AB hosts](#re-enrolling-ab-hosts). + diff --git a/articles/connect-end-user-to-wifi-with-certificate.md b/articles/connect-end-user-to-wifi-with-certificate.md index 267e401a52..6d634b9829 100644 --- a/articles/connect-end-user-to-wifi-with-certificate.md +++ b/articles/connect-end-user-to-wifi-with-certificate.md @@ -44,7 +44,7 @@ We'll deploy a certificate with a dynamic SCEP challenge. To deploy certificates 1. Create a [configuration profile](https://fleetdm.com/guides/custom-os-settings) with the SCEP payload. In the profile, for `Challenge`, use `$FLEET_VAR_NDES_SCEP_CHALLENGE`. For `URL`, use `$FLEET_VAR_NDES_SCEP_PROXY_URL`, and make sure to add `$FLEET_VAR_SCEP_RENEWAL_ID` to `OU`. -2. If you want your certificates to be unique to each host, update the `Subject`. For example, you can use `$FLEET_VAR_HOST_END_USER_EMAIL_IDP`. You can also use any of the [supported variables](https://fleetdm.com/docs/configuration/yaml-files#variables). +2. If you want your certificates to be unique to each host, update the `Subject`. For example, you can use `$FLEET_VAR_HOST_END_USER_EMAIL_IDP`. You can also use any of the [supported variables](https://fleetdm.com/guides/fleet-variables). 3. In Fleet, head to **Controls > OS settings > Custom settings** and add the configuration profile to deploy certificates to your hosts. @@ -83,7 +83,7 @@ The following steps show how to deploy DigiCert certificates. 4. If you're using DigiCert One's cloud offering, keep the default **URL**. If you're using a self-hosted (on-prem) DigiCert One, update the URL to match the one you use to log in to your DigiCert One. 5. In **API token**, paste your DigiCert server user's API token (from step 1). 6. In **Profile GUID**, paste your DigiCert One certificate profile GUID (from step 2). To find your GUID, open the profile in DigiCert and copy **GUID** from the [Certificate profiles](https://one.digicert.com/mpki/policies/profiles) page. -7. In **CN**, **UPN**, and **Certificate seat ID**, enter fixed values or any of the [supported variables](https://fleetdm.com/docs/configuration/yaml-files#variables). Most organizations use the host's serial number or end user's email to deliver a certificate that's unique to the host. +7. In **CN**, **UPN**, and **Certificate seat ID**, enter fixed values or any of the [supported variables](https://fleetdm.com/guides/fleet-variables). Most organizations use the host's serial number or end user's email to deliver a certificate that's unique to the host. 8. Select **Add CA**. Your DigiCert certificate authority (CA) should appear in your list of CAs in Fleet. ### Step 4: Add PKCS12 configuration profile to Fleet @@ -226,7 +226,7 @@ When saving the configuration, Fleet will attempt to connect to the SCEP server 1. Create a [configuration profile](https://fleetdm.com/guides/custom-os-settings) with the SCEP payload. In the profile, for `Challenge`, use `$FLEET_VAR_NDES_SCEP_CHALLENGE`. For `URL`, use `$FLEET_VAR_NDES_SCEP_PROXY_URL`, and make sure to add `$FLEET_VAR_SCEP_RENEWAL_ID` to `OU`. -2. If you want your certificates to be unique to each host, update the `Subject`. For example, you can use `$FLEET_VAR_HOST_END_USER_EMAIL_IDP`. You can use [Fleet's host variables](https://fleetdm.com/docs/configuration/yaml-files#variables) such as `$FLEET_VAR_HOST_HARDWARE_SERIAL`. For Apple hosts, you can also use any of the [supported variables](https://fleetdm.com/docs/configuration/yaml-files#variables).. +2. If you want your certificates to be unique to each host, update the `Subject`. For example, you can use `$FLEET_VAR_HOST_END_USER_EMAIL_IDP`. You can use [Fleet's host variables](https://fleetdm.com/guides/fleet-variables) such as `$FLEET_VAR_HOST_HARDWARE_SERIAL`. For Apple hosts, you can also use any of the [supported variables](https://fleetdm.com/docs/configuration/yaml-files#variables).. 3. For Windows profiles, you also need to set `CAThumbprint` to the SHA1 fingerprint of your **root CA certificate** (not the RA signing certificate). See [How to get the CAThumbprint for Windows SCEP profiles](#how-to-get-the-cathumbprint-for-windows-scep-profiles). @@ -460,7 +460,7 @@ Currently, using the Smallstep-Jamf connector is the best practice. Fleet is tes 2. Replace the `{CA_NAME}` with the name you created in step 2. For example, if the name of the CA is "WIFI_AUTHENTICATION", the variables will look like this: `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_WIFI_AUTHENTICATION` and `$FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_WIFI_AUTHENTICATION`. -3. If you want your certificates to be unique to each host, update the `Subject`. For example, you can use `$FLEET_VAR_HOST_END_USER_EMAIL_IDP`. You can also use any of the [supported variables](https://fleetdm.com/docs/configuration/yaml-files#variables). +3. If you want your certificates to be unique to each host, update the `Subject`. For example, you can use `$FLEET_VAR_HOST_END_USER_EMAIL_IDP`. You can also use any of the [supported variables](https://fleetdm.com/guides/fleet-variables). 4. In Fleet, head to **Controls > OS settings > Custom settings** and add the configuration profile to deploy certificates to your hosts. @@ -642,6 +642,38 @@ To deploy SCEP certificates to macOS, iOS, iPadOS, and Windows hosts, we'll foll For Android hosts, we use a configuration profile and a certificate template. Follow the [Android steps](#android-deploy-certificate) instead. +1. Create a [configuration profile](https://fleetdm.com/guides/custom-os-settings) with the SCEP payload. In the profile, for `Challenge`, use `$FLEET_VAR_CUSTOM_SCEP_CHALLENGE_{CA_NAME}`. For `URL`, use `$FLEET_VAR_CUSTOM_SCEP_PROXY_URL_{CA_NAME}`, and make sure to add `$FLEET_VAR_SCEP_RENEWAL_ID` to `OU`. + +2. Replace the `{CA_NAME}` with the name you created in step 3. For example, if the name of the CA is "WIFI_AUTHENTICATION", the variables will look like this: `$FLEET_VAR_CUSTOM_SCEP_CHALLENGE_WIFI_AUTHENTICATION` and `$FLEET_VAR_CUSTOM_SCEP_PROXY_URL_WIFI_AUTHENTICATION`. + +3. If you want your certificates to be unique to each host, update the `Subject`. For example, you can use `$FLEET_VAR_HOST_END_USER_EMAIL_IDP`. You can also use any of the [supported variables](https://fleetdm.com/guides/fleet-variables). + +4. In Fleet, head to **Controls > OS settings > Custom settings** and add the configuration profile to deploy certificates to your hosts. + +When the profile is delivered to your hosts, Fleet will replace the variables. If something goes wrong, errors will appear on each host's **Host details > OS settings**. + +### Android: Deploy certificate + +How to deploy SCEP certificates to Android hosts: + +1. Create a `add-certificates-to-work-profile.json` file, copy/paste the below JSON into it, and then, in Fleet, head to **Controls > OS settings > Custom settings**, select **Add profile**, and upload your new `add-certificates-to-work-profile.json` profile. + +```json +{ + "privateKeySelectionEnabled": true +} +``` + +2. In Fleet, head to **Controls > OS settings > Certificates** and select **Add certificate**. +3. In **Name**, enter a name for the certificate (e.g., "wifi-certificate"). This name is used as the certificate alias to reference in configuration profiles (e.g. [WiFi configuration](https://developers.google.com/android/management/configure-networks#eap_authentication)). +4. In **Certificate authority**, select the custom SCEP CA you created in step 1. +5. In **Subject name**, enter the certificate's subject name (SN). Separate subject fields by a ",". You can use [Fleet's host variables](https://fleetdm.com/guides/fleet-variables) to make the certificate unique to each host. For example: `CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL`. +6. Select **Save**. Fleet will deploy the certificate to your Android hosts. + +If something goes wrong, errors will appear on each host's **Host details > OS settings**. + +How does this work? Fleet installs the "Fleet" Android app on each host. Every 15 minutes, the app checks for new certificates, retrieves any from the SCEP CA, and installs them in the [Android Keystore](https://developer.android.com/privacy-and-security/keystore). + #### Example configuration profiles
@@ -852,8 +884,11 @@ How to deploy SCEP certificates to Android hosts: 2. In Fleet, head to **Controls > OS settings > Certificates** and select **Add certificate**. 3. In **Name**, enter a name for the certificate (e.g., "wifi-certificate"). This name is used as the certificate alias to reference in configuration profiles (e.g. [WiFi configuration](https://developers.google.com/android/management/configure-networks#eap_authentication)). 4. In **Certificate authority**, select the custom SCEP CA you created in step 1. -5. In **Subject name**, enter the certificate's subject name (SN). Separate subject fields by a ",". You can use [Fleet's host variables](https://fleetdm.com/docs/configuration/yaml-files#variables) to make the certificate unique to each host. For example: `CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL`. -6. Select **Save**. Fleet will deploy the certificate to your Android hosts. +5. In **Subject name (SN)**, enter the certificate's subject name (SN). Separate subject fields with a comma (`,`). +6. In **SubjSubject alternative name (SAN)**, enter the certificate's SAN. Separate SAN fields with a comma (`,`). Each field is a key-value pair. See [supported keys](https://fleetdm.com/docs/configuration/yaml-files#android-settings-certificates). +7. Select **Save**. Fleet will deploy the certificate to your Android hosts. + +You can use [Fleet's host variables](https://fleetdm.com/guides/fleet-variables) in **Subject name** and **Subject alternative name** to make the certificate unique to each host. If something goes wrong, errors will appear on each host's **Host details > OS settings**. diff --git a/articles/enable-okta-verify-on-macOS-with-configuration-profile.md b/articles/enable-okta-verify-on-macOS-with-configuration-profile.md index 03f5f8256b..0a9de29afd 100644 --- a/articles/enable-okta-verify-on-macOS-with-configuration-profile.md +++ b/articles/enable-okta-verify-on-macOS-with-configuration-profile.md @@ -80,6 +80,12 @@ The next step to ensure Okta detects the device as managed is to issue a SCEP ce %ComputerName% managementAttestation %HardwareUUID% + + + OU + $FLEET_VAR_CERTIFICATE_RENEWAL_ID + + PayloadIdentifier diff --git a/articles/enroll-hosts.md b/articles/enroll-hosts.md index e2a81cddb2..c83f54e772 100644 --- a/articles/enroll-hosts.md +++ b/articles/enroll-hosts.md @@ -17,8 +17,11 @@ To learn how to enroll Chromebooks, see the [Enroll Chromebooks guide](#enroll-c To manually enroll macOS, Windows, or Linux hosts, generate Fleet's agent (fleetd) through Fleet UI: 1. Go to the **Hosts** page, select the fleet you want your host(s) to enroll to, and select **Add hosts**. + 2. Select the tab for your desired platform (e.g. **macOS**). + 3. Copy the command to generate fleetd and run the command with [fleetctl](https://fleetdm.com/docs/using-fleet/fleetctl-cli) installed. + 4. Install fleetd on your host(s) to enroll it to Fleet. #### Mobile devices @@ -26,8 +29,11 @@ To manually enroll macOS, Windows, or Linux hosts, generate Fleet's agent (fleet To manually enroll iOS, iPadOS, or Android hosts, follow the steps below: 1. Go to the **Hosts** page, select the fleet you want your host(s) to enroll to, and select **Add hosts**. + 2. Select the tab for your desired platform (e.g. **iOS**). + 3. Copy the enrollment link from the UI and share it with your end users. + 4. When your end users visit the link and follow the steps provided on the enrollment page, their host will be enrolled. ## CLI @@ -109,6 +115,7 @@ Fleet admins who are comfortable with this situation can skip step 2 below. To install the fleetd Chrome extension on Google Admin, there are two steps: 1. Create an OU for all users who have Chromebooks and force-install the fleetd Chrome extension for those users + 2. Create an OU for all non-Chromebook devices and block the fleetd Chrome extension on this OU > More complex setups may be necessary, depending on the organization's needs, but the basic principle remains the same. @@ -119,10 +126,15 @@ Create an [organizational unit](https://support.google.com/a/answer/182537?hl=en In the Google Admin console: 1. In the navigation menu, visit **Devices > Chrome > Apps & Extensions > Users & browsers**. + 2. Select the relevant OU where you want the fleetd Chrome extension to be installed. + 3. In the bottom right, select the **+** button and select **Add Chrome app or extension by ID**. + 4. Go to your Fleet instance and select **Hosts > Add Hosts** and select **ChromeOS** in the popup modal. + 5. Enter the **Extension ID**, **Installation URL**, and **Policy for extensions** using the data provided in the modal. + 6. Under **Installation Policy**, select **Force install**, and under **Update URL**, select **Installation URL** (see above). > For the fleetd Chrome extension to have full access to Chrome data, it must be force-installed by enterprise policy as per above @@ -133,10 +145,15 @@ Create an [organizational unit](https://support.google.com/a/answer/182537?hl=en In the Google Admin console: 1. In the navigation menu, select **Devices > Chrome > Managed Browsers**. + 2. Select the relevant OU where you want the fleetd Chrome extension to be blocked. + 3. In the bottom right, select the **+** button and select **Add Chrome app or extension by ID**. + 4. Go to your Fleet instance and select **Hosts > Add Hosts** and select **ChromeOS** in the popup modal. + 5. Enter the **Extension ID** and **Installation URL** using the data provided in the modal. + 6. Under **Installation Policy**, select **Block**. ### Unenroll @@ -152,7 +169,7 @@ In the Google Admin console: 4. Select **Actions > Delete** to delete the host from Fleet. -> Delete the host from Fleet before re-enrolling it. This removes labels, prevents pending activity (like scripts or software installs) from running on the re-enrolled host, and avoids showing the original host’s vitals. +> Delete the host from Fleet before re-enrolling to clear labels, prevent pending actions, and avoid showing stale vitals. **Apple Business (AB) hosts are the exception**. Fleet automatically clears stale state on re-enrollment, so deletion isn't needed. See the [Apple MDM setup guide](https://fleetdm.com/guides/macos-mdm-setup#re-enrolling-ab-hosts) for details. ## Debugging diff --git a/articles/enroll-personal-byod-ios-ipad-hosts-with-managed-apple-account.md b/articles/enroll-personal-byod-ios-ipad-hosts-with-managed-apple-account.md index 129380c4e1..cdff94efab 100644 --- a/articles/enroll-personal-byod-ios-ipad-hosts-with-managed-apple-account.md +++ b/articles/enroll-personal-byod-ios-ipad-hosts-with-managed-apple-account.md @@ -12,7 +12,7 @@ With Account-driven User Enrollment, end users can separate work and personal da - [Step 2: Add and verify your domain in Apple Business (AB)](#step-2-add-and-verify-your-domain-in-apple-business-manager-abm) - [Step 3: Connect (federate) your identity provider (IdP) with Apple Business (AB)](#step-3-connect-federate-your-identity-provider-idp-with-apple-business-manager-abm) - [Step 4: Create a fleet for personal hosts](#step-4-create-a-fleet-for-personal-hosts) -- [Step 5: Log in on the device to enroll to Fleet (end user's iPhone or iPad)](#step-5-log-in-on-the-device-to-enroll-to-fleet-end-users-iphone-or-ipad) +- [Step 5: Instructions for end users](#step-6-instructions-for-end-users) ## Step 1: Connect Apple Business (AB) to Fleet @@ -39,18 +39,28 @@ Follow the [Apple documentation](https://support.apple.com/en-gb/guide/business/ Fleet's [best practice](https://fleetdm.com/guides/fleet#best-practice) is to create a fleet, for personal hosts that have access to company resources. +You must enable end user authentication for this fleet. Go to **Controls > Setup experience > End user authentication** and enable it. If it's not enabled, end users can't enroll. + In this fleet you can add custom OS settings that are compatible with hosts enrolled with Account-driven User Enrollment. To find out which payloads are compatible with User Enrollment, visit the [Apple documentation](https://support.apple.com/en-gb/guide/deployment/dep6ae3f1d5a/1/web/1.0). -## Step 5: Log in on the device to enroll to Fleet (end user's iPhone or iPad) +## Step 5: Instructions for end users -On their iPhone or iPad, ask end users to: +Share these instructions with end users to enroll their personal iPhone or iPad: 1. Open the **Settings** app. 2. Go to **General > VPN & Device Management**. 3. Tap **Sign In to Work or School Account**. -4. Sign in with their IdP credentials (e.g., Google Workspace or Microsoft Entra ID). +4. Sign in with your IdP credentials (e.g., Okta, Microsoft Entra ID, or Google Workspace). -After signing in, the device will automatically enroll in Fleet. +After signing in, your device will enroll to Fleet. + +Apple requires that you sign-in twice: once to Fleet, using your IdP credentials, and once to your Managed Apple Account using your Apple Account credentials. Some organizations connect their IdP to Apple. In this case, the credentials for both logins are the same. If you're not sure, ask your IT admin. + +## Migration from other MDM + +If you're migrating from another MDM, make sure to uninstall the apps that you want to update with Fleet. If apps from your current MDM aren't removed, after the end user migrates, Fleet won't be able update those apps until the end user manually uninstalls them. + +If you or the end user (via self-service) tries to install an app that is already installed, you'll see an error on the **Host details > Activity feed > Past**. ## Self-host a service discovery file (well-known resource) @@ -87,5 +97,5 @@ Apple limits the amount of host vitals Fleet can collect on personal iOS/iPadOS - + diff --git a/articles/fleet-variables.md b/articles/fleet-variables.md new file mode 100644 index 0000000000..a743ae15b9 --- /dev/null +++ b/articles/fleet-variables.md @@ -0,0 +1,46 @@ +# Built-in variables + +_Available in Fleet Premium_ + +Fleet supports built-in variables (prefixed with `$FLEET_VAR_`) to inject host vitals into [configuration profiles](https://fleetdm.com/guides/custom-os-settings) or [iOS/iPadOS managed app configurations](https://fleetdm.com/guides/install-app-store-apps#ios-and-ipados-managed-configuration). + +You can also create [custom variables](https://fleetdm.com/guides/secrets-in-scripts-and-configuration-profiles) (prefixed with `$FLEET_SECRET_`) to define your own key-value pairs. + +For macOS configuration profiles, you can also use any of Apple's [built-in variables](https://support.apple.com/en-my/guide/deployment/dep04666af94/1/web/1.0) in [Automated Certificate Management Environment (ACME)](https://developer.apple.com/documentation/devicemanagement/acmecertificate), [Simple Certificate Enrolment Protocol (SCEP)](https://developer.apple.com/documentation/devicemanagement/scep), or [VPN](https://developer.apple.com/documentation/devicemanagement/vpn) payloads. + +When the variable's value changes, Fleet automatically resends configuration profiles. For managed app configurations, changes apply on next app install or update. + +Built-in variables: + +| Name | Configuration profiles | Managed app configuration | Description | +|---|---|---|---| +| `$FLEET_VAR_NDES_SCEP_CHALLENGE` | macOS, iOS, iPadOS | None | Fleet-managed one-time NDES challenge password used during SCEP certificate configuration profile deployment. | +| `$FLEET_VAR_NDES_SCEP_PROXY_URL` | macOS, iOS, iPadOS | None | Fleet-managed NDES SCEP proxy endpoint URL used during SCEP certificate configuration profile deployment. | +| `$FLEET_VAR_HOST_END_USER_IDP_USERNAME` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Host's IdP username (e.g. "user@example.com"). When this changes, Fleet will automatically resend the profile. | +| `$FLEET_VAR_HOST_END_USER_IDP_FULL_NAME` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Host's IdP full name. When this changes, Fleet will automatically resend the profile. | +| `$FLEET_VAR_HOST_END_USER_IDP_USERNAME_LOCAL_PART` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Local part of the email (e.g. john from john@example.com). When this changes, Fleet will automatically resend the profile. | +| `$FLEET_VAR_HOST_END_USER_IDP_GROUPS` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Comma separated IdP groups that host belongs to. When these change, Fleet will automatically resend the profile. | +| `$FLEET_VAR_HOST_END_USER_IDP_DEPARTMENT` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Host's IdP department. When this changes, Fleet will automatically resend the profile. | +| `$FLEET_VAR_HOST_HARDWARE_SERIAL` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Host's hardware serial number. Not available for user enrolled iOS and iPadOS hosts with Managed Apple Account. | +| `$FLEET_VAR_HOST_UUID` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Host's hardware UUID, or Enrollment ID for user enrolled iOS and iPadOS hosts. | +| `$FLEET_VAR_HOST_PLATFORM` | macOS, iOS, iPadOS, Windows | iOS and iPadOS | Host's platform. Values are `"macos"`, `"ios"`, `"ipados"`, and `"windows"`. | +| `$FLEET_VAR_CUSTOM_SCEP_CHALLENGE_` | macOS, iOS, iPadOS, Windows | None | Fleet-managed one-time challenge password used during SCEP certificate configuration profile deployment. `` should be replaced with name of the custom SCEP certificate authority configured in **Settings > Integrations > Certificate authorities**. | +| `$FLEET_VAR_CUSTOM_SCEP_PROXY_URL_` | macOS, iOS, iPadOS, Windows | None | Fleet-managed SCEP proxy endpoint URL used during SCEP certificate configuration profile deployment. | +| `$FLEET_VAR_CERTIFICATE_RENEWAL_ID` | macOS, iOS, iPadOS, Windows | Fleet-managed ID that's required to automatically renew certificates. The ID must be specified in the Organizational Unit (OU) field in the configuration profile. | +| `$FLEET_VAR_DIGICERT_PASSWORD_` | macOS, iOS, iPadOS | None | Fleet-managed password required to decode the base64-encoded certificate data issued by a specified DigiCert certificate authority during PKCS12 profile deployment. `` should be replaced with name of the DigiCert certificate authority configured in **Settings > Integrations > Certificate authorities**. | +| `$FLEET_VAR_DIGICERT_DATA_` | macOS, iOS, iPadOS | None | Fleet-managed base64-encoded certificate data issued by a specified DigiCert certificate authority during PKCS12 profile deployment. `` should be replaced with name of the DigiCert certificate authority configured in **Settings > Integrations > Certificate authorities**. | +| `$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID` | Windows | None | ID used for SCEP configuration profile on Windows. It must be included in the `` field. | +| `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_` | macOS, iOS, iPadOS | None | Fleet-managed one-time Smallstep challenge password used during SCEP certificate configuration profile deployment. `` should be replaced with name of the Smallstep certificate authority configured in **Settings > Integrations > Certificate authorities**. | +| `$FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_` | macOS, iOS, iPadOS | None | Fleet-managed Smallstep SCEP proxy endpoint URL used during SCEP certificate configuration profile deployment. | + + + +If certificate authority (CA) variables (ex. `$FLEET_VAR_DIGICERT_DATA_`) don't exist, GitOps dry runs will succeed but GitOps runs will fail. + + + + + + + + diff --git a/articles/foreign-vitals-map-idp-users-to-hosts.md b/articles/foreign-vitals-map-idp-users-to-hosts.md index 746af39d88..3f006d17c9 100644 --- a/articles/foreign-vitals-map-idp-users-to-hosts.md +++ b/articles/foreign-vitals-map-idp-users-to-hosts.md @@ -4,7 +4,7 @@ _Available in Fleet Premium._ -Fleet can map an end user's IdP username, groups, and department to their host(s) in Fleet. Then, you can use these IdP host vitals as [variables in configuration profiles](https://fleetdm.com/docs/configuration/yaml-files#variables) or criteria for [labels](https://fleetdm.com/guides/managing-labels-in-fleet). +Fleet can map an end user's IdP username, groups, and department to their host(s) in Fleet. Then, you can use these IdP host vitals as [variables in configuration profiles](https://fleetdm.com/guides/fleet-variables) or criteria for [labels](https://fleetdm.com/guides/managing-labels-in-fleet). Fleet supports [Okta](#okta), [Microsoft Active Directory (AD) / Entra ID](#microsoft-entra-id), [Google Workspace](#google-workspace), [authentik](#google-workspace), as well as [any other IdP](#other-idps) that supports the [SCIM (System for Cross-domain Identity Management) protocol](https://scim.cloud/). diff --git a/articles/install-app-store-apps.md b/articles/install-app-store-apps.md index 5aa7884dec..457ea1d4ae 100644 --- a/articles/install-app-store-apps.md +++ b/articles/install-app-store-apps.md @@ -18,8 +18,6 @@ You can also manage which Google Play Store apps are available for self-service 3. Select **Add software > App store**, then select the app you just purchased. -> Currently, Fleet only supports Apple App Store apps from the United States (US) region. If the app is listed on the [Apple App Store](https://apps.apple.com/) and it has `/us` in the URL (e.g. https://apps.apple.com/us/app/slack/id618783545) then it's supported. - ### Google Play (Android) > Before using Fleet to manage Google Play Store apps, you must first [turn on Android MDM](https://fleetdm.com/guides/android-mdm-setup). Once you've completed that setup, you can follow the directions below for each app. @@ -86,14 +84,33 @@ Currently, Apple App Store (VPP) apps can't be uninstalled via Fleet. If the app > VPP apps on iOS/iPadOS hosts will be uninstalled when the host has MDM features turned off. +#### iOS and iPadOS managed configuration + +Currently, configuration for Apple hosts is supported on iOS and iPadOS. Managed configuration is often referred to as App Config. + +Fleet supports any option provided by the app's developer. Each app supports different options. To find the supported options, check the app documentation. + +##### Example (Zoom) + +This configuration ensures that the end user has only the SSO login option, and it pre-populates the login URL to `example.zoom.us`. For more information, visit [Zoom docs](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0064102). + +```xml + + ForceLoginWithSSO + + SetSSOURL + example + +``` + ### Google Play (Android) Android apps can be installed via self-service in the end user's managed Google Play Store (work profile). -#### Configuration +#### Managed configuration -Currently, editing configurations is only supported for Android apps. Only the `managedConfiguration` and `workProfileWidgets` options from [ApplicationPolicy - Android Management API](https://developers.google.com/android/management/reference/rest/v1/enterprises.policies#ApplicationPolicy) are currently supported. +Currently, only the `managedConfiguration` and `workProfileWidgets` options from [ApplicationPolicy - Android Management API](https://developers.google.com/android/management/reference/rest/v1/enterprises.policies#ApplicationPolicy) are supported. `managedConfiguration` supports any option provided by the app's developer. Each app supports different options. To find the supported options, check the app documentation. diff --git a/articles/lock-wipe-hosts.md b/articles/lock-wipe-hosts.md index 7b1aa27000..55f3258a1e 100644 --- a/articles/lock-wipe-hosts.md +++ b/articles/lock-wipe-hosts.md @@ -51,6 +51,8 @@ Example URL: 3. Click the **Actions** dropdown, then click **Wipe**. 4. Confirm that you want to wipe the device in the dialog. The host will now be marked with a "Wipe pending" badge. Once the wipe command is acknowledged by the host, the badge will update to "Wiped". +Wiping a host silently cancels all of its upcoming activities — no canceled activity entries are added to the host's activity history. + When wiping and re-installing the operating system (OS) on a host, delete the host from Fleet before you re-enroll it. If you re-enroll without deleting, Fleet won't escrow a new disk encryption key. If you're gifting a company-owned macOS host or you want to prevent the host from automatically re-enrolling to Fleet for some other reason, first release the host from Apple Business (AB) and then delete the host in Fleet. diff --git a/articles/role-based-access.md b/articles/role-based-access.md index 623f342992..db0f5f6c58 100644 --- a/articles/role-based-access.md +++ b/articles/role-based-access.md @@ -52,7 +52,7 @@ GitOps is an API-only and write-only role that can be used on CI/CD pipelines. | Target hosts using labels | ✅ | ✅ | ✅ | ✅ | ✅ | | | Add/remove manual labels to/from hosts | | | ✅ | ✅ | ✅ | ✅ | | Add and delete hosts | | | | ✅ | ✅ | | -| Transfer hosts between fleets\* | | | | ✅ | ✅ | ✅ | +| Transfer hosts between fleets\* | | | | ✅ | ✅ | ✅ | | Add user information from IdP to hosts\* | | | | ✅ | ✅ | | | Create, edit, and delete labels | | | ✅ | ✅ | ✅ | ✅ | | View all software | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | diff --git a/articles/secrets-in-scripts-and-configuration-profiles.md b/articles/secrets-in-scripts-and-configuration-profiles.md index af8e37c45a..9c1be64c9f 100644 --- a/articles/secrets-in-scripts-and-configuration-profiles.md +++ b/articles/secrets-in-scripts-and-configuration-profiles.md @@ -1,4 +1,4 @@ -# Variables in scripts and configuration profiles +# Custom variables in scripts and configuration profiles
@@ -6,7 +6,7 @@ In Fleet you can add variables, in [scripts](https://fleetdm.com/guides/scripts) and [configuration profiles](https://fleetdm.com/guides/custom-os-settings). Variables are hidden when the script or configuration profile is viewed in the Fleet UI or API. -Configuration profiles can also use any of Fleet's [built-in variables](https://fleetdm.com/docs/configuration/yaml-files#variables). +Configuration profiles can also use any of Fleet's [built-in variables](https://fleetdm.com/guides/fleet-variables). ## Add variables @@ -32,7 +32,7 @@ Variables are global, meaning they can be used in scripts and profiles across al env: ### Variables used by the GitOps workflow ### FLEET_URL: ${{ secrets.FLEET_URL }} - FLEET_API_TOKEN: ${{ secrets.FLEET_API_TOKEN }} + FLEET_SECRET_API_TOKEN: ${{ secrets.FLEET_API_TOKEN }} WORKSTATIONS_ENROLL_SECRET: ${{ secrets.WORKSTATIONS_ENROLL_SECRET }} ``` @@ -42,7 +42,7 @@ During a GitOps run, Fleet scans scripts and profiles for variables, pulls their Profiles with variables aren’t validated during a GitOps dry run because the variables may be missing or incorrect in Fleet. This means they’re more likely to fail during a real run. Best practice: test the script or profile by adding it to Fleet via the UI first. -> When variable values are updated or changed, Apple (macOS, iOS, iPadOS) profiles are re-sent. Automatic re-send for Windows profiles is [coming soon](https://github.com/fleetdm/fleet/issues/44852). +Some variables trigger an Apple (macOS, iOS, iPadOS) profile resend when their value changes. Automatic re-send for Windows profiles is [coming soon](https://github.com/fleetdm/fleet/issues/44852). See which variables support this in the [Fleet variable](https://fleetdm.com/guides/fleet-variables) guide. If a variable is a secret (for example, an API token), prefix it with FLEET_SECRET_. This masks the value when viewed or downloaded from the Fleet UI or API. @@ -92,7 +92,9 @@ Here's an example profile with `$FLEET_SECRET_CERT_PASSWORD` and `$FLEET_SECRET_ ``` -> Fleet variables are automatically escaped in Apple (`.mobileconfig`) and Windows (`.xml`) configuration profiles. For example, `&` will become `&`. Special characters outside of Fleet variables must be manually escaped because they have special meanings in XML. +> The dollar sign (`$`) can be escaped so it's not considered a variable by using a backslash (e.g. `\$100`). Additionally, `MY${variable}HERE` syntax can be used to put strings around the variable. + +> In XML, certain characters (`&`, `<`, `>`, `"`, `'`) must be escaped because they have special meanings in the markup language. GitHub and GitLab environment variables, as well as Fleet's reserved variables, will be automatically escaped when used in Apple (`.mobileconfig`) and Windows (`.xml`) configuration profiles. For example, `&` will become `&`. These characters must be manually escaped outside of the variables. ## Known limitations and issues @@ -102,9 +104,9 @@ Here's an example profile with `$FLEET_SECRET_CERT_PASSWORD` and `$FLEET_SECRET_ - There is no way to explicitly delete a secret variable. Instead, you can overwrite it with any value. - Do not use deprecated API endpoint(s) to upload profiles containing secret variables. Use endpoints documented in [Fleet's REST API](https://fleetdm.com/docs/rest-api/rest-api). - + - + diff --git a/articles/setup-experience.md b/articles/setup-experience.md index 1d3fab5774..8bbfdafede 100644 --- a/articles/setup-experience.md +++ b/articles/setup-experience.md @@ -64,6 +64,18 @@ To require a EULA, in Fleet, head to **Settings > Integrations > MDM > End user Currently, the EULA is only displayed for macOS hosts that automatically enroll via Apple Business Manager (ABM). +## Managed local account +Fleet can create and manage a local admin account on macOS hosts that automatically enroll via Apple Business (AB). This account gives IT admins a secure way to access a macOS host for troubleshooting without relying on shared or static credentials. + +Admins can view the current password from **Host details > Show managed account** in the Fleet UI or via the API. + +### Password rotation +Fleet rotates the managed local account password by sending an MDM command to the host. Rotation can be triggered manually by clicking **Rotate password** in the managed account modal, or automatically after the password is viewed. + +> Shortly after a host enrolls via DEP, the host's UUID may not yet be known to Fleet. In this case, password rotation is **deferred** until Fleet receives the UUID (typically after the host completes its first check-in). Any pending rotation will proceed automatically once the UUID is available. + +A manual rotation cancels any active auto-rotation timer for that host. + ## Bootstrap package Fleet supports installing a bootstrap package on macOS hosts that automatically enroll to Fleet. Apple requires that your package is a [distribution package](https://fleetdm.com/learn-more-about/macos-distribution-packages). You can install software during out-of-the-box Windows and Linux setup. Learn more in [this separate guide](https://fleetdm.com/guides/windows-linux-setup-experience). diff --git a/articles/windows-linux-setup-experience.md b/articles/windows-linux-setup-experience.md index a129505627..fe6e51f54b 100644 --- a/articles/windows-linux-setup-experience.md +++ b/articles/windows-linux-setup-experience.md @@ -4,7 +4,7 @@ _Available in Fleet Premium_ In Fleet, you can customize the out-of-the-box Windows and Linux setup. -Currently, Windows setup experience is only supported for [manual enrollments](https://fleetdm.com/guides/windows-mdm-setup#manual-enrollment). [Automatic enrollment](https://fleetdm.com/guides/windows-mdm-setup#automatic-enrollment) and [Autopilot](https://fleetdm.com/guides/windows-mdm-setup#windows-autopilot) support is coming soon. +Windows setup experience is supported for [manual enrollment](https://fleetdm.com/guides/windows-mdm-setup#manual-enrollment), [automatic enrollment](https://fleetdm.com/guides/windows-mdm-setup#automatic-enrollment), and [Autopilot](https://fleetdm.com/guides/windows-mdm-setup#windows-autopilot). On Autopilot and Entra-join-during-OOBE enrollments, Fleet holds the device at the Enrollment Status Page while setup experience runs, so software and profiles can apply before the end user reaches the desktop. Currently, Linux setup experience is only supported for Ubuntu, Debian, Fedora, Amazon Linux, CentOS, openSUSE, and Red Hat Enterprise Linux (RHEL). @@ -58,6 +58,32 @@ To replace the Fleet logo with your organization's logo: > Software installations during setup experience are automatically attempted up to 3 times (1 initial attempt + 2 retries) to handle intermittent network issues or temporary failures. This ensures a more reliable setup process for end users. +### Cancel setup if software fails (Windows) + +For Windows hosts enrolling through Autopilot or Entra OOBE, you can configure Fleet to stop setup and show a failure screen on the device when a setup-experience software install fails. Without this setting, Fleet lets the device continue past the Enrollment Status Page even if some installs fail, and the end user reaches the desktop with the failed install marked **Failed** in **My device**. + +To enable for a team: + +1. Select the team you're configuring (or **No team**) from the team dropdown. +2. Go to **Controls** > **Setup experience** > **Install software**. +3. Click the **Windows** tab. +4. Switch on **Cancel setup if software fails**. +5. Press **Save**. + +The setting only applies to Autopilot and Entra-join-during-OOBE enrollments. On those paths, when a setup-experience software install fails, Fleet does the following: + +- Cancels remaining setup-experience steps for that host. +- Posts a `canceled_setup_experience` activity to the activity feed, referencing the first failed install. The activity reads: "Fleet canceled setup experience on \ because \ failed to install. End user was asked to restart." +- Sends the Enrollment Status Page failure screen described below. + +On BYOD enrollments (**Settings** > **Accounts** > **Access work or school** > **Connect**), the Enrollment Status Page is never shown, and the **Cancel setup if software fails** setting is ignored. A failing install just shows as **Failed** in **My device** and host details; other queued installs and scripts run independently. No `canceled_setup_experience` activity is emitted. Because the end user is not notified on the device, plan to surface the failure through host details or the activity feed. + +Profile failures alone do not trigger cancellation, even when **Cancel setup if software fails** is on. Only software install failures (including a 3-hour setup-experience timeout) cause the device to block. + +#### What end users see when setup is cancelled + +On Autopilot or Entra-OOBE, the device shows "Working on it..." for roughly a minute after the failing install reports back to Fleet, then transitions to a failure screen with the configured error text and a **Reset device** button. A **Collect logs** button may also appear, but Windows does not always render it. **Reset device** wipes the device and re-enters OOBE; if the failing software is still configured for the team, the device will hit the same failure again on the next enrollment. Use the recovery procedure below to log into the device without wiping it. + ### Add software Add setup experience software setup experience: @@ -69,6 +95,69 @@ Add setup experience software setup experience: Fleet also provides a API endpoints for managing setup experience software programmatically. Learn more in Fleet's [API reference](https://fleetdm.com/docs/rest-api/rest-api#update-software-setup-experience). +## Recover a Windows host from the setup failure screen + +When a Windows host is parked at the Enrollment Status Page failure screen, the on-screen options are limited to **Reset device** (which wipes the host) and a **Collect logs** button that may or may not appear. The procedures below let you log in to the device and reach a desktop without wiping anything. + +### End user recovery from the device + +An end user sitting in front of the failure screen has two useful keyboard shortcuts: + +- **Shift+F10** opens a Command Prompt. From the prompt, run `powershell.exe` to switch to PowerShell and execute the recovery script described below. +- **Ctrl+Shift+D** opens the Windows Autopilot diagnostics page when diagnostics are enabled in the Autopilot deployment profile. Select **Export Logs** to save diagnostic logs to a USB drive. This is the documented Microsoft alternative when the on-screen **Collect logs** button doesn't appear, but it doesn't recover the device on its own. + +If Shift+F10 produces a blank screen with no console (we've seen this on some hypervisors, including Proxmox), ask an administrator to push the recovery script remotely (next section). + +### Administrator recovery through Fleet + +An administrator can push a PowerShell script to the locked-out host through Fleet. The host's Fleet agent (orbit) installs early in setup experience, so it is running in the background even while the device is parked at the failure screen. The script creates a local administrator account, clears the registry values that pin the Enrollment Status Page block, and reboots the device. + +```powershell +$Username = "IT admin" +$Password = ConvertTo-SecureString "StrongPassword123!" -AsPlainText -Force + +# Create the local user account +New-LocalUser -Name $Username -Password $Password -FullName "Fleet IT admin" -Description "Fleet breakglass admin" -AccountNeverExpires -ErrorAction Stop + +# Add the user to the Administrators group +Add-LocalGroupMember -Group "Administrators" -Member $Username -ErrorAction Stop + +# Clear the Enrollment Status Page block at the registry layer +$key = Get-ChildItem "HKLM:\Software\Microsoft\Provisioning\OMADM\Accounts\*\Protected\*\FirstSyncStatus" -ErrorAction SilentlyContinue +if ($key) { + Set-ItemProperty -Path $key.PSPath -Name "ServerHasFinishedProvisioning" -Value 1 -Type DWord + Set-ItemProperty -Path $key.PSPath -Name "BlockInStatusPage" -Value 0 -Type DWord +} +Restart-Computer -Force +``` + +To run it: + +1. Change `StrongPassword123!` to a password your organization controls. +2. Go to **Controls** > **Scripts** and upload the script, or open the host's detail page and select **Actions** > **Run script** to paste it inline. +3. Run the script against the locked-out host. +4. The host's orbit agent picks up the script within a few seconds and runs it as SYSTEM. The host reboots automatically as the last step. + +After the reboot, the device leaves the failure screen on its own and arrives at a Windows sign-in screen. + +### Sign in as the recovery account + +After the reboot, the Windows sign-in screen defaults to a work or school (Entra) account. The `IT admin` account created above is a local account, so the sign-in must be told to authenticate against this computer rather than Entra. In the username field, type: + +``` +.\IT admin +``` + +The leading `.\` tells Windows to look for the account on this computer. If the sign-in screen does not accept `.\IT admin`, try `\IT admin` (for example `DESKTOP-ABC123\IT admin`), or look for a **Sign-in options** link under the password field and pick a local-account option. + +## Windows updates during Autopilot + +While a Windows device is in Autopilot OOBE, Windows itself may present a "We've got an update for you" screen and offer to restart immediately to install a pending Windows update. Fleet does not trigger this prompt; Windows shows it based on its own update checks, independent of any Fleet OS update profile you may have configured. + +Best practice: select **Another time** so the setup experience can complete before the device reboots. The pending Windows update will install on a later reboot, including any reboot scheduled by a Fleet OS update profile if you have one configured. + +If you select **Restart now**, Windows installs the update and resumes OOBE on the next boot. Setup experience commands that hadn't completed before the restart will resume after the device finishes updating. This works, but it adds time to the user's first-boot wait and makes the OOBE timeline harder to reason about when troubleshooting. + diff --git a/docs/Configuration/agent-configuration.md b/docs/Configuration/agent-configuration.md index 5519e98aad..eb38dc1616 100644 --- a/docs/Configuration/agent-configuration.md +++ b/docs/Configuration/agent-configuration.md @@ -306,6 +306,42 @@ agent_options: script_execution_timeout: 600 ``` +## orbit + +The `orbit` block configures the orbit agent itself (as opposed to osquery). It's kept separate from `command_line_flags` so orbit-specific settings don't need to satisfy the osquery flag schema. + +To learn where to find fleetd logs on each platform, see [Finding fleetd logs](https://fleetdm.com/guides/fleet-troubleshooting-for-it-admins#finding-fleetd-logs). + +### debug_logging (_Coming soon_) + +When `true`, orbit runs at debug log level and passes `--verbose` and `--tls_dump` to osqueryd on every host in the team (or globally, if set on no-team agent options). Unlike `command_line_flags`, toggling this does **not** require an orbit restart: the change is applied on each host's next config poll (up to 30 seconds). Default: `false`. + +Individual hosts can additionally be put into debug mode temporarily via the [`POST /api/v1/fleet/hosts/:id/debug-logging`](https://fleetdm.com/docs/rest-api/rest-api#set-host-orbit-debug-logging) endpoint or the **Enable debug logging** action on the host details page. Host-level overrides can only force debug on (they can't silence a host whose team default is on) and auto-expire after a configurable duration (default 24h, max 7d). + +#### Example + +```yaml +agent_options: + orbit: + debug_logging: true +``` + +### debug_logging_on_enroll_duration + +A Go duration number in seconds (e.g. `3600`, `14400`). When greater than zero, every host that orbit-enrolls (or re-enrolls) into this team — or no-team for global agent options — is automatically put into debug mode for the configured duration after *its* enrollment. The host then reverts to the team default. Default: unset (no auto-stamp). Maximum: `86400` (24 hours). + +Use this during a rollout to capture verbose Setup Experience logs from new hosts without having to flip debug per host afterward. Each host's debug expires `duration` after its own enrollment moment, not at a shared wall-clock time. + +There is **no global fallback**: a host that enrolls into a team uses that team's setting, regardless of what's on global agent options. To apply this option broadly, set it on each team (typically via gitops). + +#### Example + +```yaml +agent_options: + orbit: + debug_logging_on_enroll_duration: 3600 +``` + diff --git a/docs/Configuration/fleet-server-configuration.md b/docs/Configuration/fleet-server-configuration.md index 892f27fe77..201b456407 100644 --- a/docs/Configuration/fleet-server-configuration.md +++ b/docs/Configuration/fleet-server-configuration.md @@ -598,6 +598,35 @@ A value of 0 means no timeout. write_timeout: 5s ``` +### redis_host_cache_enabled + +Enables a Redis-backed cache that fronts host lookups on the osquery and orbit auth paths. +When enabled, Fleet caches authenticated host records in Redis to reduce MySQL load on +high-volume check-in endpoints. Disable to bypass the cache and serve every check-in directly +from MySQL. + +- Default value: true +- Environment variable: `FLEET_REDIS_HOST_CACHE_ENABLED` +- Config file format: + ```yaml + redis: + host_cache_enabled: true + ``` + +### redis_host_cache_ttl + +Base TTL for entries in the Redis-backed host lookup cache. Each entry's actual TTL is jittered +by ±10% to avoid synchronized expiry waves. Must be greater than 0 when `redis_host_cache_enabled` +is true; to disable the cache, set `redis_host_cache_enabled=false` instead of zeroing this value. + +- Default value: 60s +- Environment variable: `FLEET_REDIS_HOST_CACHE_TTL` +- Config file format: + ```yaml + redis: + host_cache_ttl: 60s + ``` + ## Server ### server_address @@ -2682,6 +2711,25 @@ Optionally, if you're using a third-party to manage AWS resources, this is the A software_installers_sts_external_id: your_unique_id ``` +### s3_software_installers_gcs_iam_auth + +When `true`, Fleet uses Google Application Default Credentials (ADC) bearer tokens for +authentication against Google Cloud Storage's S3-compatible endpoint instead of S3 HMAC keys. + +Use this only with `s3_software_installers_endpoint_url` set to `https://storage.googleapis.com`. +This is incompatible with `s3_software_installers_access_key_id`, +`s3_software_installers_secret_access_key`, and `s3_software_installers_sts_assume_role_arn`. + +On GCE, GKE, or Cloud Run, ADC typically resolves to the runtime workload identity (metadata server). + +- Default value: false +- Environment variable: `FLEET_S3_SOFTWARE_INSTALLERS_GCS_IAM_AUTH` +- Config file format: + ```yaml + s3: + software_installers_gcs_iam_auth: true + ``` + ### s3_software_installers_endpoint_url *Available in Fleet Premium.* @@ -2843,6 +2891,25 @@ All carve objects will also be prefixed by date and hour (UTC), making the resul carves_sts_external_id: your_unique_id ``` +### s3_carves_gcs_iam_auth + +When `true`, Fleet uses Google Application Default Credentials (ADC) bearer tokens for +authentication against Google Cloud Storage's S3-compatible endpoint instead of S3 HMAC keys. + +Use this only with `s3_carves_endpoint_url` set to `https://storage.googleapis.com`. +This is incompatible with `s3_carves_access_key_id`, +`s3_carves_secret_access_key`, and `s3_carves_sts_assume_role_arn`. + +On GCE, GKE, or Cloud Run, ADC typically resolves to the runtime workload identity (metadata server). + +- Default value: false +- Environment variable: `FLEET_S3_CARVES_GCS_IAM_AUTH` +- Config file format: + ```yaml + s3: + carves_gcs_iam_auth: true + ``` + ### s3_carves_endpoint_url > Same override behavior as [`s3_software_installers_endpoint_url`](#s3_software_installers_endpoint_url). Do not set this when using IRSA or IAM role-based authentication. diff --git a/docs/Configuration/yaml-files.md b/docs/Configuration/yaml-files.md index bb895bfaf0..244fda0ffa 100644 --- a/docs/Configuration/yaml-files.md +++ b/docs/Configuration/yaml-files.md @@ -410,6 +410,7 @@ controls: - name: wifi-certificate certificate_authority_name: EST_WIFI subject_name: CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL + subject_alternative_name: "DNS=example.com, UPN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME" setup_experience: # Available in Fleet Premium bootstrap_package: https://example.org/bootstrap_package.pkg enable_end_user_authentication: true @@ -467,51 +468,19 @@ Use `labels_include_all` to target hosts that have all labels, `labels_include_a - `name` is the name of the certificate. Name can be used as a certificate alias to reference in configuration profiles (custom settings). - `certificate_authority_name` is the name of the [certificate authority (CA)](#certificate-authorities) to issue the certificate from. Currently, only a custom SCEP CA is supported. -- `subject_name` is the certificate's subject name (SN). Separate subject fields by a "/". For example: "CN=john@example.com, O=Acme Inc.". +- `subject_name` is the certificate's subject name (SN). Separate subject fields with a comma (`,`). For example: "/CN=john@example.com/O=Acme Inc.". +- `subject_alternative_name` is the certificate's subject alternative name (SAN). Separate SAN fields with a comma (`,`). Each field is a key-value pair. Supported keys (case-insensitive) are: + - `DNS` for a DNS hostname (e.g. `DNS=wifi.example.com`). + - `EMAIL` for an email address / RFC 822 name (e.g. `EMAIL=john@example.com`). + - `UPN` for a Microsoft User Principal Name (e.g. `UPN=john@corp.example.com`), commonly used for Active Directory / Intune Wi-Fi authentication. + - `IP` for an IPv4 or IPv6 address (e.g. `IP=10.0.0.1` or `IP=2001:db8::1`). + - `URI` for a URI (e.g. `URI=spiffe://example.com/workload/wifi`). -#### Variables + Example: `"DNS=wifi.example.com, UPN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME"`. -For macOS configuration profiles, you can use any of Apple's [built-in variables](https://support.apple.com/en-my/guide/deployment/dep04666af94/1/web/1.0) in [Automated Certificate Management Environment (ACME)](https://developer.apple.com/documentation/devicemanagement/acmecertificate), [Simple Certificate Enrolment Protocol (SCEP)](https://developer.apple.com/documentation/devicemanagement/scep), or [VPN](https://developer.apple.com/documentation/devicemanagement/vpn) payloads. +You can use [Fleet's host variables](https://fleetdm.com/guides/fleet-variables) in `subject_name` and `subject_alternative_name` to make the certificate unique to each host. -Fleet also supports adding [GitHub](https://docs.github.com/en/actions/learn-github-actions/variables#defining-environment-variables-for-a-single-workflow) or [GitLab](https://docs.gitlab.com/ci/variables/) environment variables in your configuration profiles. Use `$ENV_VARIABLE` format. - -If you use one of these variables in a configuration profile, Fleet will automatically resend it when the variable's value changes. - -In Fleet Premium, you can use reserved variables beginning with `$FLEET_VAR_`. Fleet will populate these variables when profiles are sent to hosts. Supported variables are: - -| Name | Platforms | Description | -| ---- | --------- | ----------- | -| `$FLEET_VAR_NDES_SCEP_CHALLENGE` | macOS, iOS, iPadOS | Fleet-managed one-time NDES challenge password used during SCEP certificate configuration profile deployment. | -| `$FLEET_VAR_NDES_SCEP_PROXY_URL` | macOS, iOS, iPadOS | Fleet-managed NDES SCEP proxy endpoint URL used during SCEP certificate configuration profile deployment. | -| `$FLEET_VAR_HOST_END_USER_IDP_USERNAME` | macOS, iOS, iPadOS, Windows | Host's IdP username (e.g. "user@example.com"). When this changes, Fleet will automatically resend the profile. | -| `$FLEET_VAR_HOST_END_USER_IDP_FULL_NAME` | macOS, iOS, iPadOS, Windows | Host's IdP full name. When this changes, Fleet will automatically resend the profile. |` | macOS, iOS, iPadOS | Host's IdP username. When this changes, Fleet will automatically resend the profile. | -| `$FLEET_VAR_HOST_END_USER_IDP_USERNAME_LOCAL_PART` | macOS, iOS, iPadOS, Windows | Local part of the email (e.g. john from john@example.com). When this changes, Fleet will automatically resend the profile. | -| `$FLEET_VAR_HOST_END_USER_IDP_GROUPS` | macOS, iOS, iPadOS, Windows | Comma separated IdP groups that host belongs to. When these change, Fleet will automatically resend the profile. | -| `$FLEET_VAR_HOST_END_USER_IDP_DEPARTMENT` | macOS, iOS, iPadOS, Windows | Host's IdP department. When this changes, Fleet will automatically resend the profile. | -| `$FLEET_VAR_HOST_UUID` | macOS, iOS, iPadOS, Windows | Host's hardware UUID. | -| `$FLEET_VAR_HOST_HARDWARE_SERIAL` | macOS, iOS, iPadOS, Windows | Host's hardware serial number. | -| `$FLEET_VAR_HOST_PLATFORM` | macOS, iOS, iPadOS, Windows | Host's platform. Values are `"macos"`, `"ios"`, `"ipados"`, and `"windows"`. | -| `$FLEET_VAR_CUSTOM_SCEP_CHALLENGE_` | macOS, iOS, iPadOS, Windows | Fleet-managed one-time challenge password used during SCEP certificate configuration profile deployment. `` should be replaced with name of the certificate authority configured in [custom_scep_proxy](#custom-scep-proxy). | -| `$FLEET_VAR_CUSTOM_SCEP_PROXY_URL_` | macOS, iOS, iPadOS, Windows | Fleet-managed SCEP proxy endpoint URL used during SCEP certificate configuration profile deployment. | -| `$FLEET_VAR_SCEP_RENEWAL_ID` | macOS, iOS, iPadOS, Windows | Fleet-managed ID that's required to automatically renew Smallstep, Microsoft NDES, and custom SCEP certificates. The ID must be specified in the Organizational Unit (OU) field in the configuration profile. | -| `$FLEET_VAR_DIGICERT_PASSWORD_` | macOS, iOS, iPadOS | Fleet-managed password required to decode the base64-encoded certificate data issued by a specified DigiCert certificate authority during PKCS12 profile deployment. `` should be replaced with name of the certificate authority configured in [digicert](#digicert). | -| `$FLEET_VAR_DIGICERT_DATA_` | macOS, iOS, iPadOS | Fleet-managed base64-encoded certificate data issued by a specified DigiCert certificate authority during PKCS12 profile deployment. `` should be replaced with name of the certificate authority configured in [digicert](#digicert). | -| `$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID` | Windows | ID used for SCEP configuration profile on Windows. It must be included in the `` field.| -| `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_` | macOS, iOS, iPadOS | Fleet-managed one-time Smallstep challenge password used during SCEP certificate configuration profile deployment. `` should be replaced with name of the certificate authority configured in [custom_scep_proxy](#custom-scep-proxy). | -| `$FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_` | macOS, iOS, iPadOS | Fleet-managed Smallstep SCEP proxy endpoint URL used during SCEP certificate configuration profile deployment. | - -The dollar sign (`$`) can be escaped so it's not considered a variable by using a backslash (e.g. `\$100`). Additionally, `MY${variable}HERE` syntax can be used to put strings around the variable. - -In XML, certain characters (`&`, `<`, `>`, `"`, `'`) must be escaped because they have special meanings in the markup language. GitHub and GitLab environment variables, as well as Fleet's reserved variables, will be automatically escaped when used in a `.mobileconfig` configuration profile. For example, `&` will become `&`. - -In JSON, certain characters (`"`, `\`, and control characters) must be escaped because they have special meanings in the data format. GitHub and GitLab environment variables, as well as Fleet's reserved variables, will be automatically escaped when used in a `.json` configuration profile (Apple DDM declaration or Android profile). For example, `"` will become `\"`. - -If certificate authority (CA) variables (ex. `$FLEET_VAR_DIGICERT_DATA_`) don't exist, GitOps dry runs will succeed but GitOps runs will fail. - -To hide variable values in the API and UI, you can use Fleet's [custom variables](https://fleetdm.com/guides/secrets-in-scripts-and-configuration-profiles#gitops). - - -### setup_experience +### macos_setup The `setup_experience` section lets you control the out-of-the-box [setup experience](https://fleetdm.com/guides/setup-experience). @@ -584,7 +553,7 @@ software: setup_experience: true - path: ../lib/software-name2.package.yml app_store_apps: - - app_store_id: "1091189122" + - app_store_id: "546505307" platform: ios labels_include_any: # Available in Fleet Premium - Product @@ -595,6 +564,8 @@ software: auto_update_enabled: true auto_update_window_start: "00:00" auto_update_window_end: "04:00" + configuration: + path: ../lib/software/zoom-config.xml - app_store_id: "us.zoom.videomeetings" platform: android self_service: true @@ -713,9 +684,9 @@ software: + For Apple App Store apps, make sure to include only the ID itself, and not the `id` prefix shown in the URL. The ID must be wrapped in quotes as shown in the example so that it is processed as a string. - `platform` is the platform of the app (`darwin`, `ios`, `ipados`, or `android`). If not specified, and `app_store_id` is Apple App Store ID, one app for each of the Apple App Store app's supported platforms is added. For example, adding [Bear](https://apps.apple.com/us/app/bear-markdown-notes/id1016366447) (supported on iOS and iPadOS) adds both the iOS and iPadOS apps to your software that's available to install in Fleet. - `icon.path` is a relative path to the PNG icon that will be displayed in Fleet and on **Fleet Desktop > Self-service** instead of the default icon the icon sourced from Apple. It must be a square PNG with dimensions between 120x120 px and 1024x1024 px. Custom icons will only override the icon for the software title and fleet where they are added. -- `configuration.path` is the Android Play Store app's managed configuration in JSON format. Currently only supported for Android. - + `managedConfiguration` and `workProfileWidgets` are supported from [Android application policy](https://developers.google.com/android/management/reference/rest/v1/enterprises.policies#ApplicationPolicy). - + Configuration keys vary by app. Refer to the app vendor's documentation for available managed configuration options. For example, see [Zoom's Android managed configuration](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0064790) or [GlobalProtect's Android configuration](https://docs.paloaltonetworks.com/globalprotect/10-1/globalprotect-admin/mobile-endpoint-management/manage-the-globalprotect-app-using-other-third-party-mdms/configure-the-globalprotect-app-for-android). +- `configuration.path` is the app managed configuration. For iOS and iPadOS apps it is in XML format, and for Android Play Store apps it is in JSON format. Currently only supported for iOS, iPadOS, and Android. + + Android: `managedConfiguration` and `workProfileWidgets` are supported from [Android application policy](https://developers.google.com/android/management/reference/rest/v1/enterprises.policies#ApplicationPolicy). + + Configuration keys vary by app. Refer to the app vendor's documentation for available managed configuration options. For example, see [Zoom's Android managed configuration](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0064790), [Zoom's iOS managed configuration](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0064102), or [GlobalProtect's Android configuration](https://docs.paloaltonetworks.com/globalprotect/10-1/globalprotect-admin/mobile-endpoint-management/manage-the-globalprotect-app-using-other-third-party-mdms/configure-the-globalprotect-app-for-android). - `auto_update_enabled` enables automatic updates for the app (default: `false`). Only supported for iOS and iPadOS App Store (VPP) apps. - `auto_update_window_start` is the start of the daily maintenance window during which Fleet will apply automatic updates, formatted as `HH:MM` in the host's local time (e.g. `"00:00"`). Required when `auto_update_enabled` is `true`. Must be wrapped in quotes so it is processed as a string. - `auto_update_window_end` is the end of the daily maintenance window, formatted as `HH:MM` in the host's local time (e.g. `"04:00"`). Required when `auto_update_enabled` is `true`. If the end time is earlier than the start time, the window wraps to the next day (e.g. `"22:00"` to `"02:00"`). Must be wrapped in quotes so it is processed as a string. @@ -795,6 +766,26 @@ org_settings: alternative_browser_host: fleet-desktop.example.com ``` +### gitops + +The `gitops` section allows configuring [GitOps mode](https://fleetdm.com/learn-more-about/ui-gitops-mode) in the Fleet UI. When GitOps mode is enabled, many UI features become read-only to ensure that configuration changes are made only via GitOps. + +- `gitops_mode_enabled` — when `true`, Fleet's UI shows GitOps-managed sections as read-only with a tooltip pointing to the repository URL. Requires Fleet Premium. +- `repository_url` (default: `""`) — the URL of the GitOps repository that manages this Fleet. Must be a valid `http://` or `https://` URL. Required when `gitops_mode_enabled: true`. + +Can only be configured for "All fleets" (`org_settings`). + +> If `gitops:` is not provided in your YAML file, any existing GitOps mode settings will be preserved. + +#### Example + +```yaml +org_settings: + gitops: + gitops_mode_enabled: true + repository_url: https://github.com/example/fleet-config +``` + ### host_expiry_settings The `host_expiry_settings` section lets you define if and when hosts should be automatically deleted from Fleet if they have not checked in. @@ -814,18 +805,37 @@ org_settings: host_expiry_window: 10 ``` +### activity_expiry_settings + +The `activity_expiry_settings` section lets you define how to handle activities. +- `activity_expiry_enabled` when enabled, allows automatic cleanup of activities (and associated live query data) older than the specified number of days. Activities linked to a host are preserved until the host is deleted. +- `activity_expiry_window` the number of days to retain activity records, if activity expiry is enabled. +- `preserve_host_activity_on_reenrollment` When enabled, preserves host activities after a wipe and re-enrollment. Currently only supported for company-owned (AB) Apple hosts. **Delete activities > Max activity age** still applies. (Default: `false`) + +#### Example + +```yaml +org_settings: + activity_expiry_settings: + activity_expiry_enabled: true + activity_expiry_window: 30 + preserve_host_activity_on_reenrollment: true +``` + ### org_info - `org_name` is the name of your organization (default: `""`) -- `org_logo_url` is a public URL of the logo for your organization (default: Fleet logo). -- `org_logo_url_light_background` is a public URL of the logo for your organization that can be used with light backgrounds (default: Fleet logo). +- `org_logo_path_dark_mode` is a path to an image file for your organization's logo (default: Fleet logo). Only one of `org_logo_path_dark_mode` or `org_logo_url_dark_mode` may be specified. +- `org_logo_path_light_mode` is a path to an image file for your organization's logo (default: Fleet logo). Only one of `org_logo_path_light_mode` or `org_logo_url_light_mode` may be specified. +- `org_logo_url_dark_mode` is a public URL of the logo for your organization (default: Fleet logo). Only one of `org_logo_path_dark_mode` or `org_logo_url_dark_mode` may be specified. +- `org_logo_url_light_mode` is a public URL of the logo for your organization that can be used with light backgrounds (default: Fleet logo). Only one of `org_logo_path_light_mode` or `org_logo_url_light_mode` may be specified. - `contact_url` is a URL or [file URI](https://en.wikipedia.org/wiki/File_URI_scheme) that appears in error messages presented to end users (default: `"https://fleetdm.com/company/contact"`) Can only be configured for "All fleets" (`org_settings`). -To get the best results for your logos (`org_logo_url` and `org_logo_url_light_background`), use the following sizes: -- For square logos, use a PNG that's 256x256 pixels (px). -- For rectangular logos (wordmark), use a PNG that's 516x256 pixels (px). +To get the best results for your logos (`org_logo_url_dark_mode`/`org_logo_path_dark_mode` and `org_logo_url_light_mode`/`org_logo_path_light_mode`), use the following sizes: +- For square logos, use a PNG, JPEG/JPG, WebP or SVGs that's 256x256 pixels (px). +- For rectangular logos (wordmark), use a PNG, JPEG/JPG, WebP or SVGs that's 516x256 pixels (px). #### Example @@ -833,8 +843,8 @@ To get the best results for your logos (`org_logo_url` and `org_logo_url_light_b org_settings: org_info: org_name: Fleet - org_logo_url: https://example.com/logo.png - org_logo_url_light_background: https://example.com/logo-light.png + org_logo_url_dark_mode: https://example.com/logo.png + org_logo_url_light_mode: https://example.com/logo-light.png contact_url: https://fleetdm.com/company/contact ``` @@ -1172,14 +1182,14 @@ org_settings: ### mdm -#### apple_business_manager +#### apple_business -After [adding an Apple Business Manager (ABM) token via the UI](https://fleetdm.com/guides/macos-mdm-setup#apple-business-manager), the `apple_business_manager` section lets you determine which fleet Apple hosts are assigned to in Fleet when they appear in Apple Business Manager. +After [adding an Apple Business (AB) token via the UI](https://fleetdm.com/guides/macos-mdm-setup#apple-business-manager), the `apple_business` section lets you determine which fleet Apple hosts are assigned to in Fleet when they appear in Apple Business. -- `organization_name` is the organization name associated with the Apple Business Manager account. -- `macos_fleet` is the fleet where macOS hosts are automatically added when they appear in Apple Business Manager. If not specified, defaults to "Unassigned". -- `ios_fleet` is the the fleet where iOS hosts are automatically added when they appear in Apple Business Manager. If not specified, defaults to "Unassigned". -- `ipados_fleet` is the fleet where iPadOS hosts are automatically added when they appear in Apple Business Manager. If not specified, defaults to "Unassigned". +- `organization_name` is the organization name associated with the Apple Business account. +- `macos_fleet` is the fleet where macOS hosts are automatically added when they appear in Apple Business. If not specified, defaults to "Unassigned". +- `ios_fleet` is the the fleet where iOS hosts are automatically added when they appear in Apple Business. If not specified, defaults to "Unassigned". +- `ipados_fleet` is the fleet where iPadOS hosts are automatically added when they appear in Apple Business. If not specified, defaults to "Unassigned". Can only be configured for "All fleets" (`org_settings`). @@ -1188,7 +1198,7 @@ Can only be configured for "All fleets" (`org_settings`). ```yaml org_settings: mdm: - apple_business_manager: # Available in Fleet Premium + apple_business: # Available in Fleet Premium - organization_name: Fleet Device Management Inc. macos_fleet: 💻 Workstations ios_fleet: 📱🏢 Company-owned iPhones @@ -1198,7 +1208,6 @@ org_settings: #### volume_purchasing_program After you've uploaded a [Volume Purchasing Program](https://fleetdm.com/guides/macos-mdm-setup#volume-purchasing-program-vpp) (VPP) token, the `volume_purchasing_program` section lets you configure the fleets in Fleet that have access to that VPP token's App Store apps. Currently, adding a VPP token is only available using Fleet's UI. - - `location` is the name of the organization unit in the Apple Business account. Apple previously called this "location." Fleet will rename it to "organization unit" in the next major version. - `fleets` is a list of fleet names. If you choose specific fleets, App Store apps in this VPP account will only be available to install on hosts in these fleets. If not specified, App Store apps will not be available to install on any fleet. To apply it to all fleets, use `- All fleets`. diff --git a/docs/Contributing/reference/audit-logs.md b/docs/Contributing/reference/audit-logs.md index 25006b5904..ed4526f556 100644 --- a/docs/Contributing/reference/audit-logs.md +++ b/docs/Contributing/reference/audit-logs.md @@ -1525,6 +1525,7 @@ This activity contains the following fields: - "policy_name": Name of the policy whose failure triggered installation. Null if no associated policy. - "command_uuid": ID of the in-house app installation. - "from_setup_experience": Whether the installation was triggered as part of the setup experience. +- "failure_reason": Reason the installation failed before reaching the device (e.g. an unresolvable Fleet variable in the managed app configuration). Only present when "status" is "failed_install" and Fleet failed the install pre-flight; omitted otherwise. #### Example @@ -1729,6 +1730,7 @@ This activity contains the following fields: - "team_id": ID of the team to which this App Store app was added, or `null`if it was added to no team. - "labels_include_any": Target hosts that have any label in the array. - "labels_exclude_any": Target hosts that don't have any label in the array. +- "configuration": The app's managed configuration, if set. For iOS and iPadOS apps it is in XML format, and for Android Play Store apps it is in JSON format. #### Example @@ -1805,6 +1807,7 @@ This activity contains the following fields: - "policy_id": ID of the policy whose failure triggered the install. Null if no associated policy. - "policy_name": Name of the policy whose failure triggered the install. Null if no associated policy. - "from_setup_experience": Whether the app was installed as part of the setup experience. +- "failure_reason": Reason the installation failed before reaching the device (e.g. an unresolvable Fleet variable in the managed app configuration). Only present when "status" is "failed_install" and Fleet failed the install pre-flight; omitted otherwise. #### Example @@ -1877,6 +1880,7 @@ This activity contains the following fields: - "auto_update_enabled": Whether automatic updates are enabled for iOS/iPadOS App Store (VPP) apps. - "auto_update_window_start": Update window start time (local time of the device) when automatic updates will take place for iOS/iPadOS App Store (VPP) apps, formatted as HH:MM. - "auto_update_window_end": Update window end time (local time of the device) when automatic updates will take place for iOS/iPadOS App Store (VPP) apps, formatted as HH:MM. +- "configuration": The app's managed configuration, if set. For iOS and iPadOS apps it is in XML format, and for Android Play Store apps it is in JSON format. #### Example @@ -2579,6 +2583,23 @@ This activity contains the following fields: } ``` +## rotated_managed_local_account_password + +Generated when a managed local account password is rotated. + +This activity contains the following fields: +- "fleet_id": The ID of the fleet that create managed local account applies to, `null` if it applies to devices that are not in a fleet. +- "fleet_name": The name of the fleet that create managed local account applies to, `null` if it applies to devices that are not in a fleet. + +#### Example + +```json +{ + "fleet_id": 123, + "fleet_name": "Workstations" +} +``` + ## enabled_managed_local_account Generated when a user turns on create managed local account for a fleet (or unassigned hosts). @@ -2621,10 +2642,94 @@ This activity contains the following fields: - "host_id": ID of the host. - "host_display_name": Display name of the host. +#### Example + ```json { - "host_id": 1, - "host_display_name": "Anna's MacBook Pro" + "host_id": 123, + "host_display_name": "Anna's MacBook Pro" +} +``` + +## failed_enrollment_profile_renewal + +Generated when an enrollment profile renewal (SCEP or ACME) has failed. + +This activity contains the following fields: +- "host_id": ID of the host. +- "host_display_name": Display name of the host. +- "command_uuid": Command ID we display details for. + +#### Example + +```json +{ + "host_id": 123, + "host_display_name": "PWNED-VM-123", + "command_uuid": "98765432-1234-1234-1234-1234567890ab" +} +``` + +## created_label + +Generated when creating labels. + +This activity contains the following fields: +- "label_id": the ID of the new label. +- "label_name": the name of the new label. +- "fleet_id": the ID of the fleet the label belongs to. +- "fleet_name": the name of the fleet the label belongs to. + +#### Example + +```json +{ + "label_id": 123, + "label_name": "foo", + "fleet_id": 1, + "fleet_name": "💻 Workstations" +} +``` + +## edited_label + +Generated when editing labels. + +This activity contains the following fields: +- "label_id": the ID of the edited label. +- "label_name": the name of the edited label. +- "fleet_id": the ID of the fleet the label belongs to. +- "fleet_name": the name of the fleet the label belongs to. + +#### Example + +```json +{ + "label_id": 123, + "label_name": "foo", + "fleet_id": 1, + "fleet_name": "💻 Workstations" +} +``` + +## deleted_label + +Generated when deleting labels. + +This activity contains the following fields: +- "label_id": the ID of the deleted label. +- "label_name": the name of the deleted label. +- "fleet_id": the ID of the fleet the label belonged to. +- "fleet_name": the name of the fleet the label belonged to. + +#### Example + +```json +{ + "label_id": 123, + "label_name": "foo", + "fleet_id": 1, + "fleet_name": "💻 Workstations" } ``` diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index faf2247610..d8da8e0083 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -760,7 +760,8 @@ Add a certificate template to deploy a certificate to all hosts on the fleet. Fl | name | string | body | **Required.** The name of the certificate. Name can be used as certificate alias to reference in configuration profiles. | | fleet_id | string | body | _Available in Fleet Premium_. The ID of the fleet to add profiles to. | | certificate_authority_id | integer | body | **Required.** The certificate authority (CA) ID to issue certificate from. Currently, only custom SCEP CA is supported. To get ID use [List certificate authorities](#list-certificate-authorities-cas). | -| subject_name | string | body |**Required** The certificate's subject name (SN). Separate subject fields by a ",". For example: "CN=john@example.com, O=Acme Inc.". | +| subject_name | string | body |**Required** The certificate's subject name (SN). Separate subject fields with a comma (`,`). For example: "CN=john@example.com,O=Acme Inc.". | +| subject_alternative_name | string | body | The certificate's subject alternative name (SAN). Separate SAN fields with a comma (`,`). Each field is a key-value pair. See [supported keys](https://fleetdm.com/docs/configuration/yaml-files#android-settings-certificates). Example: `DNS=wifi.example.com, UPN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME`. | #### Example @@ -774,7 +775,8 @@ Add a certificate template to deploy a certificate to all hosts on the fleet. Fl "team_id": 1, "fleet_id": 1, "certificate_authority_id": 1, - "subject_name": "CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL" + "subject_name": "CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL", + "subject_alternative_name": "DNS=example.com, UPN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME" } ``` @@ -787,7 +789,8 @@ Add a certificate template to deploy a certificate to all hosts on the fleet. Fl "certificate_authority_id": 1, "id": 1, "name": "wifi-certificate", - "subject_name": "CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL" + "subject_name": "CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL", + "subject_alternative_name": "DNS=example.com, UPN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME" } ``` @@ -992,6 +995,7 @@ Authorization: Bearer sunVIQ+wqYQvJlXf1aqYTt8LrlUGKBigNdWmdH5bhT1MH "certificate_authority_id": "1", "certificate_authority_name": "PRODUCTION_SCEP_SERVER", "subject_name": "CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL", + "subject_alternative_name": "DNS=example.com, UPN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME", "created_at": "2025-11-04T00:00:00Z", }, { @@ -1021,7 +1025,7 @@ Get details of the certificate added to Fleet. | Name | Type | In | Description | |---------------- |-------- |------|-------------------------------------------------------------| | id | integer | path | **Required**. The ID of the certificate. | -| host_id | integer | query | ID of the host. If included, variables in `subject_name` will be replaced with host's values. | +| host_id | integer | query | ID of the host. If included, variables in `subject_name`, and `subject_alternative_name` will be replaced with host's values. | #### Request headers @@ -1070,7 +1074,8 @@ Authorization: Bearer sunVIQ+wqYQvJlXf1aqYTt8LrlUGKBigNdWmdH5bhT1MH "created_at": "2025-11-04T00:00:00Z", "id": 1, "name": "wifi-certificate", - "subject_name": "CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL", + "subject_name": "CN=marko@example.com, O=Fleet Inc", + "subject_alternative_name": "DNS=example.com, UPN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME" } ``` @@ -1447,6 +1452,8 @@ Retrieves the specified carve block. This endpoint retrieves the data that was c - [Get Fleet certificate](#get-fleet-certificate) - [Get configuration](#get-configuration) - [Update configuration](#update-configuration) +- [Update organization logo](#update-organization-logo) +- [Delete organization logo](#delete-organization-logo) - [Get global enroll secrets](#get-global-enroll-secrets) - [Update global enroll secrets](#update-global-enroll-secrets) - [Get fleet enroll secrets](#get-fleet-enroll-secrets) @@ -1506,7 +1513,10 @@ None. { "org_info": { "org_name": "fleet", + "org_logo_url_dark_mode": "", + "org_logo_url_light_mode": "", "org_logo_url": "", + "org_logo_url_light_background": "", "contact_url": "https://fleetdm.com/company/contact" }, "server_settings": { @@ -1558,7 +1568,8 @@ None. }, "activity_expiry_settings": { "activity_expiry_enabled": false, - "activity_expiry_window": 0 + "activity_expiry_window": 0, + "preserve_host_activity_on_reenrollment": false, }, "features": { "enable_host_users": true, @@ -1846,6 +1857,8 @@ Modifies the Fleet's configuration with the supplied information. { "org_info": { "org_name": "Fleet Device Management", + "org_logo_url_dark_mode": "https://fleetdm.com/logo.png", + "org_logo_url_light_mode": "https://fleetdm.com/logo-light.png", "org_logo_url": "https://fleetdm.com/logo.png", "org_logo_url_light_background": "https://fleetdm.com/logo-light.png", "contact_url": "https://fleetdm.com/company/contact" @@ -1899,7 +1912,8 @@ Modifies the Fleet's configuration with the supplied information. }, "activity_expiry_settings": { "activity_expiry_enabled": false, - "activity_expiry_window": 0 + "activity_expiry_window": 0, + "preserve_host_activity_on_reenrollment": false, }, "features": { "enable_host_users": true, @@ -2116,10 +2130,12 @@ Modifies the Fleet's configuration with the supplied information. | Name | Type | Description | | --------------------- | ------- | ----------------------------------------------------------------------------------- | | org_name | string | The organization name. | -| org_logo_url | string | The URL for the organization logo. | -| org_logo_url_light_background | string | The URL for the organization logo displayed in Fleet on top of light backgrounds. | +| org_logo_url_dark_mode | string | The URL for the organization logo displayed on top of dark backgrounds. | +| org_logo_url_light_mode | string | The URL for the organization logo displayed in Fleet on top of light backgrounds. | | contact_url | string | A URL or [file URI](https://en.wikipedia.org/wiki/File_URI_scheme) that can be used by end users to contact the organization. | +> `org_logo_url` and `org_logo_url_light_background` are deprecated. They are maintained for backwards compatibility. Please use `org_logo_url_dark_mode` and `org_logo_url_light_mode` instead. +
##### Example request body @@ -2128,6 +2144,8 @@ Modifies the Fleet's configuration with the supplied information. { "org_info": { "org_name": "Fleet Device Management", + "org_logo_url_dark_mode": "https://fleetdm.com/logo.png", + "org_logo_url_light_mode": "https://fleetdm.com/logo-light.png", "org_logo_url": "https://fleetdm.com/logo.png", "org_logo_url_light_background": "https://fleetdm.com/logo-light.png", "contact_url": "https://fleetdm.com/company/contact" @@ -2267,6 +2285,7 @@ Modifies the Fleet's configuration with the supplied information. | --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | | activity_expiry_enabled | boolean | When enabled, allows automatic cleanup of activities (and associated live query data) older than the specified number of days. Activities linked to a host are preserved until the host is deleted. | | activity_expiry_window | integer | The number of days to retain activity records, if activity expiry is enabled. | +| preserve_host_activity_on_reenrollment | boolean | When enabled, preserves host activities after a wipe and re-enrollment. Currently only supported for company-owned (AB) Apple hosts. **Delete activities > Max activity age** still applies. (Default: `false`) |
@@ -2276,7 +2295,8 @@ Modifies the Fleet's configuration with the supplied information. { "activity_expiry_settings": { "activity_expiry_enabled": true, - "activity_expiry_window": 90 + "activity_expiry_window": 90, + "preserve_host_activity_on_reenrollment": true, } } ``` @@ -2638,6 +2658,7 @@ _Available in Fleet Premium._ | enable_managed_local_account | boolean | _Available in Fleet Premium._ During Setup experience, a managed local account will be created on macOS hosts if set to true. | | end_user_local_account_type | string | _Available in Fleet Premium._ Specifies the type of local end user account created. (Default: `"admin"`) `enable_managed_local_account` must be true. | | lock_end_user_info | boolean | If set to true, end user can't edit the local account's Account Name and Full Name in macOS Setup Assistant. These fields will be locked to values from your IdP. (Default: `true`) | +| enable_managed_local_account | boolean | Whether to enforce creating managed local accounts on macOS hosts that automatically enroll. |
@@ -2814,6 +2835,57 @@ None. } ``` +### Update organization logo + +Upload a custom logo to display in the top navigation, setup experience window, and MDM migration dialog. + +> You need to send a request of type `multipart/form-data`. + +`PUT /api/v1/fleet/logo` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ------- | ---- | -------------------------------------------- | +| logo | file | body | The logo image to upload. For best results, use a square logo at least 150px x 150px. | +| mode | string | query | Either `"light"` for the logo displayed in light mode, `"dark" for the logo displayed in dark mode`, or "all" to replace both light and dark mode logos. (Default: `"all"`.)| + +#### Example + +`PUT /api/v1/fleet/logo?mode=light` + +##### Request body + +```http +icon="fleet-logo-150x150.png" +``` + +##### Default response + +`Status: 204` + +### Delete organization logo + +Delete a custom logo added via [Update organization logo](#update-organization-logo). This will revert to using the Fleet logo. + +`DELETE /api/v1/fleet/logo` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ------- | ---- | -------------------------------------------- | +| logo | file | body | The logo image to upload. For best results, use a square logo at least 150px x 150px. | +| mode | string | query | Either `"light"` for the logo displayed in light mode, `"dark" for the logo displayed in dark mode`, or "all" to replace both light and dark mode logos. (Default: `"all"`.)| + +#### Example + +`DELETE /api/v1/fleet/logo?mode=light` + +##### Default response + +`Status: 204` + + ### Update global enroll secrets Replaces all existing global enroll secrets. @@ -3104,7 +3176,7 @@ the `software` table. | device_mapping | boolean | query | Indicates whether `device_mapping` should be included for each host. | | mdm_id | integer | query | The ID of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider and URL). | | mdm_name | string | query | The name of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider). | -| mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'automatic', 'enrolled', 'pending', or 'unenrolled'. 'pending' only includes Apple (macOS, iOS, iPadOS) hosts in Apple Business Manager (ABM) that are not yet enrolled to Fleet. | +| mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'automatic', 'enrolled', 'pending', or 'unenrolled'. 'pending' only includes Apple (macOS, iOS, iPadOS) hosts in Apple Business (AB) that are not yet enrolled to Fleet. | | connected_to_fleet | boolean | query | Filter hosts that are talking to this Fleet server for MDM features. In rare cases, hosts can be enrolled to one Fleet server but talk to a different Fleet server for MDM features. In this case, the value would be `false`. Always `false` for Linux hosts. | | macos_settings | string | query | Filters the hosts by the status of the _mobile device management_ (MDM) profiles applied to hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | | munki_issue_id | integer | query | The ID of the _munki issue_ (a Munki-reported error or warning message) to filter hosts by (that is, filter hosts that are affected by that corresponding error or warning message). | @@ -3411,7 +3483,7 @@ Response payload with the `munki_issue_id` filter provided: | label_id | integer | query | A valid label ID. Can only be used in combination with `order_key`, `order_direction`, `after`, `status`, `query` and `fleet_id`. | | mdm_id | integer | query | The ID of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider and URL). | | mdm_name | string | query | The name of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider). | -| mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'automatic', 'enrolled', 'pending', or 'unenrolled'. 'pending' only includes Apple (macOS, iOS, iPadOS) hosts in Apple Business Manager (ABM) that are not yet enrolled to Fleet. | +| mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'automatic', 'enrolled', 'pending', or 'unenrolled'. 'pending' only includes Apple (macOS, iOS, iPadOS) hosts in Apple Business (AB) that are not yet enrolled to Fleet. | | macos_settings | string | query | Filters the hosts by the status of the _mobile device management_ (MDM) profiles applied to hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | | munki_issue_id | integer | query | The ID of the _munki issue_ (a Munki-reported error or warning message) to filter hosts by (that is, filter hosts that are affected by that corresponding error or warning message). | | low_disk_space | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts with less GB of disk space available than this value. Must be a number between 1-100. | @@ -4219,7 +4291,10 @@ X-Client-Cert-Serial: "status": "online", "display_text": "Annas-MacBook-Pro.local", "self_service": true, - "org_logo_url": "https://example.com/logo.jpg", + "org_logo_url_dark_mode": "https://example.com/logo.png", + "org_logo_url_light_mode": "https://example.com/logo-light.png", + "org_logo_url": "https://example.com/logo.png", + "org_logo_url_light_background": "https://example.com/logo-light.png", "conditional_access_bypassed": false, "license": { "tier": "free", @@ -4690,6 +4765,33 @@ This report includes a subset of host vitals, and simplified policy and vulnerab } ``` +### Get host's device page URL + +Retrieves the end user url for the host's **My device** page. + +`GET /api/v1/fleet/hosts/:id/device_url` + +#### Parameters + +| Name | Type | In | Description | +| ---------- | ----------------- | ---- | ----------------------------------------------------------------------------- | +| id | integer | path | **Required**. The host's `id`. | + +#### Example + +`GET /api/v1/fleet/hosts/1/device_url` + +##### Default response + +`Status: 200` + +```json +{ + "host_id": 1, + "device_url": "example.com/device/device_id" +} +``` + --- ### Get host's mobile device management (MDM) information @@ -5269,7 +5371,7 @@ requested by a web browser. | vulnerability | string | query | The cve to filter hosts by (including "cve-" prefix, case-insensitive). | | mdm_id | integer | query | The ID of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider and URL). | | mdm_name | string | query | The name of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider). | -| mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'automatic', 'enrolled', 'pending', or 'unenrolled'. 'pending' only includes Apple (macOS, iOS, iPadOS) hosts in Apple Business Manager (ABM) that are not yet enrolled to Fleet. | +| mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'automatic', 'enrolled', 'pending', or 'unenrolled'. 'pending' only includes Apple (macOS, iOS, iPadOS) hosts in Apple Business (AB) that are not yet enrolled to Fleet. | | macos_settings | string | query | Filters the hosts by the status of the _mobile device management_ (MDM) profiles applied to hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only hosts that are "Unassigned".** | | munki_issue_id | integer | query | The ID of the _munki issue_ (a Munki-reported error or warning message) to filter hosts by (that is, filter hosts that are affected by that corresponding error or warning message). | | low_disk_space | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts with less GB of disk space available than this value. Must be a number between 1-100. | @@ -5492,7 +5594,7 @@ Retrieves a list of the configuration profiles assigned to a host. _Available in Fleet Premium_ -Sends a command to lock the specified macOS, iOS, iPadOS, Linux, or Windows host. The host is locked once it comes online. +Sends a command to lock the specified macOS, iOS, iPadOS, Linux, Windows, or Android host. The host is locked once it comes online. To lock a macOS, iOS, or iPadOS host, the host must have MDM turned on. To lock a Windows or Linux host, the host must have [scripts enabled](https://fleetdm.com/docs/using-fleet/scripts). @@ -5561,9 +5663,9 @@ To unlock an iOS or iPadOS host, the host must have MDM turned on. To unlock a W ### Wipe host -Sends a command to wipe the specified macOS, iOS, iPadOS, Windows, or Linux host. The host is wiped once it comes online. +Sends a command to wipe the specified macOS, iOS, iPadOS, Linux, Windows, or Android host. The host is wiped once it comes online. -To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on. To lock a Linux host, the host must have [scripts enabled](https://fleetdm.com/docs/using-fleet/scripts). +To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on. To wipe a Linux host, the host must have [scripts enabled](https://fleetdm.com/docs/using-fleet/scripts). To wipe an Android host, the host must be enrolled as a fully managed device. `POST /api/v1/fleet/hosts/:id/wipe` @@ -5960,15 +6062,15 @@ Grant a blocked host access for a single login. Requires Okta conditional access _Available in Fleet Premium._ -Remotely clear the passcode on an iOS/iPadOS host. Requires the host to have sent its unlock token during MDM check-in. +Remotely clear the passcode on a host. Requires iOS/iPadOS host to have sent its unlock token during MDM check-in. `POST /api/v1/fleet/hosts/:id/clear_passcode` #### Parameters -| Name | Type | In | Description | -| ----------- | ------ | ---- | ---------------------------------------------------------------------------------------------- | -| id | number | path | **Required.** The Fleet host ID of the ADE-enrolled iOS/iPadOS host to clear the passcode for. | +| Name | Type | In | Description | +| ----------- | ------ | ---- | ----------------------------------------------------------------------------------- | +| id | number | path | **Required.** The Fleet host ID of the ADE-enrolled host to clear the passcode for. | #### Example @@ -5987,6 +6089,28 @@ Remotely clear the passcode on an iOS/iPadOS host. Requires the host to have sen } ``` +### Rotate host's managed local account password + +_Available in Fleet Premium_ + +Rotates the managed local account password for a host. + +`POST /api/v1/fleet/hosts/:id/managed_account_password/rotate` + +#### Parameters + +| Name | Type | In | Description | +| ----------------------------- | ------ | ---- | -------------------------------------------------------------------------------------- | +| id | integer | path | The host ID to rotate the managed local account password for. | + +#### Example + +`POST /api/v1/fleet/hosts/123/managed_account_password/rotate` + +##### Default response + +`204` + ### Get host's managed account password Retrieves the managed account password for a macOS host. @@ -6439,7 +6563,7 @@ Returns a list of the hosts that belong to the specified label. | disable_failing_policies | boolean | query | If "true", hosts will return failing policies as 0 regardless of whether there are any that failed for the host. This is meant to be used when increased performance is needed in exchange for the extra information. | | mdm_id | integer | query | The ID of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider and URL). | | mdm_name | string | query | The name of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider). | -| mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'automatic', 'enrolled', 'pending', or 'unenrolled'. 'pending' only includes Apple (macOS, iOS, iPadOS) hosts in Apple Business Manager (ABM) that are not yet enrolled to Fleet. | +| mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'automatic', 'enrolled', 'pending', or 'unenrolled'. 'pending' only includes Apple (macOS, iOS, iPadOS) hosts in Apple Business (AB) that are not yet enrolled to Fleet. | | macos_settings | string | query | Filters the hosts by the status of the _mobile device management_ (MDM) profiles applied to hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a fleet ID filter, the results include only "Unassigned" hosts.** | | low_disk_space | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts with less GB of disk space available than this value. Must be a number between 1-100. | | macos_settings_disk_encryption | string | query | Filters the hosts by disk encryption status. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'. | @@ -7092,6 +7216,7 @@ Get status counts of a single OS settings (configuration profile) enforced on ho - [Update custom MDM setup enrollment profile](#update-custom-mdm-setup-enrollment-profile) - [Get custom MDM setup enrollment profile](#get-custom-mdm-setup-enrollment-profile) +- [Get Fleet default MDM setup enrollment profile](#get-fleet-default-mdm-setup-enrollment-profile) - [Delete custom MDM setup enrollment profile](#delete-custom-mdm-setup-enrollment-profile) - [Get Over-the-Air (OTA) enrollment profile](#get-over-the-air-ota-enrollment-profile) - [Get manual enrollment profile](#get-manual-enrollment-profile) @@ -7188,6 +7313,44 @@ Gets the custom MDM setup enrollment profile for a fleet or "Unassigned". } ``` +### Get Fleet default MDM setup enrollment profile + +_Available in Fleet Premium_ + +Gets the Fleet default MDM setup enrollment profile. This is the profile Fleet registers with Apple for devices in fleets that do not have a custom MDM setup enrollment profile uploaded. + +`GET /api/v1/fleet/enrollment_profiles/automatic/default` + +The default profile is a single profile per Fleet instance. It is shared across all fleets and all Apple Business Manager (ABM) tokens and cannot be scoped by `fleet_id`. + +If the default profile has not yet been stored (for example, on a new Fleet instance that has not completed its first automatic enrollment registration), Fleet returns the in-code defaults that will be registered on first use, and `updated_at` is `null`. + +#### Parameters + +None. + +#### Example + +`GET /api/v1/fleet/enrollment_profiles/automatic/default` + +##### Default response + +`Status: 200` + +```json +{ + "updated_at": "2026-04-04T00:00:00Z", + "enrollment_profile": { + "profile_name": "Fleet default enrollment profile", + "is_supervised": true, + "is_mdm_removable": false, + "skip_setup_items": [] + } +} +``` + +> NOTE: The `ConfigurationWebURL` and `URL` values are automatically populated by Fleet at registration time and are not included in this response. + ### Delete custom MDM setup enrollment profile _Available in Fleet Premium_ @@ -8065,7 +8228,7 @@ This endpoint returns the list of custom MDM commands that have been executed. ## Integrations - [Get Apple Push Notification service (APNs)](#get-apple-push-notification-service-apns) -- [List Apple Business Manager (ABM) tokens](#list-apple-business-manager-abm-tokens) +- [List Apple Business (AB) tokens](#list-apple-business-ab-tokens) - [List Volume Purchasing Program (VPP) tokens](#list-volume-purchasing-program-vpp-tokens) - [Get identity provider (IdP) details](#get-identity-provider-idp-details) - [Get Android Enterprise](#get-android-enterprise) @@ -8095,11 +8258,11 @@ None. } ``` -### List Apple Business Manager (ABM) tokens +### List Apple Business (AB) tokens _Available in Fleet Premium_ -`GET /api/v1/fleet/abm_tokens` +`GET /api/v1/fleet/ab_tokens` #### Parameters @@ -8107,13 +8270,47 @@ None. #### Example -`GET /api/v1/fleet/abm_tokens` +`GET /api/v1/fleet/ab_tokens` ##### Default response `Status: 200` ```json +"ab_tokens": [ + { + "id": 1, + "apple_id": "apple@example.com", + "org_name": "Fleet Device Management Inc.", + "mdm_server_url": "https://example.com/mdm/apple/mdm", + "renew_date": "2023-11-29T00:00:00Z", + "terms_expired": false, + "macos_team": { + "name": "💻 Workstations", + "id": 1 + }, + "macos_fleet": { + "name": "💻 Workstations", + "id": 1 + }, + "ios_team": { + "name": "📱🏢 Company-owned iPhones", + "id": 2 + }, + "ios_fleet": { + "name": "📱🏢 Company-owned iPhones", + "id": 2 + }, + "ipados_team": { + "name": "🔳🏢 Company-owned iPads", + "id": 3 + }, + "ipados_fleet": { + "name": "🔳🏢 Company-owned iPads", + "id": 3 + } + } +], "abm_tokens": [ { "id": 1, @@ -8174,6 +8371,7 @@ None. "id": 1, "org_name": "Fleet Device Management Inc.", "location": "https://example.com/mdm/apple/mdm", + "country_code": "us", "renew_date": "2023-11-29T00:00:00Z", "fleets": [ { @@ -11806,7 +12004,7 @@ Returns the list of Apple App Store (VPP) apps that can be added to the specifie _Available in Fleet Premium._ -Add Apple App Store or Google Play store app. Apple apps must be added in Apple Business Manager (ABM) before adding them to Fleet. +Add Apple App Store or Google Play store app. Apple apps must be added in Apple Business (AB) before adding them to Fleet. `POST /api/v1/fleet/software/app_store_apps` @@ -11822,7 +12020,7 @@ Add Apple App Store or Google Play store app. Apple apps must be added in Apple | labels_include_all | array | body | Target hosts that have all labels, specified by label name, in the array. | | labels_include_any | array | body | Target hosts that have any label, specified by label name, in the array. | | labels_exclude_any | array | form | Target hosts that don't have any label, specified by label name, in the array. | -| configuration | object | form | The Android Play Store app's managed configuration in JSON format. Currently only supported for Android. | +| configuration | object | form | The app's managed configuration. For iOS and iPadOS apps it is in XML format, and for Android Play Store apps it is in JSON format. Currently only supported for iOS, iPadOS, and Android. | Only one of `labels_include_all`, `labels_include_any` or `labels_exclude_any` can be specified. If none are specified, all hosts are targeted. @@ -11849,7 +12047,8 @@ Only one of `labels_include_all`, `labels_include_any` or `labels_exclude_any` c ```json { - "software_title_id": 123 + "software_title_id": 123, + "name": "Xcode" } ``` @@ -11859,7 +12058,8 @@ Only one of `labels_include_all`, `labels_include_any` or `labels_exclude_any` c ```json { - "software_title_id": 456 + "software_title_id": 456, + "name": "Slack" } ``` @@ -11888,7 +12088,7 @@ Modify an Apple App Store (VPP) or a Google Play app's options. | labels_include_all | array | body | Target hosts that have all labels, specified by label name, in the array. | | labels_include_any | array | body | Target hosts that have any label, specified by label name, in the array. | | labels_exclude_any | array | body | Target hosts that don't have any label, specified by label name, in the array. | -| configuration | object | body | The Android Play Store app's managed configuration in JSON format. Currently only supported for Android. | +| configuration | object | body | The app's managed configuration. For iOS and iPadOS apps it is in XML format, and for Android Play Store apps it is in JSON format. Currently only supported for iOS, iPadOS, and Android. | Only one of `labels_include_all`, `labels_include_any` or `labels_exclude_any` can be specified. If none are specified, all hosts are targeted. @@ -13284,6 +13484,7 @@ Returned when the requested name only differs from another fleet's name by lette | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | enable_end_user_authentication | boolean | If set to true, end user authentication will be required during automatic MDM enrollment of new macOS hosts. Settings for your IdP provider must also be [configured](https://fleetdm.com/guides/setup-experience#end-user-authentication). | lock_end_user_info | boolean | If set to true, end user can't edit the local account's Account Name and Full Name in macOS Setup Assistant. These fields will be locked to values from your IdP. (Default: `true`) | +| enable_managed_local_account | boolean | Whether to enforce creating managed local accounts on eligible hosts. |
diff --git a/website/config/routes.js b/website/config/routes.js index 1569da478b..7f11bda6a6 100644 --- a/website/config/routes.js +++ b/website/config/routes.js @@ -1338,7 +1338,7 @@ module.exports.routes = { 'GET /learn-more-about/setup-experience/run-script': '/guides/setup-experience', 'GET /learn-more-about/setup-experience/end-user-authentication': '/guides/setup-experience', 'GET /learn-more-about/setup-experience/bootstrap-package': '/guides/setup-experience', - 'GET /learn-more-about/built-in-variables': '/docs/configuration/yaml-files#variables', + 'GET /learn-more-about/built-in-variables': '/guides/fleet-variables', 'GET /learn-more-about/disable-entra-conditional-access': '/guides/entra-conditional-access-integration#disable', 'GET /learn-more-about/available-fma-versions': 'https://github.com/fleetdm/fleet/tree/main/ee/maintained-apps/outputs', 'GET /learn-more-about/connect-microsoft-entra': '/guides/windows-mdm-setup#step-2-connect-fleet-to-microsoft-entra-id', @@ -1348,7 +1348,8 @@ module.exports.routes = { 'GET /learn-more-about/supported-fleet-maintained-app-slugs': 'https://github.com/fleetdm/fleet/blob/main/ee/maintained-apps/outputs/apps.json', 'GET /learn-more-about/alternative-browser-host': '/guides/enroll-hosts#alternative-browser-host', 'GET /learn-more-about/deploy-self-service-to-ios': '/guides/software-self-service#deploy-self-service-on-ios-and-ipados', - 'GET /learn-more-about/android-software-managed-configuration': '/guides/install-app-store-apps#configuration', + 'GET /learn-more-about/android-software-managed-configuration': '/guides/install-app-store-apps#managed-configuration', + 'GET /learn-more-about/ios-software-managed-configuration': '/guides/install-app-store-apps#ios-and-ipados-managed-configuration', 'GET /learn-more-about/microsoft-entra-tenant-id': 'https://entra.microsoft.com/#home', 'GET /learn-more-about/recovery-lock-passwords': 'https://developer.apple.com/documentation/devicemanagement/set-recovery-lock-command', 'GET /learn-more-about/startup-security-macos': 'https://support.apple.com/guide/deployment/startup-security-dep5810e849c',