Discharge7443/fleet
1
0
Fork 0
Code Issues Pull Requests Actions 21 Packages Projects Releases Wiki Activity

v4.85.0 doc changes (#41153)

Browse Source
This commit is contained in:
Rachael Shaw
2026-05-14 17:44:17 -05:00
committed by GitHub
parent b73c8ee645
commit 2a58bbef38
16 changed files with 648 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files
articles/configure-eap-tls-wifi-android.md
+2 -2
View File
@@ -7,7 +7,7 @@ This guide walks through configuring enterprise Wi-Fi network (802.1X) with EAP-
Follow the steps below to connect your Android hosts to enterprise Wi-Fi:
1. [Add SCEP certificate authority](https://fleetdm.com/guides/connect-end-user-to-wifi-with-certificate#any-scep-simple-certificate-enrollment-protocol-ca) to Fleet
2. [Deployed SCEP certificate](https://fleetdm.com/guides/connect-end-user-to-wifi-with-certificate#android-deploy-certificate) to Android hosts.
2. [Deploy SCEP certificate](https://fleetdm.com/guides/connect-end-user-to-wifi-with-certificate#android-deploy-certificate) to Android hosts.
3. [Add Wi-Fi configuration profile](#add-a-wi-fi-configuration-profile) to Fleet.
## Add a Wi-Fi configuration profile
@@ -70,7 +70,7 @@ To check the status, go to the host and select **OS settings** in Fleet.
If the profile shows `"openNetworkConfiguration" setting couldn't apply to a host. Reason: INVALID_VALUE.` error, the certificate specified in `ClientCertKeyPairAlias` isn't available on the host. Verify the name matches the certificate in **Controls > OS settings > Certificates** and that the certificate deployed successfully.
If a Wi‑Fi configuration profile is deployed before the certificate is installed on the host, it will fail with the same error. This will be fixed in [#42405](https://github.com/fleetdm/fleet/issues/42405). In the meantime, delete and re-add the Wi‑Fi profile after the certificate is installed.
If a Wi-Fi configuration profile references a certificate that hasn't been installed yet, Fleet will automatically keep the profile pending until the certificate is installed on the host. Once the certificate is installed, Fleet will apply the Wi-Fi configuration.
## End user experience
articles/connect-end-user-to-wifi-with-certificate.md
+6 -2
View File
@@ -584,7 +584,7 @@ openssl req -new -sha256 -key /opt/company/CustomerUserNetworkAccess.key -out Cu
# Escape CSR for request
CSR=$(sed 's/$/\\n/' CustomerUserNetworkAccess.csr | tr -d '\n')
REQUEST='{ "csr": "'"${CSR}"'", "idp_oauth_url":"'"${URL}"'", "idp_token": "'"${TOKEN}"'", "idp_client_id": "'"${CLIENT_ID}"'" }'
REQUEST='{ "csr": "'"${CSR}"'", "idp_oauth_url":"'"${URL}"'", "idp_token": "'"${TOKEN}"'", "idp_client_id": "'"${CLIENT_ID}"'", "return_pem_certificate": true }'
curl 'https://<Fleet-server-URL>/api/latest/fleet/certificate_authorities/<Hydrant-CA-ID>/request_certificate' \
-X 'POST' \
@@ -596,6 +596,8 @@ curl 'https://<Fleet-server-URL>/api/latest/fleet/certificate_authorities/<Hydra
jq -r .certificate response.json > /opt/company/certificate.pem
```
By default, the `certificate` field in the response is a PEM-encoded PKCS7 envelope, not a standard `x509` certificate. The script above passes `"return_pem_certificate": true` so Fleet returns a `-----BEGIN CERTIFICATE-----` block that can be written directly to `certificate.pem`.
This script assumes that your company installs a custom Company Portal app or something similar at `/opt/company`, gathers the user's IdP session information, uses username and a password to protect the private key from `/opt/company/userinfo`, and installs the certificate in `/opt/company`. You will want to modify it to match your company's requirements.
For simplicity, the scripts use a `userinfo` file (below). However, the best practice is to load variables from the output of a command or even a separate network request:
@@ -908,7 +910,7 @@ openssl req -new -sha256 -key /opt/company/CustomerUserNetworkAccess.key -out Cu
# Escape CSR for request
CSR=$(sed 's/$/\\n/' CustomerUserNetworkAccess.csr | tr -d '\n')
REQUEST='{ "csr": "'"${CSR}"'", "idp_oauth_url":"'"${URL}"'", "idp_token": "'"${TOKEN}"'", "idp_client_id": "'"${CLIENT_ID}"'" }'
REQUEST='{ "csr": "'"${CSR}"'", "idp_oauth_url":"'"${URL}"'", "idp_token": "'"${TOKEN}"'", "idp_client_id": "'"${CLIENT_ID}"'", "return_pem_certificate": true }'
curl 'https://<Fleet-server-URL>/api/latest/fleet/certificate_authorities/<EST-CA-ID>/request_certificate' \
-X 'POST' \
@@ -920,6 +922,8 @@ curl 'https://<Fleet-server-URL>/api/latest/fleet/certificate_authorities/<EST-C
jq -r .certificate response.json > /opt/company/certificate.pem
```
By default, the `certificate` field in the response is a PEM-encoded PKCS7 envelope, not a standard `x509` certificate. The script above passes `"return_pem_certificate": true` so Fleet returns a `-----BEGIN CERTIFICATE-----` block that can be written directly to `certificate.pem`.
This script assumes that your company installs a custom Company Portal app or something similar at `/opt/company`, gathers the user's IdP session information, uses username and a password to protect the private key from `/opt/company/userinfo`, and installs the certificate in `/opt/company`. You will want to modify it to match your company's requirements.
For simplicity, the scripts use a `userinfo` file (below). However, the best practice is to load variables from the output of a command or even a separate network request:
articles/deploy-software-packages.md
+4 -4
View File
@@ -107,8 +107,8 @@ Once the package is installed, Fleet will automatically refetch the host's vital
## Edit the package
* Navigate to the **Software** page, choose a fleet, and select the software you want to edit.
* Use a dropdown above the table to filter software **Available for install** or software available in **Self-service**.
* Navigate to the **Software** page, choose a fleet, and select the **Library** tab.
* Select the software you want to edit.
* On the **Software details** page select **Actions > Edit software** to edit the software's [self-service](https://fleetdm.com/guides/software-self-service) status, change its target to different sets of hosts, or edit advanced options like pre-install query, install script, post-install script, and uninstall script.
* Select **Actions > Edit appearance** to edit the software's icon and display name. The icon and display name can be edited for software that is available for install. The new icon and display name will appear on the software list and details pages for the fleet where the package is uploaded, as well as on **My device > Self-service**. If the display name is not set, then the default name (ingested by osquery) will be used.
@@ -127,8 +127,8 @@ After a software package is installed on a host, it can be uninstalled on the ho
## Delete the package
* Navigate to the **Software** page, choose a fleet, and select the software you want to edit.
* Use the dropdown above the table to filter software **Available for install** or software available in **Self-service**.
* Navigate to the **Software** page, choose a fleet, and select the **Library** tab.
* Select the software you want to delete.
* On the **Software details** page, select the **Delete** icon next to the uploaded package file.
> Deleting a software package from a fleet will cancel pending installs for hosts that are not in the middle of installing the software, but will not uninstall the software from hosts where it is already installed.
articles/enforce-disk-encryption.md
+2 -2
View File
@@ -34,11 +34,11 @@ In the Fleet UI, head to the **Controls > OS settings > Disk encryption** tab. Y
* Verified: the host turned disk encryption on and sent their key to Fleet, and Fleet has verified the key with osquery. The [encryption key can be viewed within Fleet](#view-disk-encryption-key).
* Verifying: the host acknowledged the MDM command to install the disk encryption profile. Fleet is verifying with osquery and retrieving the disk encryption key.
* Verifying: the host acknowledged the MDM command to install the disk encryption profile. Fleet is verifying with osquery and retrieving the disk encryption key. On Windows, this means the encryption key has been escrowed to Fleet but disk encryption may still be physically completing in the background. The host will transition to "Verified" once osquery confirms encryption is complete and BitLocker protection is active.
> It may take up to two hours for Fleet to collect and store the disk encryption keys from all hosts.
* Action required (pending): the end user must take action to turn disk encryption on or reset their disk encryption key.
* Action required (pending): the end user must take action to turn disk encryption on or reset their disk encryption key. On Windows, this status also appears when the disk is encrypted and the key is escrowed but BitLocker protection is off (e.g., suspended for a BIOS update or due to a TPM configuration issue).
* Enforcing (pending): the host will receive the MDM command to install the configuration profile when the host comes online.
articles/enroll-hosts.md
+2 -5
View File
@@ -41,8 +41,7 @@ The `--type` flag is used to specify the fleetd installer type.
- macOS: `pkg`
- Generating a .pkg on Linux requires [Docker](https://docs.docker.com/get-docker) to be installed and running.
- Windows: `msi`
- Generating a .msi on Windows, Intel Macs, or Linux requires [Docker](https://docs.docker.com/get-docker) to be installed and running. On Windows, you can [use WiX without Docker instead](https://fleetdm.com/guides/enroll-hosts#generating-fleetd-for-windows-using-local-wix-toolset).
- Generating a .msi on Apple Silicon Macs requires [Wine](https://fleetdm.com/install-wine) to be installed.
- Generating a .msi on Windows, macOS, or Linux requires [Docker](https://docs.docker.com/get-docker) to be installed and running. On Windows, you can [use WiX without Docker instead](https://fleetdm.com/guides/enroll-hosts#generating-fleetd-for-windows-using-local-wix-toolset).
- Linux: `deb`, `rpm`, or `pkg.tar.zst`
- `deb`: Debian-based linux (e.g. Ubuntu, Debian).
- `rpm`: RPM-based linux (e.g. OpenSUSE, Red Hat, Fedora).
@@ -462,7 +461,7 @@ System keystore access can be disabled via `--disable-keystore` flag for the `fl
`Applies only to Fleet Premium`
When generating Fleet's agent (fleetd) for Windows hosts (**.msi**) on a Windows or macOS machine, you can tell `fleetctl package` to
When generating Fleet's agent (fleetd) for Windows hosts (**.msi**) on a Windows machine, you can tell `fleetctl package` to
use local installations of the 3 WiX v3 binaries used by this command (`heat.exe`, `candle.exe`, and
`light.exe`) instead of those in a pre-configured container, which is the default behavior. To do
so:
@@ -474,8 +473,6 @@ so:
fleetctl package --type msi --fleet-url=[YOUR FLEET URL] --enroll-secret=[YOUR ENROLL SECRET] --local-wix-dir "\Users\me\AppData\Local\Temp\wix311-binaries"
```
>**Note:** Creating a fleetd agent for Windows (.msi) on macOS also requires Wine. We've built a [Wine installation script](https://fleetdm.com/install-wine) to help you get it.
### Config-less fleetd agent deployment
Config-less deployment allows for Fleet's agent (fleetd) to be installed without embedding configuration settings directly into the package. This approach is ideal for environments requiring flexibility in managing enroll secrets and server URLs. For detailed instructions, visit the [Config-less fleetd agent deployment guide](https://fleetdm.com/guides/config-less-fleetd-agent-deployment).
articles/fleet-usage-statistics.md
+7
View File
@@ -47,7 +47,14 @@ Below is the JSON payload that is sent to Fleet Device Management Inc:
"conditionalAccessBypassDisabled": false,
"conditionalAccessEnabled": true,
"numHostsFleetDesktopEnabled": 999,
"numFleetsManagedAdminAccountEnabled": 999,
"anyFleetRecoveryLockPasswordEnabled": true,
"gitOpsModeEnabled": true,
"gitOpsModeExceptions": [
"labels",
"software",
"secrets"
],
"fleetMaintainedAppsMacOS": [
"1password/darwin",
"slack/darwin",
articles/lock-wipe-hosts.md
+19
View File
@@ -75,6 +75,25 @@ For macOS hosts, Fleet uses Erase All Content and Settings (EACS) with the [defa
If an iPhone/iPad is turned off or restarted while locked, it will disconnect from Wi-Fi and can't be unlocked remotely. Connect your iPhone/iPad to your Mac with a USB and [share the network](https://support.apple.com/en-gb/guide/mac-help/mchlp1540/mac). After connecting your iPhone/iPad to the internet, in Fleet, head to the **Host details** page and select **Actions > Unlock**.
## Clear passcode on iOS/iPadOS host
You can remotely clear the passcode on an iOS or iPadOS host to help end users who have forgotten their passcode.
> Clear passcode is only available for company-owned or manually enrolled iOS/iPadOS hosts. It is not available for hosts with a personal MDM enrollment status, or hosts that are in Lost Mode or pending wipe.
1. Navigate to the **Hosts** page by clicking the "Hosts" tab in the main navigation header. Find the iOS or iPadOS device you want to clear the passcode for. You can search by name, hostname, UUID, serial number, or private IP address in the search box in the upper right corner.
2. Click the host to open the **Host details** page.
3. Click the **Actions** dropdown, then click **Clear passcode**.
4. A confirmation dialog will appear. Click **Clear passcode** to confirm.
The clear passcode activity will be logged in the host's activity feed.
You can also clear the passcode using the [REST API](https://fleetdm.com/docs/rest-api/rest-api#clear-iosipados-host-passcode):
```shell
POST /api/v1/fleet/hosts/:id/clear_passcode
```
## Lock and wipe using `fleetctl`
You can lock, unlock, and wipe hosts using Fleet's command-line tool `fleetctl`:
articles/role-based-access.md
+2 -2
View File
@@ -55,7 +55,7 @@ GitOps is an API-only and write-only role that can be used on CI/CD pipelines.
| Transfer hosts between fleets\* | | | | ✅ | ✅ | ✅ |
| Add user information from IdP to hosts\* | | | | ✅ | ✅ | |
| Create, edit, and delete labels | | | ✅ | ✅ | ✅ | ✅ |
| View all software | ✅ | ✅ | ✅ | ✅ | ✅ | |
| View all software | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Add, edit, and delete software | | | | ✅ | ✅ | ✅ |
| Download added software | | | ✅ | ✅ | ✅ | |
| Install/uninstall software on hosts | | | ✅ | ✅ | ✅ | |
@@ -154,7 +154,7 @@ Users can be assigned to multiple fleets, and can have different roles for each
| Create and edit self-authored labels | | | ✅ | ✅ | ✅ | ✅ |
| Add and delete hosts | | | | ✅ | ✅ | |
| Transfer hosts between fleets\* | | | | ✅ | ✅ | ✅ |
| View software | ✅ | ✅ | ✅ | ✅ | ✅ | |
| View software | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Add, edit, and delete software | | | | ✅ | ✅ | ✅ |
| Download added software | | | ✅ | ✅ | ✅ | |
| Install/uninstall software on hosts | | | ✅ | ✅ | ✅ | |
articles/setup-experience.md
+18
View File
@@ -36,6 +36,24 @@ You can enforce end user authentication during automatic enrollment (ADE) for Ap
> (SSO)](https://fleetdm.com/docs/deploy/single-sign-on-sso) in Fleet, you still want to create a
> new SAML app for end user authentication. This way, only Fleet users can log in to Fleet.
## Managed local account
Fleet can create a hidden admin account (`_fleetadmin`) with a unique password on each macOS host during Setup Assistant. IT admins can use this account as a break-glass login for troubleshooting.
This feature is available for macOS hosts that automatically enroll via Apple Business (AB). Manually enrolled hosts are not supported.
To enable managed local accounts:
1. In Fleet, head to **Controls > Setup experience > Users** and check **Managed local account**. Alternatively, you can enable this using [Fleet's REST API](https://fleetdm.com/docs/rest-api/rest-api#update-setup-experience) or [GitOps workflow](https://github.com/fleetdm/fleet-gitops).
2. Wipe and re-enroll any existing macOS hosts that should receive the account. Hosts enrolled before the feature is turned on won't receive a managed account until they go through Setup Assistant again.
To view the password for a host's managed account, head to **Host details > Actions > Show managed account**. The password is unique per host and stored securely in Fleet.
> The managed account is hidden from the macOS login window. To log in as `_fleetadmin`, click **Other** on the login window (or press the username field) and type the username and password manually.
> The managed account does not have a Secure Token. To access a FileVault-encrypted disk, first unlock it using the [escrowed recovery key](https://fleetdm.com/guides/macos-mdm-setup#disk-encryption), then log in as `_fleetadmin` at the login window.
## Platform SSO
Fleet supports configuring Platform SSO (PSSO) for macOS hosts with the option to create a local user account during enrollment. If you use Okta, see [Deploying Okta Platform SSO with Fleet](https://fleetdm.com/guides/deploying-okta-platform-sso-with-fleet) for setup instructions. PSSO can be used with or without [end user authentication](#end-user-authentication) enabled.
articles/software-self-service.md
+1 -1
View File
@@ -24,7 +24,7 @@ You can also add the software and later make it available in self-service:
1. Select the fleet to which you added the software from the dropdown in the upper left corner of the page.
2. Select **Software** in the main navigation menu.
3. Select the **All software** dropdown and choose **Available for install.** This filters the results in the table to show only software that can be installed on hosts. If you don’t see your software, page through the results or search for your software's name in the search bar. Once you find the software, select its title.
3. Select the **Library** tab to view software available for install. Select the software you want to make available in self-service.
4. Select the pencil (edit) icon and check **Self-service** in the **Options** section. You can also assign categories and add a custom icon. Icons appear on the **My device > Self-service** page. Custom icons are only available for [custom packages](https://fleetdm.com/guides/deploy-software-packages) and [app store apps](https://fleetdm.com/guides/install-app-store-apps).
5. Select the **Save** button.
docs/Configuration/yaml-files.md
+35 -4
View File
@@ -519,12 +519,15 @@ The `setup_experience` section lets you control the out-of-the-box [setup experi
- `bootstrap_package` is the URL to a bootstrap package. Fleet will download the bootstrap package. Applies to macOS only (default: `""`).
- `macos_manual_agent_install` specifies whether Fleet's agent (fleetd) will be installed as part of setup experience. Applies to macOS only (default: `false`)
- `enable_end_user_authentication` specifies whether or not to require end user authentication when the user first sets up their host. Applies to macOS, Windows, Linux, iOS/iPadOS, and Android.
- `enable_end_user_authentication` specifies whether or not to require end user authentication when the user first sets up their host. Applies to macOS, Windows, Linux, iOS/iPadOS, and Android.
- `require_all_software_macos` specifies whether to cancel setup on a macOS host if any software installs fail.
- `require_all_software_windows` specifies whether to cancel setup on a Windows host if any software installs fail.
- `lock_end_user_info` specifies whether or not to enable end user to edit the local account Account Name and Full Name in macOS Setup Assistant. (default: `true`)
- `require_all_software` specifies whether to cancel setup on a macOS host if any software installs fail.
- `apple_enable_release_device_manually` when enabled, you're responsible for sending the [`DeviceConfigured` command](https://developer.apple.com/documentation/devicemanagement/device-configured-command). End users will be stuck in Setup Assistant until this command is sent. Applies to Apple (macOS, iOS, iPadOS) hosts that automatically enroll via Apple Business Manager (ABM).
- `apple_setup_assistant` is a path to a custom [automatic enrollment (ADE) profile](https://support.apple.com/guide/deployment/automated-device-enrollment-management-dep73069dd57/web) (.json). Applies to macOS and iOS/iPadOS hosts.
- `script` is the path to a custom setup script to run after the host is first set up. Applies to macOS only.
- `macos_script` is the path to a custom setup script to run after the host is first set up. Applies to macOS only.
- `enable_managed_local_account` specifies whether or not to create a local admin managed account on macOS hosts (default: `false`).
- `end_user_local_account_type` specifies the end user account type. `enable_managed_local_account` must be set to `true`. (default: `admin`).
#### Example
@@ -615,6 +618,11 @@ software:
categories:
- Communication
- Productivity
- slug: parallels/darwin
version: "^26"
self_service: true
labels_include_any:
- Engineering
```
#### self_service, labels, categories, and setup_experience
@@ -634,6 +642,7 @@ software:
- `url` specifies the URL at which the software is located. Fleet will download the software and upload it to S3 (up to 3 attempts). If you don't want to host the package, add it to Fleet first and then copy the `hash_sha256`.
- `hash_sha256` specifies the SHA256 hash of the package file. If provided, and a package with that hash was already added to Fleet, the download will be skipped. This speeds up GitOps runs. If a package with that hash doesn't exist in Fleet, Fleet will download the package from the `url` and add the package if the hash matches. Fleet will error if the hash doesn't match. You can specify `hash_sha256` without `url` if the package was already added to Fleet via the UI or the API.
- `always_download` disables conditional HTTP downloads using ETag headers. By default (`false`), Fleet stores the ETag from the download response and sends it as `If-None-Match` on subsequent GitOps runs. If the server returns 304 Not Modified, the download is skipped entirely. Set to `true` to force Fleet to re-download the package on every GitOps run. Cannot be used together with `hash_sha256` (hash-pinned packages are already cached by hash). Not all servers support ETags correctly; if your download URL returns unreliable ETags, set `always_download: true`.
- `display_name` is the package name that will be displayed in the UI. If not set, `name` will be used instead.
- `pre_install_query.path` is the SQL query Fleet runs before installing the software. Software will be installed only if the [query returns results](https://fleetdm.com/tables).
- `install_script.path` specifies the command Fleet will run on hosts to install software. The [default script](https://github.com/fleetdm/fleet/tree/main/pkg/file/scripts) is dependent on the software type (i.e. .pkg). Not supported for `.sh` and `.ps1` files.
@@ -666,6 +675,19 @@ You can view the hash for existing software in the software detail page in the F
- hash_sha256: fd22528a87f3cfdb81aca981953aa5c8d7084581b9209bb69abf69c09a0afaaf
```
##### Conditional downloads
By default, Fleet uses conditional HTTP downloads to avoid re-downloading unchanged packages. On the first GitOps run, Fleet downloads the package normally and stores the server's ETag. On subsequent runs, Fleet sends a conditional GET request. If the server confirms the content hasn't changed (304 Not Modified), the download is skipped.
If your server doesn't support ETags reliably, you can disable this behavior with `always_download: true`:
```yaml
- url: https://dl.tailscale.com/stable/tailscale-setup-1.72.0.exe
always_download: true
```
> Note: Conditional download is currently unsupported for .ipa files.
##### Script-only
Script-only packages (`.sh` and `.ps1` files) are created by referencing a script file in the fleet YAML file. Currently, script-only packages don't support `install_script`, `uninstall_script`, `post_install_script`, `pre_install_query`, or automatic install (`install_software` in policies).
@@ -715,6 +737,7 @@ The fields below are all optional.
- `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 fleet 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 [Fleet's catalog](https://fleetdm.com/software-catalog). The `version` must be wrapped in quotes (e.g. "147.0.1") so that it is processed as a string.
- To pin to the major version, use a caret (`^`) constraint. You can specify only the major version, without the minor and patch versions. For example, `"⁠^147"` means that Fleet will continuously download the latest version until the app updates to 148.0.
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).
@@ -732,6 +755,11 @@ The `features` section of the configuration YAML lets you turn on/off Fleet feat
- `additional_queries` adds extra host details. This information will be updated at the same time as other host details and is returned by the API when host objects are returned (default: empty).
- `enable_host_users` specifies whether or not Fleet collects user data from hosts (default: `true`).
- `enable_software_inventory` specifies whether or not Fleet collects software inventory from hosts (default: `true`).
- `historical_data` controls per-dataset collection of the data that drive the dashboard charts. Each sub-key defaults to `true`:
- `uptime` — host activity samples that drive the **Hosts active** dashboard chart.
- `vulnerabilities` — per-host software vulnerability data that drive the **Vulnerability exposure** dashboard chart.
A dataset is collected for a given host only when the sub-key is `true` at both the global level (`org_settings.features.historical_data`) and the host's fleet level (`settings.features.historical_data`). Setting a sub-key to `false` at either level disables collection for the affected hosts. Flipping the global sub-key off disables it for every fleet, regardless of per-fleet settings.
Can be configured for "All fleets" (`org_settings`) and specific fleets (`settings`).
@@ -745,6 +773,9 @@ org_settings:
macs: SELECT mac FROM interface_details
enable_host_users: true
enable_software_inventory: true
historical_data:
uptime: true
vulnerabilities: false
```
### fleet_desktop
@@ -1191,7 +1222,7 @@ org_settings:
The `end_user_authentication` section lets you define the identity provider (IdP) settings used for [end user authentication](https://fleetdm.com/guides/setup-experience#end-user-authentication) during Automated Device Enrollment (ADE).
Once the IdP settings are configured, you can use the [`controls.setup_experience.enable_end_user_authentication`](#macos-setup) key to control the end user experience during ADE.
Once the IdP settings are configured, you can use the [`controls.setup_experience.enable_end_user_authentication`](#setup-experience) key to control the end user experience during ADE.
- `idp_name` is the human-friendly name for the identity provider that will provide single sign-on authentication (default: `""`).
- `entity_id` is the entity ID: a Uniform Resource Identifier (URI) that you use to identify Fleet when configuring the identity provider. It must exactly match the Entity ID field used in identity provider configuration (default: `""`).
docs/Contributing/architecture/mdm/apple-declarative-device-management.md
+9 -1
View File
@@ -129,7 +129,15 @@ The profiles names must be unique across all platforms and profile types for a g
* As mentioned earlier, label restrictions (include any, include all and exclude any) are supported for DDM profiles, same as for other types of profiles.
* Fleet secrets [are supported](https://github.com/fleetdm/fleet/blob/bd027dc4210b113983c3133251b51754e7d24c6f/server/service/apple_mdm.go#L885-L888) and are expanded with their values when the declaration is sent to the host.
* Fleet _variables_ [are **not** supported](https://github.com/fleetdm/fleet/blob/bd027dc4210b113983c3133251b51754e7d24c6f/server/service/apple_mdm.go#L948-L953) for DDM.
* The following Fleet _variables_ are supported for DDM:
- `$FLEET_VAR_HOST_HARDWARE_SERIAL`
- `$FLEET_VAR_HOST_END_USER_IDP_USERNAME`
- `$FLEET_VAR_HOST_END_USER_IDP_USERNAME_LOCAL_PART`
- `$FLEET_VAR_HOST_END_USER_IDP_GROUPS`
- `$FLEET_VAR_HOST_END_USER_IDP_DEPARTMENT`
- `$FLEET_VAR_HOST_END_USER_IDP_FULL_NAME`
- `$FLEET_VAR_HOST_UUID`
- `$FLEET_VAR_HOST_PLATFORM`
* DDM profiles [cannot include OS updates settings](https://github.com/fleetdm/fleet/blob/bd027dc4210b113983c3133251b51754e7d24c6f/server/fleet/apple_mdm.go#L670-L672), as those are handled by Fleet via the "Controls -> OS updates" settings.
* DDM profiles [cannot be of a type that requires assets](https://github.com/fleetdm/fleet/blob/bd027dc4210b113983c3133251b51754e7d24c6f/server/fleet/apple_mdm.go#L674-L676), as assets are currently not supported.
* DDM profiles [cannot have a "status subscription" type](https://github.com/fleetdm/fleet/blob/bd027dc4210b113983c3133251b51754e7d24c6f/server/fleet/apple_mdm.go#L678-L680).
docs/Contributing/product-groups/software/rollback-fleet-maintained-app-version.md
+91 -24
View File
@@ -137,37 +137,104 @@ flowchart LR
style S3_v1 fill:#CC1144
```
### Scenario 4: `version` with caret (`^`) constraint - pin major version
```mermaid
flowchart LR
subgraph T1["Initial state"]
direction TB
S1_title["Fleet downloads 25.26.72 (latest)"]
subgraph S1["S3 contents"]
S1_v1["25.26.72 ✓<br/>(latest)"]
end
end
subgraph T2["25.27.73 released"]
direction TB
S2_title["Fleet downloads 25.27.73 (latest)"]
subgraph S2["S3 contents"]
S2_v2["25.27.73 ✓<br/>(latest)"]
S2_v1["25.26.72 ✓<br/>(kept)"]
end
end
subgraph T3["User specifies ^25 in YAML"]
direction TB
S3_title["No download"]
subgraph S3["S3 contents"]
S3_v2["25.27.73 ✓<br/>(within ^25 constraint)"]
S3_v1["25.26.72 ✓<br/>(within ^25 constraint)"]
S3_note["NO CHANGES"]
end
end
subgraph T4["25.36.31 released"]
direction TB
S4_title["Fleet downloads 25.36.31 (within ^25)"]
subgraph S4["S3 contents"]
S4_v3["25.36.31 ✓<br/>(latest, within ^25)"]
S4_v2["25.27.73 ✓<br/>(within ^25 constraint)"]
S4_v1["25.26.72 ✗<br/>(deleted)"]
end
end
subgraph T5["26.1.58 released"]
direction TB
S5_title["Fleet does NOT download (outside ^25)"]
subgraph S5["S3 contents"]
S5_v3["25.36.31 ✓<br/>(within ^25 constraint)"]
S5_v2["25.27.73 ✓<br/>(within ^25 constraint)"]
S5_note["NO CHANGES"]
end
end
T1 --> T2 --> T3 --> T4 --> T5
style S1_v1 fill:#319831
style S2_v2 fill:#319831
style S2_v1 fill:#319831
style S3_v2 fill:#0F93C9
style S3_v1 fill:#0F93C9
style S3_note fill:#D07D24
style S4_v3 fill:#0F93C9
style S4_v2 fill:#0F93C9
style S4_v1 fill:#CC1144
style S5_v3 fill:#0F93C9
style S5_v2 fill:#0F93C9
style S5_note fill:#D07D24
```
### 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
flowchart TB
A["New Fleet-maintained app version available in Fleet manifest"] -- Yes --> B["Is 'version'<br>specified for Fleet-maintained app?"]
B -- No --> C["Download new version"]
C --> D["Keep previous version in S3"]
D --> E{"More than 2<br>versions stored?"}
E -- Yes --> F["Delete oldest version"]
E -- No --> Z[/"End"/]
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]
B -- Yes --> BC["Does 'version' include caret (^) constraint?"]
BC -- Yes --> BCC{"Is new version below<br>next major version?"}
BCC -- Yes --> H["Download new version"]
BCC -- No --> J["No action"]
BC -- No --> G["Is specified 'version'<br>same as new?"]
G -- Yes --> H
H --> I["Keep previously specified version"]
I --> Z
G -->|No| J[No action]
G -- No --> J
J --> Z
K["Specified 'version' changed?"] -- Removed --> L["Download latest from manifest"]
L --> M["Keep previously specified version"]
M --> N["Resume automatic download of latest version"]
K -- Changed to new version --> H
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
style C fill:#00C853
style F fill:#FF6D00
style BCC fill:#BBDEFB
style H fill:#00C853
style J fill:#FFD600
```
### Install and uninstall scripts
docs/Contributing/reference/audit-logs.md
+119 -1
View File
@@ -946,6 +946,44 @@ This activity contains the following fields:
}
```
## enabled_historical_dataset
Generated when collection of a chart historical dataset is enabled, either globally or for a specific fleet.
This activity contains the following fields:
- "dataset": The public config sub-key of the dataset. One of `"uptime"`, `"vulnerabilities"`.
- "fleet_id": The ID of the fleet the toggle applies to, `null` if applied globally.
- "fleet_name": The name of the fleet the toggle applies to, `null` if applied globally.
#### Example
```json
{
"dataset": "uptime",
"fleet_id": 2,
"fleet_name": "EMEA"
}
```
## disabled_historical_dataset
Generated when collection of a chart historical dataset is disabled, either globally or for a specific fleet.
This activity contains the following fields:
- "dataset": The public config sub-key of the dataset. One of `"uptime"`, `"vulnerabilities"`.
- "fleet_id": The ID of the fleet the toggle applies to, `null` if applied globally.
- "fleet_name": The name of the fleet the toggle applies to, `null` if applied globally.
#### Example
```json
{
"dataset": "vulnerabilities",
"fleet_id": 2,
"fleet_name": "EMEA"
}
```
## added_bootstrap_package
Generated when a user adds a new bootstrap package to a team (or no team).
@@ -2524,6 +2562,55 @@ This activity contains the following fields:
}
```
## enabled_managed_local_account
Generated when a user turns on create managed local account for a fleet (or unassigned hosts).
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"
}
```
## disabled_managed_local_account
Generated when a user turns off create managed local account for a fleet (or unassigned hosts).
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"
}
```
## read_managed_local_account
Generated when a user reads the information for the local managed account for a host.
This activity contains the following fields:
- "host_id": ID of the host.
- "host_display_name": Display name of the host.
```json
{
"host_id": 1,
"host_display_name": "Anna's MacBook Pro"
}
```
## resent_certificate
Generated when a user resends a certificate to a host.
@@ -2534,7 +2621,6 @@ This activity contains the following fields:
- "certificate_template_id": The ID of the certificate template
- "certificate_name": The name of the certificate
#### Example
```json
@@ -2546,6 +2632,21 @@ This activity contains the following fields:
}
```
## cleared_passcode
Generated when a user clears the passcode on a host.
This activity contains the following fields:
- "host_id": ID of the host.
- "host_display_name": Display name of the host.
```json
{
"host_id": 1,
"host_display_name": "Anna's MacBook Pro"
}
```
## canceled_setup_experience
Generated when macOS setup experience is canceled due to software install failure.
@@ -2567,6 +2668,23 @@ This activity contains the following fields:
}
```
## created_managed_local_account
Generated when a local managed account and password is created for a host.
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"
}
```
<meta name="title" value="Audit logs">
<meta name="pageOrderInSection" value="1400">
docs/Get started/FAQ.md
+1 -1
View File
@@ -78,7 +78,7 @@ Fleet supports the following operating system versions on hosts.
| macOS | 14+ (Sonoma) |
| iOS/iPadOS | 17+ |
| Windows | Pro and Enterprise 10 21H2 (E) (LTS)+, Server 2012+ |
| Linux | CentOS 7.1+, Ubuntu 20.04+, Fedora 38, 39, Amazon Linux 2+, Debian 11+, Red Hat Enterprise Linux (RHEL) 7, 8, 9, openSUSE 15.6+, Arch Linux, Omarchy |
| Linux | CentOS 7.1+, Ubuntu 20.04+, Fedora 38+, Amazon Linux 2+, Debian 11+, Red Hat Enterprise Linux (RHEL) 7+, openSUSE 15.6+, Arch Linux, Omarchy |
| ChromeOS | 112.0.5615.134+ |
| Android | 14+ |
docs/REST API/rest-api.md
+330 -19
View File
@@ -1118,7 +1118,9 @@ Deletes the certificate template added to Fleet. When a certificate template is
### Request certificate
Requests a base64 encoded certificate (`.pem`). Currently, this endpoint is only supported for [Hydrant](#hydrant) and [custom EST](#custom-est-proxy) certificate authorities (CAs). DigiCert, NDES, and custom SCEP coming soon.
Requests a certificate from a certificate authority (CA). Currently, this endpoint is only supported for [Hydrant](#hydrant) and [custom EST](#custom-est-proxy) CAs. DigiCert, NDES, and custom SCEP coming soon.
By default, the `certificate` field in the response is a PEM-encoded PKCS7 envelope (`-----BEGIN PKCS7-----`/`-----END PKCS7-----`). Set `return_pem_certificate` to `true` to receive a standard PEM `CERTIFICATE` block instead.
As an alternative to [API token authentication](https://fleetdm.com/docs/rest-api/rest-api#retrieve-your-api-token), you can send an [HTTP signature in the request header](#example-http-signature).
@@ -1133,6 +1135,7 @@ As an alternative to [API token authentication](https://fleetdm.com/docs/rest-ap
| idp_oauth_url | string | body | OAuth introspection URL from your identity provider (IdP). Required if `idp_token` is specified. |
| idp_token | string | body | Active session token from your identity provider (IdP). Required if `idp_oauth_url` is specified.|
| idp_client_id | string | body | Client ID for which the token was issued from your identity provider (IdP). Required if `idp_oauth_url` is specified.|
| return_pem_certificate | boolean | body | If `true`, the issued certificate is returned as a PEM-encoded `CERTIFICATE` block instead of the default PEM-encoded PKCS7 envelope. Defaults to `false`. |
#### Example
@@ -1155,7 +1158,28 @@ As an alternative to [API token authentication](https://fleetdm.com/docs/rest-ap
```json
{
"certificate": "c3Viamdlkjfid098)d8f2k34jl;Yy4iLCBPVSA9IE1hbmFnZWQgTGludXgsIENOID0gQ2lzY29Vc2VyTmV0d29ya0FjY2Vzcwppc3N1ZXI9TyA9IENpc2NvLCBPVSA9IEVyaWRhbnVzLCBDTiA9IENpc2NvTmV0d29ya0FjY2VzcwotLS0tLUJFR0lOIENFUlRJRklDQVRFLS0tLS0KTUlJRkpUQ0NCQTJnQXdJQkFnSVVlSjdhYlBKd29QL0tXRlhvOXE4RmVrQlVqN293RFFZSktvWklodmNOQVFFTApCUUF3UURFT01Bd0dBMVVFQ2hNRlEybHpZMjh4RVRBUEJnTlZCQXNUQ0VWeWFXUmhiblZ6TVJzd0dRWURWUVFECkV4SkRhWE5qYjA1bGRIalskdjf098)DFj23lk4jRVMldoY05NalV3TnpJME1UYzAKTlRVMldqQlhNUnd3R2dZRFZRUUtEQk5EYVhOamJ5QlRlWE4wWlcxekxDQkpibU11TVJZd0ZBWURWUVFMREExTgpZVzVoWjJWa0lFeHBiblY0TVI4d0hRWURWUVFEREJaRGFYTmpiMVZ6WlhKT1pYUjNiM0pyUVdOalpYTnpNSUlCCklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUF4dFZmWE1xaVMyelRPTEI4WE1ESFBEZmEKMjZIY2ZBdHpmOUVmMk1rQkdrL1VHNVJaTGFrZU0rTDltc0NXaWV0Wllkdf098DSlk23n34,nxo0dfQVdkRHpDbjM0MG1iaUFhS1lIb3JIczVYWW1uSmlrRkYyQgpsQThWWWpTZFZPNGVEN2QvVytwaGo2a2FZQ212dDcwL2tUaDFYL0QzZmM1U0Z4T09OSnZHeVY2MzlvVm9Qd0lECkFRQUJvNElCL2pDQ0Fmb3dEQVlEVlIwVEFRSC9CQUl3QURBZkJnTlZIU01FR0RBV2dCUmpwK2lwUENWTHJXWnkKTlIxdnBDc0owd2Y5WURDQmdnWUlLd1lCQlFVSEFRRUVkakIwTUVNR0NDc0dBUVVGQnpBQ2hqZG9kSFJ3T2k4dgpZM0pzTG1sdWRHVnlibUZzYUc5emRHNWhiV1Z6TG1OdmJTOURhWE5qYjA1bGRIZHZjbXRCWTJObGMzTXVZM0owCk1DMEdDQ3NHQVFVRkJ6QUJoaUZvZEhSd09pOHZiMk56Y0M1cGJuUmxjbTVoYkdodmMzUnVZVzFsY3k1amIyMHcKZ1p3R0ExVWRFUVNCbERDQmtZSVdRMmx6WTI5VmMyVnlUbVYwZDI5eWEwRmpZMlZ6YzRJSlkybHpZMjh1WTI5dApnUkp5WVdocGJXWjBaRUJqYVhOamJ5NWpiMjJnSWdZS0t3WUJCQUdDTnhRQ0E2QVVEQkp5WVdocGJXWjBaRUJqCmFYTmpieTVqYjIyR05FbEVPa1pzWldWMFJFMDZSMVZKUkRwa05XVmtOamMwWXkweU5XTXpMVEV4WWpJdFlUZzEKWXkxalpXTm1NVGc1WVRneFpUSXdGd1lEVlIwZ0JCQXdEakFNQmdvckJnRUVBUWtWQVNvQk1CTUdBMVVkSlFRTQpNQW9HQ0NzR0FRVUZCd01DTUVnR0ExVWRId1JCTUQ4d1BhQTdvRG1HTjJoMGRIQTZMeTlqY213dWFXNTBaWEp1CllXeG9iM04wYm1GdFpYTXVZMjl0TDBOcGMyTnZUbVYwZDI5eWEwRmpZMlZ6Y3k1amNtd3dIUVlEVlIwT0JCWUUKRkF0NjBHd0FwbVoyUkUrNFZsbkxEYkZhZGErTE1BNEdBMVVkRHdFQi93UUVBd0lGb0RBTkJna3Foa2lHOXcwQgpBUXNGQUFPQ0FRRUFsdnRseFJUaVlOVEQvWGpldkswT1BsaVhOdUtjVWlRcW5VSDlIZXowa0d6aWpHUkxrZ1VvCnRLbEJDRTB5QjNyOGhJd3dKbDRPS1cvUzdITXFnY2FNanJTaHIwamlsNDQwNXdOaHBGbzZHRkQwSTFzWjE5eFoKL21BMndsUkY0QkZoZ2QraUE5ZnpRNmNxdVFuV3JlemQxcUxNV0hpOGR5QUJ1c1VBQVZ1OUZORFU4N3BZa0Y4MgpsTjJVSTRLSUZlRDJnTDBXeFpzOVlWTGJlZG1MY0FhZk9HcmtuUDZvVlZMNGxzV1VYQlYxR2tydlkxNWUySnVkCkhVSVEvOTVKTWlkbm1EQVZCbjg1MjA2eDkxbXM3S1lYSmI0aW0yOFBtc1BrN1JJVnJNb2w5dkFlU2ppbHQ1eS8KVitacFBwSmtwWWRyNVpEeWI3WDcwMjR0ZU42QUxmZWRjZz09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0KCg=="
"certificate": "-----BEGIN PKCS7-----\nMIIGmAYJKoZIhvcNAQcCoIIGiTCCBoUCAQExADALBgkqhkiG9w0BBwGgggZtMIIG\naTCCBVGgAwIBAgITHQAAAAQszG7Pr1bRVwABAAAABDANBgkqhkiG9w0BAQsFADBd\nMRMwEQYKCZImiZPyLGQBGRYDY29tMRcwFQYKCZImiZPyLGQBGRYHZXhhbXBsZTEt\nMCsGA1UEAxMkRXhhbXBsZSBJc3N1aW5nIENBIDEgLSBDQSBDb21wYXJ0bWVudDAe\nFw0yNjA0MzAxNjMwMDBaFw0yNjA3MjkxNjMwMDBaMBcxFTATBgNVBAMMDGZsZWV0\naWUtdXNlcjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALMrkHOVZWVG\nv9PqU20NgpWed9MdRtMc8406GGWQJ3Rj9/8Jcy8LOx1d5/XWLKK5VbN2c1hD/a26\nqkgHtDMfzRXnv5oFybkhaI5tlc9yhQmJVFI2RIBsSkZvIlX+SNWV2RuiyVHyGbjh\nzi3wZen1s0aOeXMMHdD5FVEngX4Fz3TuTb/Z8romrsSmWb32fQyQxola9/xe0IAn\nXZocrxi4xPjNKQbEN/2+gQ/MRJx+c+xnV3MVIrXn+8Av8MMBsXhCDlmT2QrpRezN\nAwWwRni9yKOb0sZMtTDrsCOgAmWsj0Qxf/ASMPh7xbozXK4ubf5ombYxEdwGgYl/\nIKQUKvBKYMMCAwEAAaA=\n-----END PKCS7-----\n"
}
```
#### Example (return PEM-encoded certificate)
##### Request body
```json
{
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC/jCCAeYCAQAwITEfMB0GA1UEAwwWQ2lzY29Vc2VyTmV0d29ya0FjY2VzczCC\n...\n-----END CERTIFICATE REQUEST-----",
"return_pem_certificate": true
}
```
##### Default response
`Status: 200`
```json
{
"certificate": "-----BEGIN CERTIFICATE-----\nMIIC5DCCAcwCCQChs1cFRAzRCTANBgkqhkiG9w0BAQsFADA0MTIwMAYDVQQDDClD\ndXN0b21lclVzZXJOZXR3b3JrQWNjZXNzOmJvYkBleGFtcGxlLmNvbTAeFw0yNTA5\nMDgxODM0MzNaFw0yODA2MDUxODM0MzNaMDQxMjAwBgNVBAMMKUN1c3RvbWVyVXNl\nck5ldHdvcmtBY2Nlc3M6Ym9iQGV4YW1wbGUuY29tMIIBIjANBgkqhkiG9w0BAQEF\nAAOCAQ8AMIIBCgKCAQEAuojcu8UBxTjpz5krPX4KmWNAmWvJ4U7yh8pGXOp6kngz\n1iRmGkBYdr0CQXlkrASejqglbdDfaRt3hz8S4raIlKyiU59gFK6f2Lory54ndzJw\nhVeNGqpLrnW1T763zvjcSKaASfVzdnsa66v6pZQte2fZAk7+q5o9ezyirSQmTuks\ndxXAZ5OiDafFwzXlanGZIvCsHBTJtbi881/QU701aTdFFrxLd+jsiaFhKSoQQcL5\nt0zu96cPS2dJivxpaogZ1f8dispWeRiMbt3njaxfWazm4RqvwvDouTSstqUxTzC8\n28Kbh7bnxPcSiuajnf35q53juhTLmB2CKEf0m1eqEwIDAQABMA0GCSqGSIb3DQEB\nCwUAA4IBAQCp75tK8cxR6A0Sfu3vg7TMPD3MkGrpdgh2giAVoCa4hOxOdHl/nYgu\nfPHodsRUfXi1SXo/77jLldGOLE6Ro447FMgrN94mRkaFUZbuLC5z2VciF9x1fdus\nIFfASIFnb4Zw24F2RDBbbGqXqRrA/1m1fWjHTb20+8rHeZW+FCJmxQrL27OG7n/n\nqDr8QmfNwTm8l72FBvUIz1xisuba5nXNAEc6rxTFw6WhPq5fgtBlVZCm55h87hHd\nQbzDGlkIXf+nypg9kwk3fDQ7VY9hrqc74wAefbIkvUSTk9rNaoncxI5Mod/imyan\ngCioUdMGd7M/dpEDDXKJNyI6lfscpG1D\n-----END CERTIFICATE-----\n"
}
```
@@ -1176,7 +1200,8 @@ Signature-Input: sig1=("@method" "@authority" "@path" "@query" \"content-digest"
"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC/jCCAeYCAQAwITEfMB0GA1UEAwwWQ2lzY29Vc2VyTmV0d29ya0FjY2VzczCC\nASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALJZtbxathh+RfK+Z613ar4E\nYSIem8yAvv2JZJtopjD3noy1yF+nGRyF/ocm+FhYvjR5u7teJXlcv24tAAHuWL4U\nuPIql0Slakjdsfl098salkj324lkjmtElWDi6XRjUIXEj1zyCnZTCxGmyHcYB/+f3fyv/\ngZ8SkPqocNOCpX6cSW8hxOlaF9aZUC+xMHRdjQgxQ79hleb5K/n2gCJjiW1sV0Es\nRg+MX0cbPCpahpzlvIAkzA7TTUTOd7ZN+V0GW0fH86uMstrqeW2QUuZmSDC9fNyj\nQhk6n5iURaHXdFjSmyrhW5AVvw1nIblHodhUtD6J+g9kjhBg1frss3ndQtnNrnMC\nAwEAAaCBlzCkldflkjc098dlkj2KoZIhvcNAQkOMYGGMIGDMIGABgNVHREEeTB3ggljaXNjby5j\nb22BEWthYW53YXJAY2lzY28uY29thjRJRDpGbGVldERNOkdVSUQ6Y2FkMTM4OTEt\nMzU3Ni00NzhmLTk1MzAtZmM1Y2VlZTEzZTkwoCEGCisGAQQBgjcUAgOgEwwRa2Fh\nbndhckBjaXNjby5jb20wDQYJKoZIhvcNAQELBQADggEBAH2U6Or14b4O22YjM22k\nXI9QDC5P+sDczcLjivv4MyXQL1ks8R6B1nXCrOmiLPPLaZ09f+UkeMnyuGAxW8Ce\n6LTKquwvlifZ+5TjyANz0I/d9ETLQF2MTphEZd4ySNLtq2RwYyDOBKaxMdW0sUsd\n6M3WyAuTBVgBkTVIqbMJBzFsgXSrr2a0LJEHszOO2BN3yT5muDQsKPJ1uXL7tNUv\n16pGaYpQZR8yGAmWyISHhAyLaJ1N1R8L77SLxdd/Sj7RunNNxqFqaEgIJMgsyu08\nGharLkQcIoW7qPHZuaLa54xMF/s/vfKH6rgGbbCAgw9kw8Klt+6H3OH1FSMeRfZ/\nDWs=\n-----END CERTIFICATE REQUEST-----",
"idp_oauth_url": "https://idp.oauth.com/introspection",
"idp_token": "88683de5858044aaacaf4046aeeef778044aaacaf4046",
"idp_client_id": "1o2czkDnUVwTqSOc747"
"idp_client_id": "1o2czkDnUVwTqSOc747",
"return_pem_certificate": true
}
```
@@ -1616,7 +1641,9 @@ None.
"enable_end_user_authentication": false,
"macos_setup_assistant": "path/to/config.json",
"enable_release_device_manually": false,
"manual_agent_install": false
"manual_agent_install": false,
"enable_managed_local_account": false,
"end_user_local_account_type": "admin",
},
"setup_experience": {
"bootstrap_package": "",
@@ -1972,6 +1999,8 @@ Modifies the Fleet's configuration with the supplied information.
"macos_setup": {
"bootstrap_package": "",
"enable_end_user_authentication": false,
"enable_managed_local_account": false,
"end_user_local_account_type": "admin",
"lock_end_user_info": true,
"macos_setup_assistant": "path/to/config.json"
},
@@ -2606,6 +2635,8 @@ _Available in Fleet Premium._
| Name | Type | Description |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| enable_end_user_authentication | boolean | If set to true, end user authentication will be required during automatic MDM enrollment of new macOS devices. Settings for your IdP provider must also be [configured](https://fleetdm.com/guides/setup-experience#end-user-authentication). |
| 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`) |
<br/>
@@ -2711,6 +2742,19 @@ _Available in Fleet Premium._
| enable_host_users | boolean | Whether to enable the users feature in Fleet. (Default: `true`) |
| enable_software_inventory | boolean | Whether to enable the software inventory feature in Fleet. (Default: `true`) |
| additional_queries | object | `additional_queries` adds extra host details. This information will be updated at the same time as other host details and is returned by the API when host objects are returned. (Default: `null`) |
| historical_data | object | Per-dataset toggles for historical data collection used by the dashboard charts. See [Historical data](#historical-data) below. |
##### Historical data
`features.historical_data` controls whether each dashboard chart's
historical data is collected. Both sub-keys default to `true`. A dataset
is collected for a given host only when both the global sub-key AND the
host's fleet sub-key are `true`.
| Name | Type | Description |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| uptime | boolean | Whether to collect host activity samples. (Default: `true`) |
| vulnerabilities | boolean | Whether to collect per-host software vulnerability data. (Default: `true`) |
<br/>
@@ -2724,6 +2768,10 @@ _Available in Fleet Premium._
"additional_queries": {
"time": "SELECT * FROM time",
"macs": "SELECT mac FROM interface_details"
},
"historical_data": {
"uptime": true,
"vulnerabilities": false
}
}
}
@@ -3000,6 +3048,7 @@ None.
- [Run live query on host (ad hoc)](#run-live-query-on-host-ad-hoc)
- [Run live query on host by identifier (ad hoc)](#run-live-query-on-host-by-identifier-ad-hoc)
- [Bypass host's conditional access](#bypass-hosts-conditional-access)
- [Get host's managed account password](#get-hosts-managed-account-password)
#### About host timestamps
@@ -5762,6 +5811,70 @@ Grant a blocked host access for a single login. Requires Okta conditional access
`Status: 200`
## Clear iOS/iPadOS host passcode
_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.
`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. |
#### Example
`POST /api/v1/fleet/hosts/123/clear_passcode`
#### Default response
`Status: 200`
```json
{
"command_uuid": "84F7F777-803E-40BB-8B47-2C0DC8B0118A",
"request_type": "ClearPasscode",
"platform": "ios"
}
```
## Get host's managed account password
Retrieves the managed account password for a host.
The host will only return a password if its managed account password status is "Verified".
`GET /api/v1/fleet/hosts/:id/managed_account_password`
#### Parameters
| Name | Type | In | Description |
| ---- | ------- | ---- | ------------------------------------------------------------------------ |
| id | integer | path | **Required** The ID of the host to get the managed account password for. |
#### Example
`GET /api/v1/fleet/hosts/8/managed_account_password`
##### Default response
`Status: 200`
```json
{
"host_id": 8,
"managed_account_password": {
"password": "test-123",
"updated_at": "2026-02-01T05:31:43Z"
}
}
```
---
@@ -6852,6 +6965,7 @@ Get status counts of a single OS settings (configuration profile) enforced on ho
- [Create setup experience script](#create-setup-experience-script)
- [Get or download setup experience script](#get-or-download-setup-experience-script)
- [Delete setup experience script](#delete-setup-experience-script)
- [Update managed local account](#update-managed-local-account)
@@ -7228,8 +7342,11 @@ _Available in Fleet Premium_
| enable_end_user_authentication | boolean | body | When enabled, require end users to authenticate with your identity provider (IdP) when they set up their new macOS hosts. |
| lock_end_user_info | boolean | body | When enabled, 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`) |
| require_all_software_macos | boolean | body | If set to `true`, setup will be canceled on macOS hosts if any software installs fail. |
| require_all_software_windows | boolean | body | If set to `true`, setup will be canceled on Windows hosts if any software installs fail. |
| enable_release_device_manually | boolean | body | When enabled, you're responsible for sending the [`DeviceConfigured` command](https://developer.apple.com/documentation/devicemanagement/device-configured-command). End users will be stuck in Setup Assistant until this command is sent. |
| manual_agent_install | boolean | body | If set to `true` Fleet's agent (fleetd) won't be installed as part of automatic enrollment (ADE) on macOS hosts. (Default: `false`) |
| enable_managed_local_account | boolean | During the Setup experience, a managed local account will be created on macOS hosts if set to true. |
| end_user_local_account_type | string | Specifies the type of local end user account created. (Default: `"admin"`) `enable_managed_local_account` must be true. |
#### Example
@@ -7583,6 +7700,36 @@ Delete a script that will automatically run during macOS setup.
`Status: 200`
### Update managed local account
_Available in Fleet Premium_
Edit managed local account enforcement settings for eligible macOS hosts.
`POST /api/v1/fleet/managed_local_account`
#### Parameters
| Name | Type | In | Description |
| ---------------------------- | ------ | ---- | -------------------------------------------------------------------------------------|
| fleet_id | integer | body | The fleet ID to apply the settings to. If omitted, settings apply to unassigned hosts.|
| enable_managed_local_account | boolean | body | Whether to enforce creating managed local accounts on eligible hosts. |
#### Example
`POST /api/v1/fleet/managed_local_account`
##### Default response
`204`
```json
{
"fleet_id": 3,
"enable_managed_local_account": true
}
```
---
## Commands
@@ -8445,10 +8592,12 @@ _Available in Fleet Premium_
| resolution | string | body | The resolution steps for the policy. |
| platform | string | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. |
| critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. |
| labels_include_any | array | form | _Available in Fleet Premium_. Target hosts that have any label, specified by label name, in the array. |
| labels_exclude_any | array | form | _Available in Fleet Premium_. Target hosts that that don’t have any, specified by label name, label in the array. |
| labels_include_any | array | form | Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **any of these** labels. |
| labels_include_all | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **all of these** labels. |
| labels_exclude_any | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **none of these** labels. |
Only one of `labels_include_any` or `labels_exclude_any` can be specified. If neither is set, all hosts on the specified `platform` are targeted.
Only one of `labels_include_any`, `labels_include_all`, or `labels_exclude_any` can be specified. If none is set, all hosts on the specified `platform` are targeted.
#### Example
@@ -8522,12 +8671,15 @@ The semantics for creating a fleet policy are the same as for global policies, s
| patch_software_title_id | integer | body | _Available in Fleet Premium_. ID of the software title (Fleet-maintained only) to create a patch policy for. Required if `type` is `patch`. |
| software_title_id | integer | body | _Available in Fleet Premium_. ID of software title to install if the policy fails. If `software_title_id` is specified and the software has `labels_include_any` or `labels_exclude_any` defined, the policy will inherit this target in addition to specified `platform`. |
| script_id | integer | body | _Available in Fleet Premium_. ID of script to run if the policy fails. |
| labels_include_any | array | form | _Available in Fleet Premium_. Target hosts that have any label, specified by label name, in the array. |
| labels_exclude_any | array | form | _Available in Fleet Premium_. Target hosts that that don’t have any label, specified by label name, in the array. |
| labels_include_any | array | form | Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **any of these** labels. |
| labels_include_all | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **all of these** labels. |
| labels_exclude_any | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **none of these** labels. |
Either `query` or `query_id` must be provided.
Only one of `labels_include_any` or `labels_exclude_any` can be specified. If neither is set, all hosts on the specified `platform` are targeted.
Only one of `labels_include_any`, `labels_include_all`, or `labels_exclude_any` can be specified. If none is set, all hosts on the specified `platform` are targeted.
#### Example
@@ -8672,10 +8824,11 @@ _Available in Fleet Premium_
| resolution | string | body | The resolution steps for the policy. |
| platform | string | body | Comma-separated target platforms, currently supported values are "windows", "linux", "darwin". The default, an empty string means target all platforms. |
| critical | boolean | body | _Available in Fleet Premium_. Mark policy as critical/high impact. |
| labels_include_any | array | form | _Available in Fleet Premium_. Target hosts that have any label, specified by label name, in the array. |
| labels_exclude_any | array | form | _Available in Fleet Premium_. Target hosts that that don’t have any label, specified by label name, in the array. |
| labels_include_any | array | form | Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **any of these** labels. |
| labels_include_all | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **all of these** labels. |
| labels_exclude_any | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **none of these** labels. |
Only one of `labels_include_any` or `labels_exclude_any` can be specified. If neither is set, all hosts on the specified `platform` are targeted.
Only one of `labels_include_any`, `labels_include_all`, or `labels_exclude_any` can be specified. If none is set, all hosts on the specified `platform` are targeted.
#### Example
@@ -8747,10 +8900,13 @@ _Available in Fleet Premium_
| conditional_access_enabled | boolean | body | _Available in Fleet Premium_. Whether to block single sign-on for end users whose hosts fail this policy. |
| 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. |
| labels_exclude_any | array | form | _Available in Fleet Premium_. Target hosts that that don’t have any label, specified by label name, in the array. |
| labels_include_any | array | form | Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **any of these** labels. |
| labels_include_all | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **all of these** labels. |
| labels_exclude_any | array | form | _Available in Fleet Premium_. Labels, specified by label name, to target with this policy. If specified, the policy will run on hosts that match **none of these** labels. |
Only one of `labels_include_any` or `labels_exclude_any` can be specified. If neither is set, all hosts on the specified `platform` are targeted.
Either `query` or `query_id` must be provided.
Only one of `labels_include_any`, `labels_include_all`, or `labels_exclude_any` can be specified. If none is set, all hosts on the specified `platform` are targeted.
#### Example
@@ -9335,15 +9491,18 @@ Creates a global report or fleet report.
| query | string | body | **Required**. The SQL query for collecting report data. |
| description | string | body | The query's description. |
| observer_can_run | boolean | body | Whether or not users with the `observer` role can run the report as a live report. This field is only relevant for the `observer` role. The `observer_plus` role can run any report and is not limited by this flag. |
| fleet_id | integer | body | _Available in Fleet Premium_. The fleet to which the new report should be added. If omitted, the report will be global. |
| fleet_id | integer | body | _Available in Fleet Premium_. The fleet to which the new report should be added. If omitted, the report will be global. |
| interval | integer | body | The amount of time, in seconds, the report waits before running. Can be set to `0` to never run. Default: 0. |
| platform | string | body | The OS platforms where this report will run (other platforms ignored). Comma-separated string. If omitted, runs on all compatible platforms. |
| labels_include_any | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this report. If specified, the report will run on hosts that match **any of these** labels. |
| labels_include_any | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this report. If specified, the report will run on hosts that match **any of these** labels. |
| labels_include_all | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this report. If specified, the report will run on hosts that match **all of these** labels. |
| min_osquery_version | string | body | The minimum required osqueryd version installed on a host. If omitted, all osqueryd versions are acceptable. |
| automations_enabled | boolean | body | Whether to send data to the configured log destination according to the report's `interval`. |
| logging | string | body | The type of log output for this report. Valid values: `"snapshot"`(default), `"differential"`, or `"differential_ignore_removals"`. |
| discard_data | boolean | body | Whether to skip saving the latest results for each host. If set to `true`, data is still sent to the configured log destination if `automations_enabled`. Default: `false`. |
Only one of `labels_include_any` or `labels_include_all` can be specified. If none are specified, all hosts are targeted.
#### Example
@@ -9440,14 +9599,17 @@ Modifies the report specified by ID.
| query | string | body | The report's SQL query. |
| description | string | body | The report's description. |
| observer_can_run | boolean | body | Whether or not users with the `observer` role can run the report as a live report. This field is only relevant for the `observer` role. The `observer_plus` role can run any query and is not limited by this flag. |
| interval | integer | body | The amount of time, in seconds, the report waits before running. Can be set to `0` to never run. Default: 0. |
| interval | integer | body | The amount of time, in seconds, the report waits before running. Can be set to `0` to never run. Default: 0. |
| platform | string | body | The OS platforms where this report will run (other platforms ignored). Comma-separated string. If set to "", runs on all compatible platforms. |
| labels_include_any | list | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this report. If specified, the report will run on hosts that match **any of these** labels. |
| labels_include_all | array | body | _Available in Fleet Premium_. Labels, specified by label name, to target with this report. If specified, the report will run on hosts that match **all of these** labels. |
| min_osquery_version | string | body | The minimum required osqueryd version installed on a host. If omitted, all osqueryd versions are acceptable. |
| automations_enabled | boolean | body | Whether to send data to the configured log destination according to the report's `interval`. |
| logging | string | body | The type of log output for this query. Valid values: `"snapshot"`(default), `"differential"`, or `"differential_ignore_removals"`. |
| discard_data | boolean | body | Whether to skip saving the latest results for each host. If set to `true`, data is still sent to the configured log destination if `automations_enabled`. |
Only one of `labels_include_any` or `labels_include_all` can be specified. If none are specified, all hosts are targeted.
> Note that any of the following conditions will cause the existing report's data to be discarded:
> - Updating the `query` (SQL) field
> - Updating the filters for targeted hosts (`platform`, `min_osquery_version`, `labels_include_any`)
@@ -12652,6 +12814,31 @@ _Available in Fleet Premium_
| integrations | object | body | Integrations settings for the fleet. See [integrations](#integrations3) for details. Note that integrations referenced here must already exist globally, created by a call to [Modify configuration](#modify-configuration). |
| mdm | object | body | MDM settings for the fleet. See [mdm](#mdm2) for details. |
| host_expiry_settings | object | body | Host expiry settings for the fleet. See [host_expiry_settings](#host-expiry-settings2) for details. |
| features | object | body | Per-fleet feature toggles. v1 accepts only the `historical_data` sub-field; other `features` sub-fields are writable per-fleet only via GitOps. See [features.historical_data](#features-historical-data) below. |
##### features.historical_data
Sub-keys mirror the global `features.historical_data` shape and default to
`true`. A dataset is collected for a host in this fleet only when both the
global sub-key AND this fleet's sub-key are `true`. Sub-keys omitted from
the PATCH body retain their current stored value.
| Name | Type | Description |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| uptime | boolean | Whether to collect host-uptime samples for hosts in this fleet. (Default: `true`) |
| vulnerabilities | boolean | Whether to collect CVE samples for hosts in this fleet. (Default: `true`) |
###### Example request body
```json
{
"features": {
"historical_data": {
"vulnerabilities": false
}
}
}
```
#### Example (transfer hosts to a fleet)
@@ -13411,6 +13598,8 @@ Transforms a host name into a host id. For example, the Fleet UI uses this endpo
- [Delete invite](#delete-invite)
- [Verify invite](#verify-invite)
- [Update invite](#update-invite)
- [Create API-only user](#create-api-only-user)
- [List API endpoints for API-only user permissions](#list-api-endpoints-for-api-only-user-permissions)
The Fleet server exposes API endpoints that handles common user management operations, including managing emailed invites to new users. All of these endpoints require prior authentication, so you'll need to log in before calling any of the endpoints documented below.
@@ -14277,6 +14466,128 @@ Verify the specified invite.
}
```
### Create API-only user
Creates an API-only user that does not have access to the UI.
`POST /api/v1/fleet/users/api_only`
| Name | Type | In | Description |
| :---------------------- | :------ | :---- | :---------- |
| name | string | body | The display name for the API-only user. |
| global_role | string | body | The role assigned to the user. If `global_role` is specified, `fleets` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). |
| fleets | array | body | _Available in Fleet Premium_. The fleets and respective roles assigned to the user. Should contain an array of objects in which each object includes the fleet's `id` and the user's `role` on each fleet. If `fleets` is specified, `global_role` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). |
| api_endpoints | array | body | _Available in Fleet Premium_. A list of `id`s of API endpoints this user will have access to. For available endpoints, see [List API endpoints for API-only user permissions](#list-api-endpoints-for-api-only-user-permissions). |
If `api_endpoints` is specified, these do not grant additional permissions otherwise forbidden by the user's `role`.
#### Example
`POST /api/v1/fleet/users/api_only`
##### Request body
```json
{
"name": "Jane Doe",
"fleets": [
{
"id": 2,
"role": "observer"
},
{
"id": 3,
"role": "maintainer"
}
],
"api_endpoints": [1,5,7,32]
}
```
##### Default response
`Status: 200`
```json
{
"user": {
"created_at": "0001-01-01T00:00:00Z",
"updated_at": "0001-01-01T00:00:00Z",
"id": 5,
"name": "Jane Doe",
"email": "janedoe+randomlygeneratedstring@example.com",
"enabled": true,
"force_password_reset": false,
"gravatar_url": "",
"sso_enabled": false,
"mfa_enabled": false,
"api_only": true,
"global_role": null,
"fleets": [
{
"id": 2,
"role": "observer"
},
{
"id": 3,
"role": "maintainer"
}
],
"api_endpoints": [1,5,7,32]
},
"token": "{API key}"
}
```
### List API endpoints for API-only user permissions
_Available in Fleet Premium._
Lists Fleet REST API endpoints that an API-only user can be granted access to.
`GET /api/v1/fleet/rest_api`
| Name | Type | In | Description |
| :---------------------- | :------ | :---- | :---------- |
| query | string | query | Search query keywords. Searchable fields include `display_name` and `path`. |
Searching by path ignores the naming of path parameters that are specified with `:` , e.g. `:id`. So searching `/hosts/:id/report` is the same as searching `/hosts/:host_id/report`.
Experimental endpoints are excluded from the results, since they are not for use in automated workflows.
#### Example
`GET /api/v1/fleet/rest_api?query=get%20host%20by%20identifier`
or
`GET /api/v1/fleet/rest_api?query=%2Fapi%2Fv1%2Ffleet%2Fhosts%2Fidentifier%2F%3Ahost_identifier`
##### Default response
`Status: 200`
```json
{
"api_endpoints": [
{
"id": 123,
"display_name": "Get host by identifier",
"method": "GET",
"path": "/api/v1/fleet/hosts/identifier/:identifier",
"deprecated": false
}
],
"meta": {
"has_next_results": true,
"has_previous_results": false
},
"count": 1
}
```
---
## Debug
- [Get errors](#get-errors)