We surveyed 200+ security practitioners to discover the state of device management in 2022.
Click here to learn about their struggles and best practices.Welcome to the documentation for Fleet, an open-source osquery management server.
Install osquery and Fleet
Get startedCan't find what you need?
SupportFor information on how to run the fleet
binary, detailed usage information can be found by running fleet --help
. This document is a more detailed version of the information presented in the help output text. If you prefer to use a CLI instead of a web browser, we hope that you like the binary interface to the Fleet application!
To get the most out of running the Fleet server, it is helpful to establish a mutual understanding of what the desired architecture looks like and what it's trying to accomplish.
Your Fleet server's two main purposes are:
The Fleet server allows you persist configuration, manage users, etc. Thus, it needs a database. Fleet uses MySQL and requires you to supply configurations to connect to a MySQL server. It is also possible to configure connection to a MySQL replica in addition to the primary, to be used for reading only. Fleet also uses Redis to perform some more high-speed data access action throughout the lifecycle of the application (for example, distributed query result ingestion). Thus, Fleet also requires that you supply Redis connection configurations.
Fleet can scale to hundreds of thousands of devices with a single Redis instance, and is also compatible with Redis Cluster. Fleet does not support Redis Sentinel.
Since Fleet is a web application, when you run Fleet there are some other configurations that must be defined, such as:
When deploying Fleet, mitigate DoS attacks as you would when deploying any app.
Since Fleet is an osquery TLS server, you are also able to define configurations that can customize your experience there, such as:
The fleet
binary contains several "commands". Similarly to how git
has many commands (git status
, git commit
, etc), the fleet
binary accepts the following commands:
fleet prepare db
fleet serve
fleet version
fleet config_dump
In order of precedence, options can be specified via:
For example, all of the following ways of launching Fleet are equivalent:
/usr/bin/fleet serve \
--mysql_address=127.0.0.1:3306 \
--mysql_database=fleet \
--mysql_username=root \
--mysql_password=toor \
--redis_address=127.0.0.1:6379 \
--server_cert=/tmp/server.cert \
--server_key=/tmp/server.key \
--logging_json
FLEET_MYSQL_ADDRESS=127.0.0.1:3306 \
FLEET_MYSQL_DATABASE=fleet \
FLEET_MYSQL_USERNAME=root \
FLEET_MYSQL_PASSWORD=toor \
FLEET_REDIS_ADDRESS=127.0.0.1:6379 \
FLEET_SERVER_CERT=/tmp/server.cert \
FLEET_SERVER_KEY=/tmp/server.key \
FLEET_LOGGING_JSON=true \
/usr/bin/fleet serve
echo '
mysql:
address: 127.0.0.1:3306
database: fleet
username: root
password: toor
redis:
address: 127.0.0.1:6379
server:
cert: /tmp/server.cert
key: /tmp/server.key
logging:
json: true
' > /tmp/fleet.yml
fleet serve --config /tmp/fleet.yml
For more information on using YAML configuration files with fleet, please see the configuration files documentation.
Note that all option names can be converted consistently from flag name to environment variable and visa-versa. For example, the --mysql_address
flag would be the FLEET_MYSQL_ADDRESS
. Further, specifying the mysql_address
option in the config would follow the pattern:
mysql:
address: 127.0.0.1:3306
And mysql_read_replica_address
would be:
mysql_read_replica:
address: 127.0.0.1:3307
Basically, just capitalize the option and prepend FLEET_
to it in order to get the environment variable. The conversion works the same the opposite way.
All duration-based settings accept valid time units of s
, m
, h
.
This section describes the configuration options for the primary - if you also want to setup a read replica, the options are the same, except that the yaml section is mysql_read_replica
, and the flags have the mysql_read_replica_
prefix instead of mysql_
(the corresponding environment variables follow the same transformation). Note that there is no default value for mysql_read_replica_address
, it must be set explicitly for Fleet to use a read replica, and it is recommended in that case to set a non-zero value for mysql_read_replica_conn_max_lifetime
as in some environments, the replica's address may dynamically change to point
from the primary to an actual distinct replica based on auto-scaling options, so existing idle connections need to be recycled
periodically.
The address of the MySQL server which Fleet should connect to. Include the hostname and port.
Default value: localhost:3306
Environment variable: FLEET_MYSQL_ADDRESS
Config file format:
mysql:
address: localhost:3306
The name of the MySQL database which Fleet will use.
Default value: fleet
Environment variable: FLEET_MYSQL_DATABASE
Config file format:
mysql:
database: fleet
The username to use when connecting to the MySQL instance.
Default value: fleet
Environment variable: FLEET_MYSQL_USERNAME
Config file format:
mysql:
username: fleet
The password to use when connecting to the MySQL instance.
Default value: fleet
Environment variable: FLEET_MYSQL_PASSWORD
Config file format:
mysql:
password: fleet
File path to a file that contains the password to use when connecting to the MySQL instance.
Default value: ""
Environment variable: FLEET_MYSQL_PASSWORD_PATH
Config file format:
mysql:
password_path: '/run/secrets/fleetdm-mysql-password'
The path to a PEM encoded certificate of MYSQL's CA for client certificate authentication.
Default value: none
Environment variable: FLEET_MYSQL_TLS_CA
Config file format:
mysql:
tls_ca: /path/to/server-ca.pem
The path to a PEM encoded certificate use for tls authentication.
Default value: none
Environment variable: FLEET_MYSQL_TLS_CERT
Config file format:
mysql:
tls_cert: /path/to/certificate.pem
The path to a PEM encoded private key use for tls authentication.
Default value: none
Environment variable: FLEET_MYSQL_TLS_KEY
Config file format:
mysql:
tls_key: /path/to/key.pem
The tls value in a MYSQL DSN. Can be true
,false
,skip-verify
or the CN value of the certificate.
Default value: none
Environment variable: FLEET_MYSQL_TLS_CONFIG
Config file format:
mysql:
tls_config: true
The server name or IP address used by the client certificate.
Default value: none
Environment variable: FLEET_MYSQL_TLS_SERVER_NAME
Config file format:
mysql:
server_name: 127.0.0.1
Maximum open connections to database
Default value: 50
Environment variable: FLEET_MYSQL_MAX_OPEN_CONNS
Config file format:
mysql:
max_open_conns: 50
Maximum idle connections to database. This value should be equal to or less than mysql_max_open_conns
Default value: 50
Environment variable: FLEET_MYSQL_MAX_IDLE_CONNS
Config file format:
mysql:
max_idle_conns: 50
Maximum amount of time, in seconds, a connection may be reused.
Default value: 0 (Unlimited)
Environment variable: FLEET_MYSQL_CONN_MAX_LIFETIME
Config file format:
mysql:
conn_max_lifetime: 50
apiVersion: v1
kind: config
spec:
msyql:
address: localhost:3306
database: fleet
password: fleet
max_open_conns: 50
max_idle_conns: 50
conn_max_lifetime: 50
Note that a TLS connection to a Redis instance can be tested by running the
tlsconnect
Go program in tools/redis-tests
, e.g. from the root of the repository:
$ go run ./tools/redis-tests/tlsconnect.go -addr <redis_address> -cacert <redis_tls_ca> -cert <redis_tls_cert> -key <redis_tls_key>
# run `go run ./tools/redis-tests/tlsconnect.go -h` for the full list of supported flags
By default, this will setup a Redis pool for that configuration and execute a
PING
command with a TLS connection, printing any error it encounters.
The address of the Redis server which Fleet should connect to. Include the hostname and port.
Default value: localhost:6379
Environment variable: FLEET_REDIS_ADDRESS
Config file format:
redis:
address: 127.0.0.1:7369
The password to use when connecting to the Redis instance.
Default value: <empty>
Environment variable: FLEET_REDIS_PASSWORD
Config file format:
redis:
password: foobar
The database to use when connecting to the Redis instance.
Default value: 0
Environment variable: FLEET_REDIS_DATABASE
Config file format:
redis:
database: 14
Use a TLS connection to the Redis server.
Default value: false
Environment variable: FLEET_REDIS_USE_TLS
Config file format:
redis:
use_tls: true
Whether or not to duplicate Live Query results to another Redis channel named LQDuplicate
. This is useful in a scenario that would involve shipping the Live Query results outside of Fleet, near-realtime.
Default value: false
Environment variable: FLEET_REDIS_DUPLICATE_RESULTS
Config file format:
redis:
duplicate_results: true
Timeout for redis connection.
Default value: 5s
Environment variable: FLEET_REDIS_CONNECT_TIMEOUT
Config file format:
redis:
connect_timeout: 10s
Interval between keep alive probes.
Default value: 10s
Environment variable: FLEET_REDIS_KEEP_ALIVE
Config file format:
redis:
keep_alive: 30s
Maximum number of attempts to retry a failed connection to a redis node. Only certain type of errors are retried, such as connection timeouts.
Default value: 0 (no retry)
Environment variable: FLEET_REDIS_CONNECT_RETRY_ATTEMPTS
Config file format:
redis:
connect_retry_attempts: 2
Whether or not to automatically follow redirection errors received from the Redis server. Applies only to Redis Cluster setups, ignored in standalone Redis. In Redis Cluster, keys can be moved around to different nodes when the cluster is unstable and reorganizing the data. With this configuration option set to true, those (typically short and transient) redirection errors can be handled transparently instead of ending in an error.
Default value: false
Environment variable: FLEET_REDIS_CLUSTER_FOLLOW_REDIRECTIONS
Config file format:
redis:
cluster_follow_redirections: true
Whether or not to prefer reading from a replica when possible. Applies only to Redis Cluster setups, ignored in standalone Redis.
Default value: false
Environment variable: FLEET_REDIS_CLUSTER_READ_FROM_REPLICA
Config file format:
redis:
cluster_read_from_replica: true
The path to a PEM-encoded certificate used for tls authentication.
Default value: none
Environment variable: FLEET_REDIS_TLS_CERT
Config file format:
redis:
tls_cert: /path/to/certificate.pem
The path to a PEM-encoded private key used for tls authentication.
Default value: none
Environment variable: FLEET_REDIS_TLS_KEY
Config file format:
redis:
tls_key: /path/to/key.pem
The path to a PEM-encoded certificate of Redis' CA for client certificate authentication.
Default value: none
Environment variable: FLEET_REDIS_TLS_CA
Config file format:
redis:
tls_ca: /path/to/server-ca.pem
The server name or IP address used by the client certificate.
Default value: none
Environment variable: FLEET_REDIS_TLS_SERVER_NAME
Config file format:
redis:
tls_server_name: 127.0.0.1
The timeout for the Redis TLS handshake part of the connection. A value of 0 means no timeout.
Default value: 10s
Environment variable: FLEET_REDIS_TLS_HANDSHAKE_TIMEOUT
Config file format:
redis:
tls_handshake_timeout: 10s
Maximum idle connections to Redis. This value should be equal to or less than redis_max_open_conns
.
Default value: 3
Environment variable: FLEET_REDIS_MAX_IDLE_CONNS
Config file format:
redis:
max_idle_conns: 50
Maximum open connections to Redis. A value of 0 means no limit.
Default value: 0
Environment variable: FLEET_REDIS_MAX_OPEN_CONNS
Config file format:
redis:
max_open_conns: 100
Maximum amount of time a Redis connection may be reused. A value of 0 means no limit.
Default value: 0 (Unlimited)
Environment variable: FLEET_REDIS_CONN_MAX_LIFETIME
Config file format:
redis:
conn_max_lifetime: 30m
Maximum amount of time a Redis connection may stay idle. A value of 0 means no limit.
Default value: 240s
Environment variable: FLEET_REDIS_IDLE_TIMEOUT
Config file format:
redis:
idle_timeout: 5m
Maximum amount of time to wait for a Redis connection if the max_open_conns limit is reached. A value of 0 means no wait. This is ignored if Redis is not running in cluster mode.
Default value: 0
Environment variable: FLEET_REDIS_CONN_WAIT_TIMEOUT
Config file format:
redis:
conn_wait_timeout: 1s
Maximum amount of time to wait to receive a response from a Redis server. A value of 0 means no timeout.
Default value: 10s
Environment variable: FLEET_REDIS_READ_TIMEOUT
Config file format:
redis:
read_timeout: 5s
Maximum amount of time to wait to send a command to a Redis server. A value of 0 means no timeout.
Default value: 10s
Environment variable: FLEET_REDIS_WRITE_TIMEOUT
Config file format:
redis:
write_timeout: 5s
apiVersion: v1
kind: config
spec:
redis:
address: localhost:7369
password: foobar
database: 14
connect_timeout: 10s
connect_retry_attempts: 2
The address to serve the Fleet webserver.
Default value: 0.0.0.0:8080
Environment variable: FLEET_SERVER_ADDRESS
Config file format:
server:
address: 0.0.0.0:443
The TLS cert to use when terminating TLS.
See TLS certificate considerations for more information about certificates and Fleet.
Default value: ./tools/osquery/fleet.crt
Environment variable: FLEET_SERVER_CERT
Config file format:
server:
cert: /tmp/fleet.crt
The TLS key to use when terminating TLS.
Default value: ./tools/osquery/fleet.key
Environment variable: FLEET_SERVER_KEY
Config file format:
server:
key: /tmp/fleet.key
Whether or not the server should be served over TLS.
Default value: true
Environment variable: FLEET_SERVER_TLS
Config file format:
server:
tls: false
Configures the TLS settings for compatibility with various user agents. Options are modern
and intermediate
. These correspond to the compatibility levels defined by the Mozilla OpSec team (updated July 24, 2020).
Default value: intermediate
Environment variable: FLEET_SERVER_TLS_COMPATIBILITY
Config file format:
server:
tls_compatibility: intermediate
Sets a URL prefix to use when serving the Fleet API and frontend. Prefixes should be in the form /apps/fleet
(no trailing slash).
Note that some other configurations may need to be changed when modifying the URL prefix. In particular, URLs that are provided to osquery via flagfile, the configuration served by Fleet, the URL prefix used by fleetctl
, and the redirect URL set with an identity provider.
Default value: Empty (no prefix set)
Environment variable: FLEET_SERVER_URL_PREFIX
Config file format:
server:
url_prefix: /apps/fleet
Controls the server side http keep alive property.
Turning off keepalives has helped reduce outstanding TCP connections in some deployments.
Default value: true
Environment variable: FLEET_SERVER_KEEPALIVE
Config file format:
server:
keepalive: true
apiVersion: v1
kind: config
spec:
server:
address: 0.0.0.0:443
password: foobar
cert: /tmp/fleet.crt
key: /tmp/fleet.key
invite_token_validity_period: 1d
The bcrypt cost to use when hashing user passwords.
Default value: 12
Environment variable: FLEET_AUTH_BCRYPT_COST
Config file format:
auth:
bcrypt_cost: 14
The key size of the salt which is generated when hashing user passwords.
Default value: 24
Environment variable: FLEET_AUTH_SALT_KEY_SIZE
Config file format:
auth:
salt_key_size: 36
apiVersion: v1
kind: config
spec:
auth:
bcrypt_cost: 14
salt_key_size: 36
Size of generated app tokens.
Default value: 24
Environment variable: FLEET_APP_TOKEN_KEY_SIZE
Config file format:
app:
token_key_size: 36
How long invite tokens should be valid for.
Default value: 5 days
Environment variable: FLEET_APP_INVITE_TOKEN_VALIDITY_PERIOD
Config file format:
app:
invite_token_validity_period: 1d
Determines whether Fleet gets scheduled query statistics from hosts or not.
Default value: true
Environment variable: FLEET_APP_ENABLE_SCHEDULED_QUERY_STATS
Config file format:
app:
enable_scheduled_query_stats: true
apiVersion: v1
kind: config
spec:
app:
token_key_size: 36
salt_key_size: 36
invite_token_validity_period: 1d
The license key provided to Fleet customers which provides access to Fleet Premium features.
Default value: none
Environment variable: FLEET_LICENSE_KEY
Config file format:
license:
key: foobar
Whether Fleet should enforce the host limit of the license, if true, attempting to enroll new hosts when the limit is reached will fail.
Default value: false
Environment variable: FLEET_LICENSE_ENFORCE_HOST_LIMIT
Config file format:
license:
enforce_host_limit: true
apiVersion: v1
kind: config
spec:
license:
key: foobar
enforce_host_limit: false
The size of the session key.
Default value: 64
Environment variable: FLEET_SESSION_KEY_SIZE
Config file format:
session:
key_size: 48
The amount of time that a session should last for.
Valid time units are s
, m
, h
.
Default value: 5d
(5 days)
Environment variable: FLEET_SESSION_DURATION
Config file format:
session:
duration: 4h
apiVersion: v1
kind: config
spec:
session:
duration: 4h
The size of the node key which is negotiated with osqueryd
clients.
Default value: 24
Environment variable: FLEET_OSQUERY_NODE_KEY_SIZE
Config file format:
osquery:
node_key_size: 36
The identifier to use when determining uniqueness of hosts.
Options are provided
(default), uuid
, hostname
, or instance
.
This setting works in combination with the --host_identifier
flag in osquery. In most deployments, using uuid
will be the best option. The flag defaults to provided
-- preserving the existing behavior of Fleet's handling of host identifiers -- using the identifier provided by osquery. instance
, uuid
, and hostname
correspond to the same meanings as for osquery's --host_identifier
flag.
Users that have duplicate UUIDs in their environment can benefit from setting this flag to instance
.
Default value: provided
Environment variable: FLEET_OSQUERY_HOST_IDENTIFIER
Config file format:
osquery:
host_identifier: uuid
The cooldown period for host enrollment. If a host (uniquely identified by the osquery_host_identifier
option) tries to enroll within this duration from the last enrollment, enroll will fail.
This flag can be used to control load on the database in scenarios in which many hosts are using the same identifier. Often configuring osquery_host_identifier
to instance
may be a better solution.
Default value: 0
(off)
Environment variable: FLEET_OSQUERY_ENROLL_COOLDOWN
Config file format:
osquery:
enroll_cooldown: 1m
The interval at which Fleet will ask osquery agents to update their results for label queries.
Setting this to a higher value can reduce baseline load on the Fleet server in larger deployments.
Valid time units are s
, m
, h
.
Default value: 1h
Environment variable: FLEET_OSQUERY_LABEL_UPDATE_INTERVAL
Config file format:
osquery:
label_update_interval: 30m
The interval at which Fleet will ask osquery agents to update their results for policy queries.
Setting this to a higher value can reduce baseline load on the Fleet server in larger deployments.
Valid time units are s
, m
, h
.
Default value: 1h
Environment variable: FLEET_OSQUERY_POLICY_UPDATE_INTERVAL
Config file format:
osquery:
policy_update_interval: 30m
The interval at which Fleet will ask osquery agents to update host details (such as uptime, hostname, network interfaces, etc.)
Setting this to a higher value can reduce baseline load on the Fleet server in larger deployments.
Valid time units are s
, m
, h
.
Default value: 1h
Environment variable: FLEET_OSQUERY_DETAIL_UPDATE_INTERVAL
Config file format:
osquery:
detail_update_interval: 30m
Which log output plugin should be used for osquery status logs received from clients. Check out the reference documentation for osquery logging options here in the Fleet documentation.
Options are filesystem
, firehose
, kinesis
, lambda
, pubsub
, kafkarest
, and stdout
.
Default value: filesystem
Environment variable: FLEET_OSQUERY_STATUS_LOG_PLUGIN
Config file format:
osquery:
status_log_plugin: firehose
Which log output plugin should be used for osquery result logs received from clients. Check out the reference documentation for osquery logging options here in the Fleet documentation.
Options are filesystem
, firehose
, kinesis
, lambda
, pubsub
, kafkarest
, and stdout
.
Default value: filesystem
Environment variable: FLEET_OSQUERY_RESULT_LOG_PLUGIN
Config file format:
osquery:
result_log_plugin: firehose
Given an update interval (label, or details), this will add up to the defined percentage in randomness to the interval.
The goal of this is to prevent all hosts from checking in with data at the same time.
So for example, if the label_update_interval is 1h, and this is set to 10. It'll add up a random number between 0 and 6 minutes to the amount of time it takes for Fleet to give the host the label queries.
Default value: 10
Environment variable: FLEET_OSQUERY_MAX_JITTER_PERCENT
Config file format:
osquery:
max_jitter_percent: 10
Experimental feature. Enable asynchronous processing of hosts' query results. Currently, only supported for label query execution, policy membership results, and hosts' last seen timestamp. This may improve the performance and CPU usage of the Fleet instances and MySQL database servers for setups with a large number of hosts while requiring more resources from Redis server(s).
Note that currently, if both the failing policies webhook and this osquery.enable_async_host_processing
option 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).
It can be set to a single boolean value ("true" or "false"), which controls all async host processing tasks, or it can be set for specific async tasks using a syntax similar to an URL query string or parameters in a Data Source Name (DSN) string, e.g., "label_membership=true&policy_membership=true". When using the per-task syntax, omitted tasks get the default value. The supported async task names are:
label_membership
for updating the hosts' label query execution;policy_membership
for updating the hosts' policy membership results;host_last_seen
for updating the hosts' last seen timestamp.Default value: false
Environment variable: FLEET_OSQUERY_ENABLE_ASYNC_HOST_PROCESSING
Config file format:
osquery:
enable_async_host_processing: true
Applies only when osquery_enable_async_host_processing
is enabled. Sets the interval at which the host data will be collected into the database. Each Fleet instance will attempt to do the collection at this interval (with some optional jitter added, see osquery_async_host_collect_max_jitter_percent
), with only one succeeding to get the exclusive lock.
It can be set to a single duration value (e.g., "30s"), which defines the interval for all async host processing tasks, or it can be set for specific async tasks using a syntax similar to an URL query string or parameters in a Data Source Name (DSN) string, e.g., "label_membership=10s&policy_membership=1m". When using the per-task syntax, omitted tasks get the default value. See osquery_enable_async_host_processing for the supported async task names.
Default value: 30s
Environment variable: FLEET_OSQUERY_ASYNC_HOST_COLLECT_INTERVAL
Config file format:
osquery:
async_host_collect_interval: 1m
Applies only when osquery_enable_async_host_processing
is enabled. A number interpreted as a percentage of osquery_async_host_collect_interval
to add to (or remove from) the interval so that not all hosts try to do the collection at the same time.
Default value: 10
Environment variable: FLEET_OSQUERY_ASYNC_HOST_COLLECT_MAX_JITTER_PERCENT
Config file format:
osquery:
async_host_collect_max_jitter_percent: 5
Applies only when osquery_enable_async_host_processing
is enabled. Timeout of the lock acquired by a Fleet instance to collect host data into the database. If the collection runs for too long or the instance crashes unexpectedly, the lock will be automatically released after this duration and another Fleet instance can proceed with the next collection.
It can be set to a single duration value (e.g., "1m"), which defines the lock timeout for all async host processing tasks, or it can be set for specific async tasks using a syntax similar to an URL query string or parameters in a Data Source Name (DSN) string, e.g., "label_membership=2m&policy_membership=5m". When using the per-task syntax, omitted tasks get the default value. See osquery_enable_async_host_processing for the supported async task names.
Default value: 1m
Environment variable: FLEET_OSQUERY_ASYNC_HOST_COLLECT_LOCK_TIMEOUT
Config file format:
osquery:
async_host_collect_lock_timeout: 5m
Applies only when osquery_enable_async_host_processing
is enabled. Interval at which the host collection statistics are logged, 0 to disable logging of statistics. Note that logging is done at the "debug" level.
Default value: 1m
Environment variable: FLEET_OSQUERY_ASYNC_HOST_COLLECT_LOG_STATS_INTERVAL
Config file format:
osquery:
async_host_collect_log_stats_interval: 5m
Applies only when osquery_enable_async_host_processing
is enabled. Size of the INSERT batch when collecting host data into the database.
Default value: 2000
Environment variable: FLEET_OSQUERY_ASYNC_HOST_INSERT_BATCH
Config file format:
osquery:
async_host_insert_batch: 1000
Applies only when osquery_enable_async_host_processing
is enabled. Size of the DELETE batch when collecting host data into the database.
Default value: 2000
Environment variable: FLEET_OSQUERY_ASYNC_HOST_DELETE_BATCH
Config file format:
osquery:
async_host_delete_batch: 1000
Applies only when osquery_enable_async_host_processing
is enabled. Size of the UPDATE batch when collecting host data into the database.
Default value: 1000
Environment variable: FLEET_OSQUERY_ASYNC_HOST_UPDATE_BATCH
Config file format:
osquery:
async_host_update_batch: 500
Applies only when osquery_enable_async_host_processing
is enabled. Maximum number of items to pop from a redis key at a time when collecting host data into the database.
Default value: 1000
Environment variable: FLEET_OSQUERY_ASYNC_HOST_REDIS_POP_COUNT
Config file format:
osquery:
async_host_redis_pop_count: 500
Applies only when osquery_enable_async_host_processing
is enabled. Order of magnitude (e.g., 10, 100, 1000, etc.) of set members to scan in a single ZSCAN/SSCAN request for items to process when collecting host data into the database.
Default value: 1000
Environment variable: FLEET_OSQUERY_ASYNC_HOST_REDIS_SCAN_KEYS_COUNT
Config file format:
osquery:
async_host_redis_scan_keys_count: 100
The minimum time difference between the software's "last opened at" timestamp reported by osquery and the last timestamp saved for that software on that host helps minimize the number of updates required when a host reports its installed software information, resulting in less load on the database. If there is no existing timestamp for the software on that host (or if the software was not installed on that host previously), the new timestamp is automatically saved.
Default value: 1h
Environment variable: FLEET_OSQUERY_MIN_SOFTWARE_LAST_OPENED_AT_DIFF
Config file format:
osquery:
min_software_last_opened_at_diff: 4h
apiVersion: v1
kind: config
spec:
osquery:
host_identifier: uuid
policy_update_interval: 30m
duration: 4h
status_log_plugin: firehose
result_log_plugin: firehose
Whether or not to enable debug logging.
Default value: false
Environment variable: FLEET_LOGGING_DEBUG
Config file format:
logging:
debug: true
Whether or not to log in JSON.
Default value: false
Environment variable: FLEET_LOGGING_JSON
Config file format:
logging:
json: true
Whether or not to log the welcome banner.
Default value: false
Environment variable: FLEET_LOGGING_DISABLE_BANNER
Config file format:
logging:
disable_banner: true
The amount of time to keep an error. Unique instances of errors are stored temporarily to help with troubleshooting, this setting controls that duration. Set to 0 to keep them without expiration, and a negative value to disable storage of errors in Redis.
Default value: 24h
Environment variable: FLEET_LOGGING_ERROR_RETENTION_PERIOD
Config file format:
logging:
error_retention_period: 1h
apiVersion: v1
kind: config
spec:
logging:
disable_banner: true
policy_update_interval: 30m
error_retention_period: 1h
This flag only has effect if osquery_status_log_plugin
is set to filesystem
(the default value).
The path which osquery status logs will be logged to.
Default value: /tmp/osquery_status
Environment variable: FLEET_FILESYSTEM_STATUS_LOG_FILE
Config file format:
filesystem:
status_log_file: /var/log/osquery/status.log
This flag only has effect if osquery_result_log_plugin
is set to filesystem
(the default value).
The path which osquery result logs will be logged to.
Default value: /tmp/osquery_result
Environment variable: FLEET_FILESYSTEM_RESULT_LOG_FILE
Config file format:
filesystem:
result_log_file: /var/log/osquery/result.log
This flag only has effect if osquery_result_log_plugin
or osquery_status_log_plugin
are set to filesystem
(the default value).
This flag will cause the osquery result and status log files to be automatically rotated when files reach a size of 500 Mb or an age of 28 days.
Default value: false
Environment variable: FLEET_FILESYSTEM_ENABLE_LOG_ROTATION
Config file format:
filesystem:
enable_log_rotation: true
This flag only has effect if filesystem_enable_log_rotation
is set to true
.
This flag will cause the rotated logs to be compressed with gzip.
Default value: false
Environment variable: FLEET_FILESYSTEM_ENABLE_LOG_COMPRESSION
Config file format:
filesystem:
enable_log_compression: true
apiVersion: v1
kind: config
spec:
osquery:
osquery_status_log_plugin: filesystem
osquery_result_log_plugin: filesystem
filesystem:
status_log_file: /var/log/osquery/status.log
result_log_file: /var/log/osquery/result.log
enable_log_rotation: true
This flag only has effect if osquery_status_log_plugin
is set to firehose
.
AWS region to use for Firehose connection
Default value: none
Environment variable: FLEET_FIREHOSE_REGION
Config file format:
firehose:
region: ca-central-1
This flag only has effect if osquery_status_log_plugin
or osquery_result_log_plugin
are set to firehose
.
If firehose_access_key_id
and firehose_secret_access_key
are omitted, Fleet will try to use AWS STS credentials.
AWS access key ID to use for Firehose authentication.
Default value: none
Environment variable: FLEET_FIREHOSE_ACCESS_KEY_ID
Config file format:
firehose:
access_key_id: AKIAIOSFODNN7EXAMPLE
This flag only has effect if osquery_status_log_plugin
or osquery_result_log_plugin
are set to firehose
.
AWS secret access key to use for Firehose authentication.
Default value: none
Environment variable: FLEET_FIREHOSE_SECRET_ACCESS_KEY
Config file format:
firehose:
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
This flag only has effect if osquery_status_log_plugin
or
osquery_result_log_plugin
are set to firehose
.
AWS STS role ARN to use for Firehose authentication.
Default value: none
Environment variable: FLEET_FIREHOSE_STS_ASSUME_ROLE_ARN
Config file format:
firehose:
sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role
This flag only has effect if osquery_status_log_plugin
is set to firehose
.
Name of the Firehose stream to write osquery status logs received from clients.
Default value: none
Environment variable: FLEET_FIREHOSE_STATUS_STREAM
Config file format:
firehose:
status_stream: osquery_status
The IAM role used to send to Firehose must allow the following permissions on the stream listed:
firehose:DescribeDeliveryStream
firehose:PutRecordBatch
This flag only has effect if osquery_result_log_plugin
is set to firehose
.
Name of the Firehose stream to write osquery result logs received from clients.
Default value: none
Environment variable: FLEET_FIREHOSE_RESULT_STREAM
Config file format:
firehose:
result_stream: osquery_result
The IAM role used to send to Firehose must allow the following permissions on the stream listed:
firehose:DescribeDeliveryStream
firehose:PutRecordBatch
apiVersion: v1
kind: config
spec:
osquery:
osquery_status_log_plugin: firehose
osquery_result_log_plugin: firehose
firehose:
region: ca-central-1
access_key_id: AKIAIOSFODNN7EXAMPLE
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role
status_stream: osquery_status
result_stream: osquery_result
This flag only has effect if osquery_status_log_plugin
is set to kinesis
.
AWS region to use for Kinesis connection
Default value: none
Environment variable: FLEET_KINESIS_REGION
Config file format:
kinesis:
region: ca-central-1
This flag only has effect if osquery_status_log_plugin
or
osquery_result_log_plugin
are set to kinesis
.
If kinesis_access_key_id
and kinesis_secret_access_key
are omitted, Fleet
will try to use
AWS STS
credentials.
AWS access key ID to use for Kinesis authentication.
Default value: none
Environment variable: FLEET_KINESIS_ACCESS_KEY_ID
Config file format:
kinesis:
access_key_id: AKIAIOSFODNN7EXAMPLE
This flag only has effect if osquery_status_log_plugin
or
osquery_result_log_plugin
are set to kinesis
.
AWS secret access key to use for Kinesis authentication.
Default value: none
Environment variable: FLEET_KINESIS_SECRET_ACCESS_KEY
Config file format:
kinesis:
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
This flag only has effect if osquery_status_log_plugin
or
osquery_result_log_plugin
are set to kinesis
.
AWS STS role ARN to use for Kinesis authentication.
Default value: none
Environment variable: FLEET_KINESIS_STS_ASSUME_ROLE_ARN
Config file format:
kinesis:
sts_assume_role_arn: arn:aws:iam::1234567890:role/kinesis-role
This flag only has effect if osquery_status_log_plugin
is set to kinesis
.
Name of the Kinesis stream to write osquery status logs received from clients.
Default value: none
Environment variable: FLEET_KINESIS_STATUS_STREAM
Config file format:
kinesis:
status_stream: osquery_status
The IAM role used to send to Kinesis must allow the following permissions on the stream listed:
kinesis:DescribeStream
kinesis:PutRecords
This flag only has effect if osquery_result_log_plugin
is set to kinesis
.
Name of the Kinesis stream to write osquery result logs received from clients.
Default value: none
Environment variable: FLEET_KINESIS_RESULT_STREAM
Config file format:
kinesis:
result_stream: osquery_result
The IAM role used to send to Kinesis must allow the following permissions on the stream listed:
kinesis:DescribeStream
kinesis:PutRecords
apiVersion: v1
kind: config
spec:
osquery:
osquery_status_log_plugin: kinesis
osquery_result_log_plugin: kinesis
kinesis:
region: ca-central-1
result_log_file: /var/log/osquery/result.log
access_key_id: AKIAIOSFODNN7EXAMPLE
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role
status_stream: osquery_status
result_stream: osquery_result
This flag only has effect if osquery_status_log_plugin
is set to lambda
.
AWS region to use for Lambda connection
Default value: none
Environment variable: FLEET_LAMBDA_REGION
Config file format:
lambda:
region: ca-central-1
This flag only has effect if osquery_status_log_plugin
or
osquery_result_log_plugin
are set to lambda
.
If lambda_access_key_id
and lambda_secret_access_key
are omitted, Fleet
will try to use
AWS STS
credentials.
AWS access key ID to use for Lambda authentication.
Default value: none
Environment variable: FLEET_LAMBDA_ACCESS_KEY_ID
Config file format:
lambda:
access_key_id: AKIAIOSFODNN7EXAMPLE
This flag only has effect if osquery_status_log_plugin
or
osquery_result_log_plugin
are set to lambda
.
AWS secret access key to use for Lambda authentication.
Default value: none
Environment variable: FLEET_LAMBDA_SECRET_ACCESS_KEY
Config file format:
lambda:
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
This flag only has effect if osquery_status_log_plugin
or
osquery_result_log_plugin
are set to lambda
.
AWS STS role ARN to use for Lambda authentication.
Default value: none
Environment variable: FLEET_LAMBDA_STS_ASSUME_ROLE_ARN
Config file format:
lambda:
sts_assume_role_arn: arn:aws:iam::1234567890:role/lambda-role
This flag only has effect if osquery_status_log_plugin
is set to lambda
.
Name of the Lambda function to write osquery status logs received from clients.
Default value: none
Environment variable: FLEET_LAMBDA_STATUS_FUNCTION
Config file format:
lambda:
status_function: statusFunction
The IAM role used to send to Lambda must allow the following permissions on the function listed:
lambda:InvokeFunction
This flag only has effect if osquery_result_log_plugin
is set to lambda
.
Name of the Lambda function to write osquery result logs received from clients.
Default value: none
Environment variable: FLEET_LAMBDA_RESULT_FUNCTION
Config file format:
lambda:
result_function: resultFunction
The IAM role used to send to Lambda must allow the following permissions on the function listed:
lambda:InvokeFunction
apiVersion: v1
kind: config
spec:
osquery:
osquery_status_log_plugin: lamda
osquery_result_log_plugin: lamda
lamda:
region: ca-central-1
access_key_id: AKIAIOSFODNN7EXAMPLE
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role
status_function: statusFunction
result_function: resultFunction
This flag only has effect if osquery_status_log_plugin
is set to pubsub
.
The identifier of the Google Cloud project containing the pubsub topics to publish logs to.
Note that the pubsub plugin uses Application Default Credentials (ADCs) for authentication with the service.
Default value: none
Environment variable: FLEET_PUBSUB_PROJECT
Config file format:
pubsub:
project: my-gcp-project
This flag only has effect if osquery_status_log_plugin
is set to pubsub
.
The identifier of the pubsub topic that client results will be published to.
Default value: none
Environment variable: FLEET_PUBSUB_RESULT_TOPIC
Config file format:
pubsub:
result_topic: osquery_result
This flag only has effect if osquery_status_log_plugin
is set to pubsub
.
The identifier of the pubsub topic that osquery status logs will be published to.
Default value: none
Environment variable: FLEET_PUBSUB_STATUS_TOPIC
Config file format:
pubsub:
status_topic: osquery_status
This flag only has effect if osquery_status_log_plugin
is set to pubsub
.
Add Pub/Sub attributes to messages. When enabled, the plugin parses the osquery result messages, and adds the following Pub/Sub message attributes:
name
- the name
attribute from the message bodytimestamp
- the unixTime
attribute from the message body, converted to rfc3339 formatThis feature is useful when combined with subscription filters.
Default value: false
Environment variable: FLEET_PUBSUB_ADD_ATTRIBUTES
Config file format:
pubsub:
add_attributes: true
apiVersion: v1
kind: config
spec:
osquery:
osquery_status_log_plugin: pubsub
osquery_result_log_plugin: pubsub
pubsub:
project: my-gcp-project
result_topic: osquery_result
status_topic: osquery_status
sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role
status_function: statusFunction
result_function: resultFunction
This flag only has effect if osquery_status_log_plugin
or osquery_result_log_plugin
is set to kafkarest
.
The URL of the host which to check for the topic existence and post messages to the specified topic.
Default value: none
Environment variable: FLEET_KAFKAREST_PROXYHOST
Config file format:
kafkarest:
proxyhost: "https://localhost:8443"
This flag only has effect if osquery_status_log_plugin
is set to kafkarest
.
The identifier of the kafka topic that osquery status logs will be published to.
Default value: none
Environment variable: FLEET_KAFKAREST_STATUS_TOPIC
Config file format:
kafkarest:
status_topic: osquery_status
This flag only has effect if osquery_result_log_plugin
is set to kafkarest
.
The identifier of the kafka topic that osquery result logs will be published to.
Default value: none
Environment variable: FLEET_KAFKAREST_RESULT_TOPIC
Config file format:
kafkarest:
status_topic: osquery_result
This flag only has effect if osquery_status_log_plugin
or osquery_result_log_plugin
is set to kafkarest
.
The timeout value for the http post attempt. Value is in units of seconds.
Default value: 5
Environment variable: FLEET_KAFKAREST_TIMEOUT
Config file format:
kafkarest:
timeout: 5
This flag only has effect if osquery_status_log_plugin
is set to kafkarest
.
The value of the Content-Type header to use in Kafka REST Proxy API calls. More information about available versions can be found here. Note: only JSON format is supported
Default value: application/vnd.kafka.json.v1+json
Environment variable: FLEET_KAFKAREST_CONTENT_TYPE_VALUE
Config file format:
kafkarest:
content_type_value: application/vnd.kafka.json.v2+json
apiVersion: v1
kind: config
spec:
osquery:
osquery_status_log_plugin: kafkarest
osquery_result_log_plugin: kafkarest
kafkarest:
proxyhost: "https://localhost:8443"
result_topic: osquery_result
status_topic: osquery_status
Name of the S3 bucket to use to store file carves.
Default value: none
Environment variable: FLEET_S3_BUCKET
Config file format:
s3:
bucket: some-carve-bucket
Prefix to prepend to carve objects.
All carve objects will also be prefixed by date and hour (UTC), making the resulting keys look like: <prefix><year>/<month>/<day>/<hour>/<carve-name>
.
Default value: none
Environment variable: FLEET_S3_PREFIX
Config file format:
s3:
prefix: carves-go-here/
AWS access key ID to use for S3 authentication.
If s3_access_key_id
and s3_secret_access_key
are omitted, Fleet will try to use
the default credential provider chain.
The IAM identity used in this context must be allowed to perform the following actions on the bucket: s3:PutObject
, s3:GetObject
, s3:ListMultipartUploadParts
, s3:ListBucket
, s3:GetBucketLocation
.
Default value: none
Environment variable: FLEET_S3_ACCESS_KEY_ID
Config file format:
s3:
access_key_id: AKIAIOSFODNN7EXAMPLE
AWS secret access key to use for S3 authentication.
Default value: none
Environment variable: FLEET_S3_SECRET_ACCESS_KEY
Config file format:
s3:
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS STS role ARN to use for S3 authentication.
Default value: none
Environment variable: FLEET_S3_STS_ASSUME_ROLE_ARN
Config file format:
s3:
sts_assume_role_arn: arn:aws:iam::1234567890:role/some-s3-role
AWS S3 Endpoint URL. Override when using a different S3 compatible object storage backend (such as Minio), or running s3 locally with localstack. Leave this blank to use the default S3 service endpoint.
Default value: none
Environment variable: FLEET_S3_ENDPOINT_URL
Config file format:
s3:
endpoint_url: http://localhost:9000
AWS S3 Disable SSL. Useful for local testing.
Default value: false
Environment variable: FLEET_S3_DISABLE_SSL
Config file format:
s3:
disable_ssl: false
AWS S3 Force S3 Path Style. Set this to true
to force the request to use path-style addressing,
i.e., http://s3.amazonaws.com/BUCKET/KEY
. By default, the S3 client
will use virtual hosted bucket addressing when possible
(http://BUCKET.s3.amazonaws.com/KEY
).
See here for details.
Default value: false
Environment variable: FLEET_S3_FORCE_S3_PATH_STYLE
Config file format:
s3:
force_s3_path_style: false
AWS S3 Region. Leave blank to enable region discovery.
Minio users must set this to any nonempty value (eg. minio
), as Minio does not support region discovery.
Default value:
Environment variable: FLEET_S3_REGION
Config file format:
s3:
region: us-east-1
apiVersion: v1
kind: config
spec:
s3:
bucket: some-carve-bucket
prefix: carves-go-here/
access_key_id: AKIAIOSFODNN7EXAMPLE
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
sts_assume_role_arn: arn:aws:iam::1234567890:role/some-s3-role
region: us-east-1
If set then fleet serve
will run even if there are database migrations missing.
Default value: false
Environment variable: FLEET_UPGRADES_ALLOW_MISSING_MIGRATIONS
Config file format:
apiVersion: v1
kind: config
spec:
upgrades:
allow_missing_migrations: true
The path specified needs to exist and Fleet needs to be able to read and write to and from it. This is the only mandatory configuration needed for vulnerability processing to work.
When current_instance_checks
is set to auto
(the default), Fleet instances will try to create the databases_path
if it doesn't exist.
Default value: none
Environment variable: FLEET_VULNERABILITIES_DATABASES_PATH
Config file format:
vulnerabilities:
databases_path: /some/path
How often vulnerabilities are checked. This is also the interval at which the counts of hosts per software is calculated.
Default value: 1h
Environment variable: FLEET_VULNERABILITIES_PERIODICITY
Config file format:
vulnerabilities:
periodicity: 1h
URL to fetch the CPE dictionary database from. Some users want to control where Fleet gets its database from. When Fleet sees this value defined, it downloads the file directly. It expects a file in the same format as can be found in https://github.com/fleetdm/nvd/releases. If this value is not defined, Fleet checks for the latest release in Github and only downloads it if needed.
Default value: ""
Environment variable: FLEET_VULNERABILITIES_CPE_DATABASE_URL
Config file format:
vulnerabilities:
cpe_database_url: ""
Similarly to the CPE dictionary, we allow users to define where to get the CVE feeds from. In this case, the url should be a host that serves the files in the path /feeds/json/cve/1.1/. Fleet expects to find there all the JSON Feeds that can be found in https://nvd.nist.gov/vuln/data-feeds. When not defined, Fleet downloads from the nvd.nist.gov host.
Default value: ""
Environment variable: FLEET_VULNERABILITIES_CVE_FEED_PREFIX_URL
Config file format:
vulnerabilities:
cve_database_url: ""
When running multiple instances of the Fleet server, by default, one of them dynamically takes the lead in vulnerability processing. This lead can change over time. Some Fleet users want to be able to define which deployment is doing this checking. If you wish to do this, you'll need to deploy your Fleet instances with this set explicitly to no and one of them set to yes.
Default value: auto
Environment variable: FLEET_VULNERABILITIES_CURRENT_INSTANCE_CHECKS
Config file format:
vulnerabilities:
current_instance_checks: yes
Fleet by default automatically downloads and keeps the different data streams needed to properly do vulnerability processing. In some setups, this behavior is not wanted, as access to outside resources might be blocked, or the data stream files might need review/audit before use.
In order to support vulnerability processing in such environments, we allow users to disable automatic sync of data streams with this configuration value.
To download the data streams, you can use fleetctl vulnerability-data-stream --dir ./somedir
. The contents downloaded can then be reviewed, and finally uploaded to the defined databases_path
in the fleet instance(s) doing the vulnerability processing.
Default value: false
Environment variable: FLEET_VULNERABILITIES_DISABLE_DATA_SYNC
Config file format:
vulnerabilities:
disable_data_sync: true
Maximum age of a vulnerability (a CVE) to be considered "recent". The age is calculated based on the published date of the CVE in the National Vulnerability Database (NVD). Recent vulnerabilities play a special role in Fleet's automations, as they are reported when discovered on a host if the vulnerabilities webhook or a vulnerability integration is enabled.
Default value: 720h
(30 days)
Environment variable: FLEET_VULNERABILITIES_RECENT_VULNERABILITY_MAX_AGE
Config file format:
vulnerabilities:
recent_vulnerability_max_age: 48h
apiVersion: v1
kind: config
spec:
vulnerabilities:
databases_path: /some/path
current_instance_checks: yes
disable_data_sync: true
The path to a valid Maxmind GeoIP database(mmdb). Support exists for the country & city versions of the database. If city database is supplied
then Fleet will attempt to resolve the location via the city lookup, otherwise it defaults to the country lookup. The IP address used
to determine location is extracted via HTTP headers in the following order: True-Client-IP
, X-Real-IP
, and finally X-FORWARDED-FOR
headers
on the Fleet web server.
Default value: none
Environment variable: FLEET_GEOIP_DATABASE_PATH
Config file format:
apiVersion: v1
kind: config
spec:
geoip:
database_path: /some/path
We recommend that you use an infrastructure configuration management tool to manage these osquery configurations consistently across your environment. If you're unsure about what configuration management tools your organization uses, contact your company's system administrators. If you are evaluating new solutions for this problem, the founders of Fleet have successfully managed configurations in large production environments using Chef and Puppet.
Once you've verified that you can run Fleet in your shell, you'll likely want to keep Fleet running in the background and after the server reboots. To do that we recommend using systemd.
Below is a sample unit file, assuming a fleet
user exists on the system. Any user with sufficient
permissions to execute the binary, open the configuration files, and write the log files can be
used. It is also possible to run as root
, though as with any other web server it is discouraged
to run Fleet as root
.
[Unit]
Description=Fleet
After=network.target
[Service]
User=fleet
Group=fleet
LimitNOFILE=8192
ExecStart=/usr/local/bin/fleet serve \
--mysql_address=127.0.0.1:3306 \
--mysql_database=fleet \
--mysql_username=root \
--mysql_password=toor \
--redis_address=127.0.0.1:6379 \
--server_cert=/tmp/server.cert \
--server_key=/tmp/server.key \
--logging_json
[Install]
WantedBy=multi-user.target
Once you created the file, you need to move it to /etc/systemd/system/fleet.service
and start the service.
sudo mv fleet.service /etc/systemd/system/fleet.service
sudo systemctl start fleet.service
sudo systemctl status fleet.service
sudo journalctl -u fleet.service -f
Sometimes you'll need to update the systemd unit file defining the service. To do that, first open /etc/systemd/system/fleet.service in a text editor, and make your modifications.
Then, run
sudo systemctl daemon-reload
sudo systemctl restart fleet.service
If you are in an enterprise environment where Fleet is behind a proxy and you would like to be able to retrieve Vulnerability data for Vulnerability Processing, it may be necessary to configure the proxy settings. Fleet automatically uses the HTTP_PROXY
, HTTPS_PROXY
, and NO_PROXY
environment variables.
For example, to configure the proxy in a systemd service file:
[Service]
Environment="HTTP_PROXY=http(s)://PROXY_URL:PORT/"
Environment="HTTPS_PROXY=http(s)://PROXY_URL:PORT/"
Environment="NO_PROXY=localhost,127.0.0.1,::1"
After modifying the configuration you will need to reload and restart the Fleet service, as explained above.
Fleet supports SAML single sign on capability.
Fleet supports both SP-initiated SAML login and IDP-initiated login, however IDP-initiated login must be enabled in the web interface's SAML single sign on options.
Fleet supports the SAML Web Browser SSO Profile using the HTTP Redirect Binding.
Note that the email being used in the SAML Assertion must match a user that already exists in Fleet.
Setting up the service provider (Fleet) with an identity provider generally requires the following information:
Assertion Consumer Service - This is the call back URL that the identity provider
will use to send security assertions to Fleet. In Okta, this field is called single sign on URL. On Google it is "ACS URL." The value that you supply will be a fully qualified URL consisting of your Fleet web address and the callback path /api/v1/fleet/sso/callback
. For example, if your Fleet web address is https://fleet.example.com, then the value you would use in the identity provider configuration would be:
https://fleet.example.com/api/v1/fleet/sso/callback
Entity ID - This value is an identifier that you choose. It identifies your Fleet instance as the service provider that issues authorization requests. The value must exactly match the Entity ID that you define in the Fleet SSO configuration.
Name ID Format - The value should be urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
. This may be shortened in the IDP setup to something like email
or EmailAddress
.
Subject Type (Application username in Okta) - email
.
After supplying the above information, the IDP will generate an issuer URI and a metadata that will be used to configure Fleet as a service provider.
A Fleet user must be assigned the Admin role to configure Fleet for SSO. In Fleet, SSO configuration settings are located in Settings > Organization settings > SAML single sign on options.
If your IDP supports dynamic configuration, like Okta, you only need to provide an identity provider name and entity ID, then paste a link in the metadata URL field. Make sure that you create the SSO application within your IDP before configuring it in Fleet.
Otherwise, the following values are required:
Identity provider name - A human readable name of the IDP. This is rendered on the login page.
Entity ID - A URI that identifies your Fleet instance as the issuer of authorization
requests (eg. fleet.example.com
). This much match the Entity ID configured with the IDP.
Issuer URI - This value is obtained from the IDP.
Metadata URL - This value is obtained from the IDP and is used by Fleet to issue authorization requests to the IDP.
Metadata - If the IDP does not provide a metadata URL, the metadata must be obtained from the IDP and entered. Note that the metadata URL is preferred if the IDP provides metadata in both forms.
When an admin creates a new user to Fleet, they may select the Enable single sign on
option. The
SSO enabled users will not be able to sign in with a regular user ID and password.
It is strongly recommended that at least one admin user is set up to use the traditional password based log in so that there is a fallback method for logging into Fleet in the event of SSO configuration problems.
Individual users must also be set up on the IDP before they can sign in to Fleet.
As an admin, you can enable SSO for existing users in Fleet. To do this, go to the Settings page, then click on the Users tab. Locate the user you want to enable SSO for and on the actions dropdown menu for that user, click on "Enable single sign on".
Once configured, you will need to retrieve the Issuer URI from the View Setup Instructions
and metadata URL from the Identity Provider metadata
link within the application Sign on
settings. See below for where to find them:
The Provider Sign-on URL within the
View Setup Instructions
has a similar format as the Provider SAML Metadata URL, but this link provides a redirect to sign-in the application, not the metadata necessary for dynamic configuration.
The names of the items required to configure an identity provider may vary from provider to provider and may not conform to the SAML spec.
Follow these steps to configure Fleet SSO with Google Workspace. This will require administrator permissions in Google Workspace.
Fleet
for the App name and click Continue.
Google
.fleet.example.com
. Note that Google seems to error when the provided ID includes https://
.Click Update settings at the bottom of the page.
https://<your_fleet_url>/api/v1/fleet/sso/callback
(eg. https://fleet.example.com/api/v1/fleet/sso/callback
).fleet.example.com
).EMAIL
.Basic Information > Primary email
.Click Continue at the bottom of the page.
Fleet features are sometimes gated behind feature flags. This will usually be due to not-yet-stable APIs, or not-fully-tested performance characteristics.
Feature flags on the server are controlled by environment variables prefixed with FLEET_BETA_
.
If set then fleet serve
will capture errors and panics and push them to Sentry.
Default value: ""
Environment variable: FLEET_SENTRY_DSN
Config file format:
sentry:
dsn: "https://somedsnprovidedby.sentry.com/"
Username to use for HTTP Basic Auth on the /metrics
endpoint.
If not set then the prometheus /metrics
endpoint is disabled.
Default value: ""
Environment variable: FLEET_PROMETHEUS_BASIC_AUTH_USERNAME
Config file format:
prometheus:
basic_auth:
username: "foo"
Password to use for HTTP Basic Auth on the /metrics
endpoint.
If not set then the prometheus /metrics
endpoint is disabled.
Default value: ""
Environment variable: FLEET_PROMETHEUS_BASIC_AUTH_PASSWORD
Config file format:
prometheus:
basic_auth:
password: "bar"
If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the Fleet repo.