From 988f50fa34bcc7b050133d883a22596e3600a5f4 Mon Sep 17 00:00:00 2001 From: Martin Angers Date: Thu, 8 Sep 2022 17:57:38 -0400 Subject: [PATCH] Document all keys in `config` and `team` YAML documents (#7449) - Add a new "Configuration for contributors" doc page. Move settings that are not recommended for production use - Remove settings modified in the `config` YAML document from the deploying/configuration doc page - Document all keys in `config` and `teams` YAML documents - Add comments to several `.go` files and remove unused struct --- ...ue-5222-document-all-organization-settings | 1 + .../Configuration-for-contributors.md | 362 ++++++++ docs/Deploying/Configuration.md | 400 +++------ docs/Using-Fleet/Fleet-desktop.md | 8 +- .../Using-Fleet/configuration-files/README.md | 786 ++++++++++++++---- ee/server/service/teams.go | 5 + server/datastore/mysql/app_configs.go | 2 + server/fleet/app.go | 10 - server/service/appconfig.go | 2 + 9 files changed, 1137 insertions(+), 439 deletions(-) create mode 100644 changes/issue-5222-document-all-organization-settings create mode 100644 docs/Contributing/Configuration-for-contributors.md diff --git a/changes/issue-5222-document-all-organization-settings b/changes/issue-5222-document-all-organization-settings new file mode 100644 index 0000000000..258e433378 --- /dev/null +++ b/changes/issue-5222-document-all-organization-settings @@ -0,0 +1 @@ +* Added detailed documentation of all organization settings, including default values and whether it is a required setting or not. diff --git a/docs/Contributing/Configuration-for-contributors.md b/docs/Contributing/Configuration-for-contributors.md new file mode 100644 index 0000000000..a815840b1d --- /dev/null +++ b/docs/Contributing/Configuration-for-contributors.md @@ -0,0 +1,362 @@ +# Configuration for contributors + +This document includes configuration files and settings that are helpful when developing or contributing to Fleet. + +Unlike the [configuration files documentation](../Using-Fleet/configuration-files/README.md), the files and settings in this document are not recommended for production use. Each setting includes the best practice for being successful in production. + +## Integrations + +Integration settings in Fleet can be configured using the `integrations` section of the `config` YAML file. To see all settings in this file, check out the [configuration files documentation](../Using-Fleet/configuration-files/README.md#organization-settings). + +> **Warning:** Be careful not to store your integration credentials in source control. The best practice is to configure integrations [via the Fleet UI](../Using-Fleet/Automations.md). + +### Jira + +Jira integrations are configured under the `integrations.jira` field, which is an array of dictionaries. + +#### integrations.jira[].url + +This is the URL of the Jira server to use, including the scheme (e.g. "https://"). + +- Required setting (string) +- Default value: none +- Config file format: + ``` + integrations: + jira: + - url: "https://example.atlassian.net" + username: "user1" + api_token: "secret" + project_key: "PJ1" + ``` + +#### integrations.jira[].username + +Use this username to authenticate API requests with the Jira server. + +- Required setting (string) +- Default value: none +- Config file format: + ``` + integrations: + jira: + - url: "https://example.atlassian.net" + username: "user1" + api_token: "secret" + project_key: "PJ1" + ``` + +#### integrations.jira[].api_token + +Use this API token to authenticate API requests with the Jira server. + +- Required setting (string) +- Default value: none +- Config file format: + ``` + integrations: + jira: + - url: "https://example.atlassian.net" + username: "user1" + api_token: "secret" + project_key: "PJ1" + ``` + +#### integrations.jira[].project_key + +Use this Jira project key to create tickets. + +- Required setting (string) +- Default value: none +- Config file format: + ``` + integrations: + jira: + - url: "https://example.atlassian.net" + username: "user1" + api_token: "secret" + project_key: "PJ1" + ``` + +#### integrations.jira[].enable_failing_policies + +Whether the integration is configured to create Jira tickets for failing policies. + +- Optional setting (boolean) +- Default value: `false` +- Config file format: + ``` + integrations: + jira: + - url: "https://example.atlassian.net" + username: "user1" + api_token: "secret" + project_key: "PJ1" + enable_failing_policies: true + ``` + +#### integrations.jira[].enable_software_vulnerabilities + +Whether the integration is configured to create Jira tickets for recent software vulnerabilities. + +- Optional setting (boolean) +- Default value: `false` +- Config file format: + ``` + integrations: + jira: + - url: "https://example.atlassian.net" + username: "user1" + api_token: "secret" + project_key: "PJ1" + enable_software_vulnerabilities: true + ``` + +### Zendesk + +Zendesk integrations are configured under the `integrations.zendesk` field, which is an array of dictionaries. + +#### integrations.zendesk[].url + +This is the URL of the Zendesk server to use, including the scheme (e.g. "https://"). + +- Required setting (string) +- Default value: none +- Config file format: + ``` + integrations: + zendesk: + - url: "https://example.zendesk.com" + email: "user1@example.com" + api_token: "secret" + group_id: 1234 + ``` + +#### integrations.zendesk[].email + +Use this email address to authenticate API requests with the Zendesk server. + +- Required setting (string) +- Default value: none +- Config file format: + ``` + integrations: + zendesk: + - url: "https://example.zendesk.com" + email: "user1@example.com" + api_token: "secret" + group_id: 1234 + ``` + +#### integrations.zendesk[].api_token + +Use this API token to authenticate API requests with the Zendesk server. + +- Required setting (string) +- Default value: none +- Config file format: + ``` + integrations: + zendesk: + - url: "https://example.zendesk.com" + email: "user1@example.com" + api_token: "secret" + group_id: 1234 + ``` + +#### integrations.zendesk[].group_id + +Use this group ID to create tickets. + +- Required setting (integer) +- Default value: none +- Config file format: + ``` + integrations: + zendesk: + - url: "https://example.zendesk.com" + email: "user1@example.com" + api_token: "secret" + group_id: 1234 + ``` + +#### integrations.zendesk[].enable_failing_policies + +Whether the integration is configured to create Zendesk tickets for failing policies. + +- Optional setting (boolean) +- Default value: `false` +- Config file format: + ``` + integrations: + zendesk: + - url: "https://example.zendesk.com" + email: "user1@example.com" + api_token: "secret" + group_id: 1234 + enable_failing_policies: true + ``` + +#### integrations.zendesk[].enable_software_vulnerabilities + +Whether the integration is configured to create Zendesk tickets for recent software vulnerabilities. + +- Optional setting (boolean) +- Default value: `false` +- Config file format: + ``` + integrations: + zendesk: + - url: "https://example.zendesk.com" + email: "user1@example.com" + api_token: "secret" + group_id: 1234 + enable_software_vulnerabilities: true + ``` + +## SMTP settings + +SMTP settings in Fleet can be configured using the `smtp_settings` section of the `config` YAML file. To see all settings in this file, check out the [configuration files documentation](../Using-Fleet/configuration-files/README.md#organization-settings). + +> **Warning:** Be careful not to store your SMTP credentials in source control. The best practice is to configure SMTP [via the Fleet UI](../Deploying/Configuration.md#configuring-single-sign-on-sso). + +### smtp_settings.authentication_method + +Use this authentication method when the authentication type is `authtype_username_password`. + +- Optional setting (string) +- Default value: `authmethod_plain` +- Possible values: + - `authmethod_cram_md5` + - `authmethod_login` + - `authmethod_plain` +- Config file format: + ``` + smtp_settings: + authentication_method: authmethod_cram_md5 + ``` + +### smtp_settings.authentication_type + +This is the type of authentication for the configured SMTP server. + +- Optional setting (string) +- Default value: `authtype_username_password` +- Possible values: + - `authtype_none` - use this if your SMTP server is open + - `authtype_username_password` - use this if your SMTP server requires authentication with a username and password +- Config file format: + ``` + smtp_settings: + authentication_type: authtype_none + ``` + +### smtp_settings.enable_smtp + +Whether SMTP support is enabled or not to send emails from Fleet. + +- Optional setting (boolean) +- Default value: `false` +- Config file format: + ``` + smtp_settings: + enable_smtp: true + ``` + +### smtp_settings.enable_ssl_tls + +Whether to enable SSL/TLS for the SMTP connection. + +- Optional setting (boolean) +- Default value: `true` +- Config file format: + ``` + smtp_settings: + enable_ssl_tls: false + ``` + +### smtp_settings.enable_start_tls + +Whether to detect if TLS is used by the SMTP server and start using it if so. + +- Optional setting (boolean) +- Default value: `true` +- Config file format: + ``` + smtp_settings: + enable_start_tls: false + ``` + +### smtp_settings.password + +Use this password for SMTP authentication when the `authentication_type` is set to `authtype_username_password`. + +- Optional setting (string) +- Default value: "" +- Config file format: + ``` + smtp_settings: + password: supersekretsmtppass + ``` + +### smtp_settings.port + +Use this port to connect to the SMTP server. + +- Optional setting (integer) +- Default value: `587` (the standard SMTP port) +- Config file format: + ``` + smtp_settings: + port: 5870 + ``` + +### smtp_settings.sender_address + +Use this email address as the sender for emails sent by Fleet. + +- Optional setting (string) +- Default value: "" +- Config file format: + ``` + smtp_settings: + sender_address: fleet@example.org + ``` + +### smtp_settings.server + +This is the server hostname for SMTP. + +- Optional setting, required to properly configue SMTP (string) +- Default value: "" +- Config file format: + ``` + smtp_settings: + server: mail.example.org + ``` + +### smtp_settings.user_name + +Use this username for SMTP authentication when the `authentication_type` is set to `authtype_username_password`. + +- Optional setting (string) +- Default value: "" +- Config file format: + ``` + smtp_settings: + user_name: test_user + ``` + +### smtp_settings.verify_ssl_certs + +Whether the SMTP server's SSL certificates should be verified. This can be turned off if self-signed certificates are used by the SMTP server. + +- Optional setting (boolean) +- Default value: `true` +- Config file format: + ``` + smtp_settings: + verify_ssl_certs: false + ``` + + diff --git a/docs/Deploying/Configuration.md b/docs/Deploying/Configuration.md index e5430337ca..518de9e6e5 100644 --- a/docs/Deploying/Configuration.md +++ b/docs/Deploying/Configuration.md @@ -310,16 +310,13 @@ This setting should not usually be used. ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - msyql: - address: localhost:3306 - database: fleet - password: fleet - max_open_conns: 50 - max_idle_conns: 50 - conn_max_lifetime: 50 +mysql: + address: localhost:3306 + database: fleet + password: fleet + max_open_conns: 50 + max_idle_conns: 50 + conn_max_lifetime: 50 ``` #### Redis @@ -613,15 +610,12 @@ A value of 0 means no timeout. ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - redis: - address: localhost:7369 - password: foobar - database: 14 - connect_timeout: 10s - connect_retry_attempts: 2 +redis: + address: localhost:7369 + password: foobar + database: 14 + connect_timeout: 10s + connect_retry_attempts: 2 ``` ### Server @@ -719,15 +713,12 @@ Turning off keepalives has helped reduce outstanding TCP connections in some dep ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - server: - address: 0.0.0.0:443 - password: foobar - cert: /tmp/fleet.crt - key: /tmp/fleet.key - invite_token_validity_period: 1d +server: + address: 0.0.0.0:443 + password: foobar + cert: /tmp/fleet.crt + key: /tmp/fleet.key + invite_token_validity_period: 1d ``` #### Auth @@ -759,12 +750,9 @@ The key size of the salt which is generated when hashing user passwords. ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - auth: - bcrypt_cost: 14 - salt_key_size: 36 +auth: + bcrypt_cost: 14 + salt_key_size: 36 ``` #### App @@ -808,13 +796,10 @@ Determines whether Fleet gets scheduled query statistics from hosts or not. ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - app: - token_key_size: 36 - salt_key_size: 36 - invite_token_validity_period: 1d +app: + token_key_size: 36 + salt_key_size: 36 + invite_token_validity_period: 1d ``` #### License @@ -846,12 +831,9 @@ Whether Fleet should enforce the host limit of the license, if true, attempting ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - license: - key: foobar - enforce_host_limit: false +license: + key: foobar + enforce_host_limit: false ``` #### Session @@ -885,11 +867,8 @@ Valid time units are `s`, `m`, `h`. ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - session: - duration: 4h +session: + duration: 4h ``` #### Osquery @@ -1180,15 +1159,12 @@ The minimum time difference between the software's "last opened at" timestamp re ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - osquery: - host_identifier: uuid - policy_update_interval: 30m - duration: 4h - status_log_plugin: firehose - result_log_plugin: firehose +osquery: + host_identifier: uuid + policy_update_interval: 30m + duration: 4h + status_log_plugin: firehose + result_log_plugin: firehose ``` #### Logging (Fleet server logging) @@ -1246,13 +1222,10 @@ and a negative value to disable storage of errors in Redis. ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - logging: - disable_banner: true - policy_update_interval: 30m - error_retention_period: 1h +logging: + disable_banner: true + policy_update_interval: 30m + error_retention_period: 1h ``` #### Filesystem @@ -1316,16 +1289,13 @@ This flag will cause the rotated logs to be compressed with gzip. ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - osquery: - osquery_status_log_plugin: filesystem - osquery_result_log_plugin: filesystem - filesystem: - status_log_file: /var/log/osquery/status.log - result_log_file: /var/log/osquery/result.log - enable_log_rotation: true +osquery: + osquery_status_log_plugin: filesystem + osquery_result_log_plugin: filesystem +filesystem: + status_log_file: /var/log/osquery/status.log + result_log_file: /var/log/osquery/result.log + enable_log_rotation: true ``` #### Firehose @@ -1432,19 +1402,16 @@ the stream listed: ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - osquery: - osquery_status_log_plugin: firehose - osquery_result_log_plugin: firehose - firehose: - region: ca-central-1 - access_key_id: AKIAIOSFODNN7EXAMPLE - secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY - sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role - status_stream: osquery_status - result_stream: osquery_result +osquery: + osquery_status_log_plugin: firehose + osquery_result_log_plugin: firehose +firehose: + region: ca-central-1 + access_key_id: AKIAIOSFODNN7EXAMPLE + secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY + sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role + status_stream: osquery_status + result_stream: osquery_result ``` #### Kinesis @@ -1556,20 +1523,17 @@ the stream listed: ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - osquery: - osquery_status_log_plugin: kinesis - osquery_result_log_plugin: kinesis - kinesis: - region: ca-central-1 - result_log_file: /var/log/osquery/result.log - access_key_id: AKIAIOSFODNN7EXAMPLE - secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY - sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role - status_stream: osquery_status - result_stream: osquery_result +osquery: + osquery_status_log_plugin: kinesis + osquery_result_log_plugin: kinesis +kinesis: + region: ca-central-1 + result_log_file: /var/log/osquery/result.log + access_key_id: AKIAIOSFODNN7EXAMPLE + secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY + sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role + status_stream: osquery_status + result_stream: osquery_result ``` @@ -1650,7 +1614,7 @@ Name of the Lambda function to write osquery status logs received from clients. - Config file format: ``` lambda: - status_function: statusFunction + status_function: statusFunction ``` The IAM role used to send to Lambda must allow the following permissions on @@ -1680,19 +1644,16 @@ the function listed: ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - osquery: - osquery_status_log_plugin: lamda - osquery_result_log_plugin: lamda - lamda: - region: ca-central-1 - access_key_id: AKIAIOSFODNN7EXAMPLE - secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY - sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role - status_function: statusFunction - result_function: resultFunction +osquery: + osquery_status_log_plugin: lambda + osquery_result_log_plugin: lambda +lambda: + region: ca-central-1 + access_key_id: AKIAIOSFODNN7EXAMPLE + secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY + sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role + status_function: statusFunction + result_function: resultFunction ``` #### PubSub @@ -1767,19 +1728,16 @@ This feature is useful when combined with [subscription filters](https://cloud.g ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - osquery: - osquery_status_log_plugin: pubsub - osquery_result_log_plugin: pubsub - pubsub: - project: my-gcp-project - result_topic: osquery_result - status_topic: osquery_status - sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role - status_function: statusFunction - result_function: resultFunction +osquery: + osquery_status_log_plugin: pubsub + osquery_result_log_plugin: pubsub +pubsub: + project: my-gcp-project + result_topic: osquery_result + status_topic: osquery_status + sts_assume_role_arn: arn:aws:iam::1234567890:role/firehose-role + status_function: statusFunction + result_function: resultFunction ``` #### Kafka REST Proxy logging @@ -1858,16 +1816,13 @@ can be found [here](https://docs.confluent.io/platform/current/kafka-rest/api.ht ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - osquery: - osquery_status_log_plugin: kafkarest - osquery_result_log_plugin: kafkarest - kafkarest: - proxyhost: "https://localhost:8443" - result_topic: osquery_result - status_topic: osquery_status +osquery: + osquery_status_log_plugin: kafkarest + osquery_result_log_plugin: kafkarest +kafkarest: + proxyhost: "https://localhost:8443" + result_topic: osquery_result + status_topic: osquery_status ``` #### S3 file carving backend @@ -1997,16 +1952,13 @@ Minio users must set this to any nonempty value (eg. `minio`), as Minio does not ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - s3: - bucket: some-carve-bucket - prefix: carves-go-here/ - access_key_id: AKIAIOSFODNN7EXAMPLE - secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY - sts_assume_role_arn: arn:aws:iam::1234567890:role/some-s3-role - region: us-east-1 +s3: + bucket: some-carve-bucket + prefix: carves-go-here/ + access_key_id: AKIAIOSFODNN7EXAMPLE + secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY + sts_assume_role_arn: arn:aws:iam::1234567890:role/some-s3-role + region: us-east-1 ``` #### Upgrades @@ -2019,11 +1971,8 @@ If set then `fleet serve` will run even if there are database migrations missing - Environment variable: `FLEET_UPGRADES_ALLOW_MISSING_MIGRATIONS` - Config file format: ``` - apiVersion: v1 - kind: config - spec: - upgrades: - allow_missing_migrations: true + upgrades: + allow_missing_migrations: true ``` #### Vulnerabilities @@ -2140,7 +2089,7 @@ Maximum age of a vulnerability (a CVE) to be considered "recent". The age is cal recent_vulnerability_max_age: 48h ``` -### disable_win_os_vulnerabilities +### disable_win_os_vulnerabilities If using osquery 5.4 or later, Fleet by default will fetch and store all applied Windows updates and use that for detecting Windows vulnerabilities — which might be a writing-intensive process (depending on the number of Windows hosts @@ -2158,13 +2107,10 @@ in your Fleet). Setting this to true will cause Fleet to skip both processes. ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - vulnerabilities: - databases_path: /some/path - current_instance_checks: yes - disable_data_sync: true +vulnerabilities: + databases_path: /some/path + current_instance_checks: yes + disable_data_sync: true ``` #### GeoIP @@ -2180,11 +2126,8 @@ on the Fleet web server. - Environment variable: `FLEET_GEOIP_DATABASE_PATH` - Config file format: ```yaml - apiVersion: v1 - kind: config - spec: - geoip: - database_path: /some/path + geoip: + database_path: /some/path ``` @@ -2269,103 +2212,7 @@ Fleet supports both SP-initiated SAML login and IDP-initiated login however, IDP Fleet supports the SAML Web Browser SSO Profile using the HTTP Redirect Binding. -_**Note: The email used in the SAML Assertion must match a user that already exists in Fleet unless you enable [JIT provisioning](#just-in-time-jit-user-provisioning).**_ - -##### sso_settings.enable_sso - -Configures if single sign-on is enabled. - -- default value: false -- config file format: - ``` - sso_settings: - enable_sso: true - ``` - -##### sso_settings.enable_sso_idp_login - -Allow single sign-on login initiated by identity provider. - -- default value: false -- config file format: - ``` - sso_settings: - enable_sso_idp_login: true - ``` - -##### sso_settings.enable_jit_provisioning - -`Applies only to Fleet Premium` - -Enables [just-in-time user provisioning](#just-in-time-jit-user-provisioning). - -- default value: false -- config file format: - ``` - sso_settings: - enable_jit_provisioning: true - ``` - -##### sso_settings.entity_id - -The required entity ID is a URI that you use to identify Fleet when configuring the identity provider. - -- default value: "" -- config file format: - ``` - sso_settings: - entity_id: "https://example.com" - -##### sso_settings.idp_image_url - -An optional link to an image such as a logo for the identity provider. - -- default value: "" -- config file format: - ``` - sso_settings: - idp_image_url: "https://example.com/logo" - -##### sso_settings.idp_name - -A required human friendly name for the identity provider that will provide single sign-on authentication. - -- default value: "" -- config file format: - ``` - sso_settings: - idp_name: "SimpleSAML" - -##### sso_settings.issuer_uri - -The issuer URI supplied by the identity provider. - -- default value: "" -- config file format: - ``` - sso_settings: - issuer_uri: "https://example.com/saml2/sso-service" - -##### sso_settings.metadata - -Metadata provided by the identity provider. Either metadata or a metadata url must be provided. - -- default value: "" -- config file format: - ``` - sso_settings: - metadata: "" - -##### sso_settings.metadata_url - -A URL that references the identity provider metadata. - -- default value: "" -- config file format: - ``` - sso_settings: - metadata: "https://example.com/saml2/metadata" - +**Note: The email used in the SAML Assertion must match a user that already exists in Fleet unless you enable [JIT provisioning](#just-in-time-jit-user-provisioning).** ### Identity provider (IDP) configuration @@ -2728,15 +2575,12 @@ Minio users must set this to any non-empty value (e.g., `minio`), as Minio does ##### Example YAML ```yaml -apiVersion: v1 -kind: config -spec: - packaging: - s3: - bucket: some-bucket - prefix: installers-go-here/ - access_key_id: AKIAIOSFODNN7EXAMPLE - secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY - sts_assume_role_arn: arn:aws:iam::1234567890:role/some-s3-role - region: us-east-1 +packaging: + s3: + bucket: some-bucket + prefix: installers-go-here/ + access_key_id: AKIAIOSFODNN7EXAMPLE + secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY + sts_assume_role_arn: arn:aws:iam::1234567890:role/some-s3-role + region: us-east-1 ``` diff --git a/docs/Using-Fleet/Fleet-desktop.md b/docs/Using-Fleet/Fleet-desktop.md index a1b9121049..38c57df108 100644 --- a/docs/Using-Fleet/Fleet-desktop.md +++ b/docs/Using-Fleet/Fleet-desktop.md @@ -4,7 +4,7 @@ - [Custom Transparency Link](#custom-transparency-link) - [Securing Fleet Desktop](#securing-fleet-desktop) -Fleet Desktop is a menubar icon available on macOS, Windows, and Linux. +Fleet Desktop is a menu bar icon available on macOS, Windows, and Linux. At its core, Fleet Desktop gives your end users visibility into the security posture of their machine. This unlocks two key benefits: * Self-remediation: end users can see which policies they are failing and resolution steps, reducing the need for IT and security teams to intervene @@ -25,8 +25,10 @@ For organizations with complex security postures, they can direct end users to a > The custom transparency link is only available for users with Fleet Premium -To turn on the custom transparency link, in the Fleet GUI, click on your profile in the top right, select "Settings." -In the settings page, under "Organization Settings" select "Fleet Desktop." Use the "Custom transparency URL" text input to specify the custom URL. +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](../Using-Fleet/configuration-files/README.md#fleet-desktop-settings) documentation. ## Securing Fleet Desktop diff --git a/docs/Using-Fleet/configuration-files/README.md b/docs/Using-Fleet/configuration-files/README.md index 2d17822601..bde6d34c40 100644 --- a/docs/Using-Fleet/configuration-files/README.md +++ b/docs/Using-Fleet/configuration-files/README.md @@ -161,7 +161,7 @@ spec: ## Teams -`Applies only to Fleet Premium` +**Applies only to Fleet Premium**. The following is an example configuration file for a Team. @@ -197,9 +197,45 @@ spec: - secret: RzTlxPvugG4o4O5IKS/HqEDJUmI1hwBoffff - secret: JZ/C/Z7ucq22dt/zjx2kEuDBN0iLjqfz ``` + +### Team settings + +#### Team agent options + +The team agent options specify options that only apply to this team. When team-specific agent options have been specified, the agent options specified at the organization level are ignored for this team. + +The documentation for this section is identical to the [Agent options](#agent-options) documentation for the organization settings, except that the YAML section where it is set must be as follows. (Note the `kind: team` key and the location of the `agent_options` key under `team` must have a `name` key to identify the team to configure.) + +```yaml +apiVersion: v1 +kind: team +spec: + team: + name: Client Platform Engineering + agent_options: + # the team-specific options go here +``` + +#### Secrets + +The `secrets` section provides the list of enroll secrets that will be valid for this team. If the section is missing, the existing secrets are left unmodified. Otherwise, they are replaced with this list of secrets for this team. + +- Optional setting (array of dictionaries) +- Default value: none (empty) +- Config file format: + ``` + team: + name: Client Platform Engineering + secrets: + - secret: RzTlxPvugG4o4O5IKS/HqEDJUmI1hwBoffff + - secret: JZ/C/Z7ucq22dt/zjx2kEuDBN0iLjqfz + ``` + ## Organization settings -The following file describes organization settings applied to the Fleet server. +The `config` YAML file controls Fleet's organization settings. + +The following example file shows the default organization settings. ```yaml apiVersion: v1 @@ -216,77 +252,633 @@ spec: distributed_interval: 10 distributed_plugin: tls distributed_tls_max_attempts: 3 - distributed_tls_read_endpoint: /api/osquery/distributed/read - distributed_tls_write_endpoint: /api/osquery/distributed/write logger_plugin: tls logger_tls_endpoint: /api/osquery/log logger_tls_period: 10 pack_delimiter: / overrides: {} - host_expiry_settings: - host_expiry_enabled: true - host_expiry_window: 10 features: - # "additional" information to collect from hosts along with the host - # details. This information will be updated at the same time as other host - # details and is returned by the API when host objects are returned. Users - # must take care to keep the data returned by these queries small in - # order to mitigate potential performance impacts on the Fleet server. - additional_queries: - time: SELECT * FROM time - macs: SELECT mac FROM interface_details + enable_host_users: true + enable_software_inventory: true + fleet_desktop: + transparency_url: https://fleetdm.com/transparency + host_expiry_settings: + host_expiry_enabled: false + host_expiry_window: 0 + integrations: + jira: null + zendesk: null org_info: - org_logo_url: "https://example.org/logo.png" - org_name: Example Org + org_logo_url: "" + org_name: Fleet server_settings: - server_url: https://fleet.example.org:8080 + deferred_save_host: false + enable_analytics: true + live_query_disabled: false + server_url: "" smtp_settings: authentication_method: authmethod_plain authentication_type: authtype_username_password - domain: example.org - enable_smtp: true + domain: "" + enable_smtp: false enable_ssl_tls: true enable_start_tls: true - password: supersekretsmtppass + password: "" port: 587 - sender_address: fleet@example.org - server: mail.example.org - user_name: test_user + sender_address: "" + server: "" + user_name: "" verify_ssl_certs: true + sso_settings: + enable_jit_provisioning: false + enable_sso: false + enable_sso_idp_login: false + entity_id: "" + idp_image_url: "" + idp_name: "" + issuer_uri: "" + metadata: "" + metadata_url: "" vulnerability_settings: databases_path: "" webhook_settings: + failing_policies_webhook: + destination_url: "" + enable_failing_policies_webhook: false + host_batch_size: 0 + policy_ids: null host_status_webhook: - enable_host_status_webhook: true - destination_url: https://server.com - host_percentage: 5 - days_count: 7 + days_count: 0 + destination_url: "" + enable_host_status_webhook: false + host_percentage: 0 + interval: 24h + vulnerabilities_webhook: + destination_url: "" + enable_vulnerabilities_webhook: false + host_batch_size: 0 +``` + +### Settings + +All possible settings are organized below by section. + +Each section's key must be one level below the `spec` key, indented with spaces (not `` charaters) as required by the YAML format. + +For example, when adding the `host_expiry_settings.host_expiry_enabled` setting, you'd specify the `host_expiry_settings` section one level below the `spec` key: + +```yaml +apiVersion: v1 +kind: config +spec: + host_expiry_settings: + host_expiry_enabled: true +``` + +#### Features + +The `features` section of the configuration YAML lets you define what predefined queries are sent to the hosts and later on processed by Fleet for different functionalities. + +> Note: this section used to be named `host_settings`, but was renamed in Fleet v4.20.0, +> `host_settings` is still supported for backwards compatibility. + +##### features.additional_queries + +This is the additional information to collect from hosts along with the host details. This information will be updated at the same time as other host details and is returned by the API when host objects are returned. Users must take care to keep the data returned by these queries small in order to mitigate potential performance impacts on the Fleet server. + +- Optional setting (dictionary of key-value strings) +- Default value: none (empty) +- Config file format: + ``` + features: + additional_queries: + time: SELECT * FROM time + macs: SELECT mac FROM interface_details + ``` +- Deprecated config file format: + ``` + host_settings: + additional_queries: + time: SELECT * FROM time + macs: SELECT mac FROM interface_details + ``` + +##### features.enable_host_users + +Whether or not Fleet sends the query needed to gather user-related data from hosts. + +- Optional setting (boolean) +- Default value: `true` +- Config file format: + ``` + features: + enable_host_users: false + ``` +- Deprecated config file format: + ``` + host_settings: + enable_host_users: false + ``` + +##### features.enable_software_inventory + +Whether or not Fleet sends the query needed to gather the list of software installed on hosts, along with other metadata. + +- Optional setting (boolean) +- Default value: `true` +- Config file format: + ``` + features: + enable_software_inventory: false + ``` +- Deprecated config file format: + ``` + host_settings: + enable_software_inventory: false + ``` + +#### Fleet Desktop settings + +For more information about Fleet Desktop, see [Fleet Desktop's documentation](../../Using-Fleet/Fleet-desktop.md). + +##### fleet_desktop.transparency_url + +**Available in Fleet Premium**. Direct users of Fleet Desktop to a custom transparency URL page. + +- Optional setting (string) +- Default value: Fleet's default transparency URL ("https://fleetdm.com/transparency") +- Config file format: + ``` + fleet_desktop: + transparency_url: "https://example.org/transparency" + ``` + +#### Host Expiry settings + +The `host_expiry` section lets you define if and when hosts should be removed from Fleet if they have not checked in. Once a host has been removed from Fleet, it will need to re-enroll with a valid `enroll_secret` to connect to your Fleet instance. + +##### host_expiry_settings.host_expiry_enabled + +Whether offline hosts' expiration is enabled. If `host_expiry_enabled` is set to `true`, Fleet allows automatic cleanup of hosts that have not communicated with Fleet in some number of days. + +- Optional setting (boolean) +- Default value: `false` +- Config file format: + ``` + host_expiry_settings: + host_expiry_enabled: true + ``` + +##### host_expiry_settings.host_expiry_window + +If a host has not communicated with Fleet in the specified number of days, it will be removed. + +- Optional setting (integer) +- Default value: `0` (must be > 0 when enabling host expiry) +- Config file format: + ``` + host_expiry_settings: + host_expiry_window: 10 + ``` + +#### Integrations + +For more information about integrations and Fleet automations in general, see the [Automations documentation](../../Using-Fleet/Automations.md). Only one automation can be enabled for a given automation type (e.g., for failing policies, only one of the webhooks, the Jira integration, or the Zendesk automation can be enabled). + +It's recommended to use the Fleet UI to configure integrations since secret credentials (in the form of an API token) must be provided. See the [Automations documentation](../../Using-Fleet/Automations.md) for the UI configuration steps. + +#### Organization information + +##### org_info.org_name + +The name of the organization. + +- Required setting (string) +- Default value: none (provided during Fleet setup) +- Config file format: + ``` + org_info: + org_name: Fleet + ``` + +##### org_info.org_logo_url + +The URL of the logo of the organization. + +- Optional setting (string) +- Default value: none (uses Fleet's logo) +- Config file format: + ``` + org_info: + org_logo_url: https://example.com/logo.png + ``` + +#### Server settings + +##### server_settings.debug_host_ids + +There's a lot of information coming from hosts, but it's sometimes useful to see exactly what a host is returning in order +to debug different scenarios. + +For example, let's say the hosts with ids 342 and 98 are not behaving as you expect in Fleet. You can enable verbose +logging with the following configuration: + +```yaml +--- +apiVersion: v1 +kind: config +spec: + server_settings: + debug_host_ids: + - 342 + - 98 +``` + +Once you have collected the logs, you can easily disable the debug logging by applying the following configuration: + +```yaml +--- +apiVersion: v1 +kind: config +spec: + server_settings: + debug_host_ids: [] +``` + +> **Warning:** This will potentially log a lot of data. Some of that data might be private. Please verify it before posting it +in a public channel or a GitHub issue. + +- Optional setting (array of integers) +- Default value: empty +- Config file format: + ``` + server_settings: + debug_host_ids: + - 342 + - 98 + ``` + +##### server_settings.deferred_save_host + +Whether saving host-related information is done synchronously in the HTTP handler of the host's request, or asynchronously. This can provide better performance in deployments with many hosts. Note that this is an **experimental feature**. + +- Optional setting (boolean) +- Default value: `false` +- Config file format: + ``` + server_settings: + deferred_save_host: true + ``` + +##### server_settings.enable_analytics + +If sending usage analytics is enabled or not. + +- Optional setting (boolean) +- Default value: `true` +- Config file format: + ``` + server_settings: + enable_analytics: false + ``` + +##### server_settings.live_query_disabled + +If the live query feature is disabled or not. + +- Optional setting (boolean) +- Default value: `false` +- Config file format: + ``` + server_settings: + live_query_disabled: true + ``` + +##### server_settings.server_url + +The base URL of the fleet server, including the scheme (e.g. "https://"). + +- Required setting (string) +- Default value: none (provided during Fleet setup) +- Config file format: + ``` + server_settings: + server_url: https://fleet.example.org:8080 + ``` + +#### SMTP settings + +It's recommended to use the Fleet UI to configure SMTP since a secret password must be provided. Navigate to **Settings -> Organization settings -> SMTP Options** to proceed with this configuration. + +#### SSO Settings + +For additional information on SSO configuration, including just-in-time (JIT) user provisioning, creating SSO users in Fleet, and identity providers configuration, see [Configuring single sign-on (SSO)](../../Deploying/Configuration.md#configuring-single-sign-on-sso). + +##### sso_settings.enable_jit_provisioning + +**Available in Fleet Premium**. Enables [just-in-time user provisioning](../../Deploying/Configuration.md#just-in-time-jit-user-provisioning). + +- Optional setting (boolean) +- Default value: `false` +- Config file format: + ``` + sso_settings: + enable_jit_provisioning: true + ``` + +##### sso_settings.enable_sso + +Configures if single sign-on is enabled. + +- Optional setting (boolean) +- Default value: `false` +- Config file format: + ``` + sso_settings: + enable_sso: true + ``` + +##### sso_settings.enable_sso_idp_login + +Allow single sign-on login initiated by identity provider. + +- Optional setting (boolean) +- Default value: `false` +- Config file format: + ``` + sso_settings: + enable_sso_idp_login: true + ``` + +##### sso_settings.entity_id + +The required entity ID is a Uniform Resource Identifier (URI) that you use to identify Fleet when configuring the identity provider. It must exactly match the Entity ID field used in identity provider configuration. + +- Required setting if SSO is enabled, must have at least 5 characters (string) +- Default value: "" +- Config file format: + ``` + sso_settings: + entity_id: "https://example.com" + ``` + +##### sso_settings.idp_image_url + +An optional link to an image such as a logo for the identity provider. + +- Optional setting (string) +- Default value: "" +- Config file format: + ``` + sso_settings: + idp_image_url: "https://example.com/logo" + ``` + +##### sso_settings.idp_name + +A required human-friendly name for the identity provider that will provide single sign-on authentication. + +- Required setting if SSO is enabled (string) +- Default value: "" +- Config file format: + ``` + sso_settings: + idp_name: "SimpleSAML" + ``` + +##### sso_settings.issuer_uri + +The issuer URI supplied by the identity provider. + +- Optional setting (string) +- Default value: "" +- Config file format: + ``` + sso_settings: + issuer_uri: "https://example.com/saml2/sso-service" + ``` + +##### sso_settings.metadata + +Metadata (in XML format) provided by the identity provider. + +- Optional setting, either `metadata` or `metadata_url` must be set if SSO is enabled, but not both (string). +- Default value: "". +- Config file format: + ``` + sso_settings: + metadata: " ... /md:EntityDescriptor>" + ``` + +##### sso_settings.metadata_url + +A URL that references the identity provider metadata. + +- Optional setting, either `metadata` or `metadata_url` must be set if SSO is enabled, but not both (string). +- Default value: "". +- Config file format: + ``` + sso_settings: + metadata_url: https://idp.example.org/idp-meta.xml + ``` + +#### Vulnerability settings + +##### vulnerability_settings.databases_path + +Path to a directory on the local filesystem (accessible to the Fleet server) where the various vulnerability databases will be stored. + +- Optional setting, must be set to enable vulnerability detection (string). +- Default value: "". +- Config file format: + ``` + vulnerability_settings: + databases_path: "/path/to/dir" + ``` + +#### Webhook settings + +For more information about webhooks and Fleet automations in general, see the [Automations documentation](../../Using-Fleet/Automations.md). + +##### webhook_settings.interval + +The interval at which to check for webhook conditions. This value currently configures both the host status and failing policies webhooks, but not the recent vulnerabilities webhook. (See the [Recent vulnerabilities section](#recent-vulnerabilities) for details.) + +- Optional setting (time duration as a string) +- Default value: `24h` +- Config file format: + ``` + webhook_settings: + interval: "12h" + ``` + +##### Failing policies + +The following options allow the configuration of a webhook that will be triggered if selected policies are not passing for some hosts. + +###### webhook_settings.failing_policies_webhook.destination_url + +The URL to `POST` to when the condition for the webhook triggers. + +- Optional setting, required if webhook is enabled (string). +- Default value: "". +- Config file format: + ``` + webhook_settings: + failing_policies_webhook: + destination_url: "https://example.org/webhook_handler" + ``` + +###### webhook_settings.failing_policies_webhook.enable_failing_policies_webhook + +Defines whether to enable the failing policies webhook. Note that currently, if the failing policies webhook and the `osquery.enable_async_host_processing` options are set, some failing policies webhooks could be missing. Some transitions from succeeding to failing or vice-versa could happen without triggering a webhook request. + +- Optional setting (boolean). +- Default value: `false`. +- Config file format: + ``` + webhook_settings: failing_policies_webhook: enable_failing_policies_webhook: true - destination_url: https://server.com + ``` + +###### webhook_settings.failing_policies_webhook.host_batch_size + +Maximum number of hosts to batch on `POST` requests. A value of `0`, the default, means no batching. All hosts failing a policy will be sent on one `POST` request. + +- Optional setting (integer). +- Default value: `0`. +- Config file format: + ``` + webhook_settings: + failing_policies_webhook: + host_batch_size: 100 + ``` + +###### webhook_settings.failing_policies_webhook.policy_ids + +The IDs of the policies for which the webhook will be enabled. + +- Optional setting (array of integers). +- Default value: empty. +- Config file format: + ``` + webhook_settings: + failing_policies_webhook: policy_ids: - 1 - 2 - 3 - host_batch_size: 0 - interval: 1m0s - sso_settings: - enable_sso: false - entity_id: 1234567890 - idp_image_url: https://idp.example.org/logo.png - idp_name: IDP Vendor 1 - issuer_uri: https://idp.example.org/SAML2/SSO/POST - metadata: " ... /md:EntityDescriptor>" - metadata_url: https://idp.example.org/idp-meta.xml -``` + ``` -### Agent options +##### Host status + +The following options allow the configuration of a webhook that will be triggered if the specified percentage of hosts are offline for the specified amount of time. + +###### webhook_settings.host_status_webhook.days_count + +Number of days that hosts need to be offline for to count as part of the percentage. + +- Optional setting, required if webhook is enabled (integer). +- Default value: `0`. +- Config file format: + ``` + webhook_settings: + host_status_webhook: + days_count: 5 + ``` + +###### webhook_settings.host_status_webhook.destination_url + +The URL to `POST` to when the condition for the webhook triggers. + +- Optional setting, required if webhook is enabled (string). +- Default value: "". +- Config file format: + ``` + webhook_settings: + host_status_webhook: + destination_url: "https://example.org/webhook_handler" + ``` + +###### webhook_settings.host_status_webhook.enable_host_status_webhook + +Defines whether the webhook check for host status will run or not. + +- Optional setting (boolean). +- Default value: `false`. +- Config file format: + ``` + webhook_settings: + host_status_webhook: + enable_host_status_webhook: true + ``` + +###### webhook_settings.host_status_webhook.host_percentage + +The percentage of hosts that need to be offline to trigger the webhook. + +- Optional setting, required if webhook is enabled (float). +- Default value: `0`. +- Config file format: + ``` + webhook_settings: + host_status_webhook: + host_percentage: 10 + ``` + +##### Recent vulnerabilities + +The following options allow the configuration of a webhook that will be triggered if recently published vulnerabilities are detected and there are affected hosts. A vulnerability is considered recent if it has been published in the last 30 days (based on the National Vulnerability Database, NVD). + +Note that the recent vulnerabilities webhook is not checked at `webhook_settings.interval` like other webhooks. It is checked as part of the vulnerability processing and runs at the `vulnerabilities.periodicity` interval specified in the [fleet configuration](../../Deploying/Configuration.md#periodicity). + +###### webhook_settings.vulnerabilities_webhook.destination_url + +The URL to `POST` to when the condition for the webhook triggers. + +- Optional setting, required if webhook is enabled (string). +- Default value: "". +- Config file format: + ``` + webhook_settings: + vulnerabilities_webhook: + destination_url: "https://example.org/webhook_handler" + ``` + +###### webhook_settings.vulnerabilities_webhook.enable_vulnerabilities_webhook + +Defines whether to enable the vulnerabilities webhook. + +- Optional setting (boolean). +- Default value: `false`. +- Config file format: + ``` + webhook_settings: + vulnerabilities_webhook: + enable_vulnerabilities_webhook: true + ``` + +###### webhook_settings.vulnerabilities_webhook.host_batch_size + +Maximum number of hosts to batch on `POST` requests. A value of `0`, the default, means no batching. All hosts affected will be sent on one `POST` request. + +- Optional setting (integer). +- Default value: `0`. +- Config file format: + ``` + webhook_settings: + vulnerabilities_webhook: + host_batch_size: 100 + ``` + +#### Agent options The `agent_options` key describes options returned to osqueryd when it checks for configuration. See the [osquery documentation](https://osquery.readthedocs.io/en/stable/deployment/configuration/#options) for the available options. Existing options will be over-written by the application of this file. > In Fleet v4.0.0, "osquery options" are renamed to "agent options" and are now configured using the organization settings (config) configuration file. [Check out out the Fleet v3 documentation](https://github.com/fleetdm/fleet/blob/3.13.0/docs/1-Using-Fleet/2-fleetctl-CLI.md#update-osquery-options) if you're using an older version of Fleet. -#### Overrides option +##### Overrides option The `overrides` key allows you to segment hosts, by their platform, and supply these groups with unique osquery configuration options. When you choose to use the overrides option for a specific platform, all options specified in the default configuration will be ignored for that platform. @@ -368,7 +960,7 @@ spec: # ... ``` -### Auto table construction +##### Auto table construction You can use Fleet to query local SQLite databases as tables. For more information on creating ATC configuration from a SQLite database, check out the [Automatic Table Construction section](https://osquery.readthedocs.io/en/stable/deployment/configuration/#automatic-table-construction) of the osquery documentation. @@ -397,7 +989,7 @@ spec: - "last_modified" ``` -### YARA configuration +##### YARA configuration You can use Fleet to configure the `yara` and `yara_events` osquery tables. Fore more information on YARA configuration and continuous monitoring using the `yara_events` table, check out the [YARA-based scanning with osquery section](https://osquery.readthedocs.io/en/stable/deployment/yara/) of the osquery documentation. @@ -427,108 +1019,6 @@ spec: overrides: {} ``` -### SMTP authentication +#### Advanced configuration -> **Warning:** Be careful not to store your SMTP credentials in source control. It is recommended to set the password through the web UI or `fleetctl` and then remove the line from the checked in version. Fleet will leave the password as-is if the field is missing from the applied configuration. - -The following options are available when configuring SMTP authentication: - -- `smtp_settings.authentication_type` - - `authtype_none` - use this if your SMTP server is open - - `authtype_username_password` - use this if your SMTP server requires authentication with a username and password -- `smtp_settings.authentication_method` - required with authentication type `authtype_username_password` - - `authmethod_cram_md5` - - `authmethod_login` - - `authmethod_plain` - -### Webhooks - -- `webhook_settings.interval`: the interval at which to check for webhook conditions. Default: 24h. - -#### Host status - -The following options allow the configuration of a webhook that will be triggered if the specified percentage of hosts -are offline for the specified amount of time. - -- `webhook_settings.host_status_webhook.enable_host_status_webhook`: true or false. Defines whether the check for host status will run or not. -- `webhook_settings.host_status_webhook.destination_url`: the URL to POST to when the condition for the webhook triggers. -- `webhook_settings.host_status_webhook.host_percentage`: the percentage of hosts that need to be offline -- `webhook_settings.host_status_webhook.days_count`: amount of days that hosts need to be offline for to count as part of the percentage. - -#### Failing policies - -The following options allow the configuration of a webhook that will be triggered if selected policies are not passing for some hosts. - -- `webhook_settings.failing_policies_webhook.enable_failing_policies_webhook`: true or false. Defines whether to enable the failing policies webhook. Note that currently, if the failing policies webhook *and* the `osquery.enable_async_host_processing` options are set, some failing policies webhooks could be missing (some transitions from succeeding to failing or vice-versa could happen without triggering a webhook request). -- `webhook_settings.failing_policies_webhook.destination_url`: the URL to POST to when the condition for the webhook triggers. -- `webhook_settings.failing_policies_webhook.policy_ids`: the IDs of the policies for which the webhook will be enabled. -- `webhook_settings.failing_policies_webhook.host_batch_size`: Maximum number of hosts to batch on POST requests. A value of `0`, the default, means no batching, all hosts failing a policy will be sent on one POST request. - -#### Recent vulnerabilities - -The following options allow the configuration of a webhook that will be triggered if recently published vulnerabilities are detected and there are affected hosts. A vulnerability is considered recent if it has been published in the last 2 days (based on the National Vulnerability Database, NVD). - -- `webhook_settings.vulnerabilities_webhook.enable_vulnerabilities_webhook`: true or false. Defines whether to enable the vulnerabilities webhook. -- `webhook_settings.vulnerabilities_webhook.destination_url`: the URL to POST to when the condition for the webhook triggers. -- `webhook_settings.vulnerabilities_webhook.host_batch_size`: Maximum number of hosts to batch on POST requests. A value of `0`, the default, means no batching, all hosts affected will be sent on one POST request. - -Note that the recent vulnerabilities webhook is not checked at `webhook_settings.interval` like other webhooks - it is checked as part of the vulnerability processing and runs at the `vulnerabilities.periodicity` interval specified in the fleet configuration. - -### Debug host - -There's a lot of information coming from hosts, but it's sometimes useful to see exactly what a host is returning in order -to debug different scenarios. - -So for example, let's say the hosts with ids 342 and 98 are not behaving as you expect in Fleet, you can enable verbose -logging with the following configuration: - -```yaml ---- -apiVersion: v1 -kind: config -spec: - server_settings: - debug_host_ids: - - 342 - - 98 -``` - -Once you have collected the logs, you can easily disable the debug logging by applying the following configuration: - -```yaml ---- -apiVersion: v1 -kind: config -spec: - server_settings: - debug_host_ids: [] -``` - -> **Warning:** This will potentially log a lot of data. Some of that data might be private. Please verify it before posting it. -in a public channel or a GitHub issue. - -## Host Expiry Settings - -The `host_expiry` section lets you define if and when hosts should be removed from Fleet if they have not checked in. Once a host has been removed from Fleet, it will need to re-enroll with a valid `enroll_secret` to connect to your Fleet instance. - -### Host Expiry Enabled - -If `host_expiry_enabled` is set to `true`, Fleet allows automatic cleanup of hosts that have not communicated with Fleet in some number of days. - -### Host Expiry Window - -If a host has not communicated with Fleet in the specified number of days, it will be removed. - -## Features - - - - -The `features` section of the configuration YAML lets you define what predefined queries are sent to the hosts and -later on processed by Fleet for different functionalities. - -- `features.enable_host_users`: boolean value that, when enabled, Fleet will send the query needed to gather user data -- `features.enable_software_inventory`: boolean value that when enabled Fleet will send the query needed to gather the list of software installed along with other metadata - -> Note: this section used to be named `host_settings`, but was renamed in Fleet v4.20.0, -> `host_settings` is still supported for backwards compatibility. +> **Note:** More settings are included in the [contributor documentation](../../Contributing/Configuration-for-contributors.md). It's possible, although not recommended, to configure these settings in the YAML configuration file. diff --git a/ee/server/service/teams.go b/ee/server/service/teams.go index afa6492da6..3b0d4483a4 100644 --- a/ee/server/service/teams.go +++ b/ee/server/service/teams.go @@ -144,7 +144,10 @@ func (svc *Service) ModifyTeamAgentOptions(ctx context.Context, teamID uint, opt if options != nil { team.Config.AgentOptions = &options + // TODO(mna): validate agent options before saving } else { + // TODO(mna): in NewTeam, we set AgentOptions to the global config, why + // do we allow setting it to nil here? team.Config.AgentOptions = nil } @@ -438,6 +441,7 @@ func (svc Service) ApplyTeamSpecs(ctx context.Context, specs []*fleet.TeamSpec) } func (svc Service) createTeamFromSpec(ctx context.Context, spec *fleet.TeamSpec, defaults *fleet.AppConfig, secrets []*fleet.EnrollSecret) (*fleet.Team, error) { + // TODO(mna): validate agent options before saving agentOptions := spec.AgentOptions if agentOptions == nil { agentOptions = defaults.AgentOptions @@ -466,6 +470,7 @@ func (svc Service) createTeamFromSpec(ctx context.Context, spec *fleet.TeamSpec, func (svc Service) editTeamFromSpec(ctx context.Context, team *fleet.Team, spec *fleet.TeamSpec, secrets []*fleet.EnrollSecret) error { team.Name = spec.Name + // TODO(mna): validate agent options before saving, and we allow nil here instead of defaulting to global? team.Config.AgentOptions = spec.AgentOptions // replace (don't merge) the features with the new ones, using a config diff --git a/server/datastore/mysql/app_configs.go b/server/datastore/mysql/app_configs.go index 670d5c5376..ff07c80dfc 100644 --- a/server/datastore/mysql/app_configs.go +++ b/server/datastore/mysql/app_configs.go @@ -14,6 +14,8 @@ import ( func (ds *Datastore) NewAppConfig(ctx context.Context, info *fleet.AppConfig) (*fleet.AppConfig, error) { info.ApplyDefaultsForNewInstalls() + // TODO(mna): to ensure we don't accidentally store invalid initial config, we + // should go through the same config/agent options validation here before saving. if err := ds.SaveAppConfig(ctx, info); err != nil { return nil, ctxerr.Wrap(ctx, err, "new app config") } diff --git a/server/fleet/app.go b/server/fleet/app.go index e7f103ca8e..f63647ede8 100644 --- a/server/fleet/app.go +++ b/server/fleet/app.go @@ -30,16 +30,6 @@ const ( MaskedPassword = "********" ) -// ModifyAppConfigRequest contains application configuration information -// sent from front end and used to change app config elements. -type ModifyAppConfigRequest struct { - // TestSMTP is this is set to true, the SMTP configuration will be tested - // with the results of the test returned to caller. No config changes - // will be applied. - TestSMTP bool `json:"test_smtp"` - AppConfig AppConfig `json:"app_config"` -} - // SSOSettings wire format for SSO settings type SSOSettings struct { // EntityID is a uri that identifies this service provider diff --git a/server/service/appconfig.go b/server/service/appconfig.go index c643e9d8bd..79ae698b91 100644 --- a/server/service/appconfig.go +++ b/server/service/appconfig.go @@ -325,6 +325,8 @@ func (svc *Service) ModifyAppConfig(ctx context.Context, p []byte) (*fleet.AppCo appConfig.FleetDesktop.TransparencyURL = "" } + // TODO(mna): validate app config / agent options before saving + if err := svc.ds.SaveAppConfig(ctx, appConfig); err != nil { return nil, err }