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

Reorganize Fleet documentation (#12871)

Browse source 
Closes: #12611

Changes:
- Added three new documentation sections `/docs/get-started/`,
`/docs/configuration` and `/docs/rest api/`
- Updated folder names: `/docs/Using-Fleet/` » `/docs/Using Fleet` and
`/docs/deploying` » `/docs/deploy/`
- Moved `/docs/using-fleet/process-events.md` to `/articles` and updated
the meta tags to change it into a guide.
- Added support for a new meta tag: `navSection`. This meta tag is used
to organize pages in the sidebar navigation on fleetdm.com/docs
- Moved `docs/using-fleet/application-security.md` and
`docs/using-fleet/security-audits.md` to the security handbook.
- Moved `docs/deploying/load-testing.md` and
`docs/deploying/debugging.md` to the engineering handbook.
- Moved the following files/folders:
- `docs/using-fleet/configuration-files/` »
`docs/configuration/configuration-files/`
- `docs/deploying/configuration.md` »
`docs/configuration/fleet-server-configuration.md`
    -  `docs/using-fleet/rest-api.md` » `docs/rest-api/rest-api.md`
- `docs/using-fleet/monitoring-fleet.md` » `docs/deploy/rest-api.md`
- Updated filenames:
- `docs/using-fleet/permissions.md` »
`docs/using-fleet/manage-access.md`
- `docs/using-fleet/adding-hosts.md` »
`docs/using-fleet/enroll-hosts.md`
    -  `docs/using-fleet/teams.md` » `docs/using-fleet/segment-hosts.md`
- `docs/using-fleet/fleet-ctl-agent-updates.md` »
`docs/using-fleet/update-agents.md`
- `docs/using-fleet/chromeos.md` »
`docs/using-fleet/enroll-chromebooks.md`
- Updated the generated markdown in `server/fleet/gen_activity_doc.go`
and `server/service/osquery_utils/gen_queries_doc.go`
- Updated the navigation sidebar and mobile dropdown links on docs pages
to group pages by their `navSection` meta tag.
- Updated fleetdm.com/docs not to show pages in the `docs/contributing/`
folder in the sidebar navigation
- Added redirects for docs pages that have moved.

.

---------

Co-authored-by: Mike Thomas <mthomas@fleetdm.com>
Co-authored-by: Rachael Shaw <r@rachael.wtf>
This commit is contained in:
Eric 2023-07-27 17:40:01 -05:00 committed by GitHub
parent 51b750a34c
commit 8fb22579ea
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
74 changed files with 870 additions and 608 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
docs/Using-Fleet/Process-File-Events.md → articles/querying-process-file-events-table-on-centos-7.md
View file

@ -175,6 +175,9 @@ auditdnetlink.cpp:354 The Audit publisher has throttled reading records from Net
```
Some events might get lost due to system load or low CPU/memory resources.
<meta name="title" value="Querying process_file_events on CentOS 7">
<meta name="pageOrderInSection" value="1900">
<meta name="description" value="Learn how to configure and query the process_file_events table on CentOS 7 with Fleet.">
<meta name="articleTitle" value="Querying process_file_events on CentOS 7">
<meta name="description" value="Learn how to configure and query the process_file_events table on CentOS 7 with Fleet.">
<meta name="category" value="guides">
<meta name="authorGitHubUsername" value="lucasmrod">
<meta name="authorFullName" value="Lucas Rodriguez">
<meta name="publishedOn" value="2023-07-17">

4
docs/01-Using-Fleet/standard-query-library/README.md
View file

@ -36,7 +36,7 @@ Do you want to add your own query?
3. If you want to contribute multiple queries, please open one pull request that includes all your queries.
For instructions on submitting pull requests to Fleet, check out [the Committing Changes
section](https://fleetdm.com/docs/contributing/committing-changes#committing-changes) in the Contributors
section](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Committing-Changes.md#committing-changes) in the Contributors
documentation.
@ -46,3 +46,5 @@ Listed below are great resources that contain additional queries.
- Osquery (https://github.com/osquery/osquery/tree/master/packs)
- Palantir osquery configuration (https://github.com/palantir/osquery-configuration/tree/master/Fleet)
<meta name="navSection" value="The basics">

7
docs/Configuration/README.md Normal file
View file

@ -0,0 +1,7 @@
# Configuration
### [Fleet server configuration](./fleet-server-configuration)
Documentation for configuring the Fleet binary, managing osquery configurations, and running with systemd.
### [Configuration files](./configuration-files/README.md)
How to use configuration files and the fleetctl command line tool to configure Fleet.

2
docs/Using-Fleet/configuration-files/README.md → docs/Configuration/configuration-files/README.md
View file

@ -1464,6 +1464,6 @@ If you're using Fleet Premium, this enforces disk encryption on all hosts assign
#### Advanced configuration
> **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.
> **Note:** More settings are included in the [contributor documentation](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Configuration-for-contributors.md). It's possible, although not recommended, to configure these settings in the YAML configuration file.
<meta name="description" value="Learn how to use configuration files and the fleetctl command line tool to configure Fleet.">

0
docs/Using-Fleet/configuration-files/kubernetes/fleet-deployment.yml → docs/Configuration/configuration-files/kubernetes/fleet-deployment.yml
View file

0
docs/Using-Fleet/configuration-files/kubernetes/fleet-migrations.yml → docs/Configuration/configuration-files/kubernetes/fleet-migrations.yml
View file

0
docs/Using-Fleet/configuration-files/kubernetes/fleet-service.yml → docs/Configuration/configuration-files/kubernetes/fleet-service.yml
View file

228
docs/Deploying/Configuration.md → docs/Configuration/fleet-server-configuration.md
View file

@ -1,4 +1,4 @@
# Configuration
# Fleet server configuration
## Configuring the Fleet binary
@ -136,7 +136,7 @@ For the address of the MySQL server that Fleet should connect to, include the ho
- Config file format:
```
mysql:
address: localhost:3306
address: localhost:3306
```
##### mysql_database
@ -148,7 +148,7 @@ This is the name of the MySQL database which Fleet will use.
- Config file format:
```
mysql:
database: fleet
database: fleet
```
##### mysql_username
@ -160,7 +160,7 @@ The username to use when connecting to the MySQL instance.
- Config file format:
```
mysql:
username: fleet
username: fleet
```
##### mysql_password
@ -172,7 +172,7 @@ The password to use when connecting to the MySQL instance.
- Config file format:
```
mysql:
password: fleet
password: fleet
```
##### mysql_password_path
@ -184,7 +184,7 @@ File path to a file that contains the password to use when connecting to the MyS
- Config file format:
```
mysql:
password_path: '/run/secrets/fleetdm-mysql-password'
password_path: '/run/secrets/fleetdm-mysql-password'
```
##### mysql_tls_ca
@ -196,7 +196,7 @@ The path to a PEM encoded certificate of MYSQL's CA for client certificate authe
- Config file format:
```
mysql:
tls_ca: /path/to/server-ca.pem
tls_ca: /path/to/server-ca.pem
```
##### mysql_tls_cert
@ -208,7 +208,7 @@ The path to a PEM encoded certificate is used for TLS authentication.
- Config file format:
```
mysql:
tls_cert: /path/to/certificate.pem
tls_cert: /path/to/certificate.pem
```
##### mysql_tls_key
@ -220,7 +220,7 @@ The path to a PEM encoded private key used for TLS authentication.
- Config file format:
```
mysql:
tls_key: /path/to/key.pem
tls_key: /path/to/key.pem
```
##### mysql_tls_config
@ -232,7 +232,7 @@ The TLS value in an MYSQL DSN. Can be `true`,`false`,`skip-verify`, or the CN va
- Config file format:
```
mysql:
tls_config: true
tls_config: true
```
##### mysql_tls_server_name
@ -244,7 +244,7 @@ This is the server name or IP address used by the client certificate.
- Config file format:
```
mysql:
server_name: 127.0.0.1
server_name: 127.0.0.1
```
##### mysql_max_open_conns
@ -256,7 +256,7 @@ The maximum open connections to the database.
- Config file format:
```
mysql:
max_open_conns: 50
max_open_conns: 50
```
##### mysql_max_idle_conns
@ -268,7 +268,7 @@ The maximum idle connections to the database. This value should be equal to or l
- Config file format:
```
mysql:
max_idle_conns: 50
max_idle_conns: 50
```
##### mysql_conn_max_lifetime
@ -280,7 +280,7 @@ The maximum amount of time, in seconds, a connection may be reused.
- Config file format:
```
mysql:
conn_max_lifetime: 50
conn_max_lifetime: 50
```
##### mysql_sql_mode
@ -293,7 +293,7 @@ This setting should not usually be used.
- Config file format:
```
mysql:
sql_mode: ANSI
sql_mode: ANSI
```
##### Example YAML
@ -330,7 +330,7 @@ For the address of the Redis server that Fleet should connect to, include the ho
- Config file format:
```
redis:
address: 127.0.0.1:7369
address: 127.0.0.1:7369
```
##### redis_username
@ -342,7 +342,7 @@ The username to use when connecting to the Redis instance.
- Config file format:
```
redis:
username: foobar
username: foobar
```
##### redis_password
@ -354,7 +354,7 @@ The password to use when connecting to the Redis instance.
- Config file format:
```
redis:
password: foobar
password: foobar
```
##### redis_database
@ -469,7 +469,7 @@ This is the path to a PEM-encoded certificate used for TLS authentication.
- Config file format:
```
redis:
tls_cert: /path/to/certificate.pem
tls_cert: /path/to/certificate.pem
```
##### redis_tls_key
@ -481,7 +481,7 @@ This is the path to a PEM-encoded private key used for TLS authentication.
- Config file format:
```
redis:
tls_key: /path/to/key.pem
tls_key: /path/to/key.pem
```
##### redis_tls_ca
@ -493,7 +493,7 @@ This is the path to a PEM-encoded certificate of Redis' CA for client certificat
- Config file format:
```
redis:
tls_ca: /path/to/server-ca.pem
tls_ca: /path/to/server-ca.pem
```
##### redis_tls_server_name
@ -505,7 +505,7 @@ The server name or IP address used by the client certificate.
- Config file format:
```
redis:
tls_server_name: 127.0.0.1
tls_server_name: 127.0.0.1
```
##### redis_tls_handshake_timeout
@ -517,7 +517,7 @@ The timeout for the Redis TLS handshake part of the connection. A value of 0 mea
- Config file format:
```
redis:
tls_handshake_timeout: 10s
tls_handshake_timeout: 10s
```
##### redis_max_idle_conns
@ -529,7 +529,7 @@ The maximum idle connections to Redis. This value should be equal to or less tha
- Config file format:
```
redis:
max_idle_conns: 50
max_idle_conns: 50
```
##### redis_max_open_conns
@ -541,7 +541,7 @@ The maximum open connections to Redis. A value of 0 means no limit.
- Config file format:
```
redis:
max_open_conns: 100
max_open_conns: 100
```
##### redis_conn_max_lifetime
@ -553,7 +553,7 @@ The maximum time a Redis connection may be reused. A value of 0 means no limit.
- Config file format:
```
redis:
conn_max_lifetime: 30m
conn_max_lifetime: 30m
```
##### redis_idle_timeout
@ -565,7 +565,7 @@ The maximum time a Redis connection may stay idle. A value of 0 means no limit.
- Config file format:
```
redis:
idle_timeout: 5m
idle_timeout: 5m
```
##### redis_conn_wait_timeout
@ -579,7 +579,7 @@ running in cluster mode.
- Config file format:
```
redis:
conn_wait_timeout: 1s
conn_wait_timeout: 1s
```
##### redis_read_timeout
@ -592,7 +592,7 @@ A value of 0 means no timeout.
- Config file format:
```
redis:
read_timeout: 5s
read_timeout: 5s
```
##### redis_write_timeout
@ -605,7 +605,7 @@ A value of 0 means no timeout.
- Config file format:
```
redis:
write_timeout: 5s
write_timeout: 5s
```
##### Example YAML
@ -630,7 +630,7 @@ The address to serve the Fleet webserver.
- Config file format:
```
server:
address: 0.0.0.0:443
address: 0.0.0.0:443
```
##### server_cert
@ -644,7 +644,7 @@ See [TLS certificate considerations](https://fleetdm.com/docs/deploying/introduc
- Config file format:
```
server:
cert: /tmp/fleet.crt
cert: /tmp/fleet.crt
```
##### server_key
@ -656,7 +656,7 @@ The TLS key to use when terminating TLS.
- Config file format:
```
server:
key: /tmp/fleet.key
key: /tmp/fleet.key
```
##### server_tls
@ -668,7 +668,7 @@ Whether or not the server should be served over TLS.
- Config file format:
```
server:
tls: false
tls: false
```
##### server_tls_compatibility
@ -680,7 +680,7 @@ Configures the TLS settings for compatibility with various user agents. Options
- Config file format:
```
server:
tls_compatibility: intermediate
tls_compatibility: intermediate
```
##### server_url_prefix
@ -694,7 +694,7 @@ Note that some other configurations may need to be changed when modifying the UR
- Config file format:
```
server:
url_prefix: /apps/fleet
url_prefix: /apps/fleet
```
##### server_keepalive
@ -708,7 +708,7 @@ Turning off keepalives has helped reduce outstanding TCP connections in some dep
- Config file format:
```
server:
keepalive: true
keepalive: true
```
##### server_websockets_allow_unsafe_origin
@ -725,7 +725,7 @@ Setting to true will disable the origin check.
- Config file format:
```
server:
websockets_allow_unsafe_origin: true
websockets_allow_unsafe_origin: true
```
##### Example YAML
@ -750,7 +750,7 @@ The bcrypt cost to use when hashing user passwords.
- Config file format:
```
auth:
bcrypt_cost: 14
bcrypt_cost: 14
```
##### auth_salt_key_size
@ -762,7 +762,7 @@ The key size of the salt which is generated when hashing user passwords.
- Config file format:
```
auth:
salt_key_size: 36
salt_key_size: 36
```
##### Example YAML
@ -784,7 +784,7 @@ Size of generated app tokens.
- Config file format:
```
app:
token_key_size: 36
token_key_size: 36
```
##### app_invite_token_validity_period
@ -796,7 +796,7 @@ How long invite tokens should be valid for.
- Config file format:
```
app:
invite_token_validity_period: 1d
invite_token_validity_period: 1d
```
##### app_enable_scheduled_query_stats
@ -808,7 +808,7 @@ Determines whether Fleet gets scheduled query statistics from hosts or not.
- Config file format:
```
app:
enable_scheduled_query_stats: true
enable_scheduled_query_stats: true
```
##### Example YAML
@ -865,7 +865,7 @@ The size of the session key.
- Config file format:
```
session:
key_size: 48
key_size: 48
```
##### session_duration
@ -879,7 +879,7 @@ Valid time units are `s`, `m`, `h`.
- Config file format:
```
session:
duration: 4h
duration: 4h
```
##### Example YAML
@ -900,7 +900,7 @@ The size of the node key which is negotiated with `osqueryd` clients.
- Config file format:
```
osquery:
node_key_size: 36
node_key_size: 36
```
##### osquery_host_identifier
@ -920,7 +920,7 @@ Users that have duplicate UUIDs in their environment can benefit from setting th
- Config file format:
```
osquery:
host_identifier: uuid
host_identifier: uuid
```
##### osquery_enroll_cooldown
@ -934,7 +934,7 @@ This flag can be used to control load on the database in scenarios in which many
- Config file format:
```
osquery:
enroll_cooldown: 1m
enroll_cooldown: 1m
```
##### osquery_label_update_interval
@ -952,7 +952,7 @@ Valid time units are `s`, `m`, `h`.
- Config file format:
```
osquery:
label_update_interval: 90m
label_update_interval: 90m
```
##### osquery_policy_update_interval
@ -970,7 +970,7 @@ Valid time units are `s`, `m`, `h`.
- Config file format:
```
osquery:
policy_update_interval: 90m
policy_update_interval: 90m
```
##### osquery_detail_update_interval
@ -988,7 +988,7 @@ Valid time units are `s`, `m`, `h`.
- Config file format:
```
osquery:
detail_update_interval: 90m
detail_update_interval: 90m
```
##### osquery_status_log_plugin
@ -1003,7 +1003,7 @@ Options are `filesystem`, `firehose`, `kinesis`, `lambda`, `pubsub`, `kafkarest`
- Config file format:
```
osquery:
status_log_plugin: firehose
status_log_plugin: firehose
```
##### osquery_result_log_plugin
@ -1017,7 +1017,7 @@ Options are `filesystem`, `firehose`, `kinesis`, `lambda`, `pubsub`, `kafkarest`
- Config file format:
```
osquery:
result_log_plugin: firehose
result_log_plugin: firehose
```
##### osquery_max_jitter_percent
@ -1034,7 +1034,7 @@ to the amount of time it takes for Fleet to give the host the label queries.
- Config file format:
```
osquery:
max_jitter_percent: 10
max_jitter_percent: 10
```
##### osquery_enable_async_host_processing
@ -1055,7 +1055,7 @@ It can be set to a single boolean value ("true" or "false"), which controls all
- Config file format:
```
osquery:
enable_async_host_processing: true
enable_async_host_processing: true
```
##### osquery_async_host_collect_interval
@ -1069,7 +1069,7 @@ It can be set to a single duration value (e.g., "30s"), which defines the interv
- Config file format:
```
osquery:
async_host_collect_interval: 1m
async_host_collect_interval: 1m
```
##### osquery_async_host_collect_max_jitter_percent
@ -1081,7 +1081,7 @@ Applies only when `osquery_enable_async_host_processing` is enabled. A number in
- Config file format:
```
osquery:
async_host_collect_max_jitter_percent: 5
async_host_collect_max_jitter_percent: 5
```
##### osquery_async_host_collect_lock_timeout
@ -1095,7 +1095,7 @@ It can be set to a single duration value (e.g., "1m"), which defines the lock ti
- Config file format:
```
osquery:
async_host_collect_lock_timeout: 5m
async_host_collect_lock_timeout: 5m
```
##### osquery_async_host_collect_log_stats_interval
@ -1107,7 +1107,7 @@ Applies only when `osquery_enable_async_host_processing` is enabled. Interval at
- Config file format:
```
osquery:
async_host_collect_log_stats_interval: 5m
async_host_collect_log_stats_interval: 5m
```
##### osquery_async_host_insert_batch
@ -1119,7 +1119,7 @@ Applies only when `osquery_enable_async_host_processing` is enabled. Size of the
- Config file format:
```
osquery:
async_host_insert_batch: 1000
async_host_insert_batch: 1000
```
##### osquery_async_host_delete_batch
@ -1131,7 +1131,7 @@ Applies only when `osquery_enable_async_host_processing` is enabled. Size of the
- Config file format:
```
osquery:
async_host_delete_batch: 1000
async_host_delete_batch: 1000
```
##### osquery_async_host_update_batch
@ -1143,7 +1143,7 @@ Applies only when `osquery_enable_async_host_processing` is enabled. Size of the
- Config file format:
```
osquery:
async_host_update_batch: 500
async_host_update_batch: 500
```
##### osquery_async_host_redis_pop_count
@ -1155,7 +1155,7 @@ Applies only when `osquery_enable_async_host_processing` is enabled. Maximum num
- Config file format:
```
osquery:
async_host_redis_pop_count: 500
async_host_redis_pop_count: 500
```
##### osquery_async_host_redis_scan_keys_count
@ -1167,7 +1167,7 @@ Applies only when `osquery_enable_async_host_processing` is enabled. Order of ma
- Config file format:
```
osquery:
async_host_redis_scan_keys_count: 100
async_host_redis_scan_keys_count: 100
```
##### osquery_min_software_last_opened_at_diff
@ -1179,7 +1179,7 @@ The minimum time difference between the software's "last opened at" timestamp re
- Config file format:
```
osquery:
min_software_last_opened_at_diff: 4h
min_software_last_opened_at_diff: 4h
```
##### Example YAML
@ -1239,7 +1239,7 @@ Whether or not to enable debug logging.
- Config file format:
```
logging:
debug: true
debug: true
```
##### logging_json
@ -1251,7 +1251,7 @@ Whether or not to log in JSON.
- Config file format:
```
logging:
json: true
json: true
```
##### logging_disable_banner
@ -1263,7 +1263,7 @@ Whether or not to log the welcome banner.
- Config file format:
```
logging:
disable_banner: true
disable_banner: true
```
##### logging_error_retention_period
@ -1277,7 +1277,7 @@ and a negative value to disable storage of errors in Redis.
- Config file format:
```
logging:
error_retention_period: 1h
error_retention_period: 1h
```
##### Example YAML
@ -1301,7 +1301,7 @@ The path which osquery status logs will be logged to.
- Config file format:
```
filesystem:
status_log_file: /var/log/osquery/status.log
status_log_file: /var/log/osquery/status.log
```
##### filesystem_result_log_file
@ -1315,7 +1315,7 @@ The path which osquery result logs will be logged to.
- Config file format:
```
filesystem:
result_log_file: /var/log/osquery/result.log
result_log_file: /var/log/osquery/result.log
```
##### filesystem_audit_log_file
@ -1434,7 +1434,7 @@ AWS region to use for Firehose connection.
- Config file format:
```
firehose:
region: ca-central-1
region: ca-central-1
```
##### firehose_access_key_id
@ -1452,7 +1452,7 @@ AWS access key ID to use for Firehose authentication.
- Config file format:
```
firehose:
access_key_id: AKIAIOSFODNN7EXAMPLE
access_key_id: AKIAIOSFODNN7EXAMPLE
```
##### firehose_secret_access_key
@ -1468,7 +1468,7 @@ AWS secret access key to use for Firehose authentication.
- Config file format:
```
firehose:
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```
##### firehose_sts_assume_role_arn
@ -1484,7 +1484,7 @@ AWS STS role ARN to use for Firehose authentication.
- Config file format:
```
firehose:
sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role
sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role
```
##### firehose_status_stream
@ -1498,7 +1498,7 @@ Name of the Firehose stream to write osquery status logs received from clients.
- Config file format:
```
firehose:
status_stream: osquery_status
status_stream: osquery_status
```
The IAM role used to send to Firehose must allow the following permissions on
@ -1518,7 +1518,7 @@ Name of the Firehose stream to write osquery result logs received from clients.
- Config file format:
```
firehose:
result_stream: osquery_result
result_stream: osquery_result
```
The IAM role used to send to Firehose must allow the following permissions on
@ -1578,7 +1578,7 @@ AWS region to use for Kinesis connection
- Config file format:
```
kinesis:
region: ca-central-1
region: ca-central-1
```
##### kinesis_access_key_id
@ -1599,7 +1599,7 @@ AWS access key ID to use for Kinesis authentication.
- Config file format:
```
kinesis:
access_key_id: AKIAIOSFODNN7EXAMPLE
access_key_id: AKIAIOSFODNN7EXAMPLE
```
##### kinesis_secret_access_key
@ -1615,7 +1615,7 @@ AWS secret access key to use for Kinesis authentication.
- Config file format:
```
kinesis:
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```
##### kinesis_sts_assume_role_arn
@ -1631,7 +1631,7 @@ AWS STS role ARN to use for Kinesis authentication.
- Config file format:
```
kinesis:
sts_assume_role_arn: arn:aws:iam::1234567890:role/kinesis-role
sts_assume_role_arn: arn:aws:iam::1234567890:role/kinesis-role
```
##### kinesis_status_stream
@ -1645,7 +1645,7 @@ Name of the Kinesis stream to write osquery status logs received from clients.
- Config file format:
```
kinesis:
status_stream: osquery_status
status_stream: osquery_status
```
The IAM role used to send to Kinesis must allow the following permissions on
@ -1665,7 +1665,7 @@ Name of the Kinesis stream to write osquery result logs received from clients.
- Config file format:
```
kinesis:
result_stream: osquery_result
result_stream: osquery_result
```
The IAM role used to send to Kinesis must allow the following permissions on
@ -1724,7 +1724,7 @@ AWS region to use for Lambda connection.
- Config file format:
```
lambda:
region: ca-central-1
region: ca-central-1
```
##### lambda_access_key_id
@ -1745,7 +1745,7 @@ AWS access key ID to use for Lambda authentication.
- Config file format:
```
lambda:
access_key_id: AKIAIOSFODNN7EXAMPLE
access_key_id: AKIAIOSFODNN7EXAMPLE
```
##### lambda_secret_access_key
@ -1761,7 +1761,7 @@ AWS secret access key to use for Lambda authentication.
- Config file format:
```
lambda:
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```
##### lambda_sts_assume_role_arn
@ -1777,7 +1777,7 @@ AWS STS role ARN to use for Lambda authentication.
- Config file format:
```
lambda:
sts_assume_role_arn: arn:aws:iam::1234567890:role/lambda-role
sts_assume_role_arn: arn:aws:iam::1234567890:role/lambda-role
```
##### lambda_status_function
@ -1810,7 +1810,7 @@ Name of the Lambda function to write osquery result logs received from clients.
- Config file format:
```
lambda:
result_function: resultFunction
result_function: resultFunction
```
The IAM role used to send to Lambda must allow the following permissions on
@ -2087,7 +2087,7 @@ AWS region to use for SES connection.
- Config file format:
```yaml
ses:
region: us-east-2
region: us-east-2
```
##### ses_access_key_id
@ -2106,7 +2106,7 @@ AWS access key ID to use for Lambda authentication.
- Config file format:
```
ses:
access_key_id: AKIAIOSFODNN7EXAMPLE
access_key_id: AKIAIOSFODNN7EXAMPLE
```
##### ses_secret_access_key
@ -2125,7 +2125,7 @@ AWS secret access key to use for SES authentication.
- Config file format:
```yaml
ses:
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```
##### ses_sts_assume_role_arn
@ -2139,7 +2139,7 @@ AWS STS role ARN to use for SES authentication.
- Config file format:
```yaml
ses:
sts_assume_role_arn: arn:aws:iam::1234567890:role/ses-role
sts_assume_role_arn: arn:aws:iam::1234567890:role/ses-role
```
##### ses_source_arn
@ -2155,7 +2155,7 @@ for the email address specified in the Source parameter of SendRawEmail.
- Config file format:
```yaml
ses:
sts_assume_role_arn: arn:aws:iam::1234567890:role/ses-role
sts_assume_role_arn: arn:aws:iam::1234567890:role/ses-role
```
#### S3 file carving backend
@ -2169,7 +2169,7 @@ Name of the S3 bucket to use to store file carves.
- Config file format:
```
s3:
bucket: some-carve-bucket
bucket: some-carve-bucket
```
##### s3_prefix
@ -2183,7 +2183,7 @@ All carve objects will also be prefixed by date and hour (UTC), making the resul
- Config file format:
```
s3:
prefix: carves-go-here/
prefix: carves-go-here/
```
##### s3_access_key_id
@ -2200,7 +2200,7 @@ The IAM identity used in this context must be allowed to perform the following a
- Config file format:
```
s3:
access_key_id: AKIAIOSFODNN7EXAMPLE
access_key_id: AKIAIOSFODNN7EXAMPLE
```
##### s3_secret_access_key
@ -2212,7 +2212,7 @@ AWS secret access key to use for S3 authentication.
- Config file format:
```
s3:
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```
##### s3_sts_assume_role_arn
@ -2224,7 +2224,7 @@ AWS STS role ARN to use for S3 authentication.
- Config file format:
```
s3:
sts_assume_role_arn: arn:aws:iam::1234567890:role/some-s3-role
sts_assume_role_arn: arn:aws:iam::1234567890:role/some-s3-role
```
##### s3_endpoint_url
@ -2237,7 +2237,7 @@ or running s3 locally with localstack. Leave this blank to use the default S3 se
- Config file format:
```
s3:
endpoint_url: http://localhost:9000
endpoint_url: http://localhost:9000
```
##### s3_disable_ssl
@ -2249,7 +2249,7 @@ AWS S3 Disable SSL. Useful for local testing.
- Config file format:
```
s3:
disable_ssl: false
disable_ssl: false
```
##### s3_force_s3_path_style
@ -2266,7 +2266,7 @@ See [here](http://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html) f
- Config file format:
```
s3:
force_s3_path_style: false
force_s3_path_style: false
```
##### s3_region
@ -2280,7 +2280,7 @@ Minio users must set this to any nonempty value (eg. `minio`), as Minio does not
- Config file format:
```
s3:
region: us-east-1
region: us-east-1
```
##### Example YAML
@ -2322,7 +2322,7 @@ When `current_instance_checks` is set to `auto` (the default), Fleet instances w
- Config file format:
```
vulnerabilities:
databases_path: /some/path
databases_path: /some/path
```
##### periodicity
@ -2334,7 +2334,7 @@ How often vulnerabilities are checked. This is also the interval at which the co
- Config file format:
```
vulnerabilities:
periodicity: 1h
periodicity: 1h
```
##### cpe_database_url
@ -2349,7 +2349,7 @@ If this value is not defined, Fleet checks for the latest release in Github and
- Config file format:
```
vulnerabilities:
cpe_database_url: ""
cpe_database_url: ""
```
##### cpe_translations_url
@ -2365,7 +2365,7 @@ If this value is not defined, Fleet checks for the latest release in Github and
- Config file format:
```
vulnerabilities:
cpe_translations_url: ""
cpe_translations_url: ""
```
##### cve_feed_prefix_url
@ -2380,7 +2380,7 @@ When not defined, Fleet downloads from the nvd.nist.gov host.
- Config file format:
```
vulnerabilities:
cve_feed_prefix_url: ""
cve_feed_prefix_url: ""
```
##### current_instance_checks
@ -2392,7 +2392,7 @@ When running multiple instances of the Fleet server, by default, one of them dyn
- Config file format:
```
vulnerabilities:
current_instance_checks: yes
current_instance_checks: yes
```
##### disable_schedule
@ -2405,7 +2405,7 @@ tools like crontab.
- Config file format:
```
vulnerabilities:
disable_schedule: false
disable_schedule: false
```
##### disable_data_sync
@ -2421,7 +2421,7 @@ To download the data streams, you can use `fleetctl vulnerability-data-stream --
- Config file format:
```
vulnerabilities:
disable_data_sync: true
disable_data_sync: true
```
##### recent_vulnerability_max_age
@ -2447,7 +2447,7 @@ in your Fleet). Setting this to true will cause Fleet to skip both processes.
- Config file format:
```
vulnerabilities:
disable_win_os_vulnerabilities: true
disable_win_os_vulnerabilities: true
```
##### Example YAML
@ -2745,11 +2745,11 @@ packaging:
## Mobile device management (MDM)
> MDM features require some endpoints to be publicly accessible outside your VPN or intranet, for more details see [What API endpoints should I expose to the public internet?](./FAQ.md#what-api-endpoints-should-i-expose-to-the-public-internet)
> MDM features require some endpoints to be publicly accessible outside your VPN or intranet, for more details see [What API endpoints should I expose to the public internet?](https://fleetdm.com/docs/get-started/faq#what-api-endpoints-should-i-expose-to-the-public-internet)
This section is a reference for the configuration required to turn on MDM features in production.
If you're a Fleet contributor and you'd like to turn on MDM features in a local environment, see the guided instructions [here](../Contributing/Testing-and-local-development.md#mdm-setup-and-testing).
If you're a Fleet contributor and you'd like to turn on MDM features in a local environment, see the guided instructions [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Testing-and-local-development.md#mdm-setup-and-testing).
##### mdm.apple_apns_cert_bytes
@ -3222,5 +3222,5 @@ The HTTP request headers are checked in the following order:
If the IP retrieved using the above heuristic belongs to a private range, then Fleet will ignore it and will not set the "Public IP address" field for the device.
<meta name="pageOrderInSection" value="300">
<meta name="pageOrderInSection" value="100">
<meta name="description" value="This page includes resources for configuring the Fleet binary, managing osquery configurations, and running with systemd.">

4
docs/Contributing/Testing-and-local-development.md
View file

@ -512,13 +512,13 @@ To enable the [DEP](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/g
First ask @zwass to create an account for you in [ABM](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#abm-apple-business-manager). You'll need an account to generate an encrypted token.
Once you have access to ABM, follow [these guided instructions](../Using-Fleet/Mobile-device-management.md#apple-business-manager-abm) in the user facing docs to generate the private key, certificate, and encrypted token.
Once you have access to ABM, follow [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-setup#apple-business-manager-abm) in the user facing docs to generate the private key, certificate, and encrypted token.
### APNs and SCEP setup
The server also needs a private key + certificate to identify with Apple's [APNs](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#apns-apple-push-notification-service) servers, and another for [SCEP](https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/glossary-and-protocols.md#scep-simple-certificate-enrollment-protocol).
To generate both, follow [these guided instructions](../Using-Fleet/Mobile-device-management.md#apple-push-notification-service-apns).
To generate both, follow [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-setup#apple-push-notification-service-apns).
Note that:

0
docs/Deploying/Introduction.md → docs/Deploy/Introduction.md
View file

1
docs/Using-Fleet/Monitoring-Fleet.md → docs/Deploy/Monitoring-Fleet.md
View file

@ -103,3 +103,4 @@ The `fleetctl debug archive` command retrieves information generated by Go's [`n
<meta name="pageOrderInSection" value="800">
<meta name="description" value="Learn about monitoring and scaling Fleet servers with health checks, metrics, and alerting.">
<meta name="navSection" value="TBD">

22
docs/Deploy/README.md Normal file
View file

@ -0,0 +1,22 @@
# Deploy
### [Introduction](./Introduction.md)
Provides an introduction to Fleet and its requirements and dependencies.
### [Server installation](./Server-Installation.md)
Includes deployment walkthroughs for Fleet on CentOS, Kubernetes, and AWS ECS.
### [Upgrading Fleet](./Upgrading-Fleet.md)
Includes a guide for how to update and run new versions of Fleet.
### [Reference architecture](./reference-architectures.md)
An opinionated view of running Fleet in a production environment, and configuration strategies to enable high availability.
### [Monitoring Fleet](./monitoring-fleet.md)
Learn about monitoring and scaling Fleet servers with health checks, metrics, and alerting
### [Deploying to Cloud.gov](./cloudgov.md)
A guide for deploying Fleet on Cloud.gov.
<meta name="description" value="An overview of the deployment documentation for Fleet.">

0
docs/Deploying/Reference-Architectures.md → docs/Deploy/Reference-Architectures.md
View file

3
docs/Deploying/Server-Installation.md → docs/Deploy/Server-Installation.md
View file

@ -25,7 +25,7 @@
- [Deploying the load balancer](#deploying-the-load-balancer)
- [Configure DNS](#configure-dns)
- [Fleet on AWS ECS](#deploying-fleet-on-aws-ecs)
- [Building Fleet from Source](https://fleetdm.com/docs/contributing/building-fleet)
- [Building Fleet from Source](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Building-Fleet.md)
- [Community projects](#community-projects)
## Fleet on CentOS
@ -522,3 +522,4 @@ Below are some projects created by Fleet community members. These projects provi
<meta name="pageOrderInSection" value="200">
<meta name="description" value="Information on installing and running the Fleet server on various platforms, including CentOS, Kubernetes, and AWS ECS.">
<meta name="navSection" value="Deployment guides">

0
docs/Deploying/Upgrading-Fleet.md → docs/Deploy/Upgrading-Fleet.md
View file

1
docs/Deploying/cloudgov.md → docs/Deploy/cloudgov.md
View file

@ -113,3 +113,4 @@ variables](https://fleetdm.com/docs/deploying/configuration#using-only-environme
<meta name="title" value="Cloud.gov">
<meta name="pageOrderInSection" value="700">
<meta name="description" value="A guide for deploying Fleet on Cloud.gov.">
<meta name="navSection" value="Deployment guides">

223
docs/Deploying/FAQ.md
View file

@ -1,223 +0,0 @@
# Deployment FAQ
- [How do I get support for working with Fleet?](#how-do-i-get-support-for-working-with-fleet)
- [Can multiple instances of the Fleet server be run behind a load-balancer?](#can-multiple-instances-of-the-fleet-server-be-run-behind-a-load-balancer)
- [Why aren't my osquery agents connecting to Fleet?](#why-arent-my-osquery-agents-connecting-to-fleet)
- [How do I fix "certificate verify failed" errors from osqueryd?](#how-do-i-fix-certificate-verify-failed-errors-from-osqueryd)
- [What do I need to do to change the Fleet server TLS certificate?](#what-do-i-need-to-do-to-change-the-fleet-server-tls-certificate)
- [How do I migrate hosts from one Fleet server to another (eg. testing to production)?](#how-do-i-migrate-hosts-from-one-fleet-server-to-another-eg-testing-to-production)
- [What do I do about "too many open files" errors?](#what-do-i-do-about-too-many-open-files-errors)
- [Can I skip versions when updating Fleet to the latest version?](#can-i-skip-versions-when-updating-to-the-latest-version)
- [I upgraded my database, but Fleet is still running slowly. What could be going on?](#i-upgraded-my-database-but-fleet-is-still-running-slowly-what-could-be-going-on)
- [Why am I receiving a database connection error when attempting to "prepare" the database?](#why-am-i-receiving-a-database-connection-error-when-attempting-to-prepare-the-database)
- [Is Fleet available as a SaaS product?](#is-fleet-available-as-a-saas-product)
- [What MySQL versions are supported?](#what-mysql-versions-are-supported)
- [What are the MySQL user access requirements?](#what-are-the-mysql-user-requirements)
- [Does Fleet support MySQL replication?](#does-fleet-support-mysql-replication)
- [What is duplicate enrollment and how do I fix it?](#what-is-duplicate-enrollment-and-how-do-i-fix-it)
- [What API endpoints should I expose to the public internet?](#what-api-endpoints-should-i-expose-to-the-public-internet)
- [What Redis versions are supported?](#what-redis-versions-are-supported)
- [Will my older version of Fleet work with Redis 6?](#will-my-older-version-of-fleet-work-with-redis-6)
## How do I get support for working with Fleet?
For bug reports, please use the [Github issue tracker](https://github.com/fleetdm/fleet/issues).
For questions and discussion, please join us in the #fleet channel of [osquery Slack](https://fleetdm.com/slack).
## Can multiple instances of the Fleet server be run behind a load-balancer?
Yes. Fleet scales horizontally out of the box as long as all of the Fleet servers are connected to the same MySQL and Redis instances.
Note that osquery logs will be distributed across the Fleet servers.
Read the [performance documentation](https://fleetdm.com/docs/using-fleet/monitoring-fleet#fleet-server-performance) for more.
## Why aren't my osquery agents connecting to Fleet?
This can be caused by a variety of problems. The best way to debug is usually to add `--verbose --tls_dump` to the arguments provided to `osqueryd` and look at the logs for the server communication.
### Common problems
- `Connection refused`: The server is not running, or is not listening on the address specified. Is the server listening on an address that is available from the host running osquery? Do you have a load balancer that might be blocking connections? Try testing with `curl`.
- `No node key returned`: Typically this indicates that the osquery client sent an incorrect enroll secret that was rejected by the server. Check what osquery is sending by looking in the logs near this error.
- `certificate verify failed`: See [How do I fix "certificate verify failed" errors from osqueryd](#how-do-i-fix-certificate-verify-failed-errors-from-osqueryd).
- `bad record MAC`: When generating your certificate for your Fleet server, ensure you set the hostname to the FQDN or the IP of the server. This error is common when setting up Fleet servers and accepting defaults when generating certificates using `openssl`.
## How do I fix "certificate verify failed" errors from osqueryd?
Osquery requires that all communication between the agent and Fleet are over a secure TLS connection. For the safety of osquery deployments, there is no (convenient) way to circumvent this check.
- Try specifying the path to the full certificate chain used by the server using the `--tls_server_certs` flag in `osqueryd`. This is often unnecessary when using a certificate signed by an authority trusted by the system, but is mandatory when working with self-signed certificates. In all cases it can be a useful debugging step.
- Ensure that the CNAME or one of the Subject Alternate Names (SANs) on the certificate matches the address at which the server is being accessed. If osquery connects via `https://localhost:443`, but the certificate is for `https://fleet.example.com`, the verification will fail.
- Is Fleet behind a load-balancer? Ensure that if the load-balancer is terminating TLS, this is the certificate provided to osquery.
- Does the certificate verify with `curl`? Try `curl -v -X POST https://fleetserver:port/api/v1/osquery/enroll`.
## What do I need to do to change the Fleet server TLS certificate?
If the both the existing and new certificates verify with osquery's default root certificates (such as a certificate issued by a well-known Certificate Authority) and no certificate chain was deployed with osquery, there is no need to deploy a new certificate chain.
If osquery has been deployed with the full certificate chain (using `--tls_server_certs`), deploying a new certificate chain is necessary to allow for verification of the new certificate.
Deploying a certificate chain cannot be done centrally from Fleet.
## How do I use a proxy server with Fleet?
Seeing your proxy's requests fail with an error like `DEPTH_ZERO_SELF_SIGNED_CERT`)?
To get your proxy server's HTTP client to work with a local Fleet when using a self-signed cert, disable SSL / self-signed verification in the client.
The exact solution to this depends on the request client you are using. For example, when using Node.js ± Sails.js, you can work around this in the requests you're sending with `await sails.helpers.http.get()` by lifting your app with the `NODE_TLS_REJECT_UNAUTHORIZED` environment variable set to `0`:
```
NODE_TLS_REJECT_UNAUTHORIZED=0 sails console
```
## I'm only getting partial results from live queries
Redis has an internal buffer limit for pubsub that Fleet uses to communicate query results. If this buffer is filled, extra data is dropped. To fix this, we recommend disabling the buffer size limit. Most installs of Redis should have plenty of spare memory to not run into issues. More info about this limit can be found [here](https://redis.io/topics/clients#:~:text=Pub%2FSub%20clients%20have%20a,64%20megabyte%20per%2060%20second.) and [here](https://raw.githubusercontent.com/redis/redis/unstable/redis.conf) (search for client-output-buffer-limit).
We recommend a config like the following:
```
client-output-buffer-limit pubsub 0 0 60
```
## How do I migrate hosts from one Fleet server to another (eg. testing to production)?
Primarily, this would be done by changing the `--tls_hostname` and enroll secret to the values for the new server. In some circumstances (see [What do I need to do to change the Fleet server TLS certificate?](#what-do-i-need-to-do-to-change-the-fleet-server-tls-certificate)) it may be necessary to deploy a new certificate chain configured with `--tls_server_certs`.
These configurations cannot be managed centrally from Fleet.
## What do I do about "too many open files" errors?
This error usually indicates that the Fleet server has run out of file descriptors. Fix this by increasing the `ulimit` on the Fleet process. See the `LimitNOFILE` setting in the [example systemd unit file](https://fleetdm.com/docs/deploying/configuration#runing-with-systemd) for an example of how to do this with systemd.
Some deployments may benefit by setting the [`--server_keepalive`](https://fleetdm.com/docs/deploying/configuration#server-keepalive) flag to false.
This was also seen as a symptom of a different issue: if you're deploying on AWS on T type instances, there are different scenarios where the activity can increase and the instances will burst. If they run out of credits, then they'll stop processing leaving the file descriptors open.
## Can I skip versions when updating Fleet to the latest version?
Absolutely! If you're updating from the current major release of Fleet (v4), you can install the [latest version](https://github.com/fleetdm/fleet/releases/latest) without upgrading to each minor version along the way. Just make sure to back up your database in case anything odd does pop up!
If you're updating from an older version (we'll use Fleet v3 as an example), it's best to take some stops along the way:
1. Back up your database.
2. Upgrade to the last release of of v3 - [3.13.0](https://github.com/fleetdm/fleet/releases/tag/3.13.0).
3. Migrate the database.
4. Test
5. Check the release post for [v4.0.0 ](https://github.com/fleetdm/fleet/releases/tag/v4.0.0) to see the breaking changes and get Fleet ready for v4.
6. Upgrade to v4.0.0.
7. Migrate the database.
8. Test
9. Upgrade to the [current release](https://github.com/fleetdm/fleet/releases/latest).
10. One last migration.
11. Test again for good measure.
Taking it a bit slower on major releases gives you an opportunity to better track down where any issues may have been introduced.
## I upgraded my database, but Fleet is still running slowly. What could be going on?
This could be caused by a mismatched connection limit between the Fleet server and the MySQL server that prevents Fleet from fully utilizing the database. First [determine how many open connections your MySQL server supports](https://dev.mysql.com/doc/refman/8.0/en/too-many-connections.html). Now set the [`--mysql_max_open_conns`](https://fleetdm.com/docs/deploying/configuration#mysql-max-open-conns) and [`--mysql_max_idle_conns`](https://fleetdm.com/docs/deploying/configuration#mysql-max-idle-conns) flags appropriately.
## Why am I receiving a database connection error when attempting to "prepare" the database?
First, check if you have a version of MySQL installed that is at least 5.7. Then, make sure that you currently have a MySQL server running.
The next step is to make sure the credentials for the database match what is expected. Test your ability to connect to the database with `mysql -u<username> -h<hostname_or_ip> -P<port> -D<database_name> -p`.
If you're successful connecting to the database and still receive a database connection error, you may need to specify your database credentials when running `fleet prepare db`. It's encouraged to put your database credentials in environment variables or a config file.
```
fleet prepare db \
--mysql_address=<database_address> \
--mysql_database=<database_name> \
--mysql_username=<username> \
--mysql_password=<database_password>
```
## Is Fleet available as a SaaS product?
Yes! Please sign up for the [Fleet Cloud Beta](https://kqphpqst851.typeform.com/to/yoo5smT9).
## What MySQL versions are supported?
Fleet is tested with MySQL 5.7.21 and 8.0.28. Newer versions of MySQL 5.7 and MySQL 8 typically work well. AWS Aurora requires at least version 2.10.0. Please avoid using MariaDB or other MySQL variants that are not officially supported. Compatibility issues have been identified with MySQL variants and these may not be addressed in future Fleet releases.
## What are the MySQL user requirements?
The user `fleet prepare db` (via environment variable `FLEET_MYSQL_USERNAME` or command line flag `--mysql_username=<username>`) uses to interact with the database needs to be able to create, alter, and drop tables as well as the ability to create temporary tables.
## Does Fleet support MySQL replication?
You can deploy MySQL or Maria any way you want. We recommend using managed/hosted mysql so you don't have to think about it, but you can think about it more if you want. Read replicas are supported. You can read more about MySQL configuration [here](https://fleetdm.com/docs/deploying/configuration#mysql).
## What is duplicate enrollment and how do I fix it?
Duplicate host enrollment is when more than one host enrolls in Fleet using the same identifier
(hardware UUID or osquery generated UUID).
Typically, this is caused by cloning a VM Image with an already enrolled
osquery client, which results in duplicate osquery generated UUIDs. To resolve this issue, it is
advised to configure `--osquery_host_identifier=uuid` (which will use the hardware UUID), and then
delete the associated host in the Fleet UI.
In rare instances, VM Hypervisors have been seen to duplicate hardware UUIDs. When this happens,
using `--osquery_host_identifier=uuid` will not resolve the duplicate enrollment problem. Sometimes
the problem can be resolved by setting `--osquery_host_identifier=instance` (which will use the
osquery generated UUID), and then delete the associated host in the Fleet UI.
Find more information about [host identifiers here](https://fleetdm.com/docs/deploying/configuration#osquery-host-identifier).
## How do I resolve an "unknown column" error when upgrading Fleet?
The `unknown column` error typically occurs when the database migrations haven't been run during the upgrade process.
Check out the [documentation on running database migrations](https://fleetdm.com/docs/deploying/upgrading-fleet#running-database-migrations) to resolve this issue.
## What API endpoints should I expose to the public internet?
If you would like to manage hosts that can travel outside your VPN or intranet we recommend only exposing the osquery endpoints to the public internet:
- `/api/osquery`
- `/api/v1/osquery`
If you are using Fleet Desktop and want it to work on remote devices, the bare minimum API to expose is `/api/latest/fleet/device/*/desktop`. This minimal endpoint will only provide the number of failing policies.
For full Fleet Desktop functionality, `/api/fleet/orbit/*` and`/api/fleet/device/ping` must also be exposed.
If you would like to use the fleetctl CLI from outside of your network, the following endpoints will also need to be exposed for `fleetctl`:
- `/api/setup`
- `/api/v1/setup`
- `/api/latest/fleet/*`
- `/api/v1/fleet/*`
If you would like to use Fleet's MDM features, the following endpoints need to be exposed:
- `/mdm/apple/scep` to allow hosts to obtain a SCEP certificate.
- `/mdm/apple/mdm` to allow hosts to reach the server using the MDM protocol.
- `/api/mdm/apple/enroll` to allow DEP enrolled devices to get an enrollment profile.
- `/api/*/fleet/device/*/mdm/apple/manual_enrollment_profile` to allow manually enrolled devices to
download an enrollment profile.
> The `/mdm/apple/scep` and `/mdm/apple/mdm` endpoints are outside of the `/api` path because they
> are not RESTful, and are not intended for use by API clients or browsers.
## What is the minimum version of MySQL required by Fleet?
Fleet requires at least MySQL version 5.7.
## How do I migrate from Fleet Free to Fleet Premium?
To migrate from Fleet Free to Fleet Premium, once you get a Fleet license, set it as a parameter to `fleet serve` either as an environment variable using `FLEET_LICENSE_KEY` or in the Fleet's config file. See [here](https://fleetdm.com/docs/deploying/configuration#license) for more details. Note: You don't need to redeploy Fleet after the migration.
## What Redis versions are supported?
Fleet is tested with Redis 5.0.14 and 6.2.7. Any version Redis after version 5 will typically work well.
## Will my older version of Fleet work with Redis 6?
Most likely, yes! While we'd definitely recommend keeping Fleet up to date in order to take advantage of new features and bug patches, most legacy versions should work with Redis 6. Just keep in mind that we likely haven't tested your particular combination so that you may run into some unforeseen hiccups.
<meta name="description" value="Commonly asked questions and answers about deployment from the Fleet community.">

27
docs/Deploying/README.md
View file

@ -1,27 +0,0 @@
# Deployment
### [Introduction](./Introduction.md)
Provides an introduction to Fleet and its requirements and dependencies.
### [Server installation](./Server-Installation.md)
Includes deployment walkthroughs for Fleet on CentOS, Kubernetes, and AWS ECS.
### [Configuration](./Configuration.md)
Includes resources for configuring the Fleet binary, managing osquery configurations, and running with systemd
### [Self-managed agent updates](./fleetctl-agent-updates.md)
Information about running an update server with fleetctl.
### [Load testing](./Load-testing.md)
Information about running an update server with fleetctl.
### [Upgrading Fleet](./Upgrading-Fleet.md)
Includes a guide for how to update and run new versions of Fleet.
### [Debugging](./Debugging.md)
Information to gather as part of debugging an issue with a deployment.
### [FAQ](./FAQ.md)
Includes commonly asked questions and answers about deployment from the Fleet community.
<meta name="description" value="An overview of the deployment documentation for Fleet.">

335
docs/Using-Fleet/FAQ.md → docs/Get started/FAQ.md
View file

@ -1,16 +1,18 @@
# Using Fleet FAQ
# FAQ
## How can I switch to Fleet from Kolide Fleet?
## Using Fleet
### How can I switch to Fleet from Kolide Fleet?
To migrate to Fleet from Kolide Fleet, please follow the steps outlined in the [Upgrading Fleet section](https://fleetdm.com/docs/deploying/upgrading-fleet) of the documentation.
## Has anyone stress tested Fleet? How many hosts can the Fleet server handle?
### Has anyone stress tested Fleet? How many hosts can the Fleet server handle?
Fleet has been stress tested to 150,000 online hosts and 400,000 total enrolled hosts. Production deployments exist with over 100,000 hosts and numerous production deployments manage tens of thousands of hosts.
It’s standard deployment practice to have multiple Fleet servers behind a load balancer. However, typically the MySQL database is the performance bottleneck and a single Fleet server can handle tens of thousands of hosts.
## Can I target my hosts using their enroll secrets?
### Can I target my hosts using their enroll secrets?
No, currently, there’s no way to retrieve the name of the enroll secret with a query. This means that there's no way to create a label using your hosts' enroll secrets and then use this label as a target for live queries or scheduled queries.
@ -18,29 +20,29 @@ Typically folks will use some other unique identifier to create labels that dist
There is, however, a way to accomplish this even though the answer to the question remains "no": Teams. As of Fleet v4.0.0, you can group hosts in Teams either by enrolling them with a team specific secret, or by transferring hosts to a team. One the hosts you want to target are part of a team, you can create a query and target the team in question.
## How often do labels refresh? Is the refresh frequency configurable?
### How often do labels refresh? Is the refresh frequency configurable?
The update frequency for labels is configurable with the [—osquery_label_update_interval](https://fleetdm.com/docs/deploying/configuration#osquery-label-update-interval) flag (default 1 hour).
## How do I revoke the authorization tokens for a user?
### How do I revoke the authorization tokens for a user?
Authorization tokens are revoked when the “require password reset” action is selected for that user. User-initiated password resets do not expire the existing tokens.
## How do I monitor the performance of my queries?
### How do I monitor the performance of my queries?
Fleet can live query the `osquery_schedule` table. Performing this live query allows you to get the performance data for your scheduled queries. Also consider scheduling a query to the `osquery_schedule` table to get these logs into your logging pipeline.
## How do I monitor a Fleet server?
### How do I monitor a Fleet server?
Fleet provides standard interfaces for monitoring and alerting. See the [Monitoring Fleet](https://fleetdm.com/docs/using-fleet/monitoring-fleet) documentation for details.
## Why is the “Add User” button disabled?
### Why is the “Add User” button disabled?
The “Add User” button is disabled if SMTP (email) has not been configured for the Fleet server. Currently, there is no way to add new users without email capabilities.
One way to hack around this is to use a simulated mailserver like [Mailhog](https://github.com/mailhog/MailHog). You can retrieve the email that was “sent” in the Mailhog UI, and provide users with the invite URL manually.
## Can I disable password-based authentication in the Fleet UI?
### Can I disable password-based authentication in the Fleet UI?
Some folks like to enforce users with SAML SSO enabled to login only via the SSO and not via password.
@ -49,18 +51,18 @@ However, users that have SSO enabled in Fleet will not be able to log in via pas
If a user has SSO enabled, the Login page in the Fleet UI displays the “Email” and “Password” fields but on attempted password-based login, this user will receive an “Authentication failed” message.
## Where are my query results?
### Where are my query results?
### Live queries
#### Live queries
Live query results (executed in the web UI or `fleetctl query`) are pushed directly to the UI where the query is running. The results never go to a file unless you as the user manually save them.
### Scheduled queries
#### Scheduled queries
Scheduled query results from enrolled hosts can be logged by Fleet.
For results to go to Fleet, the osquery `--logger_plugin` flag must be set to `tls`.
### What are my options for storing the osquery logs?
#### What are my options for storing the osquery logs?
Folks typically use Fleet to ship logs to data aggregation systems like Splunk, the ELK stack, and Graylog.
@ -70,7 +72,7 @@ See:
- https://fleetdm.com/docs/deploying/configuration#osquery-result-log-plugin.
- https://fleetdm.com/docs/deploying/configuration#osquery-status-log-plugin.
### Troubleshooting
#### Troubleshooting
Expecting results, but not seeing anything in the logs?
@ -80,30 +82,30 @@ Expecting results, but not seeing anything in the logs?
- Use live query to `SELECT * FROM osquery_schedule` to check whether the query has been scheduled on the host.
- Look at the status logs provided by osquery. In a standard configuration these are available on the filesystem of the Fleet server at the path configurable by [`--filesystem_status_log_file`](https://fleetdm.com/docs/deploying/configuration#filesystem-status-log-file). This defaults to `/tmp/osquery_status`. The host will output a status log each time it executes the query.
## Why does the same query come back faster sometimes?
### Why does the same query come back faster sometimes?
Don't worry, this behavior is expected; it's part of how osquery works.
Fleet and osquery work together by communicating with heartbeats. Depending on how close the next heartbeat is, Fleet might return results a few seconds faster or slower.
>By the way, to get around a phenomena called the "thundering herd problem", these heartbeats aren't exactly the same number of seconds apart each time. osquery implements a "splay", a few ± milliseconds that are added to or subtracted from the heartbeat interval to prevent these thundering herds. This helps prevent situations where many thousands of devices might unnecessarily attempt to communicate with the Fleet server at exactly the same time. (If you've ever used Socket.io, a similar phenomena can occur with that tool's automatic WebSocket reconnects.)
## Why don't my query results appear sorted based upon the ORDER BY clause I specified in my SQL query?
### Why don't my query results appear sorted based upon the ORDER BY clause I specified in my SQL query?
When a query executes in Fleet, the query is sent to all hosts at the same time, but results are returned from hosts at different times. In Fleet, results are shown as soon as Fleet receives a response from a host. Fleet does not sort the overall results across all hosts (the sort UI toggle is used for this). Instead, Fleet prioritizes speed when displaying the results. This means that if you use an `ORDER BY` clause selection criteria in a query, the results may not initially appear with your desired order, however, the sort UI toggle allows you to sort by ascending or descending order for any of the displayed columns.
## What happens if I have a query on a team policy and I also have it scheduled to run separately?
### What happens if I have a query on a team policy and I also have it scheduled to run separately?
Both queries will run as scheduled on applicable hosts. If there are any hosts that both the scheduled run and the policy apply to, they will be queried twice.
## Why aren’t my live queries being logged?
### Why aren’t my live queries being logged?
Live query results are never logged to the filesystem of the Fleet server. See [Where are my query results?](#where-are-my-query-results).
## Why does my query work locally with osquery but not in Fleet?
### Why does my query work locally with osquery but not in Fleet?
If you're seeing query results using `osqueryi` but not through Fleet, the most likely culprit is a permissions issue. Check out the [osquery docs](https://osquery.readthedocs.io/en/stable/deployment/process-auditing/#full-disk-access) for more details and instructions for setting up Full Disk Access.
## Can I use the Fleet API to fetch results from a scheduled query?
### Can I use the Fleet API to fetch results from a scheduled query?
You cannot. Scheduled query results are logged to whatever logging plugin you have configured and are not stored in the Fleet DB.
@ -119,7 +121,7 @@ Once the Software inventory feature is turned on, a list of a specific host’s
It’s possible in Fleet to retrieve each host’s kernel version, using the Fleet API, through `additional_queries`. The Fleet configuration options YAML file includes an `additional_queries` property that allows you to append custom query results to the host details returned by the `api/v1/fleet/hosts` endpoint. [Check out an example configuration file with the additional_queries field](https://fleetdm.com/docs/using-fleet/fleetctl-cli#fleet-configuration-options).
## Why is my host not updating a policy's response?
### Why is my host not updating a policy's response?
The following are reasons why a host may not be updating a policy's response:
@ -127,21 +129,21 @@ The following are reasons why a host may not be updating a policy's response:
* The policy's query includes invalid SQL syntax. If your policy's query includes invalid syntax, this policy will not update its response. You can check the syntax of your query by heading to the **Queries** page, selecting your query, and then selecting "Save."
## What should I do if my computer is showing up as an offline host?
### What should I do if my computer is showing up as an offline host?
If your device is showing up as an offline host in the Fleet instance, and you're sure that the computer has osquery running, we recommend trying the following:
* Try un-enrolling and re-enrolling the host. You can do this by uninstalling osquery on the host and then enrolling your device again using one of the [recommended methods](https://fleetdm.com/docs/using-fleet/adding-hosts).
## How does Fleet deal with IP duplication?
### How does Fleet deal with IP duplication?
Fleet relies on UUIDs so any overlap with host IP addresses should not cause a problem. The only time this might be an issue is if you are running a query that involves a specific IP address that exists in multiple locations as it might return multiple results - [Fleet's teams feature](https://fleetdm.com/docs/using-fleet/teams) can be used to restrict queries to specific hosts.
## Can fleetd run alongside osquery?
### Can fleetd run alongside osquery?
Yes, fleetd can be run alongside an existing, separately-installed osqueryd. If you have an existing osqueryd installed on a given host, you don't have to remove it prior to installing fleetd. The osquery instance provided by fleetd uses its own database directory that doesn't interfere with other osquery isntances installed on the host.
## Can I control how fleetd handles updates?
### Can I control how fleetd handles updates?
Yes, auto-updates can be disabled entirely by passing `--disable-updates` as a flag when running `fleetctl package` to generate your installer (easy) or by deploying a modified systemd file to your hosts (more complicated). We'd recommend the flag:
@ -149,7 +151,7 @@ Yes, auto-updates can be disabled entirely by passing `--disable-updates` as a f
fleetctl package --fleetctl package --type=deb --fleet-url=https://localhost:8080 --enroll-secret=superRandomSecret --disable-updates
```
You can also indicate the [channels you would like Fleetd to watch for updates](./fleetd.md#update-channels) using the `--orbit-channel`, `--desktop-channel` , and `--osqueryd-channel` flags:
You can also indicate the [channels you would like Fleetd to watch for updates](https://fleetdm.com/docs/using-fleet/fleetd#update-channels) using the `--orbit-channel`, `--desktop-channel` , and `--osqueryd-channel` flags:
```
fleetctl package --fleetctl package --type=deb --fleet-url=https://localhost:8080 --enroll-secret=superRandomSecret --orbit-channel=edge --desktop-channel=stable --osquery-channel=4
@ -169,15 +171,15 @@ Fleetd checks for update metadata and downloads binaries at `tuf.fleetctl.com`.
This isn't supported yet, but we're working on it!
## What happens to osquery logs if my Fleet server or my logging destination is offline?
### What happens to osquery logs if my Fleet server or my logging destination is offline?
If Fleet can't send logs to the destination, it will return an error to osquery. This causes osquery to retry sending the logs. The logs will then be stored in osquery's internal buffer until they are sent successfully, or they get expired if the `buffered_log_max`(defaults to 1,000,000 logs) is exceeded. Check out the [Remote logging buffering section](https://osquery.readthedocs.io/en/latest/deployment/remote/#remote-logging-buffering) on the osquery docs for more on this behavior.
## How does Fleet work with osquery extensions?
### How does Fleet work with osquery extensions?
Any extension table available in a host enrolled to Fleet can be queried by Fleet. Note that the "compatible with" message may show an error because it won't know your extension table, but the query will still work, and Fleet will gracefully ignore errors from any incompatible hosts.
## Why do I see "Unknown Certificate Error" when adding hosts to my dev server?
### Why do I see "Unknown Certificate Error" when adding hosts to my dev server?
If you are using a self-signed certificate on `localhost`, add the `--insecure` flag when building your installation packages:
@ -185,15 +187,15 @@ If you are using a self-signed certificate on `localhost`, add the `--insecure`
fleetctl package --fleetctl package --type=deb --fleet-url=https://localhost:8080 --enroll-secret=superRandomSecret --insecure
```
## Can I hide known vulnerabilities that I feel are insignificant?
### Can I hide known vulnerabilities that I feel are insignificant?
This isn't currently supported, but we're working on it! You can track that issue [here](https://github.com/fleetdm/fleet/issues/3152).
## Can I create reports based on historical data in Fleet?
### Can I create reports based on historical data in Fleet?
Currently, Fleet only stores the current state of your hosts (when they last communicated with Fleet). The best way at the moment to maintain historical data would be to use the [REST API](https://fleetdm.com/docs/using-fleet/rest-api) or the [`fleetctl` CLI](https://fleetdm.com/docs/using-fleet/fleetctl-cli) to retrieve it manually. Then save the data you need to your schedule.
## When do I need fleetctl vs. the REST API vs. the Fleet UI?
### When do I need fleetctl vs. the REST API vs. the Fleet UI?
[fleetctl](https://fleetdm.com/docs/using-fleet/fleetctl-cli) is great for users that like to do things in a terminal (like iTerm on a Mac). Lots of tech folks are real power users of the terminal. It is also helpful for automating things like deployments.
@ -201,19 +203,19 @@ The [REST API](https://fleetdm.com/docs/using-fleet/rest-api) is somewhat simila
The [Fleet UI](https://fleetdm.com/docs/using-fleet/fleet-ui) is built for human users to make interfacing with the Fleet server user-friendly and visually appealing. It also makes things simpler and more accessible to a broader range of users.
## Why can't I run queries with `fleetctl` using a new API-only user?
### Why can't I run queries with `fleetctl` using a new API-only user?
In versions prior to Fleet 4.13, a password reset is needed before a new API-only user can perform queries. You can find detailed instructions for setting that up [here](https://github.com/fleetdm/fleet/blob/a1eba3d5b945cb3339004dd1181526c137dc901c/docs/Using-Fleet/fleetctl-CLI.md#reset-the-password).
## Can I audit actions taken in Fleet?
### Can I audit actions taken in Fleet?
The [REST API `activities` endpoint](https://fleetdm.com/docs/using-fleet/rest-api#activities) provides a full breakdown of actions taken on queries, policies, and teams (Available in Fleet Premium) through the UI, the REST API, or `fleetctl`.
## How often is the software inventory updated?
### How often is the software inventory updated?
By default, Fleet will query hosts for software inventory hourly. If you'd like to set a different interval, you can update the [periodicity](https://fleetdm.com/docs/deploying/configuration#periodicity) in your vulnerabilities configuration.
## Can I group results from multiple hosts?
### Can I group results from multiple hosts?
There are a few ways you can go about getting counts of hosts that meet specific criteria using the REST API. You can use [`GET /api/v1/fleet/hosts`](https://fleetdm.com/docs/using-fleet/rest-api#list-hosts) or the [`fleetctl` CLI](https://fleetdm.com/docs/using-fleet/fleetctl-cli#available-commands) to gather a list of all hosts and then work with that data however you'd like. For example, you could retrieve all hosts using `fleetctl get hosts` and then use `jq` to pull out the data you need. The following example would give you a count of hosts by their OS version:
@ -230,7 +232,7 @@ $ fleetctl get hosts --json | jq '.spec .os_version' | sort | uniq -c
6 "macOS 12.3.1"
```
## How do I downgrade from Fleet Premium to Fleet Free?
### How do I downgrade from Fleet Premium to Fleet Free?
> If you'd like to renew your Fleet Premium license key, please contact us [here](https://fleetdm.com/company/contact).
@ -263,28 +265,28 @@ $ fleetctl get hosts --json | jq '.spec .os_version' | sort | uniq -c
1. Remove your license key from your Fleet configuration. Documentation on where the license key is located in your configuration is [here](https://fleetdm.com/docs/deploying/configuration#license).
2. Restart your Fleet server.
## If I use a software orchestration tool (Ansible, Chef, Puppet, etc.) to manage agent options, do I have to apply the same options in the Fleet UI?
### If I use a software orchestration tool (Ansible, Chef, Puppet, etc.) to manage agent options, do I have to apply the same options in the Fleet UI?
No. The agent options set using your software orchestration tool will override the default agent options that appear in the **Settings > Organization settings > Agent options** page. On this page, if you hit the **Save** button, the options that appear in the Fleet UI will override the agent options set using your software orchestration.
## How can I uninstall the osquery agent?
### How can I uninstall the osquery agent?
To uninstall the osquery agent, follow the below instructions for your operating system.
### MacOS
#### MacOS
Run the Orbit [cleanup script](https://github.com/fleetdm/fleet/blob/main/orbit/tools/cleanup/cleanup_macos.sh)
### Windows
#### Windows
Use the "Add or remove programs" dialog to remove Orbit.
### Ubuntu
#### Ubuntu
Run `sudo apt remove fleet-osquery -y`
### CentOS
#### CentOS
Run `sudo rpm -e fleet-osquery-X.Y.Z.x86_64`
## How does Fleet determines online and offline status?
### How does Fleet determines online and offline status?
### Online hosts
#### Online hosts
**Online** hosts will respond to a live query.
@ -301,16 +303,16 @@ A host is considered online if it has connected to Fleet in the last 70 (10+60)
`distributed_interval=30, config_tls_refresh=20`
A host is considered online if it has connected to Fleet in the last 80 (20+60) seconds.
### Offline hosts
#### Offline hosts
**Offline** hosts won't respond to a live query. These hosts may be shut down, asleep, or not connected to the internet.
A host could also be offline if there is a connection issue between the osquery agent running in the host and Fleet (see [What should I do if my computer is showing up as an offline host?](#what-should-i-do-if-my-computer-is-showing-up-as-an-offline-host)).
## Why aren't "additional queries" being applied to hosts enrolled in a team?
### Why aren't "additional queries" being applied to hosts enrolled in a team?
Changes were introduced in Fleet v4.20.0 that caused the `features.additional_queries` set in at the global level to no longer apply to hosts assigned to a team. If you would like those queries to be applied to hosts assigned to a team, you will need to be include these queries under `features.additional_queries` in each team's [configuration](https://fleetdm.com/docs/using-fleet/configuration-files#teams).
## Why am I seeing an error when using the `after` key in `api/v1/fleet/hosts`?
### Why am I seeing an error when using the `after` key in `api/v1/fleet/hosts`?
There is a [bug](https://github.com/fleetdm/fleet/issues/8443) in MySQL validation in some versions of Fleet when using the `created_at` and `updated_at` columns as `order_key` along with an `after` filter. Adding `h.` to the column in `order_key` will return your results.
@ -318,22 +320,22 @@ There is a [bug](https://github.com/fleetdm/fleet/issues/8443) in MySQL validati
{host}/api/v1/fleet/hosts?order_key=h.created_at&order_direction=desc&after=2022-10-22T20:22:03Z
```
## What can I do if Fleet is slow or unresponsive after enabling a feature?
### What can I do if Fleet is slow or unresponsive after enabling a feature?
Depending on your infrastructure capabilities, and the number of hosts enrolled into your Fleet instance, Fleet might be slow or unresponsive after globally enabling a feature like [software inventory](https://fleetdm.com/docs/deploying/configuration#software-inventory).
In those cases, we recommend a slow rollout by partially enabling the feature by teams using the `features` key of the [teams configuration](https://fleetdm.com/docs/using-fleet/configuration-files#teams).
## Why am I getting errors when generating a .msi package on my M1 Mac?
### Why am I getting errors when generating a .msi package on my M1 Mac?
There are many challenges to generating .msi packages on any OS but Windows. Errors will frequently resolve after multiple attempts and we've added retries by default in recent versions of `fleetctl package`. Package creation is much more reliable on Intel Macs, Linux and Windows.
## Where did Packs go?
### Where did Packs go?
Packs are a function of osquery that provide a portable format to import /export queries in and out of platforms like Fleet. These osquery packs still exist, but have been removed from the Fleet UI. Access via API is still available for backwards compatibility.
Within Fleet we've introduced the concept of teams in Fleet premium to target specific groups of hosts, but you can also still use scheduled queries in Fleet free (works like packs) to target all your hosts.
## What happens when I turn off MDM?
### What happens when I turn off MDM?
In the Fleet UI, you can turn off MDM for a host by selecting **Actions > Turn off MDM** on the **Host details** page.
@ -341,5 +343,230 @@ When you turn off MDM for a host, Fleet removes the enforcement of all macOS set
To enforce macOS settings and send macOS update reminders, the host has to turn MDM back on. To turn MDM on, share [these guided instructions](https://fleetdm.com/docs/using-fleet/mdm-migration-guide#instructions-for-end-users) with the end user. Turning MDM back on for a host requires end user action.
## What does "package root files: heat failed" mean?
### What does "package root files: heat failed" mean?
We've found this error when you try to build an MSI on Docker 4.17. The underlying issue has been fixed in Docker 4.18, so we recommend upgrading. More information [here](https://github.com/fleetdm/fleet/issues/10700)
## Deployment
- [How do I get support for working with Fleet?](#how-do-i-get-support-for-working-with-fleet)
- [Can multiple instances of the Fleet server be run behind a load-balancer?](#can-multiple-instances-of-the-fleet-server-be-run-behind-a-load-balancer)
- [Why aren't my osquery agents connecting to Fleet?](#why-arent-my-osquery-agents-connecting-to-fleet)
- [How do I fix "certificate verify failed" errors from osqueryd?](#how-do-i-fix-certificate-verify-failed-errors-from-osqueryd)
- [What do I need to do to change the Fleet server TLS certificate?](#what-do-i-need-to-do-to-change-the-fleet-server-tls-certificate)
- [How do I migrate hosts from one Fleet server to another (eg. testing to production)?](#how-do-i-migrate-hosts-from-one-fleet-server-to-another-eg-testing-to-production)
- [What do I do about "too many open files" errors?](#what-do-i-do-about-too-many-open-files-errors)
- [Can I skip versions when updating Fleet to the latest version?](#can-i-skip-versions-when-updating-to-the-latest-version)
- [I upgraded my database, but Fleet is still running slowly. What could be going on?](#i-upgraded-my-database-but-fleet-is-still-running-slowly-what-could-be-going-on)
- [Why am I receiving a database connection error when attempting to "prepare" the database?](#why-am-i-receiving-a-database-connection-error-when-attempting-to-prepare-the-database)
- [Is Fleet available as a SaaS product?](#is-fleet-available-as-a-saas-product)
- [What MySQL versions are supported?](#what-mysql-versions-are-supported)
- [What are the MySQL user access requirements?](#what-are-the-mysql-user-requirements)
- [Does Fleet support MySQL replication?](#does-fleet-support-mysql-replication)
- [What is duplicate enrollment and how do I fix it?](#what-is-duplicate-enrollment-and-how-do-i-fix-it)
- [What API endpoints should I expose to the public internet?](#what-api-endpoints-should-i-expose-to-the-public-internet)
- [What Redis versions are supported?](#what-redis-versions-are-supported)
- [Will my older version of Fleet work with Redis 6?](#will-my-older-version-of-fleet-work-with-redis-6)
### How do I get support for working with Fleet?
For bug reports, please use the [Github issue tracker](https://github.com/fleetdm/fleet/issues).
For questions and discussion, please join us in the #fleet channel of [osquery Slack](https://fleetdm.com/slack).
### Can multiple instances of the Fleet server be run behind a load-balancer?
Yes. Fleet scales horizontally out of the box as long as all of the Fleet servers are connected to the same MySQL and Redis instances.
Note that osquery logs will be distributed across the Fleet servers.
Read the [performance documentation](https://fleetdm.com/docs/using-fleet/monitoring-fleet#fleet-server-performance) for more.
### Why aren't my osquery agents connecting to Fleet?
This can be caused by a variety of problems. The best way to debug is usually to add `--verbose --tls_dump` to the arguments provided to `osqueryd` and look at the logs for the server communication.
#### Common problems
- `Connection refused`: The server is not running, or is not listening on the address specified. Is the server listening on an address that is available from the host running osquery? Do you have a load balancer that might be blocking connections? Try testing with `curl`.
- `No node key returned`: Typically this indicates that the osquery client sent an incorrect enroll secret that was rejected by the server. Check what osquery is sending by looking in the logs near this error.
- `certificate verify failed`: See [How do I fix "certificate verify failed" errors from osqueryd](#how-do-i-fix-certificate-verify-failed-errors-from-osqueryd).
- `bad record MAC`: When generating your certificate for your Fleet server, ensure you set the hostname to the FQDN or the IP of the server. This error is common when setting up Fleet servers and accepting defaults when generating certificates using `openssl`.
### How do I fix "certificate verify failed" errors from osqueryd?
Osquery requires that all communication between the agent and Fleet are over a secure TLS connection. For the safety of osquery deployments, there is no (convenient) way to circumvent this check.
- Try specifying the path to the full certificate chain used by the server using the `--tls_server_certs` flag in `osqueryd`. This is often unnecessary when using a certificate signed by an authority trusted by the system, but is mandatory when working with self-signed certificates. In all cases it can be a useful debugging step.
- Ensure that the CNAME or one of the Subject Alternate Names (SANs) on the certificate matches the address at which the server is being accessed. If osquery connects via `https://localhost:443`, but the certificate is for `https://fleet.example.com`, the verification will fail.
- Is Fleet behind a load-balancer? Ensure that if the load-balancer is terminating TLS, this is the certificate provided to osquery.
- Does the certificate verify with `curl`? Try `curl -v -X POST https://fleetserver:port/api/v1/osquery/enroll`.
### What do I need to do to change the Fleet server TLS certificate?
If the both the existing and new certificates verify with osquery's default root certificates (such as a certificate issued by a well-known Certificate Authority) and no certificate chain was deployed with osquery, there is no need to deploy a new certificate chain.
If osquery has been deployed with the full certificate chain (using `--tls_server_certs`), deploying a new certificate chain is necessary to allow for verification of the new certificate.
Deploying a certificate chain cannot be done centrally from Fleet.
### How do I use a proxy server with Fleet?
Seeing your proxy's requests fail with an error like `DEPTH_ZERO_SELF_SIGNED_CERT`)?
To get your proxy server's HTTP client to work with a local Fleet when using a self-signed cert, disable SSL / self-signed verification in the client.
The exact solution to this depends on the request client you are using. For example, when using Node.js ± Sails.js, you can work around this in the requests you're sending with `await sails.helpers.http.get()` by lifting your app with the `NODE_TLS_REJECT_UNAUTHORIZED` environment variable set to `0`:
```
NODE_TLS_REJECT_UNAUTHORIZED=0 sails console
```
### I'm only getting partial results from live queries
Redis has an internal buffer limit for pubsub that Fleet uses to communicate query results. If this buffer is filled, extra data is dropped. To fix this, we recommend disabling the buffer size limit. Most installs of Redis should have plenty of spare memory to not run into issues. More info about this limit can be found [here](https://redis.io/topics/clients#:~:text=Pub%2FSub%20clients%20have%20a,64%20megabyte%20per%2060%20second.) and [here](https://raw.githubusercontent.com/redis/redis/unstable/redis.conf) (search for client-output-buffer-limit).
We recommend a config like the following:
```
client-output-buffer-limit pubsub 0 0 60
```
### How do I migrate hosts from one Fleet server to another (eg. testing to production)?
Primarily, this would be done by changing the `--tls_hostname` and enroll secret to the values for the new server. In some circumstances (see [What do I need to do to change the Fleet server TLS certificate?](#what-do-i-need-to-do-to-change-the-fleet-server-tls-certificate)) it may be necessary to deploy a new certificate chain configured with `--tls_server_certs`.
These configurations cannot be managed centrally from Fleet.
### What do I do about "too many open files" errors?
This error usually indicates that the Fleet server has run out of file descriptors. Fix this by increasing the `ulimit` on the Fleet process. See the `LimitNOFILE` setting in the [example systemd unit file](https://fleetdm.com/docs/deploying/configuration#runing-with-systemd) for an example of how to do this with systemd.
Some deployments may benefit by setting the [`--server_keepalive`](https://fleetdm.com/docs/deploying/configuration#server-keepalive) flag to false.
This was also seen as a symptom of a different issue: if you're deploying on AWS on T type instances, there are different scenarios where the activity can increase and the instances will burst. If they run out of credits, then they'll stop processing leaving the file descriptors open.
### Can I skip versions when updating Fleet to the latest version?
Absolutely! If you're updating from the current major release of Fleet (v4), you can install the [latest version](https://github.com/fleetdm/fleet/releases/latest) without upgrading to each minor version along the way. Just make sure to back up your database in case anything odd does pop up!
If you're updating from an older version (we'll use Fleet v3 as an example), it's best to take some stops along the way:
1. Back up your database.
2. Upgrade to the last release of of v3 - [3.13.0](https://github.com/fleetdm/fleet/releases/tag/3.13.0).
3. Migrate the database.
4. Test
5. Check the release post for [v4.0.0 ](https://github.com/fleetdm/fleet/releases/tag/v4.0.0) to see the breaking changes and get Fleet ready for v4.
6. Upgrade to v4.0.0.
7. Migrate the database.
8. Test
9. Upgrade to the [current release](https://github.com/fleetdm/fleet/releases/latest).
10. One last migration.
11. Test again for good measure.
Taking it a bit slower on major releases gives you an opportunity to better track down where any issues may have been introduced.
### I upgraded my database, but Fleet is still running slowly. What could be going on?
This could be caused by a mismatched connection limit between the Fleet server and the MySQL server that prevents Fleet from fully utilizing the database. First [determine how many open connections your MySQL server supports](https://dev.mysql.com/doc/refman/8.0/en/too-many-connections.html). Now set the [`--mysql_max_open_conns`](https://fleetdm.com/docs/deploying/configuration#mysql-max-open-conns) and [`--mysql_max_idle_conns`](https://fleetdm.com/docs/deploying/configuration#mysql-max-idle-conns) flags appropriately.
### Why am I receiving a database connection error when attempting to "prepare" the database?
First, check if you have a version of MySQL installed that is at least 5.7. Then, make sure that you currently have a MySQL server running.
The next step is to make sure the credentials for the database match what is expected. Test your ability to connect to the database with `mysql -u<username> -h<hostname_or_ip> -P<port> -D<database_name> -p`.
If you're successful connecting to the database and still receive a database connection error, you may need to specify your database credentials when running `fleet prepare db`. It's encouraged to put your database credentials in environment variables or a config file.
```
fleet prepare db \
--mysql_address=<database_address> \
--mysql_database=<database_name> \
--mysql_username=<username> \
--mysql_password=<database_password>
```
### Is Fleet available as a SaaS product?
Yes! Please sign up for the [Fleet Cloud Beta](https://kqphpqst851.typeform.com/to/yoo5smT9).
### What MySQL versions are supported?
Fleet is tested with MySQL 5.7.21 and 8.0.28. Newer versions of MySQL 5.7 and MySQL 8 typically work well. AWS Aurora requires at least version 2.10.0. Please avoid using MariaDB or other MySQL variants that are not officially supported. Compatibility issues have been identified with MySQL variants and these may not be addressed in future Fleet releases.
### What are the MySQL user requirements?
The user `fleet prepare db` (via environment variable `FLEET_MYSQL_USERNAME` or command line flag `--mysql_username=<username>`) uses to interact with the database needs to be able to create, alter, and drop tables as well as the ability to create temporary tables.
### Does Fleet support MySQL replication?
You can deploy MySQL or Maria any way you want. We recommend using managed/hosted mysql so you don't have to think about it, but you can think about it more if you want. Read replicas are supported. You can read more about MySQL configuration [here](https://fleetdm.com/docs/deploying/configuration#mysql).
### What is duplicate enrollment and how do I fix it?
Duplicate host enrollment is when more than one host enrolls in Fleet using the same identifier
(hardware UUID or osquery generated UUID).
Typically, this is caused by cloning a VM Image with an already enrolled
osquery client, which results in duplicate osquery generated UUIDs. To resolve this issue, it is
advised to configure `--osquery_host_identifier=uuid` (which will use the hardware UUID), and then
delete the associated host in the Fleet UI.
In rare instances, VM Hypervisors have been seen to duplicate hardware UUIDs. When this happens,
using `--osquery_host_identifier=uuid` will not resolve the duplicate enrollment problem. Sometimes
the problem can be resolved by setting `--osquery_host_identifier=instance` (which will use the
osquery generated UUID), and then delete the associated host in the Fleet UI.
Find more information about [host identifiers here](https://fleetdm.com/docs/deploying/configuration#osquery-host-identifier).
### How do I resolve an "unknown column" error when upgrading Fleet?
The `unknown column` error typically occurs when the database migrations haven't been run during the upgrade process.
Check out the [documentation on running database migrations](https://fleetdm.com/docs/deploying/upgrading-fleet#running-database-migrations) to resolve this issue.
### What API endpoints should I expose to the public internet?
If you would like to manage hosts that can travel outside your VPN or intranet we recommend only exposing the osquery endpoints to the public internet:
- `/api/osquery`
- `/api/v1/osquery`
If you are using Fleet Desktop and want it to work on remote devices, the bare minimum API to expose is `/api/latest/fleet/device/*/desktop`. This minimal endpoint will only provide the number of failing policies.
For full Fleet Desktop functionality, `/api/fleet/orbit/*` and`/api/fleet/device/ping` must also be exposed.
If you would like to use the fleetctl CLI from outside of your network, the following endpoints will also need to be exposed for `fleetctl`:
- `/api/setup`
- `/api/v1/setup`
- `/api/latest/fleet/*`
- `/api/v1/fleet/*`
If you would like to use Fleet's MDM features, the following endpoints need to be exposed:
- `/mdm/apple/scep` to allow hosts to obtain a SCEP certificate.
- `/mdm/apple/mdm` to allow hosts to reach the server using the MDM protocol.
- `/api/mdm/apple/enroll` to allow DEP enrolled devices to get an enrollment profile.
- `/api/*/fleet/device/*/mdm/apple/manual_enrollment_profile` to allow manually enrolled devices to
download an enrollment profile.
> The `/mdm/apple/scep` and `/mdm/apple/mdm` endpoints are outside of the `/api` path because they
> are not RESTful, and are not intended for use by API clients or browsers.
### What is the minimum version of MySQL required by Fleet?
Fleet requires at least MySQL version 5.7.
### How do I migrate from Fleet Free to Fleet Premium?
To migrate from Fleet Free to Fleet Premium, once you get a Fleet license, set it as a parameter to `fleet serve` either as an environment variable using `FLEET_LICENSE_KEY` or in the Fleet's config file. See [here](https://fleetdm.com/docs/deploying/configuration#license) for more details. Note: You don't need to redeploy Fleet after the migration.
### What Redis versions are supported?
Fleet is tested with Redis 5.0.14 and 6.2.7. Any version Redis after version 5 will typically work well.
### Will my older version of Fleet work with Redis 6?
Most likely, yes! While we'd definitely recommend keeping Fleet up to date in order to take advantage of new features and bug patches, most legacy versions should work with Redis 6. Just keep in mind that we likely haven't tested your particular combination so that you may run into some unforeseen hiccups.
<meta name="description" value="Commonly asked questions and answers about deployment from the Fleet community.">

12
docs/Get started/README.md Normal file
View file

@ -0,0 +1,12 @@
# Get started
### [Why Fleet](./why-fleet.md)
### [Anatomy](./anatomy.md)
### [Tutorials and guides](./tutorials-and-guides)
### [FAQ](./FAQ.md)

44
docs/Get started/anatomy.md Normal file
View file

@ -0,0 +1,44 @@
# Anatomy
This page details the core concepts you need to know to use Fleet.
## Fleet UI
Fleet UI is the GUI (graphical user interface) used to control Fleet. [Docs](https://fleetdm.com/docs/using-fleet/fleet-ui).
## Fleetctl
Fleetctl (pronouced “fleet control”) is a CLI (command line interface) tool for managing Fleet from the command line. [Docs](https://fleetdm.com/docs/using-fleet/fleetctl-cli).
## Fleetd
Fleetd is a bundle of agents provided by Fleet to gather information about your devices. Fleetd includes [osquery](https://www.osquery.io/), Orbit, and Fleet Desktop. [Docs](https://fleetdm.com/docs/using-fleet/fleet-ui).
## Osquery
Osquery is an open-source tool for gathering information about the state of any device that the osquery agent has been installed on. [Learn more](https://www.osquery.io/).
## Orbit
Orbit is an osquery version and configuration manager, built by Fleet. [Docs](https://fleetdm.com/docs/using-fleet/orbit).
## Fleet Desktop
Fleet Desktop is a menu bar icon that gives end users visibility into the security and status of their machine. [Docs](https://fleetdm.com/docs/using-fleet/fleet-desktop).
## Host
A host is a computer, server, or other endpoint. Fleet gathers information from an osquery agent installed on each of your hosts. [Docs](https://fleetdm.com/docs/using-fleet/adding-hosts).
## Team
A team is a group of hosts. Use teams to segment your hosts into groups that reflect your organization's IT and security policies. [Docs](https://fleetdm.com/docs/using-fleet/teams).
## Query
A query in Fleet refers to an osquery query. Osquery uses basic SQL commands to request data from hosts. Use queries to manage, monitor, and identify threats on your devices. [Docs](https://fleetdm.com/docs/using-fleet/fleet-ui).
## Policy
A policy is a specific “yes” or “no” query. Use policies to manage security compliance in your organization.
## Host vitals
Host vitals are the hard-coded queries Fleet uses to populate device details.
## Software library
An inventory of each host’s installed software, including information about detected vulnerabilities (CVEs).
<meta name="pageOrderInSection" value="200">

6
docs/Get started/tutorials-and-guides.md Normal file
View file

@ -0,0 +1,6 @@
# Tutorials and guides
>Coming soon
<meta name="pageOrderInSection" value="300">

78
docs/Get started/why-fleet.md Normal file
View file

@ -0,0 +1,78 @@
# Why Fleet
## What's it for?
Organizations like Fastly and Gusto use Fleet for vulnerability reporting, detection engineering, device management (MDM), device health monitoring, posture-based access control, managing unused software licenses, and more.
#### Explore data
To see what kind of data you can use Fleet to gather, check out the [table reference documentation](https://fleetdm.com/tables).
#### Out-of-the-box policies
Fleet includes out-of-the box support for all [CIS benchmarks for macOS and Windows](https://fleetdm.com/pricing), as well as many [simpler queries](https://fleetdm.com/queries).
Take as much or as little as you need for your organization.
#### Supported platforms
Here are the platforms Fleet currently supports:
- Linux (all distros)
- macOS
- Windows
- Chromebooks
- Amazon Web Services (AWS)
- Google Cloud (GCP)
- Azure (Microsoft cloud)
- Data centers
- Containers (kube, etc)
- Linux-based IoT devices
## Lighter than air
Fleet is lightweight and modular. You can use it for security without using it for MDM, and vice versa. You can turn off features you are not using.
#### Openness
Fleet is dedicated to flexibility, accessibility, and clarity. We think [everyone can contribute](https://fleetdm.com/handbook/company#openness) and that tools should be as easy as possible for everyone to understand.
#### Good neighbors
Fleet has no ambition to replace all of your other tools. (Though it might replace some, if you want it to.) Ready-to-use, enterprise-friendly integrations exist for Snowflake, Splunk, GitHub Actions, Vanta, Elastic Jira, Zendesk, and more.
Fleet plays well with Munki, Chef, Puppet, and Ansible, as well as with security tools like Crowdstrike and SentinelOne. For example, you can use the free version of Fleet to quickly report on what hosts are _actually_ running your EDR agent.
While most folks prefer to use one or the other, Fleet can also coexist peacefully with Rapid7 and other agent-based vulnerability scanners. This can be useful during migrations.
#### Free as in free
The free version of Fleet will [always be free](https://fleetdm.com/pricing). Fleet is [independently backed](https://linkedin.com/company/fleetdm) and actively maintained with the help of many amazing [contributors](https://github.com/fleetdm/fleet/graphs/contributors).
#### Longevity
The [company behind Fleet](https://fleetdm.com/handbook/company) is founded (and majority-owned) by [true believers in open source](https://fleetdm.com/handbook/company/why-this-way#why-open-source). The company's business model is influenced by GitLab (NYSE: GTLB), with great investors, happy customers, and the capacity to become profitable at any time.
In keeping with Fleet's value of openness, [Fleet Device Management's company handbook](https://fleetdm.com/handbook/company) is public and open source. You can read about the [history of Fleet and osquery](https://fleetdm.com/handbook/company#history) and our commitment to improving the product.
<!-- > To upgrade from Fleet ≤3.2.0, just follow the upgrading steps for the earliest subsequent major release from this repository (it'll work out of the box until the release of Fleet 5.0). -->
## Is it any good?
Fleet is used in production by IT and security teams with thousands of laptops and servers. Many deployments support tens of thousands of hosts, and a few large organizations manage deployments as large as 400,000+ hosts.
## Chat
Please join us in [MacAdmins Slack](https://www.macadmins.org/) or in [osquery Slack](https://fleetdm.com/slack).
The Fleet community is full of [kind and helpful people](https://fleetdm.com/handbook/company#empathy). Whether or not you are a paying customer, if you need help, just ask.
## Contributing
The landscape of cybersecurity and IT is too complex. Let's open it up.
Contributions are welcome, whether you answer questions on [Slack](#chat) / [GitHub](https://github.com/fleetdm/fleet/issues) / [StackOverflow](https://stackoverflow.com/search?q=osquery) / [LinkedIn](https://linkedin.com/company/fleetdm) / [Twitter](https://twitter.com/fleetctl), improve the documentation or [website](https://github.com/fleetdm/fleet/tree/main/website), write a tutorial, give a talk at a conference or local meetup, give an [interview on a podcast](https://fleetdm.com/podcasts), troubleshoot reported issues, or [submit a patch](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Committing-Changes.md). The Fleet code of conduct is [on GitHub](https://github.com/fleetdm/fleet/blob/main/CODE_OF_CONDUCT.md).
<!-- - Great contributions are motivated by real-world use cases or learning.
- Some of the most valuable contributions might not touch any code at all.
- Small, iterative, simple (boring) changes are the easiest to merge. -->
## What's next?
Try out Fleet for yourself to see what it can do, grab time with one of the maintainers to discuss, or explore the rest of the docs and roll it out to your organization.
#### Production deployment
Fleet is simple enough to [spin up for yourself](https://fleetdm.com/docs/using-fleet/learn-how-to-use-fleet). Or you can have us [host it for you](https://fleetdm.com/pricing). Premium features are [available](https://fleetdm.com/pricing) either way.
<meta name="pageOrderInSection" value="100">

5
docs/REST API/README.md Normal file
View file

@ -0,0 +1,5 @@
# REST API
### [REST API](./rest-api.md)
Documentation for Fleet's REST API. Includes example requests and responses for each API endpoint.

79
docs/Using-Fleet/REST-API.md → docs/REST API/rest-api.md
View file

@ -424,8 +424,8 @@ This is the callback endpoint that the identity provider will use to send securi
### List activities
Returns a list of the activities that have been performed in Fleet as well as additional meta data
for pagination. For a comprehensive list of activity types and detailed information, please see [Audit activities](https://fleetdm.com/docs/using-fleet/audit-activities) page.
Returns a list of the activities that have been performed in Fleet as well as additional metadata.
for pagination. For a comprehensive list of activity types and detailed information, please see the [audit logs](https://fleetdm.com/docs/using-fleet/audit-activities) page.
`GET /api/v1/fleet/activities`
@ -3091,7 +3091,7 @@ created_at,updated_at,id,detail_updated_at,label_updated_at,policy_updated_at,la
Requires the [macadmins osquery extension](https://github.com/macadmins/osquery-extension) which comes bundled
in [Fleet's osquery installers](https://fleetdm.com/docs/using-fleet/adding-hosts#osquery-installer).
Requires Fleet's MDM properly [enabled and configured](./Mobile-device-management.md).
Requires Fleet's MDM properly [enabled and configured](https://fleetdm.com/docs/using-fleet/mdm-setup).
Retrieves the disk encryption key for a host.
@ -3124,7 +3124,7 @@ Retrieves the disk encryption key for a host.
### Get configuration profiles assigned to a host
Requires Fleet's MDM properly [enabled and configured](./Mobile-device-management.md).
Requires Fleet's MDM properly [enabled and configured](https://fleetdm.com/docs/using-fleet/mdm-setup).
Retrieves a list of the configuration profiles assigned to a host.
@ -3607,7 +3607,7 @@ Deletes the label specified by ID.
## Mobile device management (MDM)
These API endpoints are used to automate MDM features in Fleet. Read more about MDM features in Fleet [here](./Mobile-device-management.md).
These API endpoints are used to automate MDM features in Fleet. Read more about MDM features in Fleet [here](https://fleetdm.com/docs/using-fleet/mdm-setup).
- [Add custom macOS setting (configuration profile)](#add-custom-macos-setting-configuration-profile)
- [List custom macOS settings (configuration profiles)](#list-custom-macos-settings-configuration-profiles)
@ -3678,18 +3678,18 @@ Content-Type: application/octet-stream
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>PayloadContent</key>
<array/>
<key>PayloadDisplayName</key>
<string>Example profile</string>
<key>PayloadIdentifier</key>
<string>com.example.profile</string>
<key>PayloadType</key>
<string>Configuration</string>
<key>PayloadUUID</key>
<string>0BBF3E23-7F56-48FC-A2B6-5ACC598A4A69</string>
<key>PayloadVersion</key>
<integer>1</integer>
<key>PayloadContent</key>
<array/>
<key>PayloadDisplayName</key>
<string>Example profile</string>
<key>PayloadIdentifier</key>
<string>com.example.profile</string>
<key>PayloadType</key>
<string>Configuration</string>
<key>PayloadUUID</key>
<string>0BBF3E23-7F56-48FC-A2B6-5ACC598A4A69</string>
<key>PayloadVersion</key>
<integer>1</integer>
</dict>
</plist>
--------------------------f02md47480und42y--
@ -3778,9 +3778,9 @@ solely on the response status code returned by this endpoint.
##### Example response headers
```
Content-Length: 542
Content-Type: application/octet-stream
Content-Disposition: attachment;filename="2023-03-31 Example profile.mobileconfig"
Content-Length: 542
Content-Type: application/octet-stream
Content-Disposition: attachment;filename="2023-03-31 Example profile.mobileconfig"
```
###### Example response body
@ -3789,18 +3789,18 @@ solely on the response status code returned by this endpoint.
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>PayloadContent</key>
<array/>
<key>PayloadDisplayName</key>
<string>Example profile</string>
<key>PayloadIdentifier</key>
<string>com.example.profile</string>
<key>PayloadType</key>
<string>Configuration</string>
<key>PayloadUUID</key>
<string>0BBF3E23-7F56-48FC-A2B6-5ACC598A4A69</string>
<key>PayloadVersion</key>
<integer>1</integer>
<key>PayloadContent</key>
<array/>
<key>PayloadDisplayName</key>
<string>Example profile</string>
<key>PayloadIdentifier</key>
<string>com.example.profile</string>
<key>PayloadType</key>
<string>Configuration</string>
<key>PayloadUUID</key>
<string>0BBF3E23-7F56-48FC-A2B6-5ACC598A4A69</string>
<key>PayloadVersion</key>
<integer>1</integer>
</dict>
</plist>
```
@ -6173,7 +6173,7 @@ The returned lists are filtered based on the hosts the requesting user has acces
"id": 3,
"detail_updated_at": "2021-02-03T21:58:10Z",
"label_updated_at": "2021-02-03T21:58:10Z",
"policy_updated_at": "2023-06-26T18:33:15Z",
"policy_updated_at": "2023-06-26T18:33:15Z",
"last_enrolled_at": "2021-02-03T16:11:43Z",
"software_updated_at": "2020-11-05T05:09:44Z",
"seen_time": "2021-02-03T21:58:20Z",
@ -7018,8 +7018,8 @@ Creates a user account after an invited user provides registration information a
| name | string | body | **Required**. The name of the user. |
| password | string | body | The password chosen by the user (if not SSO user). |
| password_confirmation | string | body | Confirmation of the password chosen by the user. |
| global_role | string | body | The role assigned to the user. In Fleet 4.0.0, 3 user roles were introduced (`admin`, `maintainer`, and `observer`). In Fleet 4.30.0 and 4.31.0, the `observer_plus` and `gitops` roles were introduced respectively. If `global_role` is specified, `teams` cannot be specified. For more information, see [Permissions](./Permissions.md). |
| teams | array | body | _Available in Fleet Premium_ The teams and respective roles assigned to the user. Should contain an array of objects in which each object includes the team's `id` and the user's `role` on each team. In Fleet 4.0.0, 3 user roles were introduced (`admin`, `maintainer`, and `observer`). In Fleet 4.30.0 and 4.31.0, the `observer_plus` and `gitops` roles were introduced respectively. If `teams` is specified, `global_role` cannot be specified. For more information, see [Permissions](./Permissions.md). |
| global_role | string | body | The role assigned to the user. In Fleet 4.0.0, 3 user roles were introduced (`admin`, `maintainer`, and `observer`). In Fleet 4.30.0 and 4.31.0, the `observer_plus` and `gitops` roles were introduced respectively. If `global_role` is specified, `teams` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). |
| teams | array | body | _Available in Fleet Premium_ The teams and respective roles assigned to the user. Should contain an array of objects in which each object includes the team's `id` and the user's `role` on each team. In Fleet 4.0.0, 3 user roles were introduced (`admin`, `maintainer`, and `observer`). In Fleet 4.30.0 and 4.31.0, the `observer_plus` and `gitops` roles were introduced respectively. If `teams` is specified, `global_role` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). |
#### Example
@ -7135,9 +7135,9 @@ By default, the user will be forced to reset its password upon first login.
| password | string | body | The user's password (required for non-SSO users). |
| sso_enabled | boolean | body | Whether or not SSO is enabled for the user. |
| api_only | boolean | body | User is an "API-only" user (cannot use web UI) if true. |
| global_role | string | body | The role assigned to the user. In Fleet 4.0.0, 3 user roles were introduced (`admin`, `maintainer`, and `observer`). In Fleet 4.30.0 and 4.31.0, the `observer_plus` and `gitops` roles were introduced respectively. If `global_role` is specified, `teams` cannot be specified. For more information, see [Permissions](./Permissions.md). |
| global_role | string | body | The role assigned to the user. In Fleet 4.0.0, 3 user roles were introduced (`admin`, `maintainer`, and `observer`). In Fleet 4.30.0 and 4.31.0, the `observer_plus` and `gitops` roles were introduced respectively. If `global_role` is specified, `teams` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). |
| admin_forced_password_reset | boolean | body | Sets whether the user will be forced to reset its password upon first login (default=true) |
| teams | array | body | _Available in Fleet Premium_ The teams and respective roles assigned to the user. Should contain an array of objects in which each object includes the team's `id` and the user's `role` on each team. In Fleet 4.0.0, 3 user roles were introduced (`admin`, `maintainer`, and `observer`). In Fleet 4.30.0 and 4.31.0, the `observer_plus` and `gitops` roles were introduced respectively. If `teams` is specified, `global_role` cannot be specified. For more information, see [Permissions](./Permissions.md). |
| teams | array | body | _Available in Fleet Premium_ The teams and respective roles assigned to the user. Should contain an array of objects in which each object includes the team's `id` and the user's `role` on each team. In Fleet 4.0.0, 3 user roles were introduced (`admin`, `maintainer`, and `observer`). In Fleet 4.30.0 and 4.31.0, the `observer_plus` and `gitops` roles were introduced respectively. If `teams` is specified, `global_role` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). |
#### Example
@ -7612,5 +7612,6 @@ Response:
```
---
<meta name="pageOrderInSection" value="400">
<meta name="description" value="Documentation for Fleet's REST API. See example requests and responses for each API endpoint.">
<meta name="description" value="Documentation for Fleet's REST API. See example requests and responses for each API endpoint.">
<meta name="pageOrderInSection" value="30">

5
docs/Using-Fleet/Audit-Activities.md → docs/Using Fleet/Audit-logs.md
View file

@ -1,5 +1,5 @@
<!-- DO NOT EDIT. This document is automatically generated. -->
# Audit activities
# Audit logs
Fleet logs the following information for administrative actions (in JSON):
@ -839,6 +839,7 @@ Windows MDM features are not ready for production and are currently in developme
This activity does not contain any detail fields.
<meta name="title" value="Audit logs">
<meta name="pageOrderInSection" value="1400">
<meta name="description" value="Learn how Fleet logs administrative actions in JSON format.">
<meta name="navSection" value="Dig deeper">

1
docs/Using-Fleet/Automations.md → docs/Using Fleet/Automations.md
View file

@ -162,3 +162,4 @@ status webhook** in the Fleet UI.
<meta name="pageOrderInSection" value="1300">
<meta name="description" value="Configure Fleet automations to trigger webhooks or create tickets in Jira and Zendesk for vulnerability, policy, and host status events.">
<meta name="navSection" value="Vuln management">

1
docs/Using-Fleet/CIS-Benchmarks.md → docs/Using Fleet/CIS-Benchmarks.md
View file

@ -261,3 +261,4 @@ Requires this GPO in place: 'Computer Configuration\Policies\Administrative Temp
<meta name="pageOrderInSection" value="1700">
<meta name="title" value="CIS Benchmarks">
<meta name="description" value="Read about how Fleet's implementation of CIS Benchmarks offers consensus-based cybersecurity guidance, covering macOS 13.0 Ventura & Windows 10 Enterprise.">
<meta name="navSection" value="Security compliance">

2
docs/Using-Fleet/Fleet-UI.md → docs/Using Fleet/Fleet-UI.md
View file

@ -100,4 +100,4 @@ The agents may take several seconds to update because Fleet has to wait for the
<meta name="title" value="Fleet UI">
<meta name="pageOrderInSection" value="200">
<meta name="description" value="Learn how to create, run, and schedule queries, as well as update agent options in the Fleet user interface.">
<meta name="navSection" value="The basics">

3
docs/Using-Fleet/Fleet-desktop.md → docs/Using Fleet/Fleet-desktop.md
View file

@ -33,7 +33,7 @@ For organizations with complex security postures, they can direct end users to a
To turn on the custom transparency link in the Fleet GUI, click on your profile in the top right and select "Settings."
On the settings page, go to "Organization Settings" and select "Fleet Desktop." Use the "Custom transparency URL" text input to specify the custom URL.
For information on how to set the custom transparency link via a YAML configuration file, see the [configuration files](https://fleetdm.com/docs/deploying/configuration#fleet-desktop-settings) documentation.
For information on how to set the custom transparency link via a YAML configuration file, see the [configuration files](https://fleetdm.com/docs/configuration/fleet-server-configuration#fleet-desktop-settings) documentation.
## Securing Fleet Desktop
@ -63,3 +63,4 @@ This change is imperceptible to users, as clicking on the "My Device" tray item
<meta name="title" value="Fleet Desktop">
<meta name="pageOrderInSection" value="450">
<meta name="description" value="Learn about Fleet Desktop's features for self-remediation and transparency.">
<meta name="navSection" value="The basics">

1
docs/Using-Fleet/Learn-how-to-use-Fleet.md → docs/Using Fleet/Learn-how-to-use-Fleet.md
View file

@ -55,3 +55,4 @@ When the query has finished, you should see several columns in the "Results" tab
<meta name="pageOrderInSection" value="100">
<meta name="description" value="Get started with using Fleet by learning how to enroll your device into a Fleet instance and run queries to ask questions about it.">
<meta name="navSection" value="hidden">

3
docs/Using-Fleet/Log-destinations.md → docs/Using Fleet/Log-destinations.md
View file

@ -143,4 +143,5 @@ See the [osquery logging documentation](https://osquery.readthedocs.io/en/stable
If `--logger_plugin=tls` is used with osquery clients, the following configuration can be applied on the Fleet server for handling the incoming logs.
<meta name="pageOrderInSection" value="600">
<meta name="description" value="Learn about supported log destinations in Fleet, including Amazon Kinesis, AWS Lambda Snowflake, Splunk, and more.">
<meta name="description" value="Learn about supported log destinations in Fleet, including Amazon Kinesis, AWS Lambda Snowflake, Splunk, and more.">
<meta name="navSection" value="Security compliance">

1
docs/Using-Fleet/MDM-commands.md → docs/Using Fleet/MDM-commands.md
View file

@ -119,3 +119,4 @@ The command ID can be used to view command results as documented in [step 4 of t
<meta name="pageOrderInSection" value="1506">
<meta name="title" value="MDM commands">
<meta name="description" value="Learn how to run custom MDM commands on macOS hosts using Fleet.">
<meta name="navSection" value="Device management">

1
docs/Using-Fleet/MDM-custom-macOS-settings.md → docs/Using Fleet/MDM-custom-macOS-settings.md
View file

@ -102,3 +102,4 @@ Learn more about configuration options for hosts that aren't assigned to a team
<meta name="pageOrderInSection" value="1504">
<meta name="title" value="MDM custom macOS settings">
<meta name="description" value="Learn how to enforce custom settings on macOS hosts using Fleet's configuration profiles.">
<meta name="navSection" value="Device management">

1
docs/Using-Fleet/MDM-disk-encryption.md → docs/Using Fleet/MDM-disk-encryption.md
View file

@ -117,3 +117,4 @@ How to reset a macOS host's password using the disk encryption key:
<meta name="pageOrderInSection" value="1503">
<meta name="title" value="MDM disk encryption">
<meta name="description" value="Learn how to enforce disk encryption on macOS hosts and manage encryption keys with Fleet Premium.">
<meta name="navSection" value="Device management">

1
docs/Using-Fleet/MDM-macOS-setup.md → docs/Using Fleet/MDM-macOS-setup.md
View file

@ -231,3 +231,4 @@ Testing requires a test Mac that is present in your Apple Business Manager (ABM)
<meta name="pageOrderInSection" value="1505">
<meta name="title" value="MDM macOS setup">
<meta name="description" value="Customize your macOS setup experience with Fleet Premium by managing user authentication, Setup Assistant panes, and installing bootstrap packages.">
<meta name="navSection" value="Device management">

2
docs/Using-Fleet/MDM-macOS-updates.md → docs/Using Fleet/MDM-macOS-updates.md
View file

@ -161,4 +161,4 @@ Request payload:
<meta name="pageOrderInSection" value="1502">
<meta name="title" value="MDM macOS updates">
<meta name="description" value="Learn how to manage macOS updates and set up end user reminders with Fleet MDM.">
<meta name="navSection" value="Device management">

1
docs/Using-Fleet/MDM-migration-guide.md → docs/Using Fleet/MDM-migration-guide.md
View file

@ -118,3 +118,4 @@ Want to know what your organization can see? Read about [transparency](https://f
<meta name="pageOrderInSection" value="1501">
<meta name="title" value="MDM migration guide">
<meta name="description" value="Instructions for migrating hosts away from an old MDM solution to Fleet.">
<meta name="navSection" value="Device management">

1
docs/Using-Fleet/MDM-setup.md → docs/Using Fleet/MDM-setup.md
View file

@ -283,3 +283,4 @@ To renew the token:
<meta name="pageOrderInSection" value="1500">
<meta name="title" value="MDM setup">
<meta name="description" value="Learn how to configure Fleet to use Apple's Push Notification service and connect to Apple Business Manager.">
<meta name="navSection" value="Device management">

3
docs/Using-Fleet/Osquery-process.md → docs/Using Fleet/Osquery-process.md
View file

@ -26,4 +26,5 @@ If the managed extension is `Non-existent` (either because it was `Non-existent`
Lastly, we check the state of the watcher process itself. If it is deemed unhealthy because of resource contention, then the osquery process is shut down.
<meta name="pageOrderInSection" value="700">
<meta name="description" value="Learn about how osquery process manages child processes and managed extensions in Fleet.">
<meta name="description" value="Learn about how osquery process manages child processes and managed extensions in Fleet.">
<meta name="navSection" value="Osquery management">

14
docs/Using-Fleet/README.md → docs/Using Fleet/README.md
View file

@ -6,10 +6,7 @@ Provides documentation about running and scheduling queries from within the Flee
### [fleetctl CLI](./fleetctl-CLI.md)
Includes resources for setting up and configuring Fleet via the fleetctl CLI
### [REST API](./REST-API.md)
Provides resources for working with Fleet's API and includes example code for endpoints
### [Adding hosts](./Adding-hosts.md)
### [Enroll hosts](./enroll-hosts.md)
Provides resources for enrolling your hosts to Fleet
### [Log destinations](./Log-destinations.md)
@ -17,12 +14,3 @@ Includes documentation on the log destinations for sending with osquery logs
### [Osquery processes](./Osquery-process.md)
Includes documentation about osquery children processes and under which conditions they are terminated
### [Monitoring Fleet](./Monitoring-Fleet.md)
Provides documentation for load balancer health checks and working with Fleet server metrics and performance
### [Application Security](./Application-Security.md)
Includes information on how Fleet mitigates against the OWASP top 10 issues
### [FAQ](./FAQ.md)
Includes frequently asked questions and answers about using Fleet from the Fleet community

1
docs/Using-Fleet/Supported-browsers.md → docs/Using Fleet/Supported-browsers.md
View file

@ -25,3 +25,4 @@ We test each browser on Windows whenever possible, because our engineering team
<meta name="pageOrderInSection" value="1200">
<meta name="description" value="Learn what browser versions are compatible with Fleet.">
<meta name="navSection" value="The basics">

1
docs/Using-Fleet/Supported-host-operating-systems.md → docs/Using Fleet/Supported-host-operating-systems.md
View file

@ -28,3 +28,4 @@ If you aren't sure what version of `glibc` your distribution is using, [DistroWa
<meta name="pageOrderInSection" value="1200">
<meta name="description" value="This page contains information about operating systems that are compatible with the osquery agent.">
<meta name="navSection" value="The basics">

3
docs/Using-Fleet/Troubleshooting-live-queries.md → docs/Using Fleet/Troubleshooting-live-queries.md
View file

@ -138,4 +138,5 @@ If this works and the browser is not working then it might be a rendering issue
You should also try running the live query on different browsers.
<meta name="pageOrderInSection" value="1800">
<meta name="description" value="An overview of live queries in Fleet and steps for troubleshooting.">
<meta name="description" value="An overview of live queries in Fleet and steps for troubleshooting.">
<meta name="navSection" value="The basics">

6
docs/Using-Fleet/Detail-Queries-Summary.md → docs/Using Fleet/Understanding-host-vitals.md
View file

@ -1,5 +1,5 @@
<!-- DO NOT EDIT. This document is automatically generated. -->
# Detail Queries Summary
# Understanding host vitals
Following is a summary of the detail queries hardcoded in Fleet used to populate the device details:
@ -784,5 +784,7 @@ SELECT date, title FROM windows_update_history WHERE result_code = 'Succeeded'
```
<meta name="title" value="Understanding host vitals">
<meta name="navSection" value="Dig deeper">
<meta name="pageOrderInSection" value="1600">

1
docs/Using-Fleet/Usage-statistics.md → docs/Using Fleet/Usage-statistics.md
View file

@ -128,3 +128,4 @@ To disable usage statistics:
<meta name="pageOrderInSection" value="1100">
<meta name="description" value="Learn about Fleet's usage statistics and what information is collected.">
<meta name="navSection" value="Dig deeper">

1
docs/Using-Fleet/Vulnerability-Processing.md → docs/Using Fleet/Vulnerability-Processing.md
View file

@ -410,3 +410,4 @@ Once we have a good CPE, we can match it against the CVE database. We download t
<meta name="pageOrderInSection" value="1300">
<meta name="description" value="Find out how Fleet detects vulnerabilities and what software it covers.">
<meta name="navSection" value="Vuln management">

6
docs/Using-Fleet/ChromeOS.md → docs/Using Fleet/enroll-chromebooks.md
View file

@ -22,7 +22,9 @@ By default, the hostname for a Chromebook host will be blank. The hostname can b
- `usb_devices`: https://github.com/fleetdm/fleet/issues/12780
## Debugging ChromeOS
To learn how to debug the Fleetd Chrome extension, visit [here](https://fleetdm.com/docs/contributing/testing-and-local-development#fleetd-chrome-extension).
To learn how to debug the Fleetd Chrome extension, visit [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Testing-and-local-development.md#fleetd-chrome-extension).
<meta name="title" value="ChromeOS">
<meta name="title" value="Enroll Chromebooks">
<meta name="pageOrderInSection" value="2000">
<meta name="navSection" value="Dig deeper">

11
docs/Using-Fleet/Adding-hosts.md → docs/Using Fleet/enroll-hosts.md
View file

@ -1,11 +1,12 @@
# Adding hosts
- [Adding hosts](#adding-hosts)
# Enroll hosts
- [Enroll hosts](#enroll-hosts)
- [Introduction](#introduction)
- [Add hosts with Fleetd](#add-hosts-with-fleetd)
- [Signing installers](#signing-installers)
- [Including Fleet Desktop](#including-fleet-desktop)
- [Adding multiple hosts](#adding-multiple-hosts)
- [Enrolling multiple hosts](#adding-multiple-hosts)
- [Automatically adding hosts to a team](#automatically-adding-hosts-to-a-team)
- [Configuration options](#configuration-options)
- [Add hosts with plain osquery](#add-hosts-with-plain-osquery)
@ -32,7 +33,8 @@ You can also install plain osquery on your hosts and connect to Fleet using osqu
> For ChromeOS hosts, the [fleetd Chrome extension](#add-chromebooks-with-the-fleetd-chrome-extension) is installed instead of osquery.
## Add hosts with Fleetd
## Enroll hosts with Fleetd
To create a Fleet installer, you can use the `fleetctl package` command. To use the `fleetctl package` command, you must first install the `fleetctl` command-line tool. [Learn how to install `fleetctl`](https://fleetdm.com/fleetctl-preview).
@ -367,3 +369,4 @@ You can then look for `orbit` or `osquery` to narrow down results.
<meta name="pageOrderInSection" value="500">
<meta name="description" value="Learn how to generate installers and enroll hosts in your Fleet instance using fleetd or osquery.">
<meta name="navSection" value="The basics">

5
docs/Using-Fleet/fleetctl-CLI.md → docs/Using Fleet/fleetctl-CLI.md
View file

@ -60,7 +60,7 @@ This guide illustrates:
### Running Fleet
For the sake of this tutorial, we will be using the local development Docker Compose infrastructure to run Fleet locally. This is documented in some detail in the [developer documentation](https://fleetdm.com/docs/contributing/building-fleet#development-infrastructure), but the following are the minimal set of commands that you can run from the root of the repository (assuming that you have a working Go/JavaScript toolchain installed along with Docker Compose):
For the sake of this tutorial, we will be using the local development Docker Compose infrastructure to run Fleet locally. This is documented in some detail in the [developer documentation](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Building-Fleet.md#development-infrastructure), but the following are the minimal set of commands that you can run from the root of the repository (assuming that you have a working Go/JavaScript toolchain installed along with Docker Compose):
```
docker-compose up -d
@ -294,7 +294,7 @@ With fleetctl, you can run MDM commands to take some action on your macOS hosts,
Fleet supports osquery's file carving functionality as of Fleet 3.3.0. This allows the Fleet server to request files (and sets of files) from osquery agents, returning the full contents to Fleet.
File carving data can be either stored in Fleet's database or to an external S3 bucket. For information on how to configure the latter, consult the [configuration docs](https://fleetdm.com/docs/deploying/configuration#s3-file-carving-backend).
File carving data can be either stored in Fleet's database or to an external S3 bucket. For information on how to configure the latter, consult the [configuration docs](https://fleetdm.com/docs/deploying/configuration#s-3-file-carving-backend).
### Configuration
@ -433,3 +433,4 @@ This will generate a `tar.gz` file with:
<meta name="pageOrderInSection" value="300">
<meta name="description" value="Read about fleetctl, a CLI tool for managing Fleet and osquery configurations, running queries, generating installers, and more.">
<meta name="navSection" value="The basics">

4
docs/Using-Fleet/fleetd.md → docs/Using Fleet/fleetd.md
View file

@ -381,6 +381,7 @@ Run the [cleanup script](https://github.com/fleetdm/fleet/tree/main/orbit/tools/
[Create an issue](https://github.com/fleetdm/fleet/issues) to report a bug or request a feature.
## Try Fleetd
### With [`fleetctl preview` already running](https://github.com/fleetdm/fleet#try-fleet):
@ -397,4 +398,5 @@ An installer configured to point at your Fleet instance has now been generated.
Now run that installer (double click, on a Mac) to enroll your own computer as a host in Fleet. Refresh after several seconds (≈30s), and you should now see your local computer as a new host in Fleet.
<meta name="pageOrderInSection" value="301">
<meta name="pageOrderInSection" value="600">
<meta name="navSection" value="The basics">

3
docs/Using-Fleet/Permissions.md → docs/Using Fleet/manage-access.md
View file

@ -1,4 +1,4 @@
# Permissions
# Manage access
Users have different abilities depending on the access level they have.
@ -156,3 +156,4 @@ Users that are members of multiple teams can be assigned different roles for eac
<meta name="pageOrderInSection" value="900">
<meta name="description" value="Learn about the different roles and permissions in Fleet.">
<meta name="navSection" value="The basics">

5
docs/Using-Fleet/Teams.md → docs/Using Fleet/segment-hosts.md
View file

@ -1,4 +1,4 @@
# Teams
# Segment hosts
`Applies only to Fleet Premium`
@ -131,4 +131,5 @@ To delete a team:
3. On the right side, select "Delete team" and confirm the action.
<meta name="pageOrderInSection" value="1000">
<meta name="description" value="Learn how to group hosts in Fleet to apply specific queries, policies, and agent options using teams.">
<meta name="description" value="Learn how to group hosts in Fleet to apply specific queries, policies, and agent options using teams.">
<meta name="navSection" value="The basics">

1
docs/Deploying/fleetctl-agent-updates.md → docs/Using Fleet/update-agents.md
View file

@ -162,3 +162,4 @@ After the key(s) have been rotated, publish the repository in the same fashion a
<meta name="pageOrderInSection" value="400">
<meta name="description" value="Information on how to manage and secure Fleet agent updates.">
<meta name="navSection" value="Dig deeper">

14
docs/Using-Fleet/mobile-device-management.md
View file

@ -1,14 +0,0 @@
# Mobile device management (MDM)
MDM is a collection of tools that enable IT admins in companies to remotely manage employee's workstations by requiring certain settings, installing software, and executing scripts. MDM functionality is provided by the OS vendor (e.g. Apple or Microsoft).
To learn more about Fleet's MDM features, see:
* [Setup](./MDM-setup.md)
* [Migration guide](./MDM-migration-guide.md)
* [macOS updates](./MDM-macOS-updates.md)
* [Disk encryption](./MDM-disk-encryption.md)
* [Custom macOS settings](./MDM-custom-macOS-settings.md)
* [macOS setup](./MDM-macOS-setup.md)
* [Commands](./MDM-commands.md)
<meta name="pageOrderInSection" value="1499">
<meta name="title" value="Mobile device management in Fleet">

3
docs/Using-Fleet/Application-security.md → handbook/business-operations/Application-security.md
View file

@ -66,5 +66,6 @@ libraries and other vulnerabilities is available in our
[Dependabot](https://github.com/dependabot) to automatically open PRs to update vulnerable dependencies.
<meta name="pageOrderInSection" value="800">
<meta name="description" value="Explore Fleet's application security practices, including secure coding, SQL injection prevention, authentication, data encryption, access controls, and more.">
<meta name="maintainedBy" value="hollidayn">

2
handbook/business-operations/README.md
View file

@ -718,7 +718,7 @@ Here are a few different entry points for a tour of Fleet's security policies an
6. More details about internal security processes at Fleet are located on [the Security page](./security.md).
### Vendor questionnaires
In responding to security questionnaires, Fleet endeavors to provide full transparency via our [Security policies](https://fleetdm.com/handbook/security/security-policies#security-policies) and [Application security](https://fleetdm.com/docs/using-fleet/application-security) documentation. In addition to this documentation, please refer to [the Vendor questionnaires page](./vendor-questionnaires.md)
In responding to security questionnaires, Fleet endeavors to provide full transparency via our [security policies](https://fleetdm.com/handbook/security/security-policies#security-policies) and [application security](https://fleetdm.com/handbook/business-operations/application-security) documentation. In addition to this documentation, please refer to [the vendor questionnaires page](./vendor-questionnaires.md)
## Finance

2
docs/Using-Fleet/Security-audits.md → handbook/business-operations/security-audits.md
View file

@ -225,4 +225,4 @@ improvements to make it more robust and resilient to compromise.
<meta name="pageOrderInSection" value="790">
<meta name="description" value="Explanations of the latest external security audits performed on Fleet software.">
<meta name="maintainedBy" value="hollidayn">

9
handbook/business-operations/security.md
View file

@ -894,5 +894,14 @@ We make sure the fixes to vulnerable dependencies are also performed according t
We publish a trust report that includes automated checking of controls, answers to frequently asked
questions and more on [https://fleetdm.com/trust](https://fleetdm.com/trust)
## Securtiy audits
Read about Fleet's security audits on [this page](https://fleetdm.com/handbook/business-operations/security-audits).
## Application security
Read about Fleet's application security practices on the [application security page](https://fleetdm.com/handbook/business-operations/application-security).
<meta name="maintainedBy" value="hollidayn">
<meta name="title" value="Security">

2
handbook/company/why-this-way.md
View file

@ -140,7 +140,7 @@ Here are a few of the drawbacks that we have experienced when generating docs vi
- Markdown is more accessible. Anyone can edit Fleet's docs directly from our website without needing coding experience.
- A single Markdown file reduces the amount of surface area to manage that comes from spreading code comments across multiple files throughout the codebase. (see ["Why do we use one repo?"](#why-do-we-use-one-repo)).
- Autogenerated docs can become just as outdated as handmade docs, except since they are siloed, they require more skills to edit.
- When docs live at separate repo paths from source code, we are able to automate approval processes that allow contributors to make small improvements and notes, directly from the website. This [leads to more contributions](https://github.com/balderdashy/sails-docs/network/members), since it lowers the barrier of entry for [becoming a contributor](https://fleetdm.com/docs/contributing/committing-changes).
- When docs live at separate repo paths from source code, we are able to automate approval processes that allow contributors to make small improvements and notes, directly from the website. This [leads to more contributions](https://github.com/balderdashy/sails-docs/network/members), since it lowers the barrier of entry for [becoming a contributor](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Committing-Changes.md#committing-changes).
- Autogenerated docs are typically hosted on a subdomain. This means we have less control over a user's journey through our website and lose the SEO benefits of self-hosted documentation.
- Autogenerating docs from code comments is not always the best way to make sure reference docs accurately reflect the API.
- As the Fleet REST API, documentation, and tools mature, a more declarative format such as OpenAPI might become the source of truth, but only after investing in a format and processes to make it continually accurate as well as visible, accessible, and modifiable for all contributors.

3
docs/Deploying/Debugging.md → handbook/engineering/Debugging.md
View file

@ -172,5 +172,6 @@ have a request size limit? If the LB is not terminating TLS, is that appropriate
Make sure as well that your cloud provider is not having issues of their own. For instances, check
[AWS](https://health.aws.amazon.com/health/status) for status.
<meta name="pageOrderInSection" value="600">
<meta name="maintainedBy" value="lukeheath">
<meta name="description" value="A guide to triaging and diagnosing issues in Fleet.">

2
docs/Deploying/Load-testing.md → handbook/engineering/Load-testing.md
View file

@ -73,5 +73,5 @@ They are sized to be the smallest that Fargate allows, so it is still cost effec
The [osquery-perf](https://github.com/fleetdm/fleet/tree/main/cmd/osquery-perf) tool doesn't simulate all data that's included when a real device communicates to a Fleet instance. For example, system users and software inventory data are not yet simulated by osquery-perf.
<meta name="pageOrderInSection" value="500">
<meta name="maintainedBy" value="lukeheath">
<meta name="description" value="This page outlines the most recent results of a semi-annual load test of the Fleet server.">

28
handbook/engineering/README.md
View file

@ -154,6 +154,10 @@ Engineering-initiated stories follow the [user story drafting process](https://f
> We aspire to dedicate 20% of each sprint to technical changes, but may allocate less based on customer needs and business priorities.
## Documentation for contributors
Fleet's documentation for contributors can be found in the [Fleet GitHub repo](https://github.com/fleetdm/fleet/tree/main/docs/Contributing).
## Release process
- [Release freeze period](#release-freeze-period)
@ -203,7 +207,7 @@ Next, create a new GitHub issue using the [Release QA template](https://github.c
### Release day
Documentation on completing the release process can be found [here](https://fleetdm.com/docs/contributing/releasing-fleet).
Documentation on completing the release process can be found [here](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Releasing-Fleet.md).
## Deploying to dogfood
@ -366,6 +370,10 @@ At Fleet, we consider an outage to be a situation where new features or previous
Fleet, as a Go server, scales horizontally very well. It’s not very CPU or memory intensive. However, there are some specific gotchas to be aware of when implementing new features. Visit our [scaling Fleet page](https://fleetdm.com/handbook/engineering/scaling-fleet) for tips on scaling Fleet as efficiently and effectively as possible.
## Load testing
The [load testing page](https://fleetdm.com/handbook/engineering/load-testing) outlines the process we use to load test Fleet, and contains the results of our semi-annual load test.
## Version support
To provide the most accurate and efficient support, Fleet will only target fixes based on the latest released version. In the current version fixes, Fleet will not backport to older releases.
@ -466,6 +474,10 @@ For each bug found, please use the [bug report template](https://github.com/flee
For unreleased bugs in an active sprint, a new bug is created with the `~unreleased bug` label. The `:release` label and associated product group label is added, and the engineer responsible for the feature is assigned. If QA is unsure who the bug should be assigned to, it is assigned to the EM. Fixing the bug becomes part of the story.
### Debugging
You can read our guide to diagnosing issues in Fleet on the [debugging page](https://fleetdm.com/handbook/engineering/debugging).
## Bug process
- [Bug states](#bug-states)
@ -513,7 +525,7 @@ Fleeties do not have to wait for QA to reproduce the bug. If you're confident it
If a bug requires input from product, the `:product` label is added, it is assigned to the product group's PM, and the bug is moved to the "Product drafting" column of the [bugs board](https://app.zenhub.com/workspaces/-bugs-647f6d382e171b003416f51a/board). It will stay in this state until product closes the bug, or removes the `:product` label and assigns to an EM.
#### In engineering
A bug is in engineering after it has been reproduced and assigned to an EM. If a bug meets the criteria for a [critical bug](https://fleetdm.com/handbook/engineering#critical-bugs), the `:release` and `~critical bug` labels are added, and it is moved to the "Current release' column of the bugs board. If the bug is a `~critical bug`, the EM follows the [critical bug notification process](https://fleetdm.com/docs/contributing/releasing-fleet#critical-bug-notification-process).
A bug is in engineering after it has been reproduced and assigned to an EM. If a bug meets the criteria for a [critical bug](https://fleetdm.com/handbook/engineering#critical-bugs), the `:release` and `~critical bug` labels are added, and it is moved to the "Current release' column of the bugs board. If the bug is a `~critical bug`, the EM follows the [critical bug notification process](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Releasing-Fleet.md#critical-bug-notification-process).
If the bug does not meet the criteria of a critical bug, the EM will determine if there is capacity in the current sprint for this bug. If so, the `:release` label is added, and it is moved to the "Current release' column on the bugs board. If there is no available capacity in the current sprint, the EM will move the bug to the "Sprint backlog" column where it will be prioritized for the next sprint.
@ -544,9 +556,9 @@ This filter returns all "bug" issues closed after the specified date. Simply rep
When a release is in testing, QA should use the Slack channel #help-qa to keep everyone aware of issues found. All bugs found should be reported in the channel after creating the bug first.
When a critical bug is found, the Fleetie who labels the bug as critical is responsible for following the [critical bug notification process](https://fleetdm.com/docs/contributing/releasing-fleet#critical-bug-notification-process) below.
When a critical bug is found, the Fleetie who labels the bug as critical is responsible for following the [critical bug notification process](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Releasing-Fleet.md#critical-bug-notification-process) below.
All unreleased bugs are addressed before publishing a release. Released bugs that are not critical may be addressed during the next release per the standard [bug process](https://fleetdm.com/docs/contributing/releasing-fleet#bug-process).
All unreleased bugs are addressed before publishing a release. Released bugs that are not critical may be addressed during the next release per the standard [bug process](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Releasing-Fleet.md#bug-process).
### Release blockers
@ -574,7 +586,7 @@ When outside of working hours for the product team or if no one from product res
Once the critical bug is confirmed, customer experience needs to ping both customers and the community to warn them. If CX is not available, the oncall engineer is responsible for doing this.
If a quick fix workaround exists, that should be communicated as well for those who are already upgraded.
When a critical bug is identified, we will then follow the patch release process in [our documentation](https://fleetdm.com/docs/contributing/releasing-fleet#patch-releases).
When a critical bug is identified, we will then follow the patch release process in [our documentation](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Releasing-Fleet.md#patch-releases).
## Measurement
@ -686,9 +698,9 @@ The following rituals are engaged in by the directly responsible individual (DRI
| Vulnerability alerts (fleetdm.com) | Weekly | Review and remediate or dismiss [vulnerability alerts](https://github.com/fleetdm/fleet/security) for the fleetdm.com codebase on GitHub. | Eric Shaw |
| Vulnerability alerts (frontend) | Weekly | Review and remediate or dismiss [vulnerability alerts](https://github.com/fleetdm/fleet/security) for the Fleet frontend codebase (and related JS) on GitHub. | Zach Wasserman |
| Vulnerability alerts (backend) | Weekly | Review and remediate or dismiss [vulnerability alerts](https://github.com/fleetdm/fleet/security) for the Fleet backend codebase (and all Go code) on GitHub. | Zach Wasserman |
| Freeze ritual | Every three weeks | Go through [the process of freezing](https://fleetdm.com/docs/contributing/releasing-fleet#patch-releases) the `main` branch to prepare for the next release. | Luke Heath |
| Release ritual | Every three weeks | Go through [the process of releasing](https://fleetdm.com/docs/contributing/releasing-fleet) the next iteration of Fleet. | Luke Heath |
| Create patch release branch | Every patch release | Go through the process of [creating a patch release](https://fleetdm.com/docs/contributing/releasing-fleet#patch-releases) branch, cherry picking commits, and pushing the branch to github.com/fleetdm/fleet. | Luke Heath |
| Freeze ritual | Every three weeks | Go through [the process of freezing](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Releasing-Fleet.md#patch-releases) the `main` branch to prepare for the next release. | Luke Heath |
| Release ritual | Every three weeks | Go through [the process of releasing](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Releasing-Fleet.md) the next iteration of Fleet. | Luke Heath |
| Create patch release branch | Every patch release | Go through the process of [creating a patch release](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Releasing-Fleet.md#patch-releases) branch, cherry picking commits, and pushing the branch to github.com/fleetdm/fleet. | Luke Heath |
| Bug review | Weekly | Review bugs that are in QA's inbox. | Reed Haynes |
| QA report | Every three weeks | Every release cycle, on the Monday of release week, the DRI for the release ritual is updated on status of testing. | Reed Haynes |
| Release QA | Every three weeks | Every release cycle, by end of day Friday of release week, all issues move to "Ready for release" on the #g-mdm and #g-cx sprint boards. | Reed Haynes |

2
handbook/marketing/README.md
View file

@ -196,7 +196,7 @@ You will need to install the following tools to use it:
There are several locations in Fleet's public and internal documentation that can be helpful when answering questions raised by the community:
1. Find the frequently asked question (FAQ) documents in each section in the `/docs` folder. These documents are the [Using Fleet FAQ](./../../docs/Using-Fleet/FAQ.md), [Deploying FAQ](./../../docs/Deploying/FAQ.md), and [Contributing FAQ](./../../docs/Contributing/FAQ.md).
1. Find the frequently asked question (FAQ) documents in each section in the `/docs` folder. These documents are the [Get started FAQ](https://fleetdm.com/docs/get-started/FAQ), and [Contributing FAQ (on GitHub)](https://github.com/fleetdm/fleet/blob/main/docs/Contributing/FAQ.md).
2. Use the [internal FAQ](https://docs.google.com/document/d/1I6pJ3vz0EE-qE13VmpE2G3gd5zA1m3bb_u8Q2G3Gmp0/edit#heading=h.ltavvjy511qv) document.

2
server/fleet/activities.go
View file

@ -5,7 +5,7 @@ import (
"encoding/json"
)
//go:generate go run gen_activity_doc.go ../../docs/Using-Fleet/Audit-Activities.md
// go:generate go run gen_activity_doc.go "../../docs/Using Fleet/Audit-logs.md"
// ActivityDetailsList is used to generate documentation.
var ActivityDetailsList = []ActivityDetails{

4
server/fleet/gen_activity_doc.go
View file

@ -15,7 +15,7 @@ func main() {
var b strings.Builder
b.WriteString(`<!-- DO NOT EDIT. This document is automatically generated. -->
# Audit activities
# Audit logs
Fleet logs the following information for administrative actions (in JSON):
@ -64,9 +64,9 @@ Example:
}
}
b.WriteString(`
<meta name="pageOrderInSection" value="1400">
<meta name="description" value="Learn how Fleet logs administrative actions in JSON format.">
<meta name="navSection" value="Dig deeper">
`)
if err := os.WriteFile(os.Args[1], []byte(b.String()), 0600); err != nil {

8
server/service/osquery_utils/gen_queries_doc.go
View file

@ -34,7 +34,7 @@ func main() {
var b strings.Builder
b.WriteString(`<!-- DO NOT EDIT. This document is automatically generated. -->
# Detail Queries Summary
# Understanding host vitals
Following is a summary of the detail queries hardcoded in Fleet used to populate the device details:
@ -63,13 +63,13 @@ Following is a summary of the detail queries hardcoded in Fleet used to populate
}
fmt.Fprintf(&b, "- Platforms: %s\n\n", platforms)
if q.detailQuery.Discovery != "" {
fmt.Fprintf(&b, "- Discovery query:\n\n```sql\n%s\n```\n\n", strings.TrimSpace(q.detailQuery.Discovery))
fmt.Fprintf(&b, "- Discovery query:\n```sql\n%s\n```\n\n", strings.TrimSpace(q.detailQuery.Discovery))
}
fmt.Fprintf(&b, "- Query:\n\n```sql\n%s\n```\n\n", strings.TrimSpace(q.detailQuery.Query))
fmt.Fprintf(&b, "- Query:\n```sql\n%s\n```\n\n", strings.TrimSpace(q.detailQuery.Query))
}
b.WriteString(`
<meta name="navSection" value="Dig deeper">
<meta name="pageOrderInSection" value="1600">`)
if err := os.WriteFile(os.Args[1], []byte(b.String()), 0600); err != nil {

2
server/service/osquery_utils/queries.go
View file

@ -1541,7 +1541,7 @@ func directIngestMacOSProfiles(
return ds.UpdateVerificationHostMacOSProfiles(ctx, host, mapping)
}
//go:generate go run gen_queries_doc.go ../../../docs/Using-Fleet/Detail-Queries-Summary.md
// go:generate go run gen_queries_doc.go "../../../docs/Using Fleet/Understanding-host-vitals.md"
func GetDetailQueries(
ctx context.Context,

31
website/assets/js/pages/docs/basic-documentation.page.js vendored
View file

@ -17,6 +17,7 @@ parasails.registerPage('basic-documentation', {
subtopics: [],
relatedTopics: [],
scrollDistance: 0,
navSectionsByDocsSectionSlug: {},
},
@ -38,29 +39,31 @@ parasails.registerPage('basic-documentation', {
this.pages = _.sortBy(this.markdownPages, 'htmlId');
this.pages = this.pages.filter((page)=>{
return _.startsWith(page.url, '/docs');
});
this.pagesBySectionSlug = (() => {
const DOCS_SLUGS = ['using-fleet', 'deploying', 'contributing'];
let sectionSlugs = _.uniq(_.pluck(this.pages, 'url').map((url) => url.split(/\//).slice(-2)[0]));
const DOCS_SLUGS = ['get-started', 'deploy', 'using-fleet', 'configuration', 'rest-api'];
let sectionSlugs = _.uniq(this.pages.map((page) => page.url.split(/\//).slice(-2)[0]));
let pagesBySectionSlug = {};
for (let sectionSlug of sectionSlugs) {
pagesBySectionSlug[sectionSlug] = this.pages.filter((page) => {
return sectionSlug === page.url.split(/\//).slice(-2)[0];
});
// Sorting pages by pageOrderInSectionPath value, README files do not have a pageOrderInSectionPath, and FAQ pages are added to the end of the sorted array below.
pagesBySectionSlug[sectionSlug] = _.sortBy(pagesBySectionSlug[sectionSlug], (page) => {
if (!page.sectionRelativeRepoPath.match(/README\.md$/i) && !page.sectionRelativeRepoPath.match(/FAQ\.md$/i)) {
return page.pageOrderInSectionPath;
}
});
this.navSectionsByDocsSectionSlug[sectionSlug] = _.groupBy(pagesBySectionSlug[sectionSlug], 'docNavCategory');
}
// We need to re-sort the top-level sections because their htmlIds do not reflect the correct order
pagesBySectionSlug['docs'] = DOCS_SLUGS.map((slug) => {
return pagesBySectionSlug['docs'].find((page) => slug === _.kebabCase(page.title));
});
// We need to move any FAQs to the end of its array
for (let slug of DOCS_SLUGS) {
let pages = pagesBySectionSlug[slug];
@ -234,6 +237,24 @@ parasails.registerPage('basic-documentation', {
return this.pagesBySectionSlug[slug];
},
findAndSortNavSectionsByUrl: function (url='') {
let NAV_SECTION_ORDER_BY_DOCS_SLUG = {
'using-fleet':['The basics', 'Device management', 'Vuln management', 'Security compliance', 'Osquery management', 'Dig deeper'],
'deploy':['Uncategorized','TBD','Deployment guides'],
};
let slug = _.last(url.split(/\//));
//
if(NAV_SECTION_ORDER_BY_DOCS_SLUG[slug]) {
let orderForThisSection = NAV_SECTION_ORDER_BY_DOCS_SLUG[slug];
let sortedSection = {};
orderForThisSection.map((section)=>{
sortedSection[section] = this.navSectionsByDocsSectionSlug[slug][section];
});
this.navSectionsByDocsSectionSlug[slug] = sortedSection;
}
return this.navSectionsByDocsSectionSlug[slug];
},
getActiveSubtopicClass: function (currentLocation, url) {
return _.last(currentLocation.split(/#/)) === _.last(url.split(/#/)) ? 'active' : '';
},

30
website/assets/styles/pages/docs/basic-documentation.less vendored
View file

@ -330,16 +330,44 @@
.topic {
padding-left: 0px;
color: @core-fleet-black-75;
&.active {
color: @core-vibrant-blue;
}
}
}
[purpose='left-sidebar']::-webkit-scrollbar, [purpose='right-sidebar']::-webkit-scrollbar, [purpose='subtopics']::-webkit-scrollbar {
display: none;
}
[purpose='expanded-nav'] {
li {
font-size: 14px;
font-style: normal;
font-weight: 400;
line-height: 21px;
color: @core-fleet-black-75;
}
[purpose='nav-section']:not(:last-of-type) {
border-bottom: 1px solid #E2E4EA;
margin-bottom: 16px;
}
[purpose='nav-section'] {
padding-bottom: 12px;
[purpose='nav-section-title'] {
font-size: 13px;
font-weight: 500;
line-height: 18px;
text-transform: uppercase;
margin-bottom: 12px;
padding-top: 8px;
color: @core-fleet-black;
}
}
}
[purpose='right-sidebar'] {
scrollbar-width: none;
@ -364,7 +392,7 @@
box-shadow: 1px 2px 2px rgba(197, 199, 209, 0.2);
border-radius: 6px;
padding: 20px;
margin-top: 30px;
margin-top: 8px;
color: @core-fleet-black;
width: 100%;
a {

39
website/config/routes.js vendored
View file

@ -384,7 +384,46 @@ module.exports.routes = {
'GET /platform': '/',
'GET /handbook/company/senior-software-backend-engineer': 'https://www.linkedin.com/posts/mikermcneil_in-addition-to-our-product-quality-specialist-activity-7067711903166279680-6CMH',
'GET /handbook/business-operations/ceo-handbook': '/handbook/company/ceo-handbook',
'GET /docs': '/docs/get-started/why-fleet',
'GET /docs/get-started': '/docs/get-started/why-fleet',
'GET /docs/rest-api': '/docs/rest-api/rest-api',
'GET /docs/using-fleet': '/docs/using-fleet/fleet-ui',
'GET /docs/configuration': '/docs/configuration/fleet-server-configuration',
'GET /docs/contributing': 'https://github.com/fleetdm/fleet/tree/main/docs/Contributing',
'GET /docs/deploy': '/docs/deploy/introduction',
'GET /docs/using-fleet/faq': '/docs/get-started/faq',
'GET /docs/using-fleet/monitoring-fleet': '/docs/deploy/monitoring-fleet',
'GET /docs/using-fleet/adding-hosts': '/docs/using-fleet/enroll-hosts',
'GET /docs/using-fleet/teams': '/docs/using-fleet/segment-hosts',
'GET /docs/using-fleet/permissions': '/docs/using-fleet/manage-access',
'GET /docs/using-fleet/chromeos': '/docs/using-fleet/enroll-chromebooks',
'GET /docs/using-fleet/rest-api': '/docs/rest-api/rest-api',
'GET /docs/using-fleet/configuration-files': '/docs/configuration/configuration-files/',
'GET /docs/using-fleet/application-security': '/handbook/business-operations/application-security',
'GET /docs/using-fleet/security-audits': '/handbook/business-operations/security-audits',
'GET /docs/using-fleet/process-file-events': '/guides/querying-process-file-events-table-on-centos-7',
'GET /docs/using-fleet/audit-activities': '/docs/using-fleet/audit-logs',
'GET /docs/using-fleet/detail-queries-summary': '/docs/using-fleet/understanding-host-vitals',
'GET /docs/using-fleet/orbit': '/docs/using-fleet/fleetd',
'GET /docs/deploying': '/docs/deploy',
'GET /docs/deploying/faq': '/docs/get-started/faq',
'GET /docs/deploying/introduction': '/docs/deploy/introduction',
'GET /docs/deploying/reference-architectures': '/docs/deploy/reference-architectures ',
'GET /docs/deploying/upgrading-fleet': '/docs/deploy/upgrading-fleet',
'GET /docs/deploying/server-installation': '/docs/deploy/server-installation',
'GET /docs/deploying/cloudgov': '/docs/deploy/cloudgov',
'GET /docs/deploying/configuration': '/docs/configuration/fleet-server-configuration',
'GET /docs/deploying/fleetctl-agent-updates': '/docs/using-fleet/update-agents',
'GET /docs/deploying/debugging': '/handbook/engineering/debugging',
'GET /docs/deploying/load-testing': '/handbook/engineering/load-testing',
'GET /docs/contributing/configuration': '/docs/configuration/configuration-files',
'GET /docs/contributing/*': {
skipAssets: true,
fn: (req, res)=>{
return res.redirect('https://github.com/fleetdm/fleet/tree/main/docs/Contributing');
}
},
'GET /docs/contributing/orbit-development-and-release-strategy': '/docs/contributing/fleetd-development-and-release-strategy',
'GET /docs/contributing/run-locally-built-orbit': '/docs/contributing/run-locally-built-fleetd',
'GET /handbook/company/ceo-handbook': '/handbook/company/ceo',

21
website/scripts/build-static-content.js vendored
View file

@ -190,10 +190,10 @@ module.exports = {
// > Inspired by https://github.com/uncletammy/doc-templater/blob/2969726b598b39aa78648c5379e4d9503b65685e/lib/compile-markdown-tree-from-remote-git-repo.js#L308-L313
// > And https://github.com/uncletammy/doc-templater/blob/2969726b598b39aa78648c5379e4d9503b65685e/lib/compile-markdown-tree-from-remote-git-repo.js#L107-L132
let pageRelSourcePath = path.relative(path.join(topLvlRepoPath, sectionRepoPath), path.resolve(pageSourcePath));
let pageUnextensionedLowercasedRelPath = (
let pageUnextensionedUnwhitespacedLowercasedRelPath = (
pageRelSourcePath
.replace(/(^|\/)([^/]+)\.[^/]*$/, '$1$2')
.split(/\//).map((fileOrFolderName) => fileOrFolderName.toLowerCase()).join('/')
.split(/\//).map((fileOrFolderName) => fileOrFolderName.toLowerCase().replace(/\s+/g, '-')).join('/')
);
let RX_README_FILENAME = /\/?readme\.?m?d?$/i;// « for matching `readme` or `readme.md` (case-insensitive) at the end of a file path
@ -219,7 +219,7 @@ module.exports = {
(
SECTION_INFOS_BY_SECTION_REPO_PATHS[sectionRepoPath].urlPrefix +
'/' + (
pageUnextensionedLowercasedRelPath
pageUnextensionedUnwhitespacedLowercasedRelPath
.split(/\//).map((fileOrFolderName) => encodeURIComponent(fileOrFolderName.replace(/^[0-9]+[\-]+/,''))).join('/')// « Get URL-friendly by encoding characters and stripping off ordering prefixes (like the "1-" in "1-Using-Fleet") for all folder and file names in the path.
)
).replace(RX_README_FILENAME, '')// « Interpret README files as special and map it to the URL representing its containing folder.
@ -293,7 +293,7 @@ module.exports = {
let referencedPageSourcePath = path.resolve(path.join(topLvlRepoPath, sectionRepoPath, pageRelSourcePath), '../', oldRelPath);
let possibleReferencedUrlHash = oldRelPath.match(/(\.md#)([^/]*$)/) ? oldRelPath.match(/(\.md#)([^/]*$)/)[2] : false;
let referencedPageNewUrl = 'https://fleetdm.com/' + (
(path.relative(topLvlRepoPath, referencedPageSourcePath).replace(/(^|\/)([^/]+)\.[^/]*$/, '$1$2').split(/\//).map((fileOrFolderName) => fileOrFolderName.toLowerCase()).join('/'))
(path.relative(topLvlRepoPath, referencedPageSourcePath).replace(/(^|\/)([^/]+)\.[^/]*$/, '$1$2').split(/\//).map((fileOrFolderName) => fileOrFolderName.toLowerCase().replace(/\s+/g, '-')).join('/'))
.split(/\//).map((fileOrFolderName) => encodeURIComponent(fileOrFolderName.replace(/^[0-9]+[\-]+/,''))).join('/')
).replace(RX_README_FILENAME, '');
if(possibleReferencedUrlHash) {
@ -414,10 +414,11 @@ module.exports = {
// If the page has a pageOrderInSection meta tag, we'll use that to sort pages in their bottom level sections.
let pageOrderInSection;
let docNavCategory;
if(sectionRepoPath === 'docs/') {
// Set a flag to determine if the page is a readme (e.g. /docs/Using-Fleet/configuration-files/readme.md) or a FAQ page.
// READMEs in subfolders and FAQ pages don't have pageOrderInSection values, they are always sorted at the end of sections.
let isPageAReadmeOrFAQ = (_.last(pageUnextensionedLowercasedRelPath.split(/\//)) === 'faq' || _.last(pageUnextensionedLowercasedRelPath.split(/\//)) === 'readme');
let isPageAReadmeOrFAQ = (_.last(pageUnextensionedUnwhitespacedLowercasedRelPath.split(/\//)) === 'faq' || _.last(pageUnextensionedUnwhitespacedLowercasedRelPath.split(/\//)) === 'readme');
if(embeddedMetadata.pageOrderInSection) {
if(isPageAReadmeOrFAQ) {
// Throwing an error if a FAQ or README page has a pageOrderInSection meta tag
@ -433,6 +434,11 @@ module.exports = {
// If the page is not a Readme or a FAQ, we'll throw an error if its missing a pageOrderInSection meta tag.
throw new Error(`Failed compiling markdown content: A Non FAQ or README Documentation page is missing a pageOrderInSection meta tag (<meta name="pageOrderInSection" value="">) at "${path.join(topLvlRepoPath, pageSourcePath)}". To resolve, add a meta tag with a number higher than 0.`);
}
if(embeddedMetadata.navSection){
docNavCategory = embeddedMetadata.navSection;
} else {
docNavCategory = 'Uncategorized';
}
}
if(sectionRepoPath === 'handbook/') {
@ -506,7 +512,7 @@ module.exports = {
rootRelativeUrlPath = (
'/' +
(encodeURIComponent(embeddedMetadata.category === 'success stories' ? 'success-stories' : embeddedMetadata.category === 'security' ? 'securing' : embeddedMetadata.category)) + '/' +
(pageUnextensionedLowercasedRelPath.split(/\//).map((fileOrFolderName) => encodeURIComponent(fileOrFolderName.replace(/^[0-9]+[\-]+/,''))).join('/'))
(pageUnextensionedUnwhitespacedLowercasedRelPath.split(/\//).map((fileOrFolderName) => encodeURIComponent(fileOrFolderName.replace(/^[0-9]+[\-]+/,''))).join('/'))
);
}
@ -521,7 +527,7 @@ module.exports = {
let htmlId = (
sectionRepoPath.slice(0,10)+
'--'+
_.last(pageUnextensionedLowercasedRelPath.split(/\//)).slice(0,20)+
_.last(pageUnextensionedUnwhitespacedLowercasedRelPath.split(/\//)).slice(0,20)+
'--'+
sails.helpers.strings.random.with({len:10})// if two files in different folders happen to have the same filename, there is a 1/16^10 chance of a collision (this is small enough- worst case, the build fails at the uniqueness check and we rerun it.)
).replace(/[^a-z0-9\-]/ig,'');
@ -545,6 +551,7 @@ module.exports = {
lastModifiedAt: lastModifiedAt,
htmlId: htmlId,
pageOrderInSectionPath: pageOrderInSection,
docNavCategory: docNavCategory ? docNavCategory : undefined,// FUTURE: No docs specific markdown page attributes.
sectionRelativeRepoPath: sectionRelativeRepoPath,
meta: _.omit(embeddedMetadata, ['title', 'pageOrderInSection']),
linksForHandbookIndex: linksForHandbookIndex.length > 0 ? linksForHandbookIndex : undefined,

93
website/views/pages/docs/basic-documentation.ejs vendored
View file

@ -98,13 +98,18 @@
<a :href="page.url" class="font-weight-bold">
{{page.title}}
</a>
<ul class="px-0 pt-3 mb-0" v-if="!_.isEmpty(findPagesByUrl(page.url))">
<li class="px-0 mb-2" v-for="subpage in findPagesByUrl(page.url)">
<a :href="subpage.url" :class="subpage.title === thisPage.title ? 'topic active' : 'topic'">
{{subpage.title}}
</a>
</li>
</ul>
<div purpose="expanded-nav" class="pt-3" v-if="isCurrentSection(page)">
<ul class="p-0 pl-2 mb-2" v-if="!_.isEmpty(findPagesByUrl(page.url))">
<div purpose="nav-section" v-for="(section, sectionName) of findAndSortNavSectionsByUrl(page.url)" :key="sectionName" v-if="sectionName !== 'hidden'">
<p purpose="nav-section-title" v-if="sectionName !== 'Uncategorized' && sectionName !== 'TBD'">{{sectionName}}</p>
<li v-for="subpage in section" :key="subpage.title">
<a :href="subpage.url" :class="subpage.title === thisPage.title ? 'topic active' : 'topic'">
{{subpage.title}}
</a>
</li>
</div>
</ul>
</div>
</li>
</ul>
</div>
@ -124,50 +129,37 @@
<div class="container-fluid d-flex flex-column flex-lg-row p-0 pt-lg-4 pb-lg-4 m-0">
<div purpose="left-sidebar" class="d-none d-lg-flex flex-column text-left pl-0 pr-4 left-sidebar">
<ul class="p-0 pb-2 m-0 left-nav">
<ul class="p-0 pb-3 m-0 left-nav">
<li v-for="page in findPagesByUrl()" :key="page.title">
<a :href="page.url" class="font-weight-bold pb-3">{{page.title}}</a>
<div class="pt-2" v-if="isCurrentSection(page)">
<ul class="p-0 mb-2">
<li v-for="subpage in findPagesByUrl(page.url)" :key="subpage.title">
<a :href="subpage.url" :class="subpage.title === thisPage.title ? 'topic active' : 'topic'">
{{subpage.title}}
</a>
</li>
<div purpose="expanded-nav" class="pt-3" v-if="isCurrentSection(page)">
<ul class="p-0 pl-2 mb-2">
<div purpose="nav-section" v-for="(section, sectionName) of findAndSortNavSectionsByUrl(page.url)" :key="sectionName" v-if="sectionName !== 'hidden'">
<p purpose="nav-section-title" v-if="sectionName !== 'Uncategorized' && sectionName !== 'TBD'">{{sectionName}}</p>
<li v-for="subpage in section" :key="subpage.title">
<a :href="subpage.url" :class="subpage.title === thisPage.title ? 'topic active' : 'topic'">
{{subpage.title}}
</a>
</li>
</div>
</ul>
</div>
</li>
</ul>
<a class="font-weight-bold py-3" target="_blank" href="https://github.com/fleetdm/fleet/releases">Releases</a>
<a href="/support" class="btn btn-block btn-sm btn-primary">Support</a>
<div purpose="right-sidebar-buttons">
<div class="d-none d-lg-block" purpose="demo-cta">
<a class="d-flex align-items-center justify-content-center" @click="clickOpenChatWidget()">
<div class="d-flex flex-column align-items-center">
<img style="height: auto; width: 47px; margin-bottom: 8px;" alt="Target and configure specific devices" src="/images/docs-cta-icon-47x38@2x.png">
<p class="mb-2 text-center">Target and configure specific devices</p>
<span>
Talk to an expert <img purpose="right-arrow" class="d-inline" style="height: 16px; width: auto; margin-bottom: 2px;" alt="right arrow" src="/images/arrow-right-red-16x16@2x.png" />
</span>
</div>
</a>
</div>
<div>
<div purpose="premium-cta" style="background: #E59CC4;" v-if="currentDocsSection === 'using-fleet' || currentDocsSection === 'contributing'">
<div purpose="docs-cta-image" class="d-flex justify-content-center">
<img alt="A computer next to a coffee cup" src="/images/docs-premium-cta-computer-125x134@2x.png">
</div>
<p>Even more control with <span>Fleet Premium</span></p>
<a purpose="premium-cta-btn" href="/upgrade">Learn more</a>
<a class="pt-4 pb-3" target="_blank" href="https://fleetdm.com/tables">Data tables</a>
<a class="pb-3" target="_blank" href="https://fleetdm.com/queries">Built-in queries</a>
<a class="pb-3" target="_blank" href="https://github.com/fleetdm/fleet/releases">Releases</a>
<a class="pb-3" target="_blank" href="https://fleetdm.com/support">Support</a>
<div class="d-none d-lg-block" purpose="swag-cta" v-if="showSwagForm">
<a class="d-flex align-items-center justify-content-center" href="https://kqphpqst851.typeform.com/to/ZfA3sOu0" target="_blank">
<div class="d-flex flex-column align-items-center">
<img style="height: auto; width: 47px; margin-bottom: 8px;" alt="A very nice Fleet branded shirt" src="/images/fleet-shirt-60x55@2x.png">
<p class="mb-0">Request Fleet swag</p>
<span>
It's free <img purpose="right-arrow" class="d-inline" style="height: 16px; width: auto; margin-bottom: 2px;" alt="right arrow" src="/images/arrow-right-red-16x16@2x.png" />
</span>
</div>
<div purpose="premium-cta" style="background: #A182DF;" v-else-if="currentDocsSection === 'deploying'">
<div purpose="docs-cta-image" class="d-flex justify-content-center">
<img alt="A telephone in a glass display case" src="/images/docs-premium-cta-telephone-125x134@2x.png">
</div>
<p>Expertise on-demand with <span>Fleet Premium</span></p>
<a purpose="premium-cta-btn" href="/upgrade">Learn more</a>
</div>
</div>
</a>
</div>
</div>
@ -187,19 +179,6 @@
</li>
</ul>
</div>
<div class="d-none d-lg-block" purpose="swag-cta" v-if="showSwagForm">
<a class="d-flex align-items-center justify-content-center" href="https://kqphpqst851.typeform.com/to/ZfA3sOu0" target="_blank">
<div class="d-flex flex-column align-items-center">
<img style="height: auto; width: 47px; margin-bottom: 8px;" alt="A very nice Fleet branded shirt" src="/images/fleet-shirt-60x55@2x.png">
<p class="mb-0">Request Fleet swag</p>
<span>
It's free <img purpose="right-arrow" class="d-inline" style="height: 16px; width: auto; margin-bottom: 2px;" alt="right arrow" src="/images/arrow-right-red-16x16@2x.png" />
</span>
</div>
</a>
</div>
</div>
<div purpose="content" id="body-content" class="d-flex flex-column px-lg-5 content" parasails-has-no-page-script>

2
website/views/pages/get-started.ejs vendored
View file

@ -22,7 +22,7 @@
style="width: 16px; display: inline; margin-right: 8px; margin-bottom: 3px" src="/images/info-16x16@2x.png">We
use NPM to install <code>fleetctl</code>. It can also be installed via the <a
href="https://github.com/fleetdm/fleet/releases" target="_blank">release page</a> or <a
href="/docs/contributing/building-fleet" target="_blank">built from source</a>.</p>
href="https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Building-Fleet.md" target="_blank">built from source</a>.</p>
</div>
<div>
<h2 class="pt-3 mb-3">2. Run Fleet</h2>