Elgato_dark/fleet
1
0
Fork 0
mirror of https://github.com/fleetdm/fleet synced 2026-04-21 21:47:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 117
fleet/docs/Configuration/agent-configuration.md

310 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

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.

# Agent configuration
Agent configuration (agent options) updates the settings of the [Fleet agent (fleetd)](https://fleetdm.com/docs/get-started/anatomy#fleetd) installed on all your hosts.
You can modify agent options in **Settings > Organization settings > Agent options** or via Fleet's [API](https://fleetdm.com/docs/rest-api/rest-api#modify-configuration) or [YAML files](https://fleetdm.com/docs/configuration/yaml-files).
## config
The `config` section allows you to update settings like performance and and how often the agent checks-in.
#### Example
```yaml
config:
options:
distributed_interval: 3
distributed_tls_max_attempts: 3
logger_tls_endpoint: /api/osquery/log
logger_tls_period: 10
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"
yara:
file_paths:
system_binaries:
- sig_group_1
tmp:
- sig_group_1
- sig_group_2
signatures:
sig_group_1:
- /Users/wxs/sigs/foo.sig
- /Users/wxs/sigs/bar.sig
sig_group_2:
- /Users/wxs/sigs/baz.sig
command_line_flags:
verbose: true
disable_watchdog: false
disable_tables: chrome_extensions
logger_path: /path/to/logger
```
### options and command_line_flags
- `options` include the agent settings listed under `osqueryOptions` in [`agent_options_generated.go`](https://github.com/fleetdm/fleet/blob/main/server/fleet/agent_options_generated.go). These can be updated without a fleetd restart.
- `command_line_flags` include the agent settings listed under osqueryCommandLineFlags in [`agent_options_generated.go`](https://github.com/fleetdm/fleet/blob/main/server/fleet/agent_options_generated.go). These are only updated when fleetd restarts.
To see a description for all available settings, first [enroll your host](https://fleetdm.com/guides/enroll-hosts) to Fleet. Then, open your **Terminal** app and run `sudo orbit shell` to open an interactive osquery shell. Then run the following osquery query:
```
osquery > SELECT name, default_value, value, description FROM osquery_flags;
```
Running the interactive osquery shell loads a standalone instance of osquery, with a default configuration rather than the one set in agent options. If you'd like to verify that your hosts are running with the latest settings set in `options`, run the report as a live report in Fleet.
> If you revoke an old enroll secret, the `command_line_flags` won't update for hosts that enrolled to Fleet using this old enroll secret. This is because fleetd uses the enroll secret to receive new flags from Fleet. For these hosts, all existing features will work as expected.
#### Advanced
`options` and `command_line_flags` are validated using the latest version of osquery. If you are not using the latest version of osquery, you can create a YAML file and apply it with `fleetctl apply --force` command to override the validation:
```sh
fleetctl apply --force -f config.yaml
```
### decorators
In the `decorators` key, you can specify queries to include additional information in your osquery results logs.
- `load` are queries you want to update values when the configuration loads.
- `always` are queries to update every time a scheduled report is run.
- `interval` are queries you want to update on a schedule.
### yara
You can use Fleet to configure the `yara` and `yara_events` osquery tables, used to administer [YARA rules](https://fleetdm.com/guides/remote-yara-rules) for continuous monitoring.
## extensions
> This feature requires a custom TUF [auto-update server](https://fleetdm.com/guides/fleetd-updates) (available in Fleet Premium).
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 specific fleet specific or global across all fleets.
#### Example
```yaml
agent_options:
extensions: # requires Fleet's agent (fleetd)
hello_world_macos:
channel: 'stable'
platform: 'macos'
hello_world_linux:
channel: 'stable'
platform: 'linux'
hello_world_linux_arm64:
channel: 'stable'
platform: 'linux-arm64'
hello_world_windows:
channel: 'stable'
platform: 'windows'
hello_world_windows_arm64:
channel: 'stable'
platform: 'windows-arm64'
```
In the above example, we are configuring our `hello_world` extensions for all the supported operating systems. We do this by creating `hello_world_{macos|linux|linux_arm64|windows|windows_arm64}` subkeys under `extensions`, and then specifying the `channel` and `platform` keys for each extension entry.
Next, you will need to make sure to push the binary files 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 `.ext` for macOS and Linux extensions and by `.ext.exe` for Windows extensions.
In the above case, the filename for macOS should be `hello_world_macos.ext`, for Linux it should be `hello_world_linux.ext`, for Linux arm64 it should be `hello_world_linux_arm64.ext`, for Windows it should be `hello_world_windows.ext.exe`, and for Windows arm64 it should be `hello_world_windows_arm64.ext.exe`.
* The target name for the TUF server must be named as `extensions/<extension_name>`. For the above example, this would be `extensions/hello_world_{macos|linux|linux_arm64|windows|windows_arm64}`
* The `platform` field is one of `macos`, `linux`, `linux-arm64`, `windows`, or `windows-arm64`.
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:
```bash
fleetctl updates add \
--path /path/to/local/TUF/repo \
--target /path/to/extensions/binary/hello_world_macos.ext \
--name extensions/hello_world_macos \
--platform macos \
--version 0.1
fleetctl updates add \
--path /path/to/local/TUF/repo
--target /path/to/extensions/binary/hello_world_linux.ext \
--name extensions/hello_world_linux \
--platform linux \
--version 0.1
fleetctl updates add \
--path /path/to/local/TUF/repo
--target /path/to/extensions/binary/hello_world_linux_arm64.ext \
--name extensions/hello_world_linux_arm64 \
--platform linux-arm64 \
--version 0.1
fleetctl updates add \
--path /path/to/local/TUF/repo \
--target /path/to/extensions/binary/hello_world_windows.ext.exe \
--name extensions/hello_world_windows \
--platform windows \
--version 0.1
fleetctl updates add \
--path /path/to/local/TUF/repo \
--target /path/to/extensions/binary/hello_world_windows_arm64.ext.exe \
--name extensions/hello_world_windows_arm64 \
--platform windows-arm64 \
--version 0.1
```
After successfully configuring the agent options, and pushing the extension as a target on your TUF server, Fleetd 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 Fleetd'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 require the user to compile it into a single packaged binary along with all the dependencies.
### Targeting extensions with labels
_Available in Fleet Premium_
Fleet allows you to target extensions to hosts that belong to specific labels. To set these labels, you'll need to define a `labels` list under the extension name.
The label names in the list:
- must already exist (otherwise the `/api/latest/fleet/config` request will fail).
- are case insensitive.
- must **all** apply to a host in order to deploy the extension to that host.
#### Example
```yaml
agent_options:
extensions: # requires Fleet's agent (fleetd)
hello_world_macos:
channel: 'stable'
platform: 'macos'
labels:
- Zoom installed
hello_world_linux:
channel: 'stable'
platform: 'linux'
labels:
- Ubuntu Linux
- Zoom installed
hello_world_windows:
channel: 'stable'
platform: 'windows'
```
In the above example:
- the `hello_world_macos` extension is deployed to macOS hosts that are members of the 'Zoom installed' label.
- the `hello_world_linux` extension is deployed to Linux hosts that are members of the 'Ubuntu Linux' **and** 'Zoom installed' labels.
## update_channels
_Available in Fleet Premium_
Users can configure fleetd component TUF [auto-update channels](https://fleetdm.com/docs/using-fleet/enroll-hosts#specifying-update-channels) from Fleet's agent options. The components that can be configured are `orbit`, `osqueryd` and `desktop` (Fleet Desktop). When one of these components is omitted in `update_channels` then `stable` is assumed as the value for such component.
New agents default to the latest versions unless specific versions are set in the `fleetctl package` command. If `update_channels` specifies versions, agents will use those instead, even if it means downgrading (e.g., generating at 1.53.1 but enrolling with `update_channels.orbit` set to 1.50.0).
> Because Fleet moved the update server from tuf.fleetctl.com to updates.fleetdm.com, Orbit versions below 1.38.1 can’t upgrade directly to newer versions. You’ll see this error in Orbit logs: `update failed error="lookup failed: lookup orbit: tuf: file not found`. To upgrade from a version below 1.38.1 (e.g., 1.29.1) to a newer version (e.g., 1.50.2), first upgrade to 1.38.1, wait for agents to update, then upgrade to the newer version.
#### Examples
```yaml
agent_options:
update_channels: # requires Fleet's agent (fleetd)
orbit: stable
osqueryd: '5.10.2'
desktop: edge
```
```yaml
agent_options:
update_channels: # requires Fleet's agent (fleetd)
orbit: edge
osqueryd: '5.10.2'
# in this configuration `desktop` is assumed to be "stable"
```
- If a configured channel doesn't exist in the TUF repository, then fleetd will log errors on the hosts and will not auto-update the component/s until the channel is changed to a valid value in Fleet's `update_channels` configuration or until the user pushes the component to the channel (which effectively creates the channel).
- If the `update_channels` setting is removed from the agent settings, the devices will continue to use the last configured channels.
- If Fleet Desktop is disabled in fleetd, then the `desktop` channel setting is ignored by the host.
#### Auto update startup loop
Following we document an edge case scenario that could happen when using this feature.
After upgrading `orbit` on your devices to `1.20.0` using this feature, beware of downgrading `orbit` by changing it to a channel that's older than `1.20.0`. The auto-update system in orbit could end up in an update startup loop (where orbit starts, changes its channel and restarts over and over).
Following are the conditions (to avoid) that lead to the auto-update loop:
1. fleetd with `orbit` < `1.20.0` was packaged/configured to run with orbit channel `A`.
2. `orbit`'s channel `A` is updated to >= `1.20.0`.
3. `orbit`'s channel in the Fleet agent settings is configured to `B`, where channel `B` has orbit version < `1.20.0`.
This update startup loop can be fixed by any one of these actions:
A. Downgrading channel `A` to < `1.20.0`.
B. Upgrading channel `B` to >= `1.20.0`.
## overrides
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.
Note that the `command_line_flags` key is not supported in the `overrides`.
In the example file below, all macOS hosts will **only** receive the options specified in their respective overrides sections.
If a given option is not specified in a platform override section, its default value will be enforced.
#### Example
```yaml
agent_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, Ubuntu, and CentOS hosts, while Mac
# 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
docker_socket: /var/run/docker.sock
file_paths:
users:
- /Users/%/Library/%%
- /Users/%/Documents/%%
etc:
- /etc/%%
auto_table_construction:
tcc_system_entries:
# This query and its columns are restricted for compatibility. Open TCC.db with sqlite on
# your endpoints to expand this out.
query: "SELECT service, client, last_modified FROM access"
# Note that TCC.db requires fleetd to have full-disk access, ensure that endpoints have
# this enabled.
path: "/Library/Application Support/com.apple.TCC/TCC.db"
columns:
- "service"
- "client"
- "last_modified"
```
### 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.
## script_execution_timeout
The `script_execution_timeout` allows you to change the default script execution timeout (default: `300` seconds, maximum: `18000`).
#### Example
```yaml
agent_options:
script_execution_timeout: 600
```
<meta name="pageOrderInSection" value="300">
<meta name="description" value="Learn how to use configuration files and the fleetctl command line tool to configure agent options.">
Reference in a new issue View git blame Copy permalink