From 7acf4251609b55c293ab17532a24af00ad86afd6 Mon Sep 17 00:00:00 2001 From: "Lee E. Hinman" Date: Wed, 30 Oct 2024 15:21:17 -0500 Subject: [PATCH 1/7] Add documentation for elastic-agent-cert-key-passphrase option --- .../elastic-agent/configuration/env/shared-env.asciidoc | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc index 71cfd7bf8..1d81d86b3 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc @@ -37,6 +37,15 @@ OPTIONAL INFO AND EXAMPLE // end::elastic-agent-cert-key[] +// tag::elastic-agent-cert-key-passphrase[] +| +[id="env-{type}-elastic-agent-cert-key-passphrase"] +`ELASTIC_AGENT_CERT_KEY_PASSPHRASE` + +| (string) The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server}. The file must only contain the characters of the passphrase, no newline or extra non-printing characters. + +// end::elastic-agent-cert-key-passphrase[] + // ============================================================================= // tag::elastic-agent-tag[] From 9ff901280910bcfe04209b79ba1f2e866782df90 Mon Sep 17 00:00:00 2001 From: David Kilfoyle Date: Thu, 31 Oct 2024 12:34:01 -0400 Subject: [PATCH 2/7] Add the setting throughout the docs --- docs/en/ingest-management/commands.asciidoc | 14 ++++++++++++++ .../configuration/env/container-envs.asciidoc | 2 ++ .../configuration/env/shared-env.asciidoc | 2 ++ .../security/certificates.asciidoc | 3 +++ .../ingest-management/security/mutual-tls.asciidoc | 9 +++++++++ .../security/tls-overview.asciidoc | 1 + 6 files changed, 31 insertions(+) diff --git a/docs/en/ingest-management/commands.asciidoc b/docs/en/ingest-management/commands.asciidoc index 482c549ab..9074ea8af 100644 --- a/docs/en/ingest-management/commands.asciidoc +++ b/docs/en/ingest-management/commands.asciidoc @@ -164,6 +164,7 @@ elastic-agent enroll --url [--delay-enroll] [--elastic-agent-cert ] [--elastic-agent-cert-key ] + [--elastic-agent-cert-key-passphrase ] [--force] [--header ] [--help] @@ -191,6 +192,7 @@ elastic-agent enroll --fleet-server-es [--delay-enroll] [--elastic-agent-cert ] [--elastic-agent-cert-key ] + [--elastic-agent-cert-key-passphrase ] [--fleet-server-cert ] <1> [--fleet-server-cert-key ] [--fleet-server-cert-key-passphrase ] @@ -251,6 +253,11 @@ Certificate to use as the client certificate for the {agent}'s connections to {f `--elastic-agent-cert-key`:: Private key to use as for the {agent}'s connections to {fleet-server}. +`--elastic-agent-cert-key-passphrase`:: +The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server}. The file must only contain the characters of the passphrase, no newline or extra non-printing characters. ++ +This option is only used if the `--elastic-agent-cert-key` is encrypted and requires a passphrase to use. + `--enrollment-token `:: Enrollment token to use to enroll {agent} into {fleet}. You can use the same enrollment token for multiple agents. @@ -580,6 +587,7 @@ elastic-agent install --url [--delay-enroll] [--elastic-agent-cert ] [--elastic-agent-cert-key ] + [--elastic-agent-cert-key-passphrase ] [--force] [--header ] [--help] @@ -611,6 +619,7 @@ elastic-agent install --fleet-server-es [--delay-enroll] [--elastic-agent-cert ] [--elastic-agent-cert-key ] + [--elastic-agent-cert-key-passphrase ] [--fleet-server-cert ] <1> [--fleet-server-cert-key ] [--fleet-server-cert-key-passphrase ] @@ -679,6 +688,11 @@ Certificate to use as the client certificate for the {agent}'s connections to {f `--elastic-agent-cert-key`:: Private key to use as for the {agent}'s connections to {fleet-server}. +`--elastic-agent-cert-key-passphrase`:: +The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server}. The file must only contain the characters of the passphrase, no newline or extra non-printing characters. ++ +This option is only used if the `--elastic-agent-cert-key` is encrypted and requires a passphrase to use. + `--enrollment-token `:: Enrollment token to use to enroll {agent} into {fleet}. You can use the same enrollment token for multiple agents. diff --git a/docs/en/ingest-management/elastic-agent/configuration/env/container-envs.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/env/container-envs.asciidoc index e2275bc60..3aa5a0d07 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/env/container-envs.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/env/container-envs.asciidoc @@ -149,6 +149,8 @@ include::shared-env.asciidoc[tag=elastic-agent-cert] include::shared-env.asciidoc[tag=elastic-agent-cert-key] +include::shared-env.asciidoc[tag=elastic-agent-cert-key-passphrase] + include::shared-env.asciidoc[tag=elastic-agent-tag] include::shared-env.asciidoc[tag=fleet-enroll] diff --git a/docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc index 1d81d86b3..2767bf738 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc @@ -44,6 +44,8 @@ OPTIONAL INFO AND EXAMPLE | (string) The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server}. The file must only contain the characters of the passphrase, no newline or extra non-printing characters. +This option is only used if the `--elastic-agent-cert-key` is encrypted and requires a passphrase to use. + // end::elastic-agent-cert-key-passphrase[] // ============================================================================= diff --git a/docs/en/ingest-management/security/certificates.asciidoc b/docs/en/ingest-management/security/certificates.asciidoc index 60a031262..664cb47bc 100644 --- a/docs/en/ingest-management/security/certificates.asciidoc +++ b/docs/en/ingest-management/security/certificates.asciidoc @@ -231,6 +231,7 @@ sudo ./elastic-agent install \ --fleet-server-port=8220 \ --elastic-agent-cert=/tmp/fleet-server.crt \ --elastic-agent-cert-key=/tmp/fleet-server.key \ + --elastic-agent-cert-key-passphrase=/tmp/fleet-server ???? \ --fleet-server-es-cert=/tmp/fleet-server.crt \ --fleet-server-es-cert-key=/tmp/fleet-server.key \ --fleet-server-client-auth=required @@ -263,6 +264,8 @@ to the other {agents} The certificate to use as the client certificate for {agent}'s connections to {fleet-server}. `elastic-agent-cert-key`:: The path to the private key to use as for {agent}'s connections to {fleet-server}. +`elastic-agent-cert-key`:: +The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server}. The file must only contain the characters of the passphrase, no newline or extra non-printing characters. This option is only used if the `elastic-agent-cert-key` is encrypted and requires a passphrase to use. `fleet-server-es-cert`:: The path to the client certificate that {fleet-server} will use when connecting to {es}. `fleet-server-es-cert-key`:: diff --git a/docs/en/ingest-management/security/mutual-tls.asciidoc b/docs/en/ingest-management/security/mutual-tls.asciidoc index e757b69c5..acd276a5a 100644 --- a/docs/en/ingest-management/security/mutual-tls.asciidoc +++ b/docs/en/ingest-management/security/mutual-tls.asciidoc @@ -72,6 +72,9 @@ During {agent} installation on premise use the following options: |`--elastic-agent-cert-key` |{agent} certificate key to present to {fleet-server} + +|`--elastic-agent-cert-key-passphrase` +|The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server} |=== [discrete] @@ -183,6 +186,9 @@ During {agent} installation on premise use the following options: |`--elastic-agent-cert-key` |{agent}'s private certificate key used to decrypt the certificate + +|`--elastic-agent-cert-key-passphrase` +|The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server} |=== [discrete] @@ -213,6 +219,9 @@ During {agent} installation on premise use the following options, similar to < Date: Mon, 4 Nov 2024 09:00:20 -0500 Subject: [PATCH 3/7] Update docs/en/ingest-management/security/certificates.asciidoc --- docs/en/ingest-management/security/certificates.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/ingest-management/security/certificates.asciidoc b/docs/en/ingest-management/security/certificates.asciidoc index 664cb47bc..8efb4b278 100644 --- a/docs/en/ingest-management/security/certificates.asciidoc +++ b/docs/en/ingest-management/security/certificates.asciidoc @@ -231,7 +231,7 @@ sudo ./elastic-agent install \ --fleet-server-port=8220 \ --elastic-agent-cert=/tmp/fleet-server.crt \ --elastic-agent-cert-key=/tmp/fleet-server.key \ - --elastic-agent-cert-key-passphrase=/tmp/fleet-server ???? \ + --elastic-agent-cert-key-passphrase=/tmp/fleet-server/passphrase-file \ --fleet-server-es-cert=/tmp/fleet-server.crt \ --fleet-server-es-cert-key=/tmp/fleet-server.key \ --fleet-server-client-auth=required From ede4772d9dbad3708ac3bcf55c1929befddf1d0c Mon Sep 17 00:00:00 2001 From: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> Date: Mon, 4 Nov 2024 09:37:51 -0500 Subject: [PATCH 4/7] Update docs/en/ingest-management/commands.asciidoc --- docs/en/ingest-management/commands.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/en/ingest-management/commands.asciidoc b/docs/en/ingest-management/commands.asciidoc index 9074ea8af..0f745ee46 100644 --- a/docs/en/ingest-management/commands.asciidoc +++ b/docs/en/ingest-management/commands.asciidoc @@ -254,7 +254,8 @@ Certificate to use as the client certificate for the {agent}'s connections to {f Private key to use as for the {agent}'s connections to {fleet-server}. `--elastic-agent-cert-key-passphrase`:: -The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server}. The file must only contain the characters of the passphrase, no newline or extra non-printing characters. +The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server}. +The file must only contain the characters of the passphrase, no newline or extra non-printing characters. + This option is only used if the `--elastic-agent-cert-key` is encrypted and requires a passphrase to use. From f7d3776aabf63055d78612c6954a25e785cc66a9 Mon Sep 17 00:00:00 2001 From: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> Date: Mon, 4 Nov 2024 09:37:57 -0500 Subject: [PATCH 5/7] Update docs/en/ingest-management/commands.asciidoc --- docs/en/ingest-management/commands.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/en/ingest-management/commands.asciidoc b/docs/en/ingest-management/commands.asciidoc index 0f745ee46..fe4486d32 100644 --- a/docs/en/ingest-management/commands.asciidoc +++ b/docs/en/ingest-management/commands.asciidoc @@ -690,7 +690,8 @@ Certificate to use as the client certificate for the {agent}'s connections to {f Private key to use as for the {agent}'s connections to {fleet-server}. `--elastic-agent-cert-key-passphrase`:: -The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server}. The file must only contain the characters of the passphrase, no newline or extra non-printing characters. +The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server}. +The file must only contain the characters of the passphrase, no newline or extra non-printing characters. + This option is only used if the `--elastic-agent-cert-key` is encrypted and requires a passphrase to use. From 9d2cc3ac27153908ce8e5b48010604d11e8b82af Mon Sep 17 00:00:00 2001 From: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> Date: Mon, 4 Nov 2024 09:38:33 -0500 Subject: [PATCH 6/7] Update docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc --- .../elastic-agent/configuration/env/shared-env.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc b/docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc index 2767bf738..b12c947c1 100644 --- a/docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc +++ b/docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc @@ -42,7 +42,8 @@ OPTIONAL INFO AND EXAMPLE [id="env-{type}-elastic-agent-cert-key-passphrase"] `ELASTIC_AGENT_CERT_KEY_PASSPHRASE` -| (string) The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server}. The file must only contain the characters of the passphrase, no newline or extra non-printing characters. +| (string) The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server}. +The file must only contain the characters of the passphrase, no newline or extra non-printing characters. This option is only used if the `--elastic-agent-cert-key` is encrypted and requires a passphrase to use. From b760b467ea1f5473e8adef97b4107c08523a4103 Mon Sep 17 00:00:00 2001 From: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> Date: Mon, 4 Nov 2024 09:39:02 -0500 Subject: [PATCH 7/7] Update docs/en/ingest-management/security/certificates.asciidoc --- docs/en/ingest-management/security/certificates.asciidoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/en/ingest-management/security/certificates.asciidoc b/docs/en/ingest-management/security/certificates.asciidoc index 8efb4b278..56dde3b56 100644 --- a/docs/en/ingest-management/security/certificates.asciidoc +++ b/docs/en/ingest-management/security/certificates.asciidoc @@ -265,7 +265,9 @@ The certificate to use as the client certificate for {agent}'s connections to {f `elastic-agent-cert-key`:: The path to the private key to use as for {agent}'s connections to {fleet-server}. `elastic-agent-cert-key`:: -The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server}. The file must only contain the characters of the passphrase, no newline or extra non-printing characters. This option is only used if the `elastic-agent-cert-key` is encrypted and requires a passphrase to use. +The path to the file that contains the passphrase for the mutual TLS private key that {agent} will use to connect to {fleet-server}. +The file must only contain the characters of the passphrase, no newline or extra non-printing characters. +This option is only used if the `elastic-agent-cert-key` is encrypted and requires a passphrase to use. `fleet-server-es-cert`:: The path to the client certificate that {fleet-server} will use when connecting to {es}. `fleet-server-es-cert-key`::