Skip to content
Merged
Show file tree
Hide file tree
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 38 additions & 8 deletions reference/fleet/fleet-settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand All @@ -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).
Expand All @@ -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]

Expand All @@ -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.
46 changes: 40 additions & 6 deletions reference/fleet/secure-connections.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -101,15 +103,15 @@ 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}}.

::::{tip}
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}}:

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -268,6 +270,38 @@ 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:

| **UI Field** | **CLI Flag** | **Purpose** |
|--------------------------------------------------|---------------------------------------|-------------|
| Client SSL Certificate | `--elastic-agent-cert` | {{agent}} client certificate to use with {{fleet-server}} during mTLS authentication. |
| Client SSL Certificate key | `--elastic-agent-cert-key` | {{agent}} client private key to use with {{fleet-server}} during mTLS authentication. This field uses secret storage and requires {{fleet-server}} v8.12.0 or later. You can optionally choose to store the value as plain text instead. |

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that the these should be -fleet-server-es-cert and -fleet-server-es-cert-key. The --elastic-agent-cert are the ones available under the output section of fleet settings

| Server SSL certificate authorities (optional) | `--certificate-authorities` | Comma-separated list of root certificates for server verification used by {{agent}} and {{fleet-server}}. |
| SSL certificate for {{es}} | `--fleet-server-es-cert` | Client certificate for {{fleet-server}} to use when connecting to {{es}}. |
| SSL certificate key for {{es}} | `--fleet-server-es-cert-key` | Client private key for {{fleet-server}} to use when connecting to {{es}}. |
| {{es}} Certificate Authorities (optional) | `--fleet-server-es-ca` | Path to certificate authority for {{fleet-server}} to use to communicate with {{es}}. |
| Enable client authentication | `--fleet-server-client-auth=required`| Requires {{agent}} to present a valid client certificate when connecting to {{fleet-server}}. |

The {{fleet}} UI doesn't currently allow editing the {{fleet-server}}’s own exposed TLS certificate (`--fleet-server-cert`, `--fleet-server-cert-key`). These are only configurable using the CLI either during the initial installation or later.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm confused by this sentence, I don't think it should be here. These values should be in the table above.


:::{warning}
Editing SSL or proxy settings for an existing {{fleet-server}} might cause agents to lose connectivity. After changing client certificate settings, you need to re-enroll the affected agents.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you need to re-enroll the affected agents - I'm not 100% sure about this. I would replace it with
you might need to re-enroll the affected agents

:::
38 changes: 38 additions & 0 deletions reference/fleet/tls-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@ elastic-agent install --url=https://your-fleet-server.elastic.co:443 \
--fleet-server-port=8220
```

You can also configure a one-way TLS connection using {{kib}}. Refer to [Configure TLS settings in the Fleet UI](#tls-ui-settings) for more information. {applies_to}`stack: ga 9.1`


{{agent}} is configured with `fleet-ca` as the certificate authority that it needs to validate certificates from {{fleet-server}}.

During the TLS connection setup, {{fleet-server}} presents its certificate `fleet-cert` to the agent and the agent (as a client) uses `fleet-ca` to validate the presented certificate.
Expand Down Expand Up @@ -74,6 +77,9 @@ elastic-agent install --url=https://your-fleet-server.elastic.co:443 \
--fleet-server-port=8220
```

You can also configure a mutual TLS connection using {{kib}}. Refer to [Configure TLS settings in the Fleet UI](#tls-ui-settings) for more information. {applies_to}`stack: ga 9.1`


As with the [one-way TLS example](#one-way-tls-connection), {{agent}} is configured with `fleet-ca` as the certificate authority that it needs to validate certificates from the {{fleet-server}}. {{fleet-server}} presents its certificate `fleet-cert` to the agent and the agent (as a client) uses `fleet-ca` to validate the presented certificate.

To establish a mutual TLS connection, the agent presents its certificate, `agent-cert`, and {{fleet-server}} validates this certificate using the `agent-ca` that it has stored in memory.
Expand All @@ -97,3 +103,35 @@ 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}} hosts using the {{fleet}} UI instead of CLI flags. This approach simplifies certificate configuration.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see where the mix up is - the elastic-agent-cert and --elastic-agent-cert-key are the ones available under Fleet settings > output . We should point the user to that section if they want to set up a mTLS connection


The following table shows the available UI fields and their CLI equivalents:

| **UI Field** | **CLI Flag** | **Purpose** |
|--------------------------------------------------|---------------------------------------|-------------|
| Client SSL Certificate | `--elastic-agent-cert` | {{agent}} client certificate to use with {{fleet-server}} during mTLS authentication. |
| Client SSL Certificate key | `--elastic-agent-cert-key` | {{agent}} client private key to use with {{fleet-server}} during mTLS authentication. This field uses secret storage and requires {{fleet-server}} v8.12.0 or later. You can optionally choose to store the value as plain text instead. |
| Server SSL certificate authorities (optional) | `--certificate-authorities` | Comma-separated list of root certificates for server verification used by {{agent}} and {{fleet-server}}. |
| SSL certificate for {{es}} | `--fleet-server-es-cert` | Client certificate for {{fleet-server}} to use when connecting to {{es}}. |
| SSL certificate key for {{es}} | `--fleet-server-es-cert-key` | Client private key for {{fleet-server}} to use when connecting to {{es}}. |
| {{es}} Certificate Authorities (optional) | `--fleet-server-es-ca` | Path to certificate authority for {{fleet-server}} to use to communicate with {{es}}. |
| Enable client authentication | `--fleet-server-client-auth=required`| Requires {{agent}} to present a valid client certificate when connecting to {{fleet-server}}. |

The {{fleet}} UI doesn't currently allow editing the {{fleet-server}}’s own exposed TLS certificate (`--fleet-server-cert`, `--fleet-server-cert-key`). These are only configurable using the CLI either during the initial installation or later.

:::{warning}
Editing SSL or proxy settings for an existing {{fleet-server}} might cause agents to lose connectivity. After changing client certificate settings, you need to re-enroll the affected agents.
:::
Loading