Skip to content
Merged
Show file tree
Hide file tree
Changes from 5 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
30 changes: 30 additions & 0 deletions reference/fleet/fleet-settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,36 @@ To add or edit the source of binary downloads:
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**, click **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 Down
38 changes: 36 additions & 2 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 Down Expand Up @@ -271,3 +273,35 @@ To encrypt traffic between {{agent}}s, {{fleet-server}}, and {{es}}:
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.


## 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**, click **Add host** or edit an existing host.
3. Expand the **SSL options** section.

### SSL options

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. |

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}} may cause agents to lose connectivity. After changing client certificate settings, you 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**, click **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}} may cause agents to lose connectivity. After changing client certificate settings, you need to re-enroll the affected agents.
:::
Loading