Elgato_dark/fleet
1
0
Fork 0
mirror of https://github.com/fleetdm/fleet synced 2026-04-21 13:37:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 91

Preview of v4.82.0 doc changes (#38894)

Browse source 
This PR will remain in draft as a preview of upcoming documentation
changes for 4.82.0

---------

Co-authored-by: Jordan Montgomery <elijah.jordan.montgomery@gmail.com>
Co-authored-by: Marko Lisica <83164494+marko-lisica@users.noreply.github.com>
Co-authored-by: Magnus Jensen <magnus@fleetdm.com>
Co-authored-by: Victor Lyuboslavsky <2685025+getvictor@users.noreply.github.com>
Co-authored-by: Noah Talerman <47070608+noahtalerman@users.noreply.github.com>
Co-authored-by: Dante Catalfamo <43040593+dantecatalfamo@users.noreply.github.com>
Co-authored-by: melpike <79950145+melpike@users.noreply.github.com>
Co-authored-by: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com>
Co-authored-by: Nico <32375741+nulmete@users.noreply.github.com>
Co-authored-by: Scott Gress <scottmgress@gmail.com>
This commit is contained in:
Rachael Shaw 2026-03-12 18:19:53 -05:00 committed by GitHub
parent 3ab4e37c8e
commit cc671f98c9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
15 changed files with 379 additions and 74 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
articles/enforce-os-updates.md
View file

@ -6,7 +6,11 @@ In Fleet, you can enforce OS updates on your macOS, Windows, iOS, and iPadOS hos
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.
## Fleet UI
For Android hosts, you can enforce OS updates using a configuration profile with the [`systemUpdate`](https://developers.google.com/android/management/reference/rest/v1/enterprises.policies#SystemUpdate) setting. This setting is only supported on fully-managed Android hosts (not BYO). Learn how to create a configuration profile in the [custom OS settings guide](https://fleetdm.com/guides/custom-os-settings).
## Enforce
You can enforce OS settings using the Fleet UI, Fleet API, or [Fleet's best practice GitOps](https://github.com/fleetdm/fleet-gitops).
1. Head to the **Controls** > **OS updates** tab.
@ -16,8 +20,6 @@ For Apple (macOS, iOS, and iPadOS) hosts, Apple requires that the OS version is
4. *macOS only*: check "Update new hosts to latest" if you would like hosts to automatically update to the latest OS version during automatic (ADE) enrollment, regardless of the minimum version and deadline settings.
## Fleet API
Use the [modify fleet 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`
+ `ios_updates`
@ -52,18 +54,6 @@ For macOS hosts, in Fleet, head to **Controls > OS updates** and check the **Upd
For iOS/iPadOS hosts, set a minimum version and deadline. New iOS/iPadOS hosts will always update to the latest version (not the minimum version specified). On already enrolled hosts, updates are only enforced if the host is [below the minimum version](#apple-macos-ios-and-ipados-end-user-experience).
## Windows end user experience
End users are encouraged to update Windows via the native Windows dialog.
| | Before deadline | Past deadline |
| ----------------------------------------- | ----------------| ------------- |
| End user can defer automatic restart | ✅ | ❌ |
If an end user was on vacation when the deadline passed, the end user is given a grace period (configured) before the host automatically restarts.
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).
<!--
### macOS (below version 14.0)
@ -80,6 +70,18 @@ End users are encouraged to update macOS (via [Nudge](https://github.com/macadmi
-->
## Windows
End users are encouraged to update Windows via the native Windows dialog.
| | Before deadline | Past deadline |
| ----------------------------------------- | ----------------| ------------- |
| End user can defer automatic restart | ✅ | ❌ |
If an end user was on vacation when the deadline passed, the end user is given a grace period (configured) before the host automatically restarts.
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).
<meta name="category" value="guides">
<meta name="authorGitHubUsername" value="noahtalerman">
<meta name="authorFullName" value="Noah Talerman">

2
articles/fleet-usage-statistics.md
View file

@ -41,6 +41,8 @@ Below is the JSON payload that is sent to Fleet Device Management Inc:
"aiFeaturesDisabled": true,
"maintenanceWindowsEnabled": true,
"maintenanceWindowsConfigured": true,
"oktaConditionalAccessConfigured": true,
"conditionalAccessBypassDisabled": false,
"numHostsFleetDesktopEnabled": 999,
"fleetMaintainedAppsMacOS": [
"1password/darwin",

19
articles/fleetctl.md
View file

@ -201,6 +201,25 @@ This will generate a `tar.gz` file with:
- A file containing a set of all the errors that happened in the server during the interval of time defined by the [logging_error_retention_period](https://fleetdm.com/docs/deploying/configuration#logging-error-retention-period) configuration.
- Files containing database-specific information.
### Deprecation warnings
In the v4.82.0 version of `fleetctl`, several commands and options (like `fleetctl get queries`) were deprecated in favor of newer names (like `fleetctl get reports`). Starting in v4.83.0, you will begin to see warnings whenever deprecated command or option names are used. You can enable these warnings in v4.82.0 to get a head start on updating your files. To do so, either set the `FLEET_ENABLE_LOG_TOPICS` environment variable to `deprecated-field-names`, or use the `--enable_log_topics=deprecated-field-names` option in your commands. For example:
```
> FLEET_ENABLE_LOG_TOPICS=deprecated-field-names fleetctl get queries
```
```
> export FLEET_ENABLE_LOG_TOPICS=deprecated-field-names
> fleetctl get queries
```
```
> fleetctl get queries --enable_log_topics=deprecated-field-names
```
Once the warnings become enabled by default (in v4.83.0), you can use the `FLEET_DISABLE_LOG_TOPICS` environment variable or `--enable_log_topics` command-line option to disable them.
<meta name="category" value="guides">
<meta name="authorGitHubUsername" value="noahtalerman">
<meta name="authorFullName" value="Noah Talerman">

8
articles/okta-conditional-access-integration.md
View file

@ -155,6 +155,14 @@ End users can temporarily bypass conditional access from their **My device** pag
This feature is enabled by default, but can be disabled by checking the **Disable bypass** checkbox in **Settings** > **Integrations** > **Conditional access**.
### Per-policy bypass
> **Experimental feature.** The per-policy bypass setting is experimental, and will be replaced with a reference to the policy's `critical` setting in Fleet 4.83.0. To ensure a seamless upgrade, please avoid enabling bypass for policies marked critical.
By default, all conditional access policies allow bypassing. You can control which policies allow bypass individually in **Manage automations** > **Conditional access**. Each policy with conditional access enabled has an additional checkbox to allow or disallow bypass.
If a host is failing multiple conditional access policies, the bypass option is only available if **every** failing policy allows bypass. If any one of the failing policies does not allow bypass, the end user will not see the option to bypass and must resolve the issue to regain access.
<meta name="articleTitle" value="Conditional access: Okta">
<meta name="authorFullName" value="Rachael Shaw">
<meta name="authorGitHubUsername" value="rachaelshaw">

2
articles/role-based-access.md
View file

@ -121,7 +121,7 @@ GitOps is an API-only and write-only role that can be used on CI/CD pipelines.
| View [custom variables](https://fleetdm.com/docs/rest-api/rest-api#list-custom-variables) | ✅ | ✅ | ✅ | ✅ | ✅ | |
| Create, edit, and delete custom variables | ✅ | ✅ | ✅ | ✅ | ✅ | |
\* Applies only to Fleet Premium. Technician role ([coming soon](https://github.com/fleetdm/fleet/issues/35696)).
\* Applies only to Fleet Premium
\** Applies only to [Fleet REST API](https://fleetdm.com/docs/using-fleet/rest-api)

2
articles/vulnerability-processing.md
View file

@ -70,7 +70,7 @@ To opt into this functionality, be sure to configure your Fleet server deploymen
FLEET_VULNERABILITIES_DISABLE_SCHEDULE=true
```
This will **disable** the internal scheduling mechanism for vulnerability processing (and the ability to trigger vulnerability processing via the API with `fleetctl trigger --name=vulnerabilities`).
This will **disable** the internal scheduling mechanism for vulnerability processing. You can still trigger an ad-hoc vulnerability scan using `fleetctl trigger --name=vulnerabilities`. The dedicated vulnerability processing server will pick up the request within 60 seconds.
Then externally run vulnerability processing with the same environment variables/configuration files passed to the server command:

57
articles/windows-mdm-setup.md
View file

@ -2,9 +2,9 @@
![Windows MDM setup](../website/assets/images/articles/windows-mdm-fleet-1600x900@2x.png)
To control OS settings, updates, and more on Windows hosts follow the manual enrollment instructions.
To control OS settings, updates, and more on Windows hosts, follow the manual enrollment instructions.
To use automatic enrollment (aka zero-touch) features on Windows, follow instructions to connect Fleet to Microsoft Entra ID. You can further customize zero-touch with Windows Autopilot.
To use automatic enrollment (aka zero-touch) features on Windows, follow the instructions to connect Fleet to Microsoft Entra ID. You can further customize zero-touch with Windows Autopilot.
To migrate Windows hosts from your current MDM solution to Fleet, follow the [Automatic Windows MDM migration](#automatic-windows-mdm-migration) instructions.
@ -83,7 +83,7 @@ In order to connect Fleet to Entra, the IT admin (you) needs a Microsoft Enterpr
1. Sign in to [Microsoft 365 admin center](https://admin.microsoft.com/).
2. In the left-side bar select **Marketplace**.
2. In the left-side bar, select **Marketplace**.
3. On the **Marketplace** page, select **All products** and in the search bar below **All products** enter "Enterprise Mobility + Security E3".
@ -95,11 +95,11 @@ In order to connect Fleet to Entra, the IT admin (you) needs a Microsoft Enterpr
7. Sign in to [Microsoft Entra ID portal](https://portal.azure.com).
8. At the top of the page search "Users" and select **Users**.
8. At the top of the page, search "Users" and select **Users**.
9. Select or create a test user and select **Licenses**.
10. Select **+ Assignments** and assign yourself the **Enterprise Mobility + Security E3**. Assign the test user the Intune licnese.
10. Select **+ Assignments** and assign yourself the **Enterprise Mobility + Security E3**. Assign the test user the Intune license.
### Step 2: Connect Fleet to Microsoft Entra ID
@ -107,28 +107,31 @@ The end user will see Microsoft's default initial setup. You can further simplif
Some Intune/Entra deployments enable automatic enrollment into Intune. Check to ensure **Automatic Enrollment** is not enabled, or your devices will not appear in Fleet.
In your Intune settings, select **Devices**, and under **Device onbarding**, open the **Enrollment** submenu. Select **Automatic Enrollment** and ensure both **MDM user scope** and **Windows Information Protection (WIP) user scope** are set to **None**.
In your Intune settings, select **Devices**, and under **Device onboarding**, open the **Enrollment** submenu. Select **Automatic Enrollment** and ensure both **MDM user scope** and **Windows Information Protection (WIP) user scope** are set to **None**.
1. [Sign in to Azure portal](https://fleetdm.com/sign-in-to/microsoft-automatic-enrollment-tool).
2. At the top of the page, search "Domain names" and select **Domain names**. Select **+ Add custom domain**, type your Fleet URL (e.g. fleet.acme.com), and select **Add domain**.
3. Use the information presented in Azure AD to create a new TXT/MX record with your domain registrar, then select **Verify**. If you're a managed-cloud customer, please reach out to Fleet to create a TXT/MX record for you.
4. At the top of the page, search for "Mobility" and select **Mobility (MDM and WIP)**.
5. Select **+ Add application**, then select **+ Create your own application**.
6. Enter "Fleet" as the name of your application and select **Create**.
7. Set MDM user scope to **All**, then in the Fleet UI head to **Settings** > **Integrations** > **MDM** > **Windows Enrollment** and copy the URLs on the **Microsoft Entra** page (`/settings/integrations/automatic-enrollment/windows`). Paste them in Azure AD, and select **Save**.
8. While on this same page, select the **Custom MDM application settings** link.
9. Click on the **Application ID URI** which will bring you to the **Expose an API** submenu with an edit button next to the text box.
10. Replace with your Fleet URL (e.g. fleet.acme.com) and select **Save**.
11. Select **API permissions** from the sidebar, then select **+ Add a permission**.
12. Select **Microsoft Graph**, then select **Delegated permissions**, and select **Group > Group.Read.All** and **Group > Group.ReadWrite.All** and **Add permissions**.
13. Again select **+ Add a permission** and then **Microsoft Graph** and **Application permissions**, select the following:
1. [Sign in to Microsoft Entra](https://fleetdm.com/sign-in-to/microsoft-automatic-enrollment-tool).
2. On the home page, find and copy the **Tenant ID**.
3. In Fleet, navigate to **Settings** > **Integrations** > **MDM**. Under **Windows Enrollment**, select **Connect**.
4. Under **Entra tenants**, select **Add**, paste tenant ID, and select **Add**. If you don't add the Entra Tenant ID, end users will see the "Device management could not be enabled" error, and won't be able to enroll their host.
5. Head to Entra, and on the top of the page, search "Domain names" and select **Domain names**. Select **+ Add custom domain**, type your Fleet URL (e.g. fleet.acme.com), and select **Add domain**.
6. Use the information presented in Azure AD to create a new TXT/MX record with your domain registrar, then select **Verify**. If you're a managed-cloud customer, please reach out to Fleet to create a TXT/MX record for you.
7. At the top of the page, search for "Mobility" and select **Mobility (MDM and WIP)**.
8. Select **+ Add application**, then select **+ Create your own application**.
9. Enter "Fleet" as the name of your application and select **Create**.
10. Set MDM user scope to **All**, then in Fleet head to **Settings** > **Integrations** > **MDM** > **Windows Enrollment > Edit** and copy the **MDM URLs**. Paste them in Entra, and select **Save**.
11. While on this same page, select the **Custom MDM application settings** link.
12. Click on the **Application ID URI**, which will bring you to the **Expose an API** submenu with an edit button next to the text box.
13. Replace with your Fleet URL (e.g., fleet.acme.com) and select **Save**.
14. Select **API permissions** from the sidebar, then select **+ Add a permission**.
15. Select **Microsoft Graph**, then select **Delegated permissions**, and select **Group > Group.Read.All** and **Group > Group.ReadWrite.All** and **Add permissions**.
16. Again select **+ Add a permission** and then **Microsoft Graph** and **Application permissions**, select the following:
+ Device > Device.Read.All
+ Device > Device.ReadWrite.All
+ Directory > Directory.Read.All
+ Group > Group.Read.All
+ User > User.Read.All
14. Select **Add permissions**.
15. Select **Grant admin consent for [your tenant name]**, and confirm.
17. Select **Add permissions**.
18. Select **Grant admin consent for [your tenant name]**, and confirm.
Now you're ready to automatically enroll Windows hosts to Fleet.
@ -138,13 +141,13 @@ Testing automatic enrollment requires creating a test user in Microsoft Entra ID
1. Sign in to [Microsoft Entra ID portal](https://portal.azure.com).
2. At the top of the page search "Users" and select **Users**.
2. At the top of the page, search "Users" and select **Users**.
3. Select **+ New user > Create new user**, fill out the details for your test user, and select **Review + Create > Create**.
4. Go back to **Users** and refresh the page to confirm that your test user was created.
5. Open your Windows workstation and follow the setup steps. When you reach the **How would you like to set up?** screen, select **Set up for an organization**. If your workstations has Windows 11, select **Set up for work or school**.
5. Open your Windows workstation and follow the setup steps. When you reach the **How would you like to set up?** screen, select **Set up for an organization**. If your workstations have Windows 11, select **Set up for work or school**.
6. Sign in with your test user's credentials and finish the setup steps.
@ -158,13 +161,13 @@ Testing automatic enrollment requires creating a test user in Microsoft Entra ID
1. Sign in to [Microsoft Intune](https://endpoint.microsoft.com/) using the Intune admin user from step 1.
2. In the left-side bar select **Devices > Enrollment** under **Device onboarding**. Under **Windows Autopilot** select **Deployment Profiles** to navigate to the **Windows Autopilot deployment profiles** page.
2. In the left-side bar, select **Devices > Enrollment** under **Device onboarding**. Under **Windows Autopilot** select **Deployment Profiles** to navigate to the **Windows Autopilot deployment profiles** page.
3. Select **+ Create profile > Windows PC** and follow steps to create an Autopilot profile. On the **Assignments** step, select **+ Add all devices**.
### Step 2: Register a test workstation
1. Open your test workstation and follow these [Microsoft instructions](https://learn.microsoft.com/en-us/autopilot/add-devices#desktop-hash-export) to export your workstations's device hash as a CSV. The CSV should look something like `DeviceHash_DESKTOP-2V08FUI.csv`
1. Open your test workstation and follow these [Microsoft instructions](https://learn.microsoft.com/en-us/autopilot/add-devices#desktop-hash-export) to export your workstation's device hash as a CSV. The CSV should look something like `DeviceHash_DESKTOP-2V08FUI.csv`
2. In Intune, in the left-side bar, select **Devices > Enroll devices**. Under **Windows Autopilot Deployment Program** select **Devices** to navigate to the **Windows Autopilot devices** page.
@ -188,7 +191,7 @@ Testing automatic enrollment requires creating a test user in Microsoft Entra ID
1. Wipe your test workstation.
2. After it's been wiped, open your workstation and follow the setup steps. At screen in which you're asked to sign in, you should see the title "Welcome to [your organziation]!" next to the logo you uploaded in step 4.
2. After it's been wiped, open your workstation and follow the setup steps. On the screen in which you're asked to sign in, you should see the title "Welcome to [your organization]!" next to the logo you uploaded in step 4.
## Automatic Windows MDM migration
@ -221,7 +224,7 @@ You can [track migration progress in Fleet](https://fleetdm.com/guides/mdm-migra
## Turn off Windows MDM
1. Turn off MDM for each host, by running [this script](https://github.com/fleetdm/fleet/blob/main/it-and-security/lib/windows/scripts/turn-off-mdm.ps1) from Fleet on all your Windows hosts.
1. Turn off MDM for each host by running [this script](https://github.com/fleetdm/fleet/blob/main/it-and-security/lib/windows/scripts/turn-off-mdm.ps1) from Fleet on all your Windows hosts.
2. Head to **Settings > Integrations > MDM**.
3. In the **Mobile device management (MDM)** section, select **Edit** next to "Windows MDM turned on."
4. Switch **Windows MDM on** to **Windows MDM off** and select **Save**.

2
docs/Configuration/agent-configuration.md
View file

@ -293,7 +293,7 @@ You can use Fleet to query local SQLite databases as tables. For more informatio
## script_execution_timeout
The `script_execution_timeout` allows you to change the default script execution timeout (default: `300` seconds, maximum: `3600`).
The `script_execution_timeout` allows you to change the default script execution timeout (default: `300` seconds, maximum: `18000`).
#### Example

26
docs/Configuration/fleet-server-configuration.md
View file

@ -1407,6 +1407,32 @@ and a negative value to disable storage of errors in Redis.
error_retention_period: 1h
```
### logging_enable_topics
A comma-delimited set of log topics to enable.
In Fleet v4.82.0, a number of API parameters and URLs were deprecated. Starting with version 4.83.0, Fleet server will begin logging warnings when deprecated API parameters or URLs are used. To see the warnings in v4.82.0, enable the `deprecated-field-names` topic using this setting.
- Default value: none
- Environment variable: `FLEET_LOGGING_ENABLE_TOPICS`
- Config file format:
```yaml
logging:
enable_topics: deprecated-field-names
```
### logging_disable_topics
A comma-delimited set of log topics to disable. If a topic is included in both this and the `logging_enable_topics` setting, it will be enabled.
- Default value: none
- Environment variable: `FLEET_LOGGING_DISABLE_TOPICS`
- Config file format:
```yaml
logging:
disable_topics: deprecated-field-names
```
## Filesystem
### filesystem_status_log_file

15
docs/Configuration/yaml-files.md
View file

@ -159,6 +159,7 @@ policies:
critical: false
calendar_events_enabled: false
conditional_access_enabled: true
conditional_access_bypass_enabled: true
- name: macOS - Disable guest account
description: This policy checks if the guest account is disabled.
resolution: As an IT admin, deploy a macOS, login window profile with the DisableGuestAccount option set to true.
@ -388,18 +389,18 @@ controls:
### macos_updates
- `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: `""`).
- `deadline` specifies the deadline in `YYYY-MM-DD` format. The exact deadline is set to 7PM 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
- `deadline` specifies the deadline in `YYYY-MM-DD` format; the exact deadline is set to noon local time. (default: `""`).
- `deadline` specifies the deadline in `YYYY-MM-DD` format; the exact deadline is set to 7PM local time. (default: `""`).
- `minimum_version` specifies the minimum required iOS version (default: `""`).
### ipados_updates
- `deadline` specifies the deadline in `YYYY-MM-DD` format; the exact deadline is set to noon local time. (default: `""`).
- `deadline` specifies the deadline in `YYYY-MM-DD` format; the exact deadline is set to 7PM local time. (default: `""`).
- `minimum_version` specifies the minimum required iPadOS version (default: `""`).
### windows_updates
@ -551,6 +552,7 @@ software:
path: ../lib/software/zoom-config.json
fleet_maintained_apps:
- slug: slack/darwin
version: "4.47.65"
install_script:
path: ../lib/software/slack-install-script.sh
uninstall_script:
@ -634,16 +636,17 @@ When you update an Android app's configuration via GitOps, the app's settings ar
- `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.
The fields below are all optional.
- `self_service` specifies whether end users can install from **Fleet Desktop > Self-service**.
- `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.
- `⁠version` specifies the app version. Available versions are listed in the Fleet UI under Actions > Edit software. If omitted, Fleet automatically downloads the latest version found in [the app's metadata on GitHub](https://github.com/fleetdm/fleet/tree/main/ee/maintained-apps/outputs). The `version` must be wrapped in quotes (e.g. "147.0.1") so that it is processed as a string.
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).
If the fields below are omitted, they default to values specified in [the app's metadata on GitHub](https://github.com/fleetdm/fleet/tree/main/ee/maintained-apps/outputs).
- `install_script.path` specifies the command Fleet will run on hosts to install software.
- `uninstall_script.path` is the script Fleet will run on hosts to uninstall software.

223
docs/Contributing/product-groups/software/rollback-fleet-maintained-app-version.md Normal file
View file

@ -0,0 +1,223 @@
# Fleet-maintained version caching on Fleet server
Describes how Fleet manages version caching on each Fleet instance's S3 storage.
## Summary
User can define a `version` for `fleet_maintained_apps` in the [YAML file](https://fleetdm.com/docs/configuration/yaml-files). This is currently only supported in GitOps.
| Scenario | Action | S3 cache state |
|----------|--------|----------------|
| **No `version` specified** | New version released | Download latest, keep previous (n -1), delete older (n-2) |
| **`version` specified** | New versions released | No action - keep specified version only |
| **`version` specified** | User changes `version` | Download new specified version, keep previously specified version |
| **`version` removed** | Transition to "latest mode" | Download latest, keep previously specified version |
| **After `version` removal** | New version released | Resume normal latest tracking (download latest, keep n - 1, keep n - 2) |
## Diagrams
### Scenario 1: No `version` specified
```mermaid
flowchart LR
subgraph T1["Initial state"]
direction TB
S1_title["Fleet downloads 1.0 (latest)"]
subgraph S1["S3 contents"]
S1_1["1.0 ✓<br/>(latest)"]
end
end
subgraph T2["2.0 released"]
direction TB
S2_title["Fleet downloads 2.0 (latest)"]
subgraph S2["S3 contents"]
S2_v2["2.0 ✓<br/>(latest)"]
S2_v1["1.0 ✓<br/>(kept)"]
end
end
subgraph T3["3.0 released"]
direction TB
S3_title["Fleet downloads 3.0 (latest)"]
subgraph S3["S3 contents"]
S3_v3["3.0 ✓<br/>(latest)"]
S3_v2["2.0 ✓<br/>(kept)"]
S3_v1["1.0 ✗<br/>(deleted)"]
end
end
T1 --> T2 --> T3
style S1_v1 fill:#319831
style S2_v2 fill:#319831
style S2_v1 fill:#319831
style S3_v3 fill:#319831
style S3_v2 fill:#319831
style S3_v1 fill:#CC1144
```
### Scenario 2: `version` specified
```mermaid
flowchart LR
subgraph T1["User specifies 1.0 in YAML"]
direction TB
S1_title["Fleet has 1.0 cached"]
subgraph S1["S3 contents"]
S1_v1["1.0 ✓<br/>(specified version in YAML)"]
end
end
subgraph T2["2.0, 3.0 released"]
direction TB
S2_title["Fleet does NOT download"]
subgraph S2["S3 contents"]
S2_v1["1.0 ✓<br/>(specified version in YAML)"]
S2_note["NO CHANGES"]
end
end
subgraph T3["User changes specified version to 4.0"]
direction TB
S3_title["Fleet downloads 4.0"]
subgraph S3["S3 contents"]
S3_v4["4.0 ✓<br/>(specified version in YAML)"]
S3_v1["1.0 ✓<br/>(prev specified version in YAML)"]
end
end
T1 --> T2 --> T3
style S1_v1 fill:#0F93C9
style S2_v1 fill:#0F93C9
style S2_note fill:#D07D24
style S3_v4 fill:#0F93C9
style S3_v1 fill:#319831
```
### Scenario 3: `version` removed
```mermaid
flowchart LR
subgraph T1["Before removing version from YAML"]
direction TB
S1_title["YAML: version specified to 1.0"]
subgraph S1["S3 contents"]
S1_v1["1.0 ✓<br/>(specified version in YAML)"]
end
end
subgraph T2["Version removed"]
direction TB
S2_title["Fleet downloads 4.0 (latest)"]
subgraph S2["S3 contents"]
S2_v4["4.0 ✓<br/>(latest)"]
S2_v1["1.0 ✓<br/>(prev specified version)"]
end
end
subgraph T3["v5.0 released"]
direction TB
S3_title["Fleet downloads v5.0 (latest)"]
subgraph S3["S3 contents"]
S3_v5["5.0 ✓<br/>(latest)"]
S3_v4["4.0 ✓<br/>(kept)"]
S3_v1["1.0 ✗<br/>(deleted)"]
end
end
T1 --> T2 --> T3
style S1_v1 fill:#0F93C9
style S2_v4 fill:#319831
style S2_v1 fill:#0F93C9
style S3_v5 fill:#319831
style S3_v4 fill:#319831
style S3_v1 fill:#CC1144
```
### Version caching decision flowchart
```mermaid
flowchart TD
A[New FMA version available?] -->|Yes| B{Is version<br/>specified in YAML?}
A -->|No| Z[No action needed]
B -->|No| C[Download new version]
C --> D[Keep previous version n-1]
D --> E{More than 2<br/>versions cached?}
E -->|Yes| F[Delete oldest version n-2]
E -->|No| Z
F --> Z
B -->|Yes| G{Is YAML specified version<br/>same as new?}
G -->|Yes| H[Download new YAML specified version]
H --> I[Keep previous YAML specified version]
I --> Z
G -->|No| J[No action]
J --> Z
K[YAML specified version changed?] -->|Removed| L[Download current latest]
L --> M[Keep previously specified YAML version]
M --> N[Resume track latest mode]
K -->|Changed to new version| H
style C fill:#319831
style H fill:#0F93C9
style F fill:#CC1144
style J fill:#D07D24
```
### Install and uninstall scripts
When Fleet downloads new version from the manifest, install and uninstall scripts are downloaded as well. If user use custom scripts defined through YAML, then server uses those for each new version. Let's say active scripts could be custom or ones from the manifest.
If user defines `version` for Fleet-maintained app:
- If custom scripts were active at a download time, store them together with a package and use them when user rollback to that version.
- If manifest scripts were active at a download time, store them together with a package.
### Examples
```yaml
software:
fleet_maintained_apps:
- slug: firefox/darwin
```
User adds Firefox Fleet-maintained app at some point, without specifying `version`. Each time GitOps runs, new version available in the manifest is downloaded (`147.0`) and stored to S3, while previous version (`146.0.1`) is kept as well.
↓
↓
```yaml
software:
fleet_maintained_apps:
- slug: firefox/darwin
version: "146.0" # Latest
```
Firefox is automatically updated to `147.0`, and the user found a bug, so they want to get back to the previous version. They specify `version` for `firefox`.
↓
↓
After a while, new version (`150.0.1`) is released and available in manifest. Fleet don't download this because it's not needed.
↓
↓
```yaml
software:
fleet_maintained_apps:
- slug: firefox/darwin
```
User now removes the `version` to get the latest. Fleet downloads latest version, and removes oldest version (`146.0`). So Fleet instance has 2 versions, latest (`150.0.1`) and another one that was cached before (`147.0`).
`version` is not specified so Fleet now always download the latest version of `firefox`. After next Firefox release, Fleet will download the latest, keep `n - 1` and remove `147.0`

6
docs/Contributing/reference/api-for-contributors.md
View file

@ -1393,7 +1393,7 @@ This endpoint is used to delete Android Enterprise. Once deleted, hosts that bel
### Get Android enrollment token
> **Experimental feature.** This feature is undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows.
This endpoint is used to retrieve an Android enrollment token and enrollment URL using a Fleet enroll secret which opens the Android enrollment wizard (settings app) to enroll the Android host.
This endpoint is used to retrieve an Android enrollment token and enrollment URL or QR Code contents using a Fleet enroll secret which opens the Android enrollment wizard (settings app) to enroll the Android host. The QR Code contents can only be used to trigger enrollment of an Android host that has been factory reset and is at the initial setup screen, and likewise if fully_managed is true, the host can only be enrolled at this initial setup screen.
`GET /api/v1/fleet/android_enterprise/enrollment_token`
@ -1402,6 +1402,7 @@ This endpoint is used to retrieve an Android enrollment token and enrollment URL
| Name | Type | In | Description |
|---------------|--------|-------|-----------------------------------------------------|
| enroll_secret | string | query | **Required.** The enroll secret of a team in Fleet. |
| fully_managed | bool | query | **Optional.** If set to true, creates the enrollment token with AllowPersonalUsage set to PERSONAL_USAGE_DISALLOWED |
#### Example
@ -1414,7 +1415,8 @@ This endpoint is used to retrieve an Android enrollment token and enrollment URL
```json
{
"android_enrollment_token": "OJDDNCYSEZPAUZZOXHDF",
"android_enrollment_url": "https://enterprise.google.com/android/enroll?et=OJDDNCYSEZPAUZZOXHDF"
"android_enrollment_url": "https://enterprise.google.com/android/enroll?et=OJDDNCYSEZPAUZZOXHDF",
"android_enrollment_qrcode": "{\"android.app.extra.PROVISIONING_DEVICE_ADMIN_COMPONENT_NAME\":\"com.google.android.apps.work.clouddpc\/.receivers.CloudDeviceAdminReceiver\",\"android.app.extra.PROVISIONING_DEVICE_ADMIN_SIGNATURE_CHECKSUM\":\"I9DvS1O5hXZ46mb01AlRjq4oJJGs2kuZcHvCkACEXlg\",\"android.app.extra.PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_LOCATION\":\"https:\/\/play.google.com\/managed\/downloadManagingApp?identifier=setup\",\"android.app.extra.PROVISIONING_ADMIN_EXTRAS_BUNDLE\":{\"com.google.android.apps.work.clouddpc.EXTRA_ENROLLMENT_TOKEN\":\"OJDDNCYSEZPAUZZOXHDF\"}}"
}
```

2
docs/Deploy/single-sign-on-sso.md
View file

@ -202,7 +202,7 @@ Fleet will attempt to parse SAML custom attributes with the following format:
- `FLEET_JIT_USER_ROLE_GLOBAL`: Specifies the global role to use when creating the user.
- `FLEET_JIT_USER_ROLE_TEAM_<TEAM_ID>`: Specifies fleet role for fleet with ID `<TEAM_ID>` to use when creating the user.
Currently supported values for the above attributes are: `admin`, `maintainer`, `observer`, `observer_plus` and `null`.
Currently supported values for the above attributes are: `admin`, `maintainer`, `observer`, `observer_plus`, `technician` and `null`.
A role attribute with value `null` will be ignored by Fleet. (This is to support limitations on some IdPs which do not allow you to choose what keys are sent to Fleet when creating a new user.)
SAML supports multi-valued attributes, Fleet will always use the last value.

55
docs/REST API/rest-api.md
View file

@ -510,7 +510,7 @@ Returns a list of the activities that have been performed in Fleet. For a compre
| Name | Type | In | Description |
|:--------------- |:------- |:----- |:------------------------------------------------------------|
| page | integer | query | Page number of the results to fetch. |
| per_page | integer | query | Results per page. |
| per_page | integer | query | Results per page. Maximum is 10,000 records. If no pagination parameters are specified, defaults to 10,000. |
| order_key | string | query | What to order results by. Can be any column in the `activities` table. |
| order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `"asc"` and `"desc"`. Default is `"asc"`. |
| query | string | query | Search query keywords. Searchable fields include `actor_full_name` and `actor_email`.
@ -2385,7 +2385,7 @@ _Available in Fleet Premium._
| okta_assertion_consumer_service_url | string | The assertion consumer service URL found in Okta after creating an IdP in **Security** > **Identity Providers** > **SAML 2.0 IdP** |
| okta_audience_uri | string | The audience URI found in Okta after creating an IdP in **Security** > **Identity Providers** > **SAML 2.0 IdP** |
| okta_certificate | string | The certificate provided by Okta during the **Set Up Authenticator** workflow |
| bypass_disabled | boolean | Whether to allow end users the option to bypass conditional access blocking for a single login attempt. (Default: `false`.)|
| bypass_disabled | boolean | Disables the per-policy setting to allow bypassing Okta conditional access. (Default: `false`.) |
When updating conditional access config, all `conditional_access` fields must either be empty or included in the request.
@ -2435,7 +2435,7 @@ _Available in Fleet Premium._
| Name | Type | Description |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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). |
| 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 (7PM 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`. |
<br/>
@ -2449,7 +2449,7 @@ _Available in Fleet Premium._
| Name | Type | Description |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| minimum_version | string | Hosts that belong to no team will be prompted to update when their OS is below this version. |
| deadline | string | Hosts that belong to no team will be forced to update their OS after this deadline (noon local time). |
| deadline | string | Hosts that belong to no team will be forced to update their OS after this deadline (7PM local time). |
<br/>
@ -2462,7 +2462,7 @@ _Available in Fleet Premium._
| Name | Type | Description |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| minimum_version | string | Hosts that belong to no team will be prompted to update when their OS is below this version. |
| deadline | string | Hosts that belong to no team will be forced to update their OS after this deadline (noon local time). |
| deadline | string | Hosts that belong to no team will be forced to update their OS after this deadline (7PM local time). |
<br/>
@ -5197,7 +5197,7 @@ To wipe a macOS, iOS, iPadOS, or Windows host, the host must have MDM turned on.
| ---- | ------- | ---- | ---------------------------- |
| id | integer | path | **Required**. The host's ID. |
| page | integer | query | Page number of the results to fetch.|
| per_page | integer | query | Results per page.|
| per_page | integer | query | Results per page. Maximum is 10,000 records. If no pagination parameters are specified, defaults to 10,000.|
#### Example
@ -8136,6 +8136,8 @@ _Available in Fleet Premium_
"host_count_updated_at": null,
"calendar_events_enabled": true,
"conditional_access_enabled": false,
"conditional_access_bypass_enabled": false,
"fleet_maintained": false,
"labels_include_any": ["Macs on Sonoma"],
"install_software": {
"name": "Adobe Acrobat.app",
@ -8445,7 +8447,9 @@ Only one of `labels_include_any` or `labels_exclude_any` can be specified. If ne
_Available in Fleet Premium_
> **Experimental feature**. Software related features (like install software policy automation) are undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows.
> **Experimental features.**
> + The `conditional_access_bypass_enabled` setting is experimental, and will be replaced with a reference to the policy's `critical` setting in Fleet 4.83.0. To ensure a seamless upgrade, please avoid enabling bypass for policies marked `critical`.
> + Software related features (like install software policy automation) are undergoing rapid improvement, which may result in breaking changes to the API or configuration surface. It is not recommended for use in automated workflows.
`PATCH /api/v1/fleet/teams/:team_id/policies/:policy_id`
@ -8463,6 +8467,7 @@ _Available in Fleet Premium_
| critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. |
| calendar_events_enabled | boolean | body | _Available in Fleet Premium_. Whether to trigger calendar events when policy is failing. |
| conditional_access_enabled | boolean | body | _Available in Fleet Premium_. Whether to block single sign-on for end users whose hosts fail this policy. |
| conditional_access_bypass_enabled | boolean | body | _Available in Fleet Premium_. Additional option to allow end users to bypass conditional access for this policy for a single Okta login. This setting is ignored if `conditional_access_enabled` is `false`, if Okta conditional access is not configured, or if bypass is disabled in org settings. (Default: `true`.) |
| software_title_id | integer | body | _Available in Fleet Premium_. ID of software title to install if the policy fails. Set to `null` to remove the automation. |
| script_id | integer | body | _Available in Fleet Premium_. ID of script to run if the policy fails. Set to `null` to remove the automation. |
| labels_include_any | array | form | _Available in Fleet Premium_. Target hosts that have any label, specified by label name, in the array. |
@ -8513,6 +8518,8 @@ Only one of `labels_include_any` or `labels_exclude_any` can be specified. If ne
"host_count_updated_at": null,
"calendar_events_enabled": true,
"conditional_access_enabled": false,
"conditional_access_bypass_enabled": false,
"fleet_maintained": false,
"install_software": {
"name": "Adobe Acrobat.app",
"software_title_id": 1234
@ -10261,17 +10268,27 @@ Returns information about the specified software. By default, `versions` are sor
{
"software_title": {
"id": 12,
"name": "Falcon.app",
"display_name": "Crowdstrike Falcon",
"name": "Google Chrome.app",
"display_name": "Google Chrome",
"icon_url":"/api/latest/fleet/software/titles/12/icon?team_id=3",
"display_name": "",
"bundle_identifier": "crowdstrike.falcon.Agent",
"bundle_identifier": "com.google.Chrome",
"software_package": {
"name": "FalconSensor-6.44.pkg",
"version": "6.44",
"name": "GoogleChrome.pkg",
"version": "143.0.7499.193",
"categories": ["Productivity"],
"platform": "darwin",
"fleet_maintained_app_id": 42,
"fleet_maintained_versions": [
{
"id": 1,
"version": "143.0.7499.193"
},
{
"id": 2,
"version": "142.0.7444.176"
},
],
"installer_id": 23,
"team_id": 3,
"uploaded_at": "2024-04-01T14:22:58Z",
@ -10290,7 +10307,7 @@ Returns information about the specified software. By default, `versions` are sor
"automatic_install_policies": [
{
"id": 343,
"name": "[Install software] Crowdstrike Agent",
"name": "[Install software] Crowdstrike Agent"
}
],
"status": {
@ -10308,19 +10325,19 @@ Returns information about the specified software. By default, `versions` are sor
"versions": [
{
"id": 123,
"version": "117.0",
"version": "142.0.7444.176",
"vulnerabilities": ["CVE-2023-1234"],
"hosts_count": 37
},
{
"id": 124,
"version": "116.0",
"version": "141.0.7444.170",
"vulnerabilities": ["CVE-2023-4321"],
"hosts_count": 7
},
{
"id": 127,
"version": "115.5",
"version": "138.0.7655.171",
"vulnerabilities": ["CVE-2023-7654"],
"hosts_count": 4
}
@ -12270,7 +12287,7 @@ _Available in Fleet Premium_
| Name | Type | Description |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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). |
| 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 (7PM 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`. |
<br/>
@ -12282,7 +12299,7 @@ _Available in Fleet Premium_
| Name | Type | Description |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| minimum_version | string | Hosts that belong to this team will be prompted to update when their OS is below this version. |
| deadline | string | Hosts that belong to this team will be forced to update their OS after this deadline (noon local time). |
| deadline | string | Hosts that belong to this team will be forced to update their OS after this deadline (7PM local time). |
<br/>
@ -12294,7 +12311,7 @@ _Available in Fleet Premium_
| Name | Type | Description |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| minimum_version | string | Hosts that belong to this team will be prompted to update when their OS is below this version. |
| deadline | string | Hosts that belong to this team will be forced to update their OS after this deadline (noon local time). |
| deadline | string | Hosts that belong to this team will be forced to update their OS after this deadline (7PM local time). |
<br/>

2
website/config/routes.js vendored
View file

@ -1124,7 +1124,7 @@ module.exports.routes = {
'GET /learn-more-about/chromeos-updates': 'https://support.google.com/chrome/a/answer/6220366',
'GET /learn-more-about/just-in-time-provisioning': '/docs/deploy/single-sign-on-sso#just-in-time-jit-user-provisioning',
'GET /learn-more-about/os-updates': '/docs/using-fleet/mdm-os-updates',
'GET /sign-in-to/microsoft-automatic-enrollment-tool': 'https://portal.azure.com',
'GET /sign-in-to/microsoft-automatic-enrollment-tool': 'https://entra.microsoft.com',
'GET /learn-more-about/custom-os-settings': '/docs/using-fleet/mdm-custom-os-settings',
'GET /learn-more-about/ndes': 'https://learn.microsoft.com/en-us/windows-server/identity/ad-cs/network-device-enrollment-service-overview', // TODO: Confirm URL
'GET /learn-more-about/setup-ndes': '/guides/ndes-scep-proxy',