diff --git a/docs/Using-Fleet/Process-File-Events.md b/articles/querying-process-file-events-table-on-centos-7.md similarity index 94% rename from docs/Using-Fleet/Process-File-Events.md rename to articles/querying-process-file-events-table-on-centos-7.md index dbc3a18c6f..bbc71cdc6f 100644 --- a/docs/Using-Fleet/Process-File-Events.md +++ b/articles/querying-process-file-events-table-on-centos-7.md @@ -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. - - - \ No newline at end of file + + + + + + \ No newline at end of file diff --git a/docs/01-Using-Fleet/standard-query-library/README.md b/docs/01-Using-Fleet/standard-query-library/README.md index 4311e744c1..8a217926bf 100644 --- a/docs/01-Using-Fleet/standard-query-library/README.md +++ b/docs/01-Using-Fleet/standard-query-library/README.md @@ -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) + + \ No newline at end of file diff --git a/docs/Configuration/README.md b/docs/Configuration/README.md new file mode 100644 index 0000000000..edeffc8a56 --- /dev/null +++ b/docs/Configuration/README.md @@ -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. \ No newline at end of file diff --git a/docs/Using-Fleet/configuration-files/README.md b/docs/Configuration/configuration-files/README.md similarity index 99% rename from docs/Using-Fleet/configuration-files/README.md rename to docs/Configuration/configuration-files/README.md index ed9adca4c7..05aa1dbe01 100644 --- a/docs/Using-Fleet/configuration-files/README.md +++ b/docs/Configuration/configuration-files/README.md @@ -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. diff --git a/docs/Using-Fleet/configuration-files/kubernetes/fleet-deployment.yml b/docs/Configuration/configuration-files/kubernetes/fleet-deployment.yml similarity index 100% rename from docs/Using-Fleet/configuration-files/kubernetes/fleet-deployment.yml rename to docs/Configuration/configuration-files/kubernetes/fleet-deployment.yml diff --git a/docs/Using-Fleet/configuration-files/kubernetes/fleet-migrations.yml b/docs/Configuration/configuration-files/kubernetes/fleet-migrations.yml similarity index 100% rename from docs/Using-Fleet/configuration-files/kubernetes/fleet-migrations.yml rename to docs/Configuration/configuration-files/kubernetes/fleet-migrations.yml diff --git a/docs/Using-Fleet/configuration-files/kubernetes/fleet-service.yml b/docs/Configuration/configuration-files/kubernetes/fleet-service.yml similarity index 100% rename from docs/Using-Fleet/configuration-files/kubernetes/fleet-service.yml rename to docs/Configuration/configuration-files/kubernetes/fleet-service.yml diff --git a/docs/Deploying/Configuration.md b/docs/Configuration/fleet-server-configuration.md similarity index 96% rename from docs/Deploying/Configuration.md rename to docs/Configuration/fleet-server-configuration.md index fe471e9647..f99394cc0b 100644 --- a/docs/Deploying/Configuration.md +++ b/docs/Configuration/fleet-server-configuration.md @@ -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. - + \ No newline at end of file diff --git a/docs/Contributing/Testing-and-local-development.md b/docs/Contributing/Testing-and-local-development.md index c34e5aa10b..4201047594 100644 --- a/docs/Contributing/Testing-and-local-development.md +++ b/docs/Contributing/Testing-and-local-development.md @@ -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: diff --git a/docs/Deploying/Introduction.md b/docs/Deploy/Introduction.md similarity index 100% rename from docs/Deploying/Introduction.md rename to docs/Deploy/Introduction.md diff --git a/docs/Using-Fleet/Monitoring-Fleet.md b/docs/Deploy/Monitoring-Fleet.md similarity index 99% rename from docs/Using-Fleet/Monitoring-Fleet.md rename to docs/Deploy/Monitoring-Fleet.md index 7b6f575118..18de9f6a61 100644 --- a/docs/Using-Fleet/Monitoring-Fleet.md +++ b/docs/Deploy/Monitoring-Fleet.md @@ -103,3 +103,4 @@ The `fleetctl debug archive` command retrieves information generated by Go's [`n + \ No newline at end of file diff --git a/docs/Deploy/README.md b/docs/Deploy/README.md new file mode 100644 index 0000000000..aa36c95b91 --- /dev/null +++ b/docs/Deploy/README.md @@ -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. + + + diff --git a/docs/Deploying/Reference-Architectures.md b/docs/Deploy/Reference-Architectures.md similarity index 100% rename from docs/Deploying/Reference-Architectures.md rename to docs/Deploy/Reference-Architectures.md diff --git a/docs/Deploying/Server-Installation.md b/docs/Deploy/Server-Installation.md similarity index 99% rename from docs/Deploying/Server-Installation.md rename to docs/Deploy/Server-Installation.md index 8be3a6e778..0719667827 100644 --- a/docs/Deploying/Server-Installation.md +++ b/docs/Deploy/Server-Installation.md @@ -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 + \ No newline at end of file diff --git a/docs/Deploying/Upgrading-Fleet.md b/docs/Deploy/Upgrading-Fleet.md similarity index 100% rename from docs/Deploying/Upgrading-Fleet.md rename to docs/Deploy/Upgrading-Fleet.md diff --git a/docs/Deploying/cloudgov.md b/docs/Deploy/cloudgov.md similarity index 98% rename from docs/Deploying/cloudgov.md rename to docs/Deploy/cloudgov.md index d5a3b7d2c6..e61d79ee8e 100644 --- a/docs/Deploying/cloudgov.md +++ b/docs/Deploy/cloudgov.md @@ -113,3 +113,4 @@ variables](https://fleetdm.com/docs/deploying/configuration#using-only-environme + diff --git a/docs/Deploying/FAQ.md b/docs/Deploying/FAQ.md deleted file mode 100644 index 0923e40799..0000000000 --- a/docs/Deploying/FAQ.md +++ /dev/null @@ -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 -h -P -D -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= \ - --mysql_database= \ - --mysql_username= \ - --mysql_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=`) 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. - - - diff --git a/docs/Deploying/README.md b/docs/Deploying/README.md deleted file mode 100644 index 40c63cac04..0000000000 --- a/docs/Deploying/README.md +++ /dev/null @@ -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. - - diff --git a/docs/Using-Fleet/FAQ.md b/docs/Get started/FAQ.md similarity index 55% rename from docs/Using-Fleet/FAQ.md rename to docs/Get started/FAQ.md index 01d23d2ae9..8fbcce33a8 100644 --- a/docs/Using-Fleet/FAQ.md +++ b/docs/Get started/FAQ.md @@ -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 -h -P -D -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= \ + --mysql_database= \ + --mysql_username= \ + --mysql_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=`) 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. + + + \ No newline at end of file diff --git a/docs/Get started/README.md b/docs/Get started/README.md new file mode 100644 index 0000000000..f626704770 --- /dev/null +++ b/docs/Get started/README.md @@ -0,0 +1,12 @@ +# Get started + +### [Why Fleet](./why-fleet.md) + + +### [Anatomy](./anatomy.md) + + +### [Tutorials and guides](./tutorials-and-guides) + + +### [FAQ](./FAQ.md) \ No newline at end of file diff --git a/docs/Get started/anatomy.md b/docs/Get started/anatomy.md new file mode 100644 index 0000000000..757c9614a1 --- /dev/null +++ b/docs/Get started/anatomy.md @@ -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). + + diff --git a/docs/Get started/tutorials-and-guides.md b/docs/Get started/tutorials-and-guides.md new file mode 100644 index 0000000000..b943291b7a --- /dev/null +++ b/docs/Get started/tutorials-and-guides.md @@ -0,0 +1,6 @@ +# Tutorials and guides + +>Coming soon + + + \ No newline at end of file diff --git a/docs/Get started/why-fleet.md b/docs/Get started/why-fleet.md new file mode 100644 index 0000000000..bf7f2ed53f --- /dev/null +++ b/docs/Get started/why-fleet.md @@ -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. + + + + +## 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). + + + +## 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. + + \ No newline at end of file diff --git a/docs/REST API/README.md b/docs/REST API/README.md new file mode 100644 index 0000000000..f903695a72 --- /dev/null +++ b/docs/REST API/README.md @@ -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. \ No newline at end of file diff --git a/docs/Using-Fleet/REST-API.md b/docs/REST API/rest-api.md similarity index 99% rename from docs/Using-Fleet/REST-API.md rename to docs/REST API/rest-api.md index 2dcbe5454a..da1f41388c 100644 --- a/docs/Using-Fleet/REST-API.md +++ b/docs/REST API/rest-api.md @@ -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 - PayloadContent - - PayloadDisplayName - Example profile - PayloadIdentifier - com.example.profile - PayloadType - Configuration - PayloadUUID - 0BBF3E23-7F56-48FC-A2B6-5ACC598A4A69 - PayloadVersion - 1 + PayloadContent + + PayloadDisplayName + Example profile + PayloadIdentifier + com.example.profile + PayloadType + Configuration + PayloadUUID + 0BBF3E23-7F56-48FC-A2B6-5ACC598A4A69 + PayloadVersion + 1 --------------------------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. - PayloadContent - - PayloadDisplayName - Example profile - PayloadIdentifier - com.example.profile - PayloadType - Configuration - PayloadUUID - 0BBF3E23-7F56-48FC-A2B6-5ACC598A4A69 - PayloadVersion - 1 + PayloadContent + + PayloadDisplayName + Example profile + PayloadIdentifier + com.example.profile + PayloadType + Configuration + PayloadUUID + 0BBF3E23-7F56-48FC-A2B6-5ACC598A4A69 + PayloadVersion + 1 ``` @@ -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: ``` --- - - \ No newline at end of file + + + diff --git a/docs/Using-Fleet/Audit-Activities.md b/docs/Using Fleet/Audit-logs.md similarity index 99% rename from docs/Using-Fleet/Audit-Activities.md rename to docs/Using Fleet/Audit-logs.md index 0af5c79dfa..7cd16c82ae 100644 --- a/docs/Using-Fleet/Audit-Activities.md +++ b/docs/Using Fleet/Audit-logs.md @@ -1,5 +1,5 @@ -# 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. - + + diff --git a/docs/Using-Fleet/Automations.md b/docs/Using Fleet/Automations.md similarity index 99% rename from docs/Using-Fleet/Automations.md rename to docs/Using Fleet/Automations.md index 27191afa2e..a21b3f13bc 100644 --- a/docs/Using-Fleet/Automations.md +++ b/docs/Using Fleet/Automations.md @@ -162,3 +162,4 @@ status webhook** in the Fleet UI. + diff --git a/docs/Using-Fleet/CIS-Benchmarks.md b/docs/Using Fleet/CIS-Benchmarks.md similarity index 99% rename from docs/Using-Fleet/CIS-Benchmarks.md rename to docs/Using Fleet/CIS-Benchmarks.md index 712eb6c862..9d0a6fafac 100644 --- a/docs/Using-Fleet/CIS-Benchmarks.md +++ b/docs/Using Fleet/CIS-Benchmarks.md @@ -261,3 +261,4 @@ Requires this GPO in place: 'Computer Configuration\Policies\Administrative Temp + diff --git a/docs/Using-Fleet/Fleet-UI.md b/docs/Using Fleet/Fleet-UI.md similarity index 99% rename from docs/Using-Fleet/Fleet-UI.md rename to docs/Using Fleet/Fleet-UI.md index fe3af2d7ff..531568ae80 100644 --- a/docs/Using-Fleet/Fleet-UI.md +++ b/docs/Using Fleet/Fleet-UI.md @@ -100,4 +100,4 @@ The agents may take several seconds to update because Fleet has to wait for the - + diff --git a/docs/Using-Fleet/Fleet-desktop.md b/docs/Using Fleet/Fleet-desktop.md similarity index 96% rename from docs/Using-Fleet/Fleet-desktop.md rename to docs/Using Fleet/Fleet-desktop.md index 3eead535de..d0a1034e66 100644 --- a/docs/Using-Fleet/Fleet-desktop.md +++ b/docs/Using Fleet/Fleet-desktop.md @@ -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 + \ No newline at end of file diff --git a/docs/Using-Fleet/Learn-how-to-use-Fleet.md b/docs/Using Fleet/Learn-how-to-use-Fleet.md similarity index 98% rename from docs/Using-Fleet/Learn-how-to-use-Fleet.md rename to docs/Using Fleet/Learn-how-to-use-Fleet.md index 730646d2c0..c9dfb74426 100644 --- a/docs/Using-Fleet/Learn-how-to-use-Fleet.md +++ b/docs/Using Fleet/Learn-how-to-use-Fleet.md @@ -55,3 +55,4 @@ When the query has finished, you should see several columns in the "Results" tab + \ No newline at end of file diff --git a/docs/Using-Fleet/Log-destinations.md b/docs/Using Fleet/Log-destinations.md similarity index 99% rename from docs/Using-Fleet/Log-destinations.md rename to docs/Using Fleet/Log-destinations.md index 9114dcd737..dadc244d17 100644 --- a/docs/Using-Fleet/Log-destinations.md +++ b/docs/Using Fleet/Log-destinations.md @@ -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. - \ No newline at end of file + + \ No newline at end of file diff --git a/docs/Using-Fleet/MDM-commands.md b/docs/Using Fleet/MDM-commands.md similarity index 99% rename from docs/Using-Fleet/MDM-commands.md rename to docs/Using Fleet/MDM-commands.md index ec0a2880bb..b7659bf981 100644 --- a/docs/Using-Fleet/MDM-commands.md +++ b/docs/Using Fleet/MDM-commands.md @@ -119,3 +119,4 @@ The command ID can be used to view command results as documented in [step 4 of t + diff --git a/docs/Using-Fleet/MDM-custom-macOS-settings.md b/docs/Using Fleet/MDM-custom-macOS-settings.md similarity index 98% rename from docs/Using-Fleet/MDM-custom-macOS-settings.md rename to docs/Using Fleet/MDM-custom-macOS-settings.md index 62289de880..6f3b9c5383 100644 --- a/docs/Using-Fleet/MDM-custom-macOS-settings.md +++ b/docs/Using Fleet/MDM-custom-macOS-settings.md @@ -102,3 +102,4 @@ Learn more about configuration options for hosts that aren't assigned to a team + \ No newline at end of file diff --git a/docs/Using-Fleet/MDM-disk-encryption.md b/docs/Using Fleet/MDM-disk-encryption.md similarity index 99% rename from docs/Using-Fleet/MDM-disk-encryption.md rename to docs/Using Fleet/MDM-disk-encryption.md index 4d0253eecb..03946184ce 100644 --- a/docs/Using-Fleet/MDM-disk-encryption.md +++ b/docs/Using Fleet/MDM-disk-encryption.md @@ -117,3 +117,4 @@ How to reset a macOS host's password using the disk encryption key: + \ No newline at end of file diff --git a/docs/Using-Fleet/MDM-macOS-setup.md b/docs/Using Fleet/MDM-macOS-setup.md similarity index 99% rename from docs/Using-Fleet/MDM-macOS-setup.md rename to docs/Using Fleet/MDM-macOS-setup.md index 222089270b..3841f07247 100644 --- a/docs/Using-Fleet/MDM-macOS-setup.md +++ b/docs/Using Fleet/MDM-macOS-setup.md @@ -231,3 +231,4 @@ Testing requires a test Mac that is present in your Apple Business Manager (ABM) + \ No newline at end of file diff --git a/docs/Using-Fleet/MDM-macOS-updates.md b/docs/Using Fleet/MDM-macOS-updates.md similarity index 99% rename from docs/Using-Fleet/MDM-macOS-updates.md rename to docs/Using Fleet/MDM-macOS-updates.md index 3adfaec59c..369a854c95 100644 --- a/docs/Using-Fleet/MDM-macOS-updates.md +++ b/docs/Using Fleet/MDM-macOS-updates.md @@ -161,4 +161,4 @@ Request payload: - + diff --git a/docs/Using-Fleet/MDM-migration-guide.md b/docs/Using Fleet/MDM-migration-guide.md similarity index 99% rename from docs/Using-Fleet/MDM-migration-guide.md rename to docs/Using Fleet/MDM-migration-guide.md index a8757262e7..26d416ffbc 100644 --- a/docs/Using-Fleet/MDM-migration-guide.md +++ b/docs/Using Fleet/MDM-migration-guide.md @@ -118,3 +118,4 @@ Want to know what your organization can see? Read about [transparency](https://f + \ No newline at end of file diff --git a/docs/Using-Fleet/MDM-setup.md b/docs/Using Fleet/MDM-setup.md similarity index 99% rename from docs/Using-Fleet/MDM-setup.md rename to docs/Using Fleet/MDM-setup.md index eb68a3484f..01b3929e60 100644 --- a/docs/Using-Fleet/MDM-setup.md +++ b/docs/Using Fleet/MDM-setup.md @@ -283,3 +283,4 @@ To renew the token: + \ No newline at end of file diff --git a/docs/Using-Fleet/Osquery-process.md b/docs/Using Fleet/Osquery-process.md similarity index 96% rename from docs/Using-Fleet/Osquery-process.md rename to docs/Using Fleet/Osquery-process.md index 76aa4e3f47..68efcd81da 100644 --- a/docs/Using-Fleet/Osquery-process.md +++ b/docs/Using Fleet/Osquery-process.md @@ -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. - \ No newline at end of file + + \ No newline at end of file diff --git a/docs/Using-Fleet/README.md b/docs/Using Fleet/README.md similarity index 50% rename from docs/Using-Fleet/README.md rename to docs/Using Fleet/README.md index 902922a88c..67af32f274 100644 --- a/docs/Using-Fleet/README.md +++ b/docs/Using Fleet/README.md @@ -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 diff --git a/docs/Using-Fleet/Supported-browsers.md b/docs/Using Fleet/Supported-browsers.md similarity index 95% rename from docs/Using-Fleet/Supported-browsers.md rename to docs/Using Fleet/Supported-browsers.md index 3f941f9c8b..00dfe7a9a9 100644 --- a/docs/Using-Fleet/Supported-browsers.md +++ b/docs/Using Fleet/Supported-browsers.md @@ -25,3 +25,4 @@ We test each browser on Windows whenever possible, because our engineering team + \ No newline at end of file diff --git a/docs/Using-Fleet/Supported-host-operating-systems.md b/docs/Using Fleet/Supported-host-operating-systems.md similarity index 97% rename from docs/Using-Fleet/Supported-host-operating-systems.md rename to docs/Using Fleet/Supported-host-operating-systems.md index 44c3b409d1..05d216eadc 100644 --- a/docs/Using-Fleet/Supported-host-operating-systems.md +++ b/docs/Using Fleet/Supported-host-operating-systems.md @@ -28,3 +28,4 @@ If you aren't sure what version of `glibc` your distribution is using, [DistroWa + \ No newline at end of file diff --git a/docs/Using-Fleet/Troubleshooting-live-queries.md b/docs/Using Fleet/Troubleshooting-live-queries.md similarity index 98% rename from docs/Using-Fleet/Troubleshooting-live-queries.md rename to docs/Using Fleet/Troubleshooting-live-queries.md index 6f985ca9f6..6f1ad55ad9 100644 --- a/docs/Using-Fleet/Troubleshooting-live-queries.md +++ b/docs/Using Fleet/Troubleshooting-live-queries.md @@ -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. - \ No newline at end of file + + \ No newline at end of file diff --git a/docs/Using-Fleet/Detail-Queries-Summary.md b/docs/Using Fleet/Understanding-host-vitals.md similarity index 99% rename from docs/Using-Fleet/Detail-Queries-Summary.md rename to docs/Using Fleet/Understanding-host-vitals.md index d403494c7c..9ebf41c6db 100644 --- a/docs/Using-Fleet/Detail-Queries-Summary.md +++ b/docs/Using Fleet/Understanding-host-vitals.md @@ -1,5 +1,5 @@ -# 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' ``` - + + + \ No newline at end of file diff --git a/docs/Using-Fleet/Usage-statistics.md b/docs/Using Fleet/Usage-statistics.md similarity index 98% rename from docs/Using-Fleet/Usage-statistics.md rename to docs/Using Fleet/Usage-statistics.md index 87469f29ed..197318904e 100644 --- a/docs/Using-Fleet/Usage-statistics.md +++ b/docs/Using Fleet/Usage-statistics.md @@ -128,3 +128,4 @@ To disable usage statistics: + \ No newline at end of file diff --git a/docs/Using-Fleet/Vulnerability-Processing.md b/docs/Using Fleet/Vulnerability-Processing.md similarity index 99% rename from docs/Using-Fleet/Vulnerability-Processing.md rename to docs/Using Fleet/Vulnerability-Processing.md index 178dfc690e..bca5886eff 100644 --- a/docs/Using-Fleet/Vulnerability-Processing.md +++ b/docs/Using Fleet/Vulnerability-Processing.md @@ -410,3 +410,4 @@ Once we have a good CPE, we can match it against the CVE database. We download t + \ No newline at end of file diff --git a/docs/Using-Fleet/ChromeOS.md b/docs/Using Fleet/enroll-chromebooks.md similarity index 88% rename from docs/Using-Fleet/ChromeOS.md rename to docs/Using Fleet/enroll-chromebooks.md index e2db8d5d46..5050556bfe 100644 --- a/docs/Using-Fleet/ChromeOS.md +++ b/docs/Using Fleet/enroll-chromebooks.md @@ -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). - + + + \ No newline at end of file diff --git a/docs/Using-Fleet/Adding-hosts.md b/docs/Using Fleet/enroll-hosts.md similarity index 99% rename from docs/Using-Fleet/Adding-hosts.md rename to docs/Using Fleet/enroll-hosts.md index 4be9f17d17..2f2545a82e 100644 --- a/docs/Using-Fleet/Adding-hosts.md +++ b/docs/Using Fleet/enroll-hosts.md @@ -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. + \ No newline at end of file diff --git a/docs/Using-Fleet/fleetctl-CLI.md b/docs/Using Fleet/fleetctl-CLI.md similarity index 97% rename from docs/Using-Fleet/fleetctl-CLI.md rename to docs/Using Fleet/fleetctl-CLI.md index d833f8dba1..acc7145144 100644 --- a/docs/Using-Fleet/fleetctl-CLI.md +++ b/docs/Using Fleet/fleetctl-CLI.md @@ -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: + \ No newline at end of file diff --git a/docs/Using-Fleet/fleetd.md b/docs/Using Fleet/fleetd.md similarity index 99% rename from docs/Using-Fleet/fleetd.md rename to docs/Using Fleet/fleetd.md index f10fe1a01f..58c6d0d049 100644 --- a/docs/Using-Fleet/fleetd.md +++ b/docs/Using Fleet/fleetd.md @@ -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. - + + diff --git a/docs/Using-Fleet/Permissions.md b/docs/Using Fleet/manage-access.md similarity index 99% rename from docs/Using-Fleet/Permissions.md rename to docs/Using Fleet/manage-access.md index 5aa124d52a..b5e30ab384 100644 --- a/docs/Using-Fleet/Permissions.md +++ b/docs/Using Fleet/manage-access.md @@ -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 + \ No newline at end of file diff --git a/docs/Using-Fleet/Teams.md b/docs/Using Fleet/segment-hosts.md similarity index 98% rename from docs/Using-Fleet/Teams.md rename to docs/Using Fleet/segment-hosts.md index 9006277bac..7d49ea6e98 100644 --- a/docs/Using-Fleet/Teams.md +++ b/docs/Using Fleet/segment-hosts.md @@ -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. - \ No newline at end of file + + \ No newline at end of file diff --git a/docs/Deploying/fleetctl-agent-updates.md b/docs/Using Fleet/update-agents.md similarity index 99% rename from docs/Deploying/fleetctl-agent-updates.md rename to docs/Using Fleet/update-agents.md index b7bed5d469..2fe3b6df68 100644 --- a/docs/Deploying/fleetctl-agent-updates.md +++ b/docs/Using Fleet/update-agents.md @@ -162,3 +162,4 @@ After the key(s) have been rotated, publish the repository in the same fashion a + diff --git a/docs/Using-Fleet/mobile-device-management.md b/docs/Using-Fleet/mobile-device-management.md deleted file mode 100644 index 0fae8de903..0000000000 --- a/docs/Using-Fleet/mobile-device-management.md +++ /dev/null @@ -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) - - - diff --git a/docs/Using-Fleet/Application-security.md b/handbook/business-operations/Application-security.md similarity index 99% rename from docs/Using-Fleet/Application-security.md rename to handbook/business-operations/Application-security.md index 359f314e53..14b0553b2a 100644 --- a/docs/Using-Fleet/Application-security.md +++ b/handbook/business-operations/Application-security.md @@ -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. - + + diff --git a/handbook/business-operations/README.md b/handbook/business-operations/README.md index dff3800243..fc0acbdf3c 100644 --- a/handbook/business-operations/README.md +++ b/handbook/business-operations/README.md @@ -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 diff --git a/docs/Using-Fleet/Security-audits.md b/handbook/business-operations/security-audits.md similarity index 99% rename from docs/Using-Fleet/Security-audits.md rename to handbook/business-operations/security-audits.md index b105c74608..539c44cba0 100644 --- a/docs/Using-Fleet/Security-audits.md +++ b/handbook/business-operations/security-audits.md @@ -225,4 +225,4 @@ improvements to make it more robust and resilient to compromise. - + diff --git a/handbook/business-operations/security.md b/handbook/business-operations/security.md index 86db4539e8..102099aebe 100644 --- a/handbook/business-operations/security.md +++ b/handbook/business-operations/security.md @@ -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). + diff --git a/handbook/company/why-this-way.md b/handbook/company/why-this-way.md index e6cf6ae4f2..8396c94bd2 100644 --- a/handbook/company/why-this-way.md +++ b/handbook/company/why-this-way.md @@ -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. diff --git a/docs/Deploying/Debugging.md b/handbook/engineering/Debugging.md similarity index 99% rename from docs/Deploying/Debugging.md rename to handbook/engineering/Debugging.md index f511651408..36da026286 100644 --- a/docs/Deploying/Debugging.md +++ b/handbook/engineering/Debugging.md @@ -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. - + + diff --git a/docs/Deploying/Load-testing.md b/handbook/engineering/Load-testing.md similarity index 98% rename from docs/Deploying/Load-testing.md rename to handbook/engineering/Load-testing.md index 4aff6e487d..bcdab25be4 100644 --- a/docs/Deploying/Load-testing.md +++ b/handbook/engineering/Load-testing.md @@ -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. - + diff --git a/handbook/engineering/README.md b/handbook/engineering/README.md index bbb6aeee31..14a3e8d10d 100644 --- a/handbook/engineering/README.md +++ b/handbook/engineering/README.md @@ -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 | diff --git a/handbook/marketing/README.md b/handbook/marketing/README.md index 239215d6fa..306dd11c0a 100644 --- a/handbook/marketing/README.md +++ b/handbook/marketing/README.md @@ -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. diff --git a/server/fleet/activities.go b/server/fleet/activities.go index 6dee14e934..e805fa1606 100644 --- a/server/fleet/activities.go +++ b/server/fleet/activities.go @@ -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{ diff --git a/server/fleet/gen_activity_doc.go b/server/fleet/gen_activity_doc.go index 65b9ea977f..86155e1e39 100644 --- a/server/fleet/gen_activity_doc.go +++ b/server/fleet/gen_activity_doc.go @@ -15,7 +15,7 @@ func main() { var b strings.Builder b.WriteString(` -# Audit activities +# Audit logs Fleet logs the following information for administrative actions (in JSON): @@ -64,9 +64,9 @@ Example: } } b.WriteString(` - + `) if err := os.WriteFile(os.Args[1], []byte(b.String()), 0600); err != nil { diff --git a/server/service/osquery_utils/gen_queries_doc.go b/server/service/osquery_utils/gen_queries_doc.go index 4fcda31e34..d7c8eaabf4 100644 --- a/server/service/osquery_utils/gen_queries_doc.go +++ b/server/service/osquery_utils/gen_queries_doc.go @@ -34,7 +34,7 @@ func main() { var b strings.Builder b.WriteString(` -# 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(` - + `) if err := os.WriteFile(os.Args[1], []byte(b.String()), 0600); err != nil { diff --git a/server/service/osquery_utils/queries.go b/server/service/osquery_utils/queries.go index 23df5abc12..cf7d84ea33 100644 --- a/server/service/osquery_utils/queries.go +++ b/server/service/osquery_utils/queries.go @@ -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, diff --git a/website/assets/js/pages/docs/basic-documentation.page.js b/website/assets/js/pages/docs/basic-documentation.page.js index 8a685fca93..e140bc6f27 100644 --- a/website/assets/js/pages/docs/basic-documentation.page.js +++ b/website/assets/js/pages/docs/basic-documentation.page.js @@ -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' : ''; }, diff --git a/website/assets/styles/pages/docs/basic-documentation.less b/website/assets/styles/pages/docs/basic-documentation.less index 840e9c2cba..17c8bf504f 100644 --- a/website/assets/styles/pages/docs/basic-documentation.less +++ b/website/assets/styles/pages/docs/basic-documentation.less @@ -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 { diff --git a/website/config/routes.js b/website/config/routes.js index 413324b7cb..40bdc58ed5 100644 --- a/website/config/routes.js +++ b/website/config/routes.js @@ -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', diff --git a/website/scripts/build-static-content.js b/website/scripts/build-static-content.js index a87c89ac55..8846a27ecb 100644 --- a/website/scripts/build-static-content.js +++ b/website/scripts/build-static-content.js @@ -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 () 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, diff --git a/website/views/pages/docs/basic-documentation.ejs b/website/views/pages/docs/basic-documentation.ejs index 25e674e2c3..37e5f5d702 100644 --- a/website/views/pages/docs/basic-documentation.ejs +++ b/website/views/pages/docs/basic-documentation.ejs @@ -98,13 +98,18 @@ {{page.title}} - +
+ +
@@ -124,50 +129,37 @@
-
-
- -
- A very nice Fleet branded shirt -

Request Fleet swag

- - It's free right arrow - -
- -
- -
diff --git a/website/views/pages/get-started.ejs b/website/views/pages/get-started.ejs index 9fd46bf257..b2c22dd90e 100644 --- a/website/views/pages/get-started.ejs +++ b/website/views/pages/get-started.ejs @@ -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 fleetctl. It can also be installed via the release page or built from source.

+ href="https://github.com/fleetdm/fleet/blob/main/docs/Contributing/Building-Fleet.md" target="_blank">built from source.

2. Run Fleet