From 967c5a258ab56864272d40438d8207a15e2a8ad1 Mon Sep 17 00:00:00 2001 From: Noah Talerman <47070608+noahtalerman@users.noreply.github.com> Date: Tue, 18 Nov 2025 09:44:46 -0500 Subject: [PATCH 1/3] [Guide updates] Only install the bootstrap package during first time Mac setup (#35823) Guide updates for the following user story: - #31292 --- articles/macos-setup-experience.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/macos-setup-experience.md b/articles/macos-setup-experience.md index b63d302ff1bc..b377816f6ac3 100644 --- a/articles/macos-setup-experience.md +++ b/articles/macos-setup-experience.md @@ -58,7 +58,7 @@ Fleet supports installing a bootstrap package on macOS hosts that automatically This enables installing tools like [Puppet](https://www.puppet.com/), [Munki](https://www.munki.org/munki/), or [Chef](https://www.chef.io/products/chef-infra) for configuration management and/or running custom scripts and installing tools like [DEP notify](https://gitlab.com/Mactroll/DEPNotify) to customize the setup experience for your end users. -The bootstrap package and Fleet's agent (fleetd) are also installed during [MDM migration](https://fleetdm.com/guides/mdm-migration) and when the enrollment profile is renewed manually by running `sudo profiles renew -type enrollment`. If you [manually install fleetd](#advanced), fleetd won't be installed. +Fleet's agent (fleetd) is also installed during [MDM migration](https://fleetdm.com/guides/mdm-migration) and when the enrollment profile is renewed manually with `sudo profiles renew -type enrollment`. If you [manually install fleetd](#advanced), fleetd won't be installed automatically. The following are examples of what some organizations deploy using a bootstrap package: From 926167cd6406faa7f80080994bd64cfdecbd11ce Mon Sep 17 00:00:00 2001 From: Noah Talerman <47070608+noahtalerman@users.noreply.github.com> Date: Tue, 18 Nov 2025 14:30:06 -0800 Subject: [PATCH 2/3] [API and YAML changes] Only enforce latest macOS version for new hosts (#35776) YAML and API changes for the following user story: - #31293 --------- Co-authored-by: Rachael Shaw --- articles/enforce-os-updates.md | 30 ++++++++++++++++++------------ docs/Configuration/yaml-files.md | 2 ++ docs/REST API/rest-api.md | 20 ++++++++++++++------ website/config/routes.js | 1 + 4 files changed, 35 insertions(+), 18 deletions(-) diff --git a/articles/enforce-os-updates.md b/articles/enforce-os-updates.md index c404b94070eb..cca01baaaa11 100644 --- a/articles/enforce-os-updates.md +++ b/articles/enforce-os-updates.md @@ -4,11 +4,9 @@ _Available in Fleet Premium_ In Fleet, you can enforce OS updates on your macOS, Windows, iOS, and iPadOS hosts remotely using the Fleet UI, Fleet API, or Fleet's GitOps workflow. -## Turning on enforcement +For Apple (macOS, iOS, and iPadOS) hosts, Apple requires that the OS version is one from the [list of available OS versions](https://gdmf.apple.com/v2/pmv). The update will only be enforced if you use a version in that list. -For Apple (macOS, iOS, and iPadOS) hosts, Apple provides a [list of available OS versions](https://gdmf.apple.com/v2/pmv) in the Apple Software Lookup Service. The update will only be enforced if you use a version in that list. - -### Fleet UI +## Fleet UI 1. Head to the **Controls** > **OS updates** tab. @@ -16,7 +14,7 @@ For Apple (macOS, iOS, and iPadOS) hosts, Apple provides a [list of available OS 3. For Windows, select **Windows** and set a **Deadline** and **Grace period**. -### Fleet API +## Fleet API Use the [modify team endpoint](https://fleetdm.com/docs/rest-api/rest-api#modify-team) to turn on minimum OS version enforcement. The relevant payload keys in the `mdm` object are: + `macos_updates` @@ -24,7 +22,7 @@ Use the [modify team endpoint](https://fleetdm.com/docs/rest-api/rest-api#modify + `ipados_updates` + `windows_updates` -### GitOps +## GitOps OS version enforcement options are declared within the [controls](https://fleetdm.com/docs/configuration/yaml-files#controls) section of a Fleet GitOps YAML file, using the following keys: + [macos_updates](https://fleetdm.com/docs/configuration/yaml-files#macos-updates) @@ -32,9 +30,7 @@ OS version enforcement options are declared within the [controls](https://fleetd + [ipados_updates](https://fleetdm.com/docs/configuration/yaml-files#ipados-updates) + [windows_updates](https://fleetdm.com/docs/configuration/yaml-files#windows-updates) -## End user experience - -### Apple (macOS, iOS, and iPadOS) +## Apple (macOS, iOS, and iPadOS) end user experience On macOS hosts, when a minimum version is enforced, end users see a native macOS notification (DDM) once per day. Users can choose to update ahead of the deadline or schedule it for that night. 24 hours before the deadline, the notification appears hourly and ignores Do Not Disturb. One hour before the deadline, the notification appears every 30 minutes and then every 10 minutes. @@ -46,9 +42,15 @@ If the host was turned off when the deadline passed, the update will be schedule If you set a past date (ex. yesterday) as the deadline, the end user will immediately be prompted to install the update. If they don't, the update will automatically install in one hour. Similarly, if you set the deadline to today, end users will experience the same behavior if it's after 12 PM (end user local time). -For hosts that use Automated Device Enrollment (ADE), if the device is below the specified minimum version, it will be required to update to the latest version during ADE before device setup and enrollment can proceed. You can find the latest version in the [Apple Software Lookup Service](https://gdmf.apple.com/v2/pmv). Apple's software updates are relatively large (up to several GBs) so ask your end users to connect to a Wi-Fi network that can handle large downloads during ADE. +### Update new hosts to latest + +You can require hosts that automatically enroll via ADE to update to the latest version before they enroll to Fleet (during Setup Assistant). + +For iOS/iPadOS hosts, set a minimum version and deadline. -### Windows +For macOS hosts, in Fleet, head to **Controls > OS updates** and check the **Update new hosts to latest** checkbox. + +## Windows end user experience End users are encouraged to update Windows via the native Windows dialog. @@ -60,6 +62,8 @@ If an end user was on vacation when the deadline passed, the end user is given a Fleet enforces OS updates for [quality and feature updates](https://github.com/fleetdm/fleet/blob/ca865af01312728997ea6526c548246ab98955fb/ee/server/service/mdm_profiles.go#L106). Microsoft provides documentation on [types of Windows updates](https://learn.microsoft.com/en-us/windows/deployment/update/get-started-updates-channels-tools#types-of-updates). + + - + diff --git a/docs/Configuration/yaml-files.md b/docs/Configuration/yaml-files.md index 2a3071791f34..026d53ea6215 100644 --- a/docs/Configuration/yaml-files.md +++ b/docs/Configuration/yaml-files.md @@ -338,6 +338,7 @@ controls: macos_updates: # Available in Fleet Premium deadline: "2024-12-31" minimum_version: "15.1" + update_new_hosts: true ios_updates: # Available in Fleet Premium deadline: "2024-12-31" minimum_version: "18.1" @@ -381,6 +382,7 @@ controls: - `deadline` specifies the deadline in `YYYY-MM-DD` format. The exact deadline is set to noon local time for hosts on macOS 14 and above, 20:00 UTC for hosts on older macOS versions. (default: `""`). - `minimum_version` specifies the minimum required macOS version (default: `""`). +- `update_new_hosts` - macOS hosts that automatically enroll (ADE) are updated to [Apple's latest version](https://fleetdm.com/guides/enforce-os-updates) during macOS Setup Assistant. For backwards compatibility, if not specified, and `deadline` and `minimum_version` are set, `update_new_hosts` is set to `true`. Otherwise, `update_new_hosts` defaults to `false`. ### ios_updates diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 66458be626c7..f8fe2818a087 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -1220,7 +1220,8 @@ None. "windows_require_bitlocker_pin": false, "macos_updates": { "minimum_version": "12.3.1", - "deadline": "2022-01-01" + "deadline": "2022-01-01", + "update_new_hosts": true }, "ios_updates": { "minimum_version": "17.0.1", @@ -1528,7 +1529,8 @@ Modifies the Fleet's configuration with the supplied information. "windows_require_bitlocker_pin": false, "macos_updates": { "minimum_version": "12.3.1", - "deadline": "2022-01-01" + "deadline": "2022-01-01", + "update_new_hosts": true }, "ios_updates": { "minimum_version": "17.0.1", @@ -2103,6 +2105,7 @@ _Available in Fleet Premium._ | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | minimum_version | string | Hosts that belong to no team and are enrolled into Fleet's MDM will be prompted to update when their OS is below this version. | | deadline | string | Hosts that belong to no team and are enrolled into Fleet's MDM will be forced to update their OS after this deadline (noon local time for hosts already on macOS 14 or above, 20:00 UTC for hosts on earlier macOS versions). | +| update_new_hosts | string | macOS hosts that automatically enroll (ADE) are updated to [Apple's latest version](https://fleetdm.com/guides/enforce-os-updates) during macOS Setup Assistant. For backwards compatibility, if not specified, and `deadline` and `minimum_version` are set, `update_new_hosts` is set to `true`. Otherwise, `update_new_hosts` defaults to `false`. |
@@ -2214,7 +2217,8 @@ _Available in Fleet Premium._ "windows_require_bitlocker_pin": false, "macos_updates": { "minimum_version": "12.3.1", - "deadline": "2022-01-01" + "deadline": "2022-01-01", + "update_new_hosts": true }, "windows_updates": { "deadline_days": 5, @@ -11453,7 +11457,8 @@ _Available in Fleet Premium_ "windows_require_bitlocker_pin": false, "macos_updates": { "minimum_version": "12.3.1", - "deadline": "2022-01-01" + "deadline": "2022-01-01", + "update_new_hosts": true }, "windows_updates": { "deadline_days": 5, @@ -11781,6 +11786,7 @@ _Available in Fleet Premium_ | --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | minimum_version | string | Hosts that belong to this team and are enrolled into Fleet's MDM will be prompted to update when their OS is below this version. | | deadline | string | Hosts that belong to this team and are enrolled into Fleet's MDM will be forced to update their OS after this deadline (noon local time for hosts already on macOS 14 or above, 20:00 UTC for hosts on earlier macOS versions). | +| update_new_hosts | string | macOS hosts that automatically enroll (ADE) are updated to [Apple's latest version](https://fleetdm.com/guides/enforce-os-updates) during macOS Setup Assistant. For backwards compatibility, if not specified, and `deadline` and `minimum_version` are set, `update_new_hosts` is set to `true`. Otherwise, `update_new_hosts` defaults to `false`. |
@@ -11861,7 +11867,8 @@ _Available in Fleet Premium_ "mdm": { "macos_updates": { "minimum_version": "12.3.1", - "deadline": "2025-04-01" + "deadline": "2025-04-01", + "update_new_hosts": true }, "ios_updates": { "minimum_version": "18.3.1", @@ -12000,7 +12007,8 @@ _Available in Fleet Premium_ "windows_require_bitlocker_pin": false, "macos_updates": { "minimum_version": "12.3.1", - "deadline": "2022-01-01" + "deadline": "2022-01-01", + "update_new_hosts": true }, "windows_updates": { "deadline_days": 5, diff --git a/website/config/routes.js b/website/config/routes.js index 5ca4c1a881fa..657278c9b102 100644 --- a/website/config/routes.js +++ b/website/config/routes.js @@ -1010,6 +1010,7 @@ module.exports.routes = { 'GET /learn-more-about/setup-experience/end-user-authentication': '/guides/macos-setup-experience#end-user-authentication', 'GET /learn-more-about/setup-experience/bootstrap-package': '/guides/macos-setup-experience#bootstrap-package', 'GET /learn-more-about/built-in-variables': '/docs/configuration/yaml-files#variables', + 'GET /learn-more-about/apple-available-os-updates': 'guides/enforce-os-updates', 'GET /learn-more-about/disable-entra-conditional-access': '/guides/entra-conditional-access-integration#disable', // Sitemap From e5c91720b20344a449f6226329d2c871df6552fc Mon Sep 17 00:00:00 2001 From: Marko Lisica <83164494+marko-lisica@users.noreply.github.com> Date: Thu, 20 Nov 2025 18:17:23 +0100 Subject: [PATCH 3/3] [YAML] Pin Fleet-maintained apps to a specific version (#35972) Related to: - #31919 --- docs/Configuration/yaml-files.md | 4 +++- website/config/routes.js | 1 + 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/Configuration/yaml-files.md b/docs/Configuration/yaml-files.md index 026d53ea6215..f7da1fa9442f 100644 --- a/docs/Configuration/yaml-files.md +++ b/docs/Configuration/yaml-files.md @@ -514,6 +514,7 @@ software: setup_experience: true fleet_maintained_apps: - slug: slack/darwin + pin_version: "4.47.59" install_script: path: ../lib/software/slack-install-script.sh uninstall_script: @@ -594,7 +595,7 @@ Currently, one app for each of an App Store app's supported platforms are added, - `fleet_maintained_apps` is a list of Fleet-maintained apps. Provide the `slug` field to include a Fleet-maintained app on a team. To find the `slug`, head to **Software > Add software** and select a Fleet-maintained app, then select **Show details**. You can also see the [list of app slugs on GitHub](https://github.com/fleetdm/fleet/blob/main/ee/maintained-apps/outputs/apps.json). -Currently, Fleet-maintained apps will be updated to the latest version published by Fleet when GitOps runs. +By default, Fleet-maintained apps will be updated to the latest version published by Fleet when GitOps runs. The below fields are all optional. @@ -602,6 +603,7 @@ The below fields are all optional. - `pre_install_query.path` is the osquery query Fleet runs before installing the software. Software will be installed only if the [query returns results](https://fleetdm.com/tables). - `post_install_script.path` is the script that, if supplied, Fleet will run on hosts after the software installs. - `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 team where they are added. +- `pin_version` specifies the version of the package that will be downloaded by Fleet. Version can be set only to the version that is available in [the app's metadata on GitHub](https://github.com/fleetdm/fleet/tree/main/ee/maintained-apps/outputs). If version isn't specified, Fleet downloads the latest version as soon as it's available in the app's metadata. The below fields are optional, and if omitted will default to values specified in [the app's metadata on GitHub](https://github.com/fleetdm/fleet/tree/main/ee/maintained-apps/outputs). diff --git a/website/config/routes.js b/website/config/routes.js index fa63443afba6..434f2cbe1669 100644 --- a/website/config/routes.js +++ b/website/config/routes.js @@ -1012,6 +1012,7 @@ module.exports.routes = { 'GET /learn-more-about/built-in-variables': '/docs/configuration/yaml-files#variables', 'GET /learn-more-about/apple-available-os-updates': 'guides/enforce-os-updates', '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', // Sitemap // =============================================================================================================