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
fleet/docs/Configuration/yaml-files.md

1279 lines
65 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# GitOps
Use Fleet's best practice GitOps workflow to manage your computers as code. To learn how to set up a GitOps workflow see the [Fleet GitOps repo](https://github.com/fleetdm/fleet-gitops).
<div purpose="embedded-content">
<iframe src="https://www.youtube.com/embed/wgqI_lHnGJc" allowfullscreen></iframe>
</div>
> When renaming a fleet, first update the name in the UI, then update your YAML. If you only update the YAML, the fleet will be deleted and its hosts will lose their settings because they become "Unassigned".
Any settings not defined in your YAML files (including missing or misspelled keys) will be reset to the default values or deleted (e.g. software packages).
The following are the required keys in the `default.yml` and any `fleets/fleet-name.yml` files:
```yaml
name: # Only fleets/fleet-name.yml
policies:
reports:
agent_options:
controls:
software:
org_settings: # Only default.yml
settings: # Only fleets/fleet-name.yml
```
Paths in YAML files are always relative to the file you’re editing.
For example:
```yaml
# If the file is in the same directory:
package_path: package_name.yml
# If the file is in a different directory:
package_path: ../software/package_name.yml
```
For the GitOps API token, create a dedicated API-only user with `fleetctl user create --api-only`. These users can modify configurations via GitOps but can’t access the Fleet UI. Assign the GitOps role and set the appropriate global or fleet scope in the UI.
## labels
Labels can be specified in your `default.yml` and `fleets/fleet-name.yml` files using inline configuration or references to separate files in your `lib/` folder. Labels cannot be specified in `fleets/unassigned.yml`.
- `name` specifies the label's name. Must be unique across all global and fleet labels.
+ Changing a label's `name` in GitOps will delete and re-create the label, temporarily clearing its membership. To avoid this, update the label name in the UI before making the change in YAML.
- `description` specifies the label's description.
- `platform` specifies platforms for the label to target. Provides an additional filter. Choices for platform are `darwin`, `windows`, `ubuntu`, and `centos`. All platforms are included by default and this option is represented by an empty string. Only supported if `label_membership_type` is `dynamic`.
- `label_membership_type` specifies label type which determines. Choices for type are `dynamic` , `manual`, and `host_vitals` (default: `dynamic`).
- `query` is the query in SQL syntax used to filter the hosts. Only supported if `label_membership_type` is `dynamic`.
- `hosts` is a list of host identifiers (`id`, `hardware_serial`, or `uuid`). The label will apply to any host with a matching identifier. Only supported if `label_membership_type` is `manual`.
- `criteria` - is the criteria for adding hosts to a host vitals label. Hosts with `vital` data matching the specified `value` will be added to the label. See [criteria](https://fleetdm.com/docs/rest-api/rest-api#criteria) documentation for details.
Only one of `query`, `hosts`, or `criteria` can be specified. If none are specified, a manual label with no hosts will be created.
The `hostname` host identifier is deprecated. Please use a host's `id`, `hardware_serial`, or `uuid` instead.
> `labels` is an optional key: if included in `default.yml`, existing global labels not listed will be deleted. If included in `fleets/fleet-name.yml`, the fleet's existing labels not listed will be deleted. If the `label` key is omitted, existing labels will stay intact. For this reason, enabling [GitOps mode](https://fleetdm.com/learn-more-about/ui-gitops-mode) _does not_ restrict creating/editing labels via the UI.
>
> Any labels referenced in other sections (like [policies](https://fleetdm.com/docs/configuration/yaml-files#policies), [reports](https://fleetdm.com/docs/configuration/yaml-files#reports) or [software](https://fleetdm.com/docs/configuration/yaml-files#software)) _must_ be specified in the `labels` section.
### Example
#### Inline
`default.yml`
```yaml
labels:
- name: Arm64
platform: darwin,windows
description: Hosts on the Arm64 architecture
query: "SELECT 1 FROM system_info WHERE cpu_type LIKE 'arm64%' OR cpu_type LIKE 'aarch64%'"
label_membership_type: dynamic
- name: C-Suite
description: Hosts belonging to the C-Suite
label_membership_type: manual
hosts:
- "IR7M6ZGQJM"
- "JMFWY8VZ09"
- name: Engineering department
description: Hosts used by engineers
label_membership_type: host_vitals
criteria:
vital: end_user_idp_department
value: Engineering
```
#### Separate file
`lib/labels-name.labels.yml`
```yaml
- name: Arm64
description: Hosts on the Arm64 architecture
query: SELECT 1 FROM system_info WHERE cpu_type LIKE "arm64%" OR cpu_type LIKE "aarch64%"
label_membership_type: dynamic
- name: C-Suite
description: Hosts belonging to the C-Suite
label_membership_type: manual
hosts:
- "IR7M6ZGQJM"
- "JMFWY8VZ09"
- name: Engineering department
description: Hosts used by engineers
label_membership_type: host_vitals
criteria:
vital: end_user_idp_department
value: Engineering
```
`default.yml`
```yaml
labels:
- path: ./lib/labels-name.labels.yml
- paths: ./lib/labels/*.yml
```
## policies
Policies can be specified inline in your `default.yml`, `fleets/fleet-name.yml`, or `fleets/unassigned.yml` files. They can also be specified in separate files in your `lib/` folder.
### Options
For available options, see the parameters for the [Create policy](https://fleetdm.com/docs/rest-api/rest-api#create-policy) and [Create team policy](https://fleetdm.com/docs/rest-api/rest-api#create-team-policy) API endpoints.
#### Patch policy
_Available in Fleet Premium_
You can create a patch policy by setting `type` to `patch` and specifying `fleet_maintained_app_slug`.
A patch policy's `query` automatically updates. Hosts will fail this policy if they’re not running the latest version found in [the app's metadata](https://github.com/fleetdm/fleet/tree/main/ee/maintained-apps/outputs). If `version` is set for `fleet_maintained_apps`, that version is included in the query.
To automatically install the app when this policy fails, you can add an automation by setting `install_software` to `true`.
#### Automations
##### Install software
_Available in Fleet Premium_
To trigger software install, when policy fails, specify one of:
- `install_software.package_path` is the path to a custom package YAML. Only one package can be specified in the package YAML.
- `install_software.hash_sha256` is [SHA256 hash](https://fleetdm.com/docs/configuration/yaml-files#hash) of a custom package.
#### Run script
_Available in Fleet Premium_
To trigger script run, when policy fails, specify:
- `run_script.path` is a path to a script YAML.
> Specifying one package without a list is deprecated as of Fleet 4.73. It is maintained for backwards compatibility. Please use a list instead even if you're only specifying one package.
### Example
#### Inline
`default.yml`, `fleets/fleet-name.yml`, or `fleets/unassigned.yml`
```yaml
policies:
- name: macOS - Enable FileVault
description: This policy checks if FileVault (disk encryption) is enabled.
resolution: As an IT admin, turn on disk encryption in Fleet.
query: "SELECT 1 FROM filevault_status WHERE status = 'FileVault is On.';"
platform: darwin
critical: false
calendar_events_enabled: false
conditional_access_enabled: true
labels_include_any:
- Engineering
- Customer Support
```
#### Separate file
`lib/policies-name.policies.yml`
```yaml
- name: macOS - Enable FileVault
description: This policy checks if FileVault (disk encryption) is enabled.
resolution: As an IT admin, turn on disk encryption in Fleet.
query: "SELECT 1 FROM filevault_status WHERE status = 'FileVault is On.';"
platform: darwin
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.
query: "SELECT 1 FROM managed_policies WHERE domain='com.apple.mcx' AND username = '' AND name='DisableGuestAccount' AND CAST(value AS INT) = 1;"
platform: darwin
critical: false
calendar_events_enabled: false
run_script:
path: ./disable-guest-account.sh
- name: Install Firefox on macOS
platform: darwin
description: This policy checks that Firefox is installed.
resolution: Install Firefox app if not installed.
query: "SELECT 1 FROM apps WHERE name = 'Firefox.app'"
install_software:
package_path: ./firefox.package.yml
- name: [Install software] Logic Pro
platform: darwin
description: This policy checks that Logic Pro is installed
resolution: Install Logic Pro App Store app if not installed
query: "SELECT 1 FROM apps WHERE name = 'Logic Pro'"
install_software:
package_path: ./linux-firefox.deb.package.yml
# app_store_id: "1487937127" (for App Store apps)
- name: Zoom up to date
description: Outdated software might introduce security vulnerabilities or compatibility issues.
resolution: Install the latest version from self-service.
type: patch
fleet_maintained_app_slug: zoom/darwin
install_software: true
```
`default.yml` (for policies that neither install software nor run scripts), `fleets/fleet-name.yml`, or `fleet/unassigned.yml`
```yaml
policies:
- path: ../lib/policies-name.policies.yml
- paths: ../lib/*.policies.yml
```
> Currently, the `run_script` and `install_software` policy automations can only be configured for a fleet (`fleets/fleet-name.yml`) or "Unassigned" (`fleets/unassigned.yml`). The automations can only be added to policies in which the script (or software) is defined in the same fleet (or "Unassigned"). `calendar_events_enabled` can only be configured for policies on a fleet.
> If using `labels_include_any`/`labels_exclude_any` for targeting, these keys are specified on the individual policies. Specifying at the top level of `policies` will _not_ apply the labels to each policy.
## reports
Reports can be specified inline in your `default.yml` file or `fleets/fleet-name.yml` files. They can also be specified in separate files in your `lib/` folder.
### Options
For possible options, see the parameters for the [Create report API endpoint](https://fleetdm.com/docs/rest-api/rest-api#create-report).
### Example
#### Inline
`default.yml` or `fleets/fleet-name.yml`
```yaml
reports:
- name: Collect failed login attempts
description: Lists the users at least one failed login attempt and timestamp of failed login. Number of failed login attempts reset to zero after a user successfully logs in.
query: SELECT users.username, account_policy_data.failed_login_count, account_policy_data.failed_login_timestamp FROM users INNER JOIN account_policy_data using (uid) WHERE account_policy_data.failed_login_count > 0;
platform: darwin,linux,windows
interval: 300
observer_can_run: false
automations_enabled: false
labels_include_any:
- Engineering
- Customer Support
```
#### Separate file
`lib/reports-name.reports.yml`
```yaml
- name: Collect failed login attempts
description: Lists the users at least one failed login attempt and timestamp of failed login. Number of failed login attempts reset to zero after a user successfully logs in.
query: SELECT users.username, account_policy_data.failed_login_count, account_policy_data.failed_login_timestamp FROM users INNER JOIN account_policy_data using (uid) WHERE account_policy_data.failed_login_count > 0;
platform: darwin,linux,windows
interval: 300
observer_can_run: false
automations_enabled: false
- name: Collect USB devices
description: Collects the USB devices that are currently connected to macOS and Linux hosts.
query: SELECT model, vendor FROM usb_devices;
platform: darwin,linux
interval: 300
observer_can_run: true
automations_enabled: false
```
`default.yml` or `fleets/fleet-name.yml`
```yaml
reports:
- path: ../lib/reports-name.reports.yml
labels_include_any:
- Engineering
- Customer Support
- paths: ../lib/*.reports.yml
```
## agent_options
Agent options can be specified inline in your `default.yml` file or `fleets/fleet-name.yml` files. They can also be specified in separate files in your `lib/` folder.
See "[Agent configuration](https://fleetdm.com/docs/configuration/agent-configuration)" to find all possible options.
### Example
#### Inline
`default.yml` or `fleets/fleet-name.yml`
```yaml
agent_options:
config:
decorators:
load:
- SELECT uuid AS host_uuid FROM system_info;
- SELECT hostname AS hostname FROM system_info;
options:
disable_distributed: false
distributed_interval: 10
distributed_plugin: tls
distributed_tls_max_attempts: 3
logger_tls_endpoint: /api/osquery/log
logger_tls_period: 10
pack_delimiter: /
```
#### Separate file
`lib/agent-options.yml`
```yaml
config:
decorators:
load:
- SELECT uuid AS host_uuid FROM system_info;
- SELECT hostname AS hostname FROM system_info;
options:
disable_distributed: false
distributed_interval: 10
distributed_plugin: tls
distributed_tls_max_attempts: 3
logger_tls_endpoint: /api/osquery/log
logger_tls_period: 10
pack_delimiter: /
```
`default.yml` or `fleets/fleet-name.yml`
> We want `-` for policies and reports because it’s an array. Agent Options we do not use `-` for `path`.
```yaml
agent_options:
path: ../lib/agent-options.yml
```
## controls
The `controls` section allows you to configure scripts and device management (MDM) features in Fleet.
- `scripts` is a list of paths to macOS, Windows, or Linux scripts.
- `windows_enabled_and_configured` specifies whether or not to turn on Windows MDM features (default: `false`). Can only be configured for "All fleets" (`default.yml`).
- `windows_entra_tenant_ids` is a list of Microsoft Entra tenant IDs to enable automatic (Autopilot) and manual enrollment by end users (**Settings** > **Accounts** > **Access work or school** on Windows). Can only be configured for "All fleets" (`default.yml`). Find your **Tenant ID**, on [**Microsoft Entra ID** > **Home**](https://entra.microsoft.com/#home).
- `enable_turn_on_windows_mdm_manually` specifies whether or not to require end users to manually turn on MDM in **Settings > Access work or school** (default: `false`). If `false`, MDM is automatically turned on for all Windows hosts that aren't connected to any MDM solution. Can only be configured for "All fleets" (`default.yml`).
- `windows_migration_enabled` specifies whether or not to automatically migrate Windows hosts connected to another MDM solution. If `false`, MDM is only turned on after hosts are unenrolled from your old MDM solution. `enable_turn_on_windows_mdm_manually` must be set to `false`. (default: `false`). Can only be configured for "All fleets" (`default.yml`).
- `enable_disk_encryption` specifies whether or not to enforce disk encryption on macOS, Windows, and Linux hosts (default: `false`).
- `windows_require_bitlocker_pin` specifies whether or not to require end users on Windows hosts to set a BitLocker PIN. When set, this PIN is required to unlock Windows host during startup. `enable_disk_encryption` must be set to `true`. (default: `false`).
- `enable_recovery_lock_password` specifies whether or not to enforce Recovery Lock password on eligible macOS hosts (default: `false`).
#### Example
```yaml
controls:
scripts:
- path: ../lib/macos-script.sh
- path: ../lib/windows-script.ps1
- path: ../lib/linux-script.sh
windows_enabled_and_configured: true
windows_entra_tenant_ids:
- 4e342a0d-ec1a-4353-bdeb-785542e0a8fb
enable_turn_on_windows_mdm_manually: false # Available in Fleet Premium
windows_migration_enabled: true # Available in Fleet Premium
enable_disk_encryption: true # Available in Fleet Premium
enable_recovery_lock_password: true # Available in Fleet Premium
macos_updates: # Available in Fleet Premium
deadline: "2024-12-31"
minimum_version: "15.1"
update_new_hosts: true
ios_updates: # Available in Fleet Premium
deadline: "2024-12-31"
minimum_version: "18.1"
ipados_updates: # Available in Fleet Premium
deadline: "2024-12-31"
minimum_version: "18.1"
windows_updates: # Available in Fleet Premium
deadline_days: 5
grace_period_days: 2
apple_settings:
configuration_profiles:
- path: ../lib/macos-profile1.mobileconfig
labels_exclude_any: # Available in Fleet Premium
- Macs on Sequoia
- path: ../lib/macos-profile3.mobileconfig
labels_include_any: # Available in Fleet Premium
- Engineering
- Product
- paths: ../lib/configuration-profiles/*.json
windows_settings:
configuration_profiles:
- path: ../lib/windows-profile.xml
android_settings:
configuration_profiles:
- path: ../lib/android-profile.json
certificates:
- name: wifi-certificate
certificate_authority_name: EST_WIFI
subject_name: CN=$FLEET_VAR_HOST_END_USER_IDP_USERNAME, OU=$FLEET_VAR_HOST_UUID, ST=$FLEET_VAR_HOST_HARDWARE_SERIAL
setup_experience: # Available in Fleet Premium
bootstrap_package: https://example.org/bootstrap_package.pkg
enable_end_user_authentication: true
apple_enable_release_device_manually: true
apple_setup_assistant: ../lib/dep-profile.json
macos_script: ../lib/macos-setup-script.sh
macos_migration: # Available in Fleet Premium
enable: true
mode: voluntary
webhook_url: https://example.org/webhook_handler
```
### 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: `""`).
- `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: `""`).
- `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: `""`).
- `minimum_version` specifies the minimum required iPadOS version (default: `""`).
### windows_updates
- `deadline_days` specifies the number of days before Windows installs updates (default: `null`)
- `grace_period_days` specifies the number of days before Windows restarts to install updates (default: `null`)
### apple_settings and windows_settings
- `apple_settings.configuration_profiles` is a list of paths to macOS, iOS, and iPadOS configuration profiles (.mobileconfig) or declaration profiles (.json).
- `windows_settings.configuration_profiles` is a list of paths to Windows configuration profiles (.xml).
Use `labels_include_all` to target hosts that have all labels, `labels_include_any` to target hosts that have any label, or `labels_exclude_any` to target hosts that don't have any of the labels. Only one of `labels_include_all`, `labels_include_any`, or `labels_exclude_any` can be specified. If none are specified, all hosts are targeted.
### android_settings
- `android_settings.configuration_profiles` is a list of paths to Android configuration profiles (.json).
Use `labels_include_all` to target hosts that have all labels, `labels_include_any` to target hosts that have any label, or `labels_exclude_any` to target hosts that don't have any of the labels. Only one of `labels_include_all`, `labels_include_any`, or `labels_exclude_any` can be specified. If none are specified, all hosts are targeted.
#### android_settings.certificates
- `name` is the name of the certificate. Name can be used as a certificate alias to reference in configuration profiles (custom settings).
- `certificate_authority_name` is the name of the [certificate authority (CA)](#certificate-authorities) to issue the certificate from. Currently, only a custom SCEP CA is supported.
- `subject_name` is the certificate's subject name (SN). Separate subject fields by a "/". For example: "CN=john@example.com, O=Acme Inc.".
#### Variables
For macOS configuration profiles, you can use any of Apple's [built-in variables](https://support.apple.com/en-my/guide/deployment/dep04666af94/1/web/1.0) in [Automated Certificate Management Environment (ACME)](https://developer.apple.com/documentation/devicemanagement/acmecertificate), [Simple Certificate Enrolment Protocol (SCEP)](https://developer.apple.com/documentation/devicemanagement/scep), or [VPN](https://developer.apple.com/documentation/devicemanagement/vpn) payloads.
Fleet also supports adding [GitHub](https://docs.github.com/en/actions/learn-github-actions/variables#defining-environment-variables-for-a-single-workflow) or [GitLab](https://docs.gitlab.com/ci/variables/) environment variables in your configuration profiles. Use `$ENV_VARIABLE` format.
If you use one of these variables in a configuration profile, Fleet will automatically resend it when the variable's value changes.
In Fleet Premium, you can use reserved variables beginning with `$FLEET_VAR_`. Fleet will populate these variables when profiles are sent to hosts. Supported variables are:
| Name | Platforms | Description |
| ---- | --------- | ----------- |
| <span style="display: inline-block; min-width: 240px;">`$FLEET_VAR_NDES_SCEP_CHALLENGE`</span> | macOS, iOS, iPadOS | Fleet-managed one-time NDES challenge password used during SCEP certificate configuration profile deployment. |
| `$FLEET_VAR_NDES_SCEP_PROXY_URL` | macOS, iOS, iPadOS | Fleet-managed NDES SCEP proxy endpoint URL used during SCEP certificate configuration profile deployment. |
| `$FLEET_VAR_HOST_END_USER_IDP_USERNAME` | macOS, iOS, iPadOS, Windows | Host's IdP username (e.g. "user@example.com"). When this changes, Fleet will automatically resend the profile. |
| `$FLEET_VAR_HOST_END_USER_IDP_FULL_NAME` | macOS, iOS, iPadOS, Windows | Host's IdP full name. When this changes, Fleet will automatically resend the profile. |` | macOS, iOS, iPadOS | Host's IdP username. When this changes, Fleet will automatically resend the profile. |
| `$FLEET_VAR_HOST_END_USER_IDP_USERNAME_LOCAL_PART` | macOS, iOS, iPadOS, Windows | Local part of the email (e.g. john from john@example.com). When this changes, Fleet will automatically resend the profile. |
| `$FLEET_VAR_HOST_END_USER_IDP_GROUPS` | macOS, iOS, iPadOS, Windows | Comma separated IdP groups that host belongs to. When these change, Fleet will automatically resend the profile. |
| `$FLEET_VAR_HOST_END_USER_IDP_DEPARTMENT` | macOS, iOS, iPadOS, Windows | Host's IdP department. When this changes, Fleet will automatically resend the profile. |
| `$FLEET_VAR_HOST_UUID` | macOS, iOS, iPadOS, Windows | Host's hardware UUID. |
| `$FLEET_VAR_HOST_HARDWARE_SERIAL` | macOS, iOS, iPadOS, Windows | Host's hardware serial number. |
| `$FLEET_VAR_HOST_PLATFORM` | macOS, iOS, iPadOS, Windows | Host's platform. Values are `"macos"`, `"ios"`, `"ipados"`, and `"windows"`. |
| `$FLEET_VAR_CUSTOM_SCEP_CHALLENGE_<CA_NAME>` | macOS, iOS, iPadOS, Windows | Fleet-managed one-time challenge password used during SCEP certificate configuration profile deployment. `<CA_NAME>` should be replaced with name of the certificate authority configured in [custom_scep_proxy](#custom-scep-proxy). |
| `$FLEET_VAR_CUSTOM_SCEP_PROXY_URL_<CA_NAME>` | macOS, iOS, iPadOS, Windows | Fleet-managed SCEP proxy endpoint URL used during SCEP certificate configuration profile deployment. |
| `$FLEET_VAR_SCEP_RENEWAL_ID` | macOS, iOS, iPadOS, Windows | Fleet-managed ID that's required to automatically renew Smallstep, Microsoft NDES, and custom SCEP certificates. The ID must be specified in the Organizational Unit (OU) field in the configuration profile. |
| `$FLEET_VAR_DIGICERT_PASSWORD_<CA_NAME>` | macOS, iOS, iPadOS | Fleet-managed password required to decode the base64-encoded certificate data issued by a specified DigiCert certificate authority during PKCS12 profile deployment. `<CA_NAME>` should be replaced with name of the certificate authority configured in [digicert](#digicert). |
| `$FLEET_VAR_DIGICERT_DATA_<CA_NAME>` | macOS, iOS, iPadOS | Fleet-managed base64-encoded certificate data issued by a specified DigiCert certificate authority during PKCS12 profile deployment. `<CA_NAME>` should be replaced with name of the certificate authority configured in [digicert](#digicert). |
| `$FLEET_VAR_SCEP_WINDOWS_CERTIFICATE_ID` | Windows | ID used for SCEP configuration profile on Windows. It must be included in the `<LocURI>` field.|
| `$FLEET_VAR_SMALLSTEP_SCEP_CHALLENGE_<CA_NAME>` | macOS, iOS, iPadOS | Fleet-managed one-time Smallstep challenge password used during SCEP certificate configuration profile deployment. `<CA_NAME>` should be replaced with name of the certificate authority configured in [custom_scep_proxy](#custom-scep-proxy). |
| `$FLEET_VAR_SMALLSTEP_SCEP_PROXY_URL_<CA_NAME>` | macOS, iOS, iPadOS | Fleet-managed Smallstep SCEP proxy endpoint URL used during SCEP certificate configuration profile deployment. |
The dollar sign (`$`) can be escaped so it's not considered a variable by using a backslash (e.g. `\$100`). Additionally, `MY${variable}HERE` syntax can be used to put strings around the variable.
In XML, certain characters (`&`, `<`, `>`, `"`, `'`) must be escaped because they have special meanings in the markup language. GitHub and GitLab environment variables, as well as Fleet's reserved variables, will be automatically escaped when used in a `.mobileconfig` configuration profile. For example, `&` will become `&amp;`.
If certificate authority (CA) variables (ex. `$FLEET_VAR_DIGICERT_DATA_<CA_NAME>`) don't exist, GitOps dry runs will succeed but GitOps runs will fail.
To hide variable values in the API and UI, you can use Fleet's [custom variables](https://fleetdm.com/guides/secrets-in-scripts-and-configuration-profiles#gitops).
### setup_experience
The `setup_experience` section lets you control the out-of-the-box [setup experience](https://fleetdm.com/guides/setup-experience).
> **Experimental feature.** The `macos_manual_agent_install` 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.
- `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.
- `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.
#### Example
`fleets/fleet-name.yml`, or `fleets/unassigned.yml`
```yaml
setup_experience:
bootstrap_package: "https://your-storage/package.pkg"
macos_manual_agent_install: false
enable_end_user_authentication: true
lock_end_user_info: true
apple_enable_release_device_manually: false
apple_setup_assistant: "./setup_assistant.json"
macos_script: "./post_setup.sh"
```
### macos_migration
The `macos_migration` section lets you control the [end user migration workflow](https://fleetdm.com/docs/using-fleet/mdm-migration-guide#end-user-workflow) for macOS hosts that enrolled to your old MDM solution.
- `enable` specifies whether or not to enable end user migration workflow (default: `false`)
- `mode` specifies whether the end user initiates migration (`voluntary`) or they're nudged every 15-20 minutes to migrate (`forced`) (default: `""`).
- `webhook_url` is the URL that Fleet sends a webhook to when the end user selects **Start**. Receive this webhook using your automation tool (ex. Tines) to unenroll your end users from your old MDM solution.
Can only be configured for "All fleets" (`default.yml`).
## software
> **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.
The `software` section allows you to configure packages, store apps (Apple App Store and Google Play Store), and Fleet-maintained apps that you want to install on your hosts.
- `packages` is a list of paths to custom packages (.pkg, .ipa, .msi, .exe, .deb, .rpm, .tar.gz, .sh, or .ps1).
- `app_store_apps` is a list of Apple App Store or Android Play Store apps.
- `fleet_maintained_apps` is a list of Fleet-maintained apps.
Currently, you can specify `install_software` in the [`policies` YAML](#policies) to automatically install a custom package or App Store app when a host fails a policy. [Automatic install support for Fleet-maintained apps](https://github.com/fleetdm/fleet/issues/34492) is coming soon.
Currently, Fleet only allows one package, Apple App Store app, or Fleet-maintained app for a specific software. This means, if you specify a Google Chrome for macOS twice in `packages` or once in `packages` and once in `fleet_maintained_apps`, only one of them will be added to Fleet.
Currently, when a `.ipa` file is added in `packages`, Fleet adds software for both iOS and iPadOS, along with all specified settings (e.g. `self_service`). If software for one platform is deleted in the UI, it will come back when GitOps is re-run.
#### Example
`fleets/fleet-name.yml`, or `fleets/unassigned.yml`
```yaml
software:
packages:
- path: ../lib/software-name.package.yml
categories:
- Browsers
self_service: true
setup_experience: true
- path: ../lib/software-name2.package.yml
app_store_apps:
- app_store_id: "1091189122"
platform: ios
labels_include_any: # Available in Fleet Premium
- Product
- Marketing
categories:
- Communication
setup_experience: true
auto_update_enabled: true
auto_update_window_start: "00:00"
auto_update_window_end: "04:00"
- app_store_id: "us.zoom.videomeetings"
platform: android
self_service: true
setup_experience: true
configuration:
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:
path: ../lib/software/slack-uninstall-script.sh
post_install_script:
path: ../lib/software/slack-config-script.sh
self_service: true
setup_experience: true
labels_include_any:
- Design
- Sales
categories:
- Communication
- Productivity
```
#### self_service, labels, categories, and setup_experience
- `self_service` specifies whether end users can install from **Fleet Desktop > Self-service** (default: `false`) on macOS or [self-service web app](https://fleetdm.com/learn-more-about/deploy-self-service-to-ios) on iOS/iPadOS.
- `labels_include_any` targets hosts that have **any** of the specified labels. `labels_exclude_any` targets hosts that have **none** of the specified labels. Only one of these fields can be set. If neither is set, all hosts are targeted.
- `categories` groups self-service software on your end users' **Fleet Desktop > My device** page. If none are set, Fleet-maintained apps get their [default categories](https://github.com/fleetdm/fleet/tree/main/ee/maintained-apps/outputs) and all other software only appears in the **All** group. Supported values:
- `Browsers`: shown as **🌎 Browsers**
- `Communication`: shown as **👬 Communication**
- `Developer tools`: shown as **🧰 Developer tools**
- `Productivity`: shown as **🖥️ Productivity**
- `Security`: shown as **🔐 Security**
- `Utilities`: shown as **🛠️ Utilities**
- `setup_experience` installs the software when hosts enroll (default: `false`). Learn more in the [setup experience guide](https://fleetdm.com/guides/setup-experience).
### packages
- `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.
- `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.
- `uninstall_script.path` is the script Fleet will run on hosts to uninstall 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.
- `post_install_script.path` is the script Fleet will run on hosts after the software install. There is no default. Not supported for `.sh` and `.ps1` files.
- `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 built into Fleet. 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.
#### Example
##### URL
`lib/software-name.package.yml`:
```yaml
- url: https://dl.tailscale.com/stable/tailscale-setup-1.72.0.exe
install_script:
path: ../lib/software/tailscale-install-script.ps1
uninstall_script:
path: ../lib/software/tailscale-uninstall-script.ps1
post_install_script:
path: ../lib/software/tailscale-config-script.ps1
```
##### Hash
You can view the hash for existing software in the software detail page in the Fleet UI. It is also returned after uploading a new software item via the API.
```yaml
# Mozilla Firefox (Firefox 136.0.1.pkg) version 136.0.1
- hash_sha256: fd22528a87f3cfdb81aca981953aa5c8d7084581b9209bb69abf69c09a0afaaf
```
##### Script-only
Script-only packages (`.sh` and `.ps1` files) are referenced directly inline in the team YAML file. The file contents become the install script. Script packages do not support `install_script`, `uninstall_script`, `post_install_script`, `pre_install_query`, or automatic install (`install_software` in policies).
`self_service`, `categories`, `labels`, and `icon` are specified inline in the team YAML file.
```yaml
software:
packages:
- path: ../lib/linux/scripts/vpn-setup.sh
self_service: true
categories:
- Utilities
```
> Script-only packages do not currently support configuration via a separate package YAML file. All options must be specified inline in the team YAML file.
### app_store_apps
- `app_store_id` is the ID of the Apple App Store or Android Play Store app. You can find this ID at the end of the app's URL. For example, "Bear - Markdown Notes" URL is "https://apps.apple.com/us/app/bear-markdown-notes/id1016366447" making the `app_store_id` is "1016366447". Similarly, the URL for "Google Chrome" on Android is "https://play.google.com/store/apps/details?id=com.android.chrome," so the `app_store_id` is "com.android.chrome."
+ For Apple App Store apps, make sure to include only the ID itself, and not the `id` prefix shown in the URL. The ID must be wrapped in quotes as shown in the example so that it is processed as a string.
- `platform` is the platform of the app (`darwin`, `ios`, `ipados`, or `android`). If not specified, and `app_store_id` is Apple App Store ID, one app for each of the Apple App Store app's supported platforms is added. For example, adding [Bear](https://apps.apple.com/us/app/bear-markdown-notes/id1016366447) (supported on iOS and iPadOS) adds both the iOS and iPadOS apps to your software that's available to install in Fleet.
- `icon.path` is a relative path to the PNG icon that will be displayed in Fleet and on **Fleet Desktop > Self-service** instead of the default icon the icon sourced from Apple. It must be a square PNG with dimensions between 120x120 px and 1024x1024 px. Custom icons will only override the icon for the software title and fleet where they are added.
- `configuration.path` is the Android Play Store app's managed configuration in JSON format. Currently only supported for Android.
+ `managedConfiguration` and `workProfileWidgets` are supported from [Android application policy](https://developers.google.com/android/management/reference/rest/v1/enterprises.policies#ApplicationPolicy).
+ Configuration keys vary by app. Refer to the app vendor's documentation for available managed configuration options. For example, see [Zoom's Android managed configuration](https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0064790) or [GlobalProtect's Android configuration](https://docs.paloaltonetworks.com/globalprotect/10-1/globalprotect-admin/mobile-endpoint-management/manage-the-globalprotect-app-using-other-third-party-mdms/configure-the-globalprotect-app-for-android).
To add the same App Store app for multiple platforms, specify the `app_store_id` multiple times, along with the `platform` you want. If you don't specify a platform, one app for each available platform will be added (macOS, iOS, and iPadOS).
When you update an Android app's configuration via GitOps, the app's settings are applied without reinstalling the app. The install status will show as "Pending" until the configuration is applied.
### fleet_maintained_apps
- `fleet_maintained_apps` is a list of Fleet-maintained apps. Provide the `slug` field to include a Fleet-maintained app on a fleet. 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).
By default, Fleet-maintained apps will be updated to the latest version published by Fleet when GitOps runs.
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 SQL 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 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.
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.
- `categories` is an array of categories, from [supported categories](#labels-and-categories).
## org_settings and settings
Currently, managing users and ticket destinations (Jira and Zendesk) are only supported using Fleet's UI or [API](https://fleetdm.com/docs/rest-api/rest-api).
### features
The `features` section of the configuration YAML lets you turn on/off Fleet features.
- `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`).
Can be configured for "All fleets" (`org_settings`) and specific fleets (`settings`).
#### Example
```yaml
org_settings:
features:
additional_queries:
time: SELECT * FROM time
macs: SELECT mac FROM interface_details
enable_host_users: true
enable_software_inventory: true
```
### fleet_desktop
The `fleet_desktop` section lets you customize the Fleet Desktop experience by overriding default URLs.
- `transparency_url` directs end users to a custom URL when they select **About Fleet** in the Fleet Desktop dropdown (default: [https://fleetdm.com/transparency](https://fleetdm.com/transparency)).
- `alternative_browser_host` is a custom hostname that my hosts will access Fleet Desktop from.
Can only be configured for "All fleets" (`org_settings`).
#### Example
```yaml
org_settings:
fleet_desktop:
transparency_url: https://example.org/transparency
alternative_browser_host: fleet-desktop.example.com
```
### host_expiry_settings
The `host_expiry_settings` section lets you define if and when hosts should be automatically deleted from Fleet if they have not checked in.
- `host_expiry_enabled` (default: `false`)
- `host_expiry_window` if a host has not communicated with Fleet in the specified number of days, it will be removed. Must be > `0` when host expiry is enabled (default: `0`).
If this setting is not defined in your YAML files, unlike all other settings, it will not get reset to the default values.
Can be configured for "All fleets" (`org_settings`) and specific fleets (`settings`).
#### Example
```yaml
org_settings:
host_expiry_settings:
host_expiry_enabled: true
host_expiry_window: 10
```
### org_info
- `org_name` is the name of your organization (default: `""`)
- `org_logo_url` is a public URL of the logo for your organization (default: Fleet logo).
- `org_logo_url_light_background` is a public URL of the logo for your organization that can be used with light backgrounds (default: Fleet logo).
- `contact_url` is a URL or [file URI](https://en.wikipedia.org/wiki/File_URI_scheme) that appears in error messages presented to end users (default: `"https://fleetdm.com/company/contact"`)
Can only be configured for "All fleets" (`org_settings`).
To get the best results for your logos (`org_logo_url` and `org_logo_url_light_background`), use the following sizes:
- For square logos, use a PNG that's 256x256 pixels (px).
- For rectangular logos (wordmark), use a PNG that's 516x256 pixels (px).
#### Example
```yaml
org_settings:
org_info:
org_name: Fleet
org_logo_url: https://example.com/logo.png
org_logo_url_light_background: https://example.com/logo-light.png
contact_url: https://fleetdm.com/company/contact
```
### secrets
The `secrets` section defines the valid secrets that hosts can use to enroll to Fleet. Supply one of these secrets when generating the fleetd agent you'll use to [enroll hosts](https://fleetdm.com/docs/using-fleet/enroll-hosts).
Can be configured for "All fleets" (`org_settings`) and specific fleets (`settings`).
#### Example
```yaml
org_settings:
secrets:
- secret: $ENROLL_SECRET
```
### server_settings
- `ai_features_disabled` disables AI-assisted policy descriptions and resolutions. (default: `false`)
- `enable_analytics` specifies whether or not to enable Fleet's [usage statistics](https://fleetdm.com/docs/using-fleet/usage-statistics). (default: `true`)
- `live_reporting_disabled` disables the ability to run live reports (ad hoc reports executed via the UI or fleetctl). (default: `false`)
- `discard_reports_data` disables storing results for all reports and deletes existing stored data. If set to `true`, data is still sent to the configured log destination if `automations_enabled`. (default: `false`)
- `report_cap` sets the maximum number of results to store per report before the report is clipped. If increasing this cap, we recommend enabling reports for one query at a time and monitoring your infrastructure. (default: `1000`)
- `scripts_disabled` blocks access to run scripts. Scripts may still be added in the UI and CLI. (default: `false`)
- `server_url` is the base URL of the Fleet instance. If this URL changes and Apple (macOS, iOS, iPadOS) hosts already have MDM turned on, the end users will have to turn MDM off and back on to use MDM features. (default: provided during Fleet setup)
Can only be configured for "All fleets" (`org_settings`).
#### Example
```yaml
org_settings:
server_settings:
ai_features_disabled: false
enable_analytics: true
live_report_disabled: false
query_reports_disabled: false
scripts_disabled: false
server_url: https://instance.fleet.com
```
### sso_settings
The `sso_settings` section lets you define [single sign-on (SSO)](https://fleetdm.com/docs/deploying/configuration#configuring-single-sign-on-sso) settings.
- `enable_sso` (default: `false`)
- `idp_name` is the human-friendly name for the identity provider that will provide single sign-on authentication (default: `""`).
- `idp_image_url` is an optional link to an image such as a logo for the identity provider. (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: `""`).
- `metadata` is the metadata (in XML format) provided by the identity provider. (default: `""`)
- `metadata_url` is the URL that references the identity provider metadata. Only one of `metadata` or `metadata_url` is required (default: `""`).
- `enable_jit_provisioning` specifies whether or not to enable [just-in-time user provisioning](https://fleetdm.com/docs/deploy/single-sign-on-sso#just-in-time-jit-user-provisioning) (default: `false`).
- `enable_sso_idp_login` specifies whether or not to allow single sign-on login initiated by identity provider (default: `false`).
- `sso_server_url` is used if the URL your Fleet users (admins, maintainers, observers) use to login to Fleet via SSO is different than the base URL of your Fleet instance. If not configured, login via SSO will use the base URL of the Fleet instance.
Can only be configured for "All fleets" (`org_settings`).
#### Example
```yaml
org_settings:
sso_settings:
enable_sso: true
idp_name: Okta
idp_image_url: https://www.okta.com/favicon.ico
entity_id: https://example.okta.com
metadata: $SSO_METADATA
enable_jit_provisioning: true # Available in Fleet Premium
enable_sso_idp_login: true
sso_server_url: https://admin.example.com # Optional, SSO will only work from this URL
```
### integrations
The `integrations` section lets you configure your Google Calendar, Conditional access (enabling/disabling for hosts in "Unassigned"), Jira, and Zendesk. After configuration, you can enable [automations](https://fleetdm.com/docs/using-fleet/automations) like calendar event and ticket creation for failing policies. Currently, enabling ticket creation is only available using Fleet's UI or [API](https://fleetdm.com/docs/rest-api/rest-api) (YAML files coming soon).
Can be configured for "All fleets" (`org_settings`) and specific fleets (`settings`).
#### Example
`default.yml`
```yaml
org_settings:
integrations:
conditional_access_enabled: true
google_calendar:
- api_key_json: $GOOGLE_CALENDAR_API_KEY_JSON
domain: fleetdm.com
jira:
- url: https://example.atlassian.net
username: user1
api_token: $JIRA_API_TOKEN
project_key: PJ1
zendesk:
- url: https://example.zendesk.com
email: user1@example.com
api_token: $ZENDESK_API_TOKEN
group_id: 1234
```
`/fleets/fleet-name.yml`
At the fleet level, there is the additional option to enable conditional access, which blocks third party app sign-ins on hosts failing policies. (Available in Fleet Premium. Must have Microsoft Entra connected.)
```yaml
integrations:
conditional_access_enabled: true
```
#### google_calendar
For "All fleets" (`org_settings`):
- `api_key_json` is the contents of the JSON file downloaded when you create your Google Workspace service account API key (default: `""`).
- `domain` is the primary domain used to identify your end user's work calendar (default: `""`).
For specific fleets (`settings`):
- `enable_calendar_events` to enable calendar events for a fleet (default: `false`).
- `webhook_url` is the webhook URL triggered during a user's calendar event (default: `""`).
#### jira
- `url` is the URL of your Jira (default: `""`)
- `username` is the username of your Jira account (default: `""`).
- `api_token` is the Jira API token (default: `""`).
- `project_key` is the project key location in your Jira project's URL. For example, in "jira.example.com/projects/EXMPL," "EXMPL" is the project key (default: `""`).
Can be configured for "All fleets" (`org_settings`). Use API to configure Jira for specific fleets or "Unassigned" hosts.
#### zendesk
- `url` is the URL of your Zendesk (default: `""`)
- `username` is the username of your Zendesk account (default: `""`).
- `api_token` is the Zendesk API token (default: `""`).
- `group_id`is found by selecting **Admin > People > Groups** in Zendesk. Find your group and select it. The group ID will appear in the search field.
Can be configured for "All fleets" (`org_settings`). Use API to configure Zendesk for specific fleets or "Unassigned" hosts.
### certificate_authorities
_Available in Fleet Premium._
This section lets you configure your [certificate authorities (CA)](https://fleetdm.com/guides/certificate-authorities) to help your end users connect to Wi-Fi and VPN.
#### Example
`default.yml`
```yaml
org_settings:
certificate_authorities:
digicert:
- name: DIGICERT_WIFI
url: https://one.digicert.com
api_token: $DIGICERT_API_TOKEN
profile_id: 926dbcdd-41c4-4fe5-96c3-b6a7f0da81d8
certificate_common_name: $FLEET_VAR_HOST_HARDWARE_SERIAL@example.com
certificate_user_principal_names:
- $FLEET_VAR_HOST_HARDWARE_SERIAL@example.com
certificate_seat_id: $FLEET_VAR_HOST_HARDWARE_SERIAL@example.com
ndes_scep_proxy:
url: https://example.com/certsrv/mscep/mscep.dll
admin_url: https://example.com/certsrv/mscep_admin/
username: Administrator@example.com
password: myPassword
custom_scep_proxy:
- name: SCEP_VPN
url: https://example.com/scep
challenge: $SCEP_VPN_CHALLENGE
custom_est_proxy:
- name: SECTIGO_WIFI
url: https://example.com/.well-known/est/abc123
username: $SECTIGO_USERNAME_PASSWORD
password: $SECTIGO_WIFI_PASSWORD
hydrant: # Available in Fleet Premium
- name: EST_WIFI
url: https://example.com/est
username: $EST_PROXY_USERNAME
password: $EST_PROXY_PASSWORD
hydrant:
- name: HYDRANT_WIFI
url: https://example.hydrantid.com/.well-known/est/abc123
client_id: $HYDRANT_CLIENT_ID
client_secret: $HYDRANT_CLIENT_SECRET
smallstep:
- name: SMALLSTEP_WIFI
url: https://example.scep.smallstep.com/p/agents/integration-fleet
challenge_url: https://example.scep.smallstep.com/xr9f4db7-83f1-48ab-8982-8b6870d4fl85/challenge
username: $SMALLSTEP_USERNAME
password: $SMALLSTEP_PASSWORD
```
#### digicert
- `name` is the name of certificate authority that will be used in variables in configuration profiles. Only letters, numbers, and underscores are allowed.
- `url` is the URL to DigiCert One instance (default: `https://one.digicert.com`).
- `api_token` is the token used to authenticate requests to DigiCert.
- `profile_id` is the ID of certificate profile in DigiCert.
- `certificate_common_name` is the certificate's CN.
- `certificate_user_principal_names` is the certificate's user principal names (UPN) attribute in Subject Alternative Name (SAN).
- `certificate_seat_id` is the ID of the DigiCert's seat. Seats are license units in DigiCert.
Can only be configured for "All fleets" (`org_settings`).
#### ndes_scep_proxy
- `url` is the URL of the NDES SCEP endpoint (default: `""`).
- `admin_url` is the URL of the NDES admin endpoint (default: `""`).
- `username` is the username of the NDES admin endpoint (default: `""`).
- `password` is the password of the NDES admin endpoint (default: `""`).
Can only be configured for "All fleets" (`org_settings`).
#### custom_scep_proxy
- `name` is the name of certificate authority that will be used in variables in configuration profiles. Only letters, numbers, and underscores are allowed.
- `url` is the URL of the Simple Certificate Enrollment Protocol (SCEP) server.
- `challenge` is the static challenge password used to authenticate requests to SCEP server.
#### custom_est_proxy
- `name` is the name of the certificate authority that will be used in variables in configuration profiles. Only letters, numbers, and underscores are allowed.
- `url` is the EST (Enrollment Over Secure Transport) endpoint's URL.
- `username` is the username used to authenticate with the EST endpoint.
- `password` is the password used to authenticate with the EST endpoint.
#### hydrant
- `name` is the name of the certificate authority that will be used in variables in configuration profiles. Only letters, numbers, and underscores are allowed.
- `url` is the EST (Enrollment Over Secure Transport) endpoint provided by Hydrant.
- `client_id` is the client ID provided by Hydrant.
- `client_secret` is the client secret provided by Hydrant.
#### smallstep
- `name` is the name of the certificate authority that will be used in variables in configuration profiles. Only letters, numbers, and underscores are allowed.
- `url` is the **SCEP URL** from Smallstep.
- `challenge_url` is the **Webhook URL** from Smallstep.
- `username` is the **Challenge Basic Authentication Username** from Smallstep.
- `password` is the **Challenge Basic Authentication Password** from Smallstep.
Can only be configured for "All fleets" (`org_settings`).
### webhook_settings
The `webhook_settings` section lets you define webhook settings for failing policy, vulnerability, and host status [automations](https://fleetdm.com/docs/using-fleet/automations).
- `interval` is how often policy webhooks/tickets and host status webhooks are triggered, formatted as number + unit of measurement (e.g. `"90m"`). Can be specified in seconds (`"s"`), minutes (`"m"`), or hours (`"h"`). (Default: `"24h"`)
#### activities_webhook
- `enable_activities_webhook` (default: `false`)
- `destination_url` is the URL to `POST` to when an activity is generated (default: `""`)
Can be configured for all fleets (`org_settings`), specific fleets (`settings`), or "Unassigned" (`settings`).
### Example
```yaml
org_settings:
webhook_settings:
activities_webhook:
enable_activities_webhook: true
destination_url: https://example.org/webhook_handler
```
#### failing_policies_webhook
> These settings can also be configured per-fleet when nested under `settings`.
- `enable_failing_policies_webhook` (default: `false`)
- `destination_url` is the URL to `POST` to when the condition for the webhook triggers (default: `""`).
- `policy_ids` is the list of policies that will trigger a webhook.
- `host_batch_size` is the maximum number of host identifiers to send in one webhook request. A value of `0` means all host identifiers with a failing policy will be sent in a single request.
#### Example
```yaml
org_settings:
webhook_settings:
failing_policies_webhook:
enable_failing_policies_webhook: true
destination_url: https://example.org/webhook_handler
host_batch_size: 0
policy_ids:
- 1
- 2
- 3
```
#### host_status_webhook
- `enable_host_status_webhook` (default: `false`)
- `destination_url` is the URL to `POST` to when the condition for the webhook triggers (default: `""`).
- `days_count` is the number of days that hosts need to be offline to count as part of the percentage (default: `0`).
- `host_percentage` is the percentage of hosts that need to be offline to trigger the webhook. (default: `0`).
Can be configured for "All fleets" (`org_settings`) and specific fleets (`settings`).
#### Example
```yaml
org_settings:
webhook_settings:
host_status_webhook:
enable_host_status_webhook: true
destination_url: https://example.org/webhook_handler
days_count: 7
host_percentage: 25
```
#### vulnerabilities_webhook
- `enable_vulnerabilities_webhook` (default: `false`)
- `destination_url` is the URL to `POST` to when the condition for the webhook triggers (default: `""`).
- `host_batch_size` is the maximum number of host identifiers to send in one webhook request. A value of `0` means all host identifiers with a detected vulnerability will be sent in a single request.
Can only be configured for "All fleets" (`org_settings`).
#### Example
```yaml
org_settings:
webhook_settings:
vulnerabilities_webhook:
enable_vulnerabilities_webhook: true
destination_url: https://example.org/webhook_handler
host_batch_size: 0
```
### mdm
#### apple_business_manager
After [adding an Apple Business Manager (ABM) token via the UI](https://fleetdm.com/guides/macos-mdm-setup#apple-business-manager), the `apple_business_manager` section lets you determine which fleet Apple hosts are assigned to in Fleet when they appear in Apple Business Manager.
- `organization_name` is the organization name associated with the Apple Business Manager account.
- `macos_fleet` is the fleet where macOS hosts are automatically added when they appear in Apple Business Manager. If not specified, defaults to "Unassigned".
- `ios_fleet` is the the fleet where iOS hosts are automatically added when they appear in Apple Business Manager. If not specified, defaults to "Unassigned".
- `ipados_fleet` is the fleet where iPadOS hosts are automatically added when they appear in Apple Business Manager. If not specified, defaults to "Unassigned".
Can only be configured for "All fleets" (`org_settings`).
#### Example
```yaml
org_settings:
mdm:
apple_business_manager: # Available in Fleet Premium
- organization_name: Fleet Device Management Inc.
macos_fleet: 💻 Workstations
ios_fleet: 📱🏢 Company-owned iPhones
ipados_fleet: 🔳🏢 Company-owned iPads
```
#### volume_purchasing_program
After you've uploaded a [Volume Purchasing Program](https://fleetdm.com/guides/macos-mdm-setup#volume-purchasing-program-vpp) (VPP) token, the `volume_purchasing_program` section lets you configure the fleets in Fleet that have access to that VPP token's App Store apps. Currently, adding a VPP token is only available using Fleet's UI.
- `location` is the name of the location in the Apple Business Manager account.
- `fleets` is a list of fleet names. If you choose specific fleets, App Store apps in this VPP account will only be available to install on hosts in these fleets. If not specified, App Store apps will not be available to install on any fleet. To apply it to all fleets, use `- All fleets`.
Can only be configured for "All fleets" (`org_settings`).
#### Example
```yaml
org_settings:
mdm:
volume_purchasing_program: # Available in Fleet Premium
- location: Fleet Device Management Inc.
fleets:
- 💻 Workstations
- 💻🐣 Workstations (canary)
- 📱🏢 Company-owned iPhones
- 🔳🏢 Company-owned iPads
```
#### end_user_authentication
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.
- `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: `""`).
- `metadata` is the metadata (in XML format) provided by the identity provider. (default: `""`)
- `metadata_url` is the URL that references the identity provider metadata. Only one of `metadata` or `metadata_url` is required (default: `""`).
Can only be configured for "All fleets" (`org_settings`):
#### Example
```
org_settings:
mdm:
end_user_authentication:
entity_id: https://example.okta.com
idp_name: Okta
metadata: $END_USER_SSO_METADATA
metadata_url: ""
```
##### end_user_license_agreement
You can require an end user to agree to an end user license agreement (EULA) before they can use their new Mac. `end_user_authentication` must be configured, and `controls.enable_end_user_authentication` must be set to `true`.
- `end_user_license_agreement` is the path to the PDF document.
Can only be configured for "All fleets" (`org_settings`).
##### Example
```yaml
org_settings:
mdm:
end_user_license_agreement: ./lib/eula.pdf
```
##### apple_server_url
Update this URL if you're self-hosting Fleet and you want your hosts to talk to this URL for MDM features. (If not configured, hosts will use the base URL of the Fleet instance.)
If this URL changes and hosts already have MDM turned on, the end users will have to turn MDM off and back on to use MDM features.
Can only be configured for "All fleets" (`org_settings`).
##### Example
```yaml
org_settings:
mdm:
apple_server_url: https://instance.fleet.com
```
#### yara_rules
The `yara_rules` section lets you define [YARA rules](https://virustotal.github.io/yara/) that will be served by Fleet's [authenticated
YARA rule](https://fleetdm.com/guides/remote-yara-rules) functionality.
Can only be configured for "All fleets" (`org_settings`). To target rules to specific fleets, target the reports referencing the rules to the desired fleets.
##### Example
```yaml
org_settings:
yara_rules:
- path: ./lib/rule1.yar
- path: ./lib/rule2.yar
```
#### smtp_settings
If you're self hosting Fleet, the `smtp_settings` section lets you configure an e-mail (SMTP) server. This enables Fleet to send user invite and password reset emails.
If you're using Fleet's managed-cloud offering, an SMTP server is already setup for you.
For possible options, see the parameters for the [smtp_settings object in the API](https://fleetdm.com/docs/rest-api/rest-api#smtp-settings).
Can only be configured for "All fleets" (`org_settings`).
##### Example
```yaml
org_settings:
smtp_settings:
enable_smtp: true
sender_address: organization@example.com
server: localhost
port: 1025
authentication_type: none
```
Can only be configured for "All fleets" (`org_settings`).
Unlike other options, omitting `smtp_settings` or leaving it blank won't reset the values back to the default.
<meta name="title" value="GitOps">
<meta name="description" value="Reference documentation for Fleet's GitOps workflow. See examples and configuration options.">
<meta name="pageOrderInSection" value="1500">
Reference in a new issue View git blame Copy permalink