diff --git a/reference/fleet/fleet-settings.md b/reference/fleet/fleet-settings.md index 4584ed3ac6..1d31e858ed 100644 --- a/reference/fleet/fleet-settings.md +++ b/reference/fleet/fleet-settings.md @@ -18,7 +18,7 @@ On the **Settings** tab in **Fleet**, you can configure global settings availabl ## {{fleet-server}} host settings [fleet-server-hosts-setting] -Click **Edit hosts** and specify the host URLs your {{agent}}s will use to connect to a {{fleet-server}}. +Select **Edit hosts** and specify the host URLs your {{agent}}s will use to connect to a {{fleet-server}}. ::::{tip} If the **Edit hosts** option is grayed out, {{fleet-server}} hosts are configured outside of {{fleet}}. For more information, refer to [{{fleet}} settings in {{kib}}](kibana://reference/configuration-reference/fleet-settings.md). @@ -49,7 +49,7 @@ The exposed ports must be open for ingress and egress in the firewall and networ :::: -Specify multiple URLs (click **Add row**) to scale out your deployment and provide automatic failover. If multiple URLs exist, {{fleet}} shows the first provided URL for enrollment purposes. Enrolled {{agent}}s will connect to the URLs in round robin order until they connect successfully. +Specify multiple URLs (select **Add row**) to scale out your deployment and provide automatic failover. If multiple URLs exist, {{fleet}} shows the first provided URL for enrollment purposes. Enrolled {{agent}}s will connect to the URLs in round robin order until they connect successfully. When a {{fleet-server}} is added or removed from the list, all agent policies are updated automatically. @@ -76,8 +76,8 @@ The {{ecloud}} internal output is locked and cannot be edited. This output is us To add or edit an output: -1. Go to **{{fleet}} → Settings**. -2. Under **Outputs**, click **Add output** or **Edit**. +1. Go to **{{fleet}} > Settings**. +2. Under **Outputs**, select **Add output** or **Edit**. :::{image} images/fleet-add-output-button.png :alt: {{fleet}} Add output button @@ -93,7 +93,7 @@ To add or edit an output: * [Kafka output settings](/reference/fleet/kafka-output-settings.md) * [Remote {{es}} output](/reference/fleet/remote-elasticsearch-output.md) -5. Click **Save and apply settings**. +5. Select **Save and apply settings**. ::::{tip} If the options for editing an output are grayed out, outputs are configured outside of {{fleet}}. For more information, refer to [{{fleet}} settings in {{kib}}](kibana://reference/configuration-reference/fleet-settings.md). @@ -109,12 +109,42 @@ For {{agent}}s that cannot access the internet, you can specify agent binary dow To add or edit the source of binary downloads: -1. Go to **{{fleet}} → Settings**. -2. Under **Agent Binary Download**, click **Add agent binary source** or **Edit**. +1. Go to **{{fleet}} > Settings**. +2. Under **Agent Binary Download**, select **Add agent binary source** or **Edit**. 3. Set the agent binary source name. 4. For **Host**, specify the address where you are hosting the artifacts repository. 5. (Optional) To make this location the default, select **Make this host the default for all agent policies**. {{agent}}s use the default location if you don’t select a different agent binary source in the agent policy. +## Agent binary download settings [fleet-agent-binary-download-settings] + +{{agent}}s must be able to access the {{artifact-registry}} to download binaries during upgrades. By default {{agent}}s download artifacts from the artifact registry at `https://artifacts.elastic.co/downloads/`. + +For {{agent}}s that cannot access the internet, you can specify agent binary download settings, and then configure agents to download their artifacts from the alternate location. For more information about running {{agent}}s in a restricted environment, refer to [Air-gapped environments](/reference/fleet/air-gapped.md). + +To add or edit the source of binary downloads: + +1. Go to **{{fleet}} > Settings**. +2. Under **Agent Binary Download**, select **Add agent binary source** or **Edit**. +3. Set the agent binary source name. +4. For **Host**, specify the address where you are hosting the artifacts repository. +5. (Optional) To make this location the default, select **Make this host the default for all agent policies**. {{agent}}s use the default location if you don’t select a different agent binary source in the agent policy. + + +### Configure SSL for binary downloads [agent-binary-ssl] +```{applies_to} + stack: ga 9.1 +``` + +You can optionally secure connections to your binary download source using TLS. These settings correspond to the certificates the agent uses when connecting to the download host. + +The following SSL options are available when adding or editing an agent binary source: + +| **UI Field** | **Purpose** | +|------------------------|------------------------------------------------------------------------------| +| Certificate authorities | Trusted CAs for verifying the server certificate. | +| Certificate | Client certificate to use for mTLS authentication with the download host. | +| Certificate key | Private key associated with the client certificate. | + ## Proxies [proxy-settings] @@ -129,5 +159,5 @@ Note that this option can also be enabled by adding the `xpack.fleet.enableDelet To enable automatic deletion of unenrolled agents: -1. Go to **{{fleet}} → Settings**. +1. Go to **{{fleet}} > Settings**. 2. Under **Advanced Settings**, enable the **Delete unenrolled agents** option. diff --git a/reference/fleet/secure-connections.md b/reference/fleet/secure-connections.md index 0165957493..305879f0f8 100644 --- a/reference/fleet/secure-connections.md +++ b/reference/fleet/secure-connections.md @@ -42,7 +42,6 @@ When you run {{agent}} with the {{elastic-defend}} integration, the [TLS certifi :::: - ## Generate a custom certificate and private key for {{fleet-server}} [generate-fleet-server-certs] This section describes how to use the `certutil` tool provided by {{es}}, but you can use whatever process you typically use to generate PEM-formatted certificates. @@ -84,8 +83,11 @@ This section describes how to use the `certutil` tool provided by {{es}}, but yo Store the files in a secure location. You’ll need these files later to encrypt traffic between {{agent}}s and {{fleet-server}}. +## Configure SSL/TLS using CLI [fleet-server-ssl-cli-settings] + +Use the CLI to configure SSL or TLS when installing or enrolling {{fleet-server}}. This method gives you granular control over certificate paths, verification modes, and authentication behavior. -## Encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}} [_encrypt_traffic_between_agents_fleet_server_and_es] +### Encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}} [_encrypt_traffic_between_agents_fleet_server_and_es] {{fleet-server}} needs a CA certificate or the CA fingerprint to connect securely to {{es}}. It also needs to expose a {{fleet-server}} certificate so other {{agent}}s can connect to it securely. @@ -101,7 +103,7 @@ For the steps in this section, imagine you have the following files: To encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}}: 1. Configure {{fleet}} settings. These settings are applied to all {{fleet}}-managed {{agent}}s. -2. In {{kib}}, open the main menu, then click **Management > {{fleet}} > Settings**. +2. In {{kib}}, open the main menu, then select **Management > {{fleet}} > Settings**. 1. Under **{{fleet-server}} hosts**, specify the URLs {{agent}}s will use to connect to {{fleet-server}}. For example, [https://192.0.2.1:8220](https://192.0.2.1:8220), where 192.0.2.1 is the host IP where you will install {{fleet-server}}. @@ -109,7 +111,7 @@ To encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}}: For host settings, use the `https` protocol. DNS-based names are also allowed. :::: - 2. Under **Outputs**, search for the default output, then click the **Edit** icon in the **Action** column. + 2. Under **Outputs**, search for the default output, then select the **Edit** icon in the **Action** column. 3. In the **Hosts** field, specify the {{es}} URLs where {{agent}}s will send data. For example, [https://192.0.2.0:9200](https://192.0.2.0:9200). 4. Specify either a CA certificate or CA fingerprint to connect securely {{es}}: @@ -156,7 +158,7 @@ To encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}}: 1. Install an {{agent}} as a {{fleet-server}} on the host and configure it to use TLS: - 1. If you don’t already have a {{fleet-server}} service token, click the **Agents** tab in {{fleet}} and follow the instructions to generate the service token now. + 1. If you don’t already have a {{fleet-server}} service token, select the **Agents** tab in {{fleet}} and follow the instructions to generate the service token now. ::::{tip} The in-product installation steps are incomplete. Before running the `install` command, add the settings shown in the next step. @@ -268,6 +270,40 @@ To encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}}: `certificate-authorities` : CA certificate to use to connect to {{fleet-server}}. This is the CA used to [generate a certificate and key](#generate-fleet-server-certs) for {{fleet-server}}. - Don’t have an enrollment token? On the **Agents** tab in {{fleet}}, click **Add agent**. Under **Enroll and start the Elastic Agent**, follow the in-product installation steps, making sure that you add the `--certificate-authorities` option before you run the command. + Don’t have an enrollment token? On the **Agents** tab in {{fleet}}, select **Add agent**. Under **Enroll and start the Elastic Agent**, follow the in-product installation steps, making sure that you add the `--certificate-authorities` option before you run the command. + + +## Configure SSL/TLS using {{kib}} [fleet-server-ssl-ui-settings] +```{applies_to} + stack: ga 9.1 +``` + +You can configure SSL/TLS settings for {{fleet-server}} hosts directly in the {{fleet}} UI, without relying on CLI flags or policy overrides. + +To access these settings: + +1. In **Kibana**, go to **Management > {{fleet}} > Settings**. +2. Under **{{fleet-server}} hosts**, select **Add host** or edit an existing host. +3. Expand the **SSL options** section. + +### SSL options + +These are the available UI fields and their CLI equivalents: + +The following table shows the available UI fields and their CLI equivalents: + +| **UI Field** | **CLI Flag** | **Purpose** | +| ------------------------------------- | ---------------------------- | -------------------------------------------------------------------- | +| Server SSL certificate authorities | `--certificate-authorities` | CA to validate agent certificates (Fleet Server authenticates agent) | +| Client SSL certificate | `--fleet-server-cert` | TLS certificate Fleet Server presents to agent (agent validates it) | +| Client SSL certificate key | `--fleet-server-cert-key` | Key paired with the Fleet Server client certificate | +| Elasticsearch certificate authorities | `--fleet-server-es-ca` | CA Fleet Server uses to validate Elasticsearch cert | +| SSL certificate for Elasticsearch | `--fleet-server-es-cert` | Fleet Server’s mTLS certificate for Elasticsearch | +| SSL certificate key for Elasticsearch | `--fleet-server-es-cert-key` | Key paired with the Fleet Server’s Elasticsearch certificate | +| Enable client authentication | `--fleet-server-client-auth` | Require agents to present client certificates (mTLS only) | +:::{warning} +Editing SSL or proxy settings for an existing {{fleet-server}} might cause agents to lose connectivity. After changing client certificate settings, you might need to re-enroll the affected agents. +::: +To configure a mutual TLS connection from {{fleet-server}} to {{es}}, use the {{es}} output settings. For more information, refer to [Output SSL options](/reference/fleet/tls-overview.md#output-ssl-options). diff --git a/reference/fleet/tls-overview.md b/reference/fleet/tls-overview.md index 82f0f68613..051e07077a 100644 --- a/reference/fleet/tls-overview.md +++ b/reference/fleet/tls-overview.md @@ -10,8 +10,11 @@ products: This page provides an overview of the relationship between the various certificates and certificate authorities (CAs) that you configure for {{fleet-server}} and {{agent}}, using the `elastic-agent install` TLS command options. +You can also configure one-way and mutual TLS connections using {{kib}}. {applies_to}`stack: ga 9.1` + * [Simple one-way TLS connection](#one-way-tls-connection) * [Mutual TLS connection](#mutual-tls-connection) +* [Configure TLS/mTLS settings in {{kib}}](#tls-ui-settings) {applies_to}`stack: ga 9.1` ## Simple one-way TLS connection [one-way-tls-connection] @@ -97,3 +100,49 @@ Note that you can also configure mutual TLS for {{fleet-server}} and {{agent}} [ :alt: Diagram of mutual TLS connection between components ::: +## Configure TLS/mTLS settings in the Fleet UI [tls-ui-settings] +```{applies_to} + stack: ga 9.1 +``` + +You can configure TLS and mutual TLS (mTLS) settings for {{fleet-server}} and outputs using the {{fleet}} UI. + +### Fleet Server SSL options + +To access these settings: + +1. In **Kibana**, go to **Management > {{fleet}} > Settings**. +2. Under **Fleet Server hosts**, select **Add host** or edit an existing host. +3. Expand the **SSL options** or **Authentication** section. + +The following table shows the available UI fields and their CLI equivalents: + +| **UI Field** | **CLI Flag** | **Purpose** | +| ------------------------------------- | ---------------------------- | -------------------------------------------------------------------- | +| Server SSL certificate authorities | `--certificate-authorities` | CA to validate agent certificates (Fleet Server authenticates agent) | +| Client SSL certificate | `--fleet-server-cert` | TLS certificate Fleet Server presents to agent (agent validates it) | +| Client SSL certificate key | `--fleet-server-cert-key` | Key paired with the Fleet Server client certificate | +| Elasticsearch certificate authorities | `--fleet-server-es-ca` | CA Fleet Server uses to validate Elasticsearch cert | +| SSL certificate for Elasticsearch | `--fleet-server-es-cert` | Fleet Server’s mTLS certificate for Elasticsearch | +| SSL certificate key for Elasticsearch | `--fleet-server-es-cert-key` | Key paired with the Fleet Server’s Elasticsearch certificate | +| Enable client authentication | `--fleet-server-client-auth` | Require agents to present client certificates (mTLS only) | + +### Output SSL options + +To access these settings: + +1. In **Kibana**, go to **Management > {{fleet}} > Settings**. +2. Under **Outputs**, select **Add output** or edit an existing output. +3. Expand the **SSL options** or **Authentication** section. + +These apply to {{es}} and Remote {{es}} only, and are only necessary when setting up an mTLS connection: + +| **UI Field** | **CLI Flag** | **Purpose** | +| ---------------------------------- | --------------------------- | ---------------------------------------------------------------- | +| Server SSL certificate authorities | `--certificate-authorities` | CA the agent uses to verify the output’s TLS certificate | +| Client SSL certificate | `--elastic-agent-cert` | Certificate used by agent to authenticate with output (for mTLS) | +| Client SSL certificate key | `--elastic-agent-cert-key` | Key paired with agent mTLS certificate | + +:::{warning} +Editing SSL or proxy settings for an existing {{fleet-server}} might cause agents to lose connectivity. After changing client certificate settings, you might need to re-enroll the affected agents. +::: \ No newline at end of file