Skip to content
Merged
Show file tree
Hide file tree
Changes from 7 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.
48 changes: 42 additions & 6 deletions reference/fleet/secure-connections.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,6 @@
::::



## 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 @@
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 @@
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 @@

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,40 @@
`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](tls-overview#output-ssl-options).

Check failure on line 309 in reference/fleet/secure-connections.md

View workflow job for this annotation

GitHub Actions / preview / build

`tls-overview` does not exist. resolved to `/github/workspace/reference/fleet/tls-overview
49 changes: 49 additions & 0 deletions reference/fleet/tls-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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.
:::
Loading