Fleet can be managed with configuration files (YAML syntax) and the fleetctl command line tool. This page tells you how to write these configuration files.
Changes are applied to Fleet when the configuration file is applied using fleetctl. Check out the [fleetctl documentation](https://fleetdm.com/docs/using-fleet/fleetctl-cli#using-fleetctl-to-configure-fleet) to learn how to apply configuration files.
The following file describes the labels which hosts should be automatically grouped into. The label resource should include the actual SQL query so that the label is self-contained:
The team agent options specify options that only apply to this team. When team-specific agent options have been specified, the agent options specified at the organization level are ignored for this team.
The documentation for this section is identical to the [Agent options](#agent-options) documentation for the organization settings, except that the YAML section where it is set must be as follows. (Note the `kind: team` key and the location of the `agent_options` key under `team` must have a `name` key to identify the team to configure.)
```yaml
apiVersion: v1
kind: team
spec:
team:
name: Client Platform Engineering
agent_options:
# the team-specific options go here
```
#### Secrets
The `secrets` section provides the list of enroll secrets that will be valid for this team. If the section is missing, the existing secrets are left unmodified. Otherwise, they are replaced with this list of secrets for this team.
> MDM features are not ready for production and are currently in development. These features are disabled by default.
The `mdm` section of the configuration YAML lets you control MDM settings for the team in Fleet.
The documentation for this section is identical to the [MDM settings](#mobile-device-management-mdm-settings) documentation for the organization settings, except that the YAML section where it is set must be as follows. (Note the `kind: team` key and the location of the `mdm` key under `team` must have a `name` key to identify the team to configure.)
All possible settings are organized below by section.
Each section's key must be one level below the `spec` key, indented with spaces (not `<tab>` charaters) as required by the YAML format.
For example, when adding the `host_expiry_settings.host_expiry_enabled` setting, you'd specify the `host_expiry_settings` section one level below the `spec` key:
```yaml
apiVersion: v1
kind: config
spec:
host_expiry_settings:
host_expiry_enabled: true
```
#### Features
The `features` section of the configuration YAML lets you define what predefined queries are sent to the hosts and later on processed by Fleet for different functionalities.
> Note: this section used to be named `host_settings`, but was renamed in Fleet v4.20.0,
> `host_settings` is still supported for backwards compatibility.
##### features.additional_queries
This is the additional information to collect from hosts along with the 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. Users must take care to keep the data returned by these queries small in order to mitigate potential performance impacts on the Fleet server.
- Optional setting (dictionary of key-value strings)
The `host_expiry_settings` section lets you define if and when hosts should be removed from Fleet if they have not checked in. Once a host has been removed from Fleet, it will need to re-enroll with a valid `enroll_secret` to connect to your Fleet instance.
Whether offline hosts' expiration is enabled. If `host_expiry_enabled` is set to `true`, Fleet allows automatic cleanup of hosts that have not communicated with Fleet in some number of days.
For more information about integrations and Fleet automations in general, see the [Automations documentation](https://fleetdm.com/docs/using-fleet/automations). Only one automation can be enabled for a given automation type (e.g., for failing policies, only one of the webhooks, the Jira integration, or the Zendesk automation can be enabled).
It's recommended to use the Fleet UI to configure integrations since secret credentials (in the form of an API token) must be provided. See the [Automations documentation](https://fleetdm.com/docs/using-fleet/automations) for the UI configuration steps.
There's a lot of information coming from hosts, but it's sometimes useful to see exactly what a host is returning in order
to debug different scenarios.
For example, let's say the hosts with ids 342 and 98 are not behaving as you expect in Fleet. You can enable verbose
logging with the following configuration:
```yaml
---
apiVersion: v1
kind: config
spec:
server_settings:
debug_host_ids:
- 342
- 98
```
Once you have collected the logs, you can easily disable the debug logging by applying the following configuration:
```yaml
---
apiVersion: v1
kind: config
spec:
server_settings:
debug_host_ids: []
```
> **Warning:** This will potentially log a lot of data. Some of that data might be private. Please verify it before posting it
in a public channel or a GitHub issue.
- Optional setting (array of integers)
- Default value: empty
- Config file format:
```
server_settings:
debug_host_ids:
- 342
- 98
```
##### server_settings.deferred_save_host
Whether saving host-related information is done synchronously in the HTTP handler of the host's request, or asynchronously. This can provide better performance in deployments with many hosts. Note that this is an **experimental feature**.
It's recommended to use the Fleet UI to configure SMTP since a secret password must be provided. Navigate to **Settings -> Organization settings -> SMTP Options** to proceed with this configuration.
For additional information on SSO configuration, including just-in-time (JIT) user provisioning, creating SSO users in Fleet, and identity providers configuration, see [Configuring single sign-on (SSO)](https://fleetdm.com/docs/deploying/configuration#configuring-single-sign-on-sso).
**Available in Fleet Premium**. Enables [just-in-time user provisioning](https://fleetdm.com/docs/deploying/configuration#just-in-time-jit-user-provisioning).
The required entity ID is 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.
- Required setting if SSO is enabled, must have at least 5 characters (string)
For more information about webhooks and Fleet automations in general, see the [Automations documentation](https://fleetdm.com/docs/using-fleet/automations).
The interval at which to check for webhook conditions. This value currently configures both the host status and failing policies webhooks, but not the recent vulnerabilities webhook. (See the [Recent vulnerabilities section](#recent-vulnerabilities) for details.)
Defines whether to enable the failing policies webhook. Note that currently, if the failing policies webhook and the `osquery.enable_async_host_processing` options are set, some failing policies webhooks could be missing. Some transitions from succeeding to failing or vice-versa could happen without triggering a webhook request.
Maximum number of hosts to batch on `POST` requests. A value of `0`, the default, means no batching. All hosts failing a policy will be sent on one `POST` request.
The following options allow the configuration of a webhook that will be triggered if the specified percentage of hosts are offline for the specified amount of time.
The following options allow the configuration of a webhook that will be triggered if recently published vulnerabilities are detected and there are affected hosts. A vulnerability is considered recent if it has been published in the last 30 days (based on the National Vulnerability Database, NVD).
Note that the recent vulnerabilities webhook is not checked at `webhook_settings.interval` like other webhooks. It is checked as part of the vulnerability processing and runs at the `vulnerabilities.periodicity` interval specified in the [fleet configuration](https://fleetdm.com/docs/deploying/configuration#periodicity).
Maximum number of hosts to batch on `POST` requests. A value of `0`, the default, means no batching. All hosts affected will be sent on one `POST` request.
See the [osquery documentation](https://osquery.readthedocs.io/en/stable/installation/cli-flags/#configuration-control-flags) for the available options. This document shows all examples in command line flag format. Remove the dashed lines (`--`) for Fleet to successfully update the setting. For example, use `distributed_interval` instead of `--distributed_interval`.
You can verify that your agent options are valid by using [the fleetctl apply command](https://fleetdm.com/docs/using-fleet/fleetctl-cli#fleetctl-apply) with the `--dry-run` flag. This will report any error and do nothing if the configuration was valid. If you don't use the latest version of osquery, you can override validation using the `--force` flag. This will update agent options even if they are invalid.
> This feature requires [Orbit, the Fleet agent manager](https://fleetdm.com/announcements/introducing-orbit-your-fleet-agent-manager).
The `command_line_flags` key inside of `agent_options` allows you to remotely manage the osquery command line flags. These command line flags are options that typically require osquery to restart for them to take effect. But with Orbit, you can use the `command_line_flags` key to take care of that. Orbit will write these to the flagfile on the host and pass it to osquery.
To see the full list of these osquery command line flags, please run `osquery` with the `--help` switch.
Just like the other `agent_options` above, remove the dashed lines (`--`) for Fleet to successfully update them.
Here is an example of using the `command_line_flags` key:
Note that the `command_line_flags` key does not support the `overrides` key, which is documented below.
You can verfiy that these flags have taken effect on the hosts by running a query against the `osquery_flags` table.
If you revoked an old enroll secret, this feature won't work for hosts that were added to Fleet using this old enroll secret. This is because Orbit uses the enroll secret to receive new flags from Fleet. For these hosts, all existing features will work as expected.
For further documentation on how to rotate enroll secrets, please see [this guide](https://fleetdm.com/docs/deploying/faq#how-can-enroll-secrets-be-rotated).
If you prefer to deploy a new package with the updated enroll secret:
1. Check which hosts need a new enroll secret by running the following query: `SELECT * FROM orbit_info WHERE enrolled = false`.
> The hosts that don't have Orbit installed will return an error because the `orbit_info` table doesn't exist. You can safely ignore these errors.
2. In Fleet, head to the Hosts page and select **Add hosts** to find the fleetctl package command with an active enroll secret.
3. Copy and run the fleetctl package command to create a new package. Distribute this package to the hosts that returned results in step 1.
> In order for these options to be applied to your hosts, the `osquery` agent must be configured to use the `tls` config plugin and pointed to the correct endpoint. If you are using Orbit to enroll your hosts, this is done automatically.
> This feature requires [Orbit, the Fleet agent manager](https://fleetdm.com/announcements/introducing-orbit-your-fleet-agent-manager), along with a custom TUF auto-update server.
The `extensions` key inside of `agent_options` allows you to remotely manage and deploy osquery extensions. Just like other `agent_options` the `extensions` key can be applied either to a team specific one or the global one.
This is best illustrated with an example. Here is an example of using the `extensions` key:
```yaml
apiVersion: v1
kind: config
spec:
agent_options:
extensions: # requires Fleet's osquery installer
hello_world:
channel: 'stable'
platform: 'macos'
```
In the above example, we are configuring our `hello_world` extension. We do this by creating a `hello_world` sub-key under `extensions`, and then specifying the `channel` and `platform` keys for that extension.
Next, you will need to make sure to push the binary file of our `hello_world` extension as a target on your TUF server. This step needs to follow these conventions:
* The binary file of the extension, must have the same name as the extension, followed by the `.ext`. In the above case, the filename should be `hello_world.ext`
* The target name for the TUF server must be named as `extensions/<extension_name>`. For the above example, this would be `extensions/hello_world`
*`platform` is one of `macos`, `linux`, or `windows`
If you are using `fleetctl` to manage your TUF server, these same conventions apply. You can run the following command to add a new target:
After successfully configuring the agent options, and pushing the extension as a target on your TUF server, Orbit will periodically check with the TUF server for updates to these extensions.
If you are using a self-hosted TUF server, you must also manage all of Orbit's versions, including osquery, Fleet Desktop and osquery extensions.
Fleet recommends deploying extensions created with osquery-go or natively with C++, instead of Python. Extensions written in Python requires the user to compile it into a single packaged binary along with all the dependencies.
The config key sets the osqueryd configuration options for your agents. In a plain osquery deployment, these would typically be set in `osquery.conf`. Each key below represents a corresponding key in the osquery documentation.
For detailed information on osquery configuration options, check out the [osquery configuration docs](https://osquery.readthedocs.io/en/stable/deployment/configuration/).
In the options key, you can set your osqueryd options and feature flags.
Any command line only flags must be set using the `command_line_flags` key for Orbit agents, or by modifying the osquery flags on your hosts if you're using plain osquery.
To see a full list of flags, broken down by the method you can use to set them (configuration options vs command line flags), you can run `osqueryd --help` on a plain osquery agent. For Orbit agents, run `sudo orbit osqueryd --help`. The options will be shown there in command line format as `--key value`. In `yaml` format, that would become `key: value`.
In the decorators key, you can specify queries to include additional information in your osquery results logs.
Use `load` for details you want to update values when the configuration loads, `always` to update every time a scheduled query is run, and `interval` if you want to update on a schedule.
```yaml
agent_options:
config:
options: ~
decorators:
load:
- "SELECT version FROM osquery_info"
- "SELECT uuid AS host_uuid FROM system_info"
always:
- "SELECT user AS username FROM logged_in_users WHERE user <> '' ORDER BY time LIMIT 1"
interval:
3600: "SELECT total_seconds AS uptime FROM uptime"
You can use Fleet to configure the `yara` and `yara_events` osquery tables. Fore more information on YARA configuration and continuous monitoring using the `yara_events` table, check out the [YARA-based scanning with osquery section](https://osquery.readthedocs.io/en/stable/deployment/yara/) of the osquery documentation.
The following is an example Fleet configuration file with YARA configuration. The values are taken from an example config supplied in the above link to the osquery documentation.
The `overrides` key allows you to segment hosts, by their platform, and supply these groups with unique osquery configuration options. When you choose to use the overrides option for a specific platform, all options specified in the default configuration will be ignored for that platform.
In the example file below, all Darwin and Ubuntu hosts will **only** receive the options specified in their respective overrides sections.
```yaml
agent_options:
config:
options: ~
overrides:
# Note configs in overrides take precedence over the default config defined
# under the config key above. Hosts receive overrides based on the platform
# returned by `SELECT platform FROM os_version`. In this example, the base
# config would be used for Windows and CentOS hosts, while Mac and Ubuntu
# hosts would receive their respective overrides. Note, these overrides are
# NOT merged with the top level configuration.
platforms:
darwin:
options:
distributed_interval: 10
distributed_tls_max_attempts: 10
logger_tls_endpoint: /api/osquery/log
logger_tls_period: 300
disable_tables: chrome_extensions
docker_socket: /var/run/docker.sock
file_paths:
users:
- /Users/%/Library/%%
- /Users/%/Documents/%%
etc:
- /etc/%%
```
##### agent_options.auto_table_construction
You can use Fleet to query local SQLite databases as tables. For more information on creating ATC configuration from a SQLite database, check out the [Automatic Table Construction section](https://osquery.readthedocs.io/en/stable/deployment/configuration/#automatic-table-construction) of the osquery documentation.
If you already know what your ATC configuration needs to look like, you can add it to an options config file:
```yaml
apiVersion: v1
kind: config
spec:
agent_options:
config:
options:
# ...
overrides:
platforms:
darwin:
auto_table_construction:
tcc_system_entries:
query: "SELECT service, client, allowed, prompt_count, last_modified FROM access"
The following options allow to configure the behavior of Nudge for macOS hosts that belong to no team and are enrolled into Fleet's MDM.
##### mdm.macos_updates.minimum_version
Hosts that belong to no team and are enrolled into Fleet's MDM will be nudged until their macOS is at or above this version.
Requires `mdm.macos_updates.deadline` to be set.
- Default value: ""
- Config file format:
```yaml
mdm:
macos_updates:
minimum_version: "12.1.1"
```
##### mdm.macos_updates.deadline
A deadline in the form `YYYY-MM-DD`. Hosts that belong to no team and are enrolled into Fleet's MDM won't be able to dismiss the Nudge window once this deadline is past.
Requires `mdm.macos_updates.minimum_version` to be set.
> **Note:** More settings are included in the [contributor documentation](https://fleetdm.com/docs/contributing/configuration-for-contributors). It's possible, although not recommended, to configure these settings in the YAML configuration file.
