Add documentation for elastic-agent-cert-key-passphrase option (#1413)

* Add documentation for elastic-agent-cert-key-passphrase option * Add the setting throughout the docs * Update docs/en/ingest-management/security/certificates.asciidoc * Update docs/en/ingest-management/commands.asciidoc * Update docs/en/ingest-management/commands.asciidoc * Update docs/en/ingest-management/elastic-agent/configuration/env/shared-env.asciidoc * Update docs/en/ingest-management/security/certificates.asciidoc --------- Co-authored-by: David Kilfoyle <[email protected]> Co-authored-by: David Kilfoyle <[email protected]>
elastic · Nov 4, 2024 · f9b079d · f9b079d
1 parent f5344bf
commit f9b079d
Show file tree

Hide file tree

Showing 6 changed files with 45 additions and 0 deletions.
diff --git a/docs/en/ingest-management/commands.asciidoc b/docs/en/ingest-management/commands.asciidoc
@@ -164,6 +164,7 @@ elastic-agent enroll --url <string>
                      [--delay-enroll]
                      [--elastic-agent-cert <string>]
                      [--elastic-agent-cert-key <string>]
+                     [--elastic-agent-cert-key-passphrase <string>]
                      [--force]
                      [--header <strings>]
                      [--help]
@@ -191,6 +192,7 @@ elastic-agent enroll --fleet-server-es <string>
                      [--delay-enroll]
                      [--elastic-agent-cert <string>]
                      [--elastic-agent-cert-key <string>]
+                     [--elastic-agent-cert-key-passphrase <string>]
                      [--fleet-server-cert <string>] <1>
                      [--fleet-server-cert-key <string>]
                      [--fleet-server-cert-key-passphrase <string>]
@@ -251,6 +253,12 @@ 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 <string>`::
 Enrollment token to use to enroll {agent} into {fleet}. You can use
 the same enrollment token for multiple agents.
@@ -580,6 +588,7 @@ elastic-agent install --url <string>
                       [--delay-enroll]
                       [--elastic-agent-cert <string>]
                       [--elastic-agent-cert-key <string>]
+                      [--elastic-agent-cert-key-passphrase <string>]
                       [--force]
                       [--header <strings>]
                       [--help]
@@ -611,6 +620,7 @@ elastic-agent install --fleet-server-es <string>
                       [--delay-enroll]
                       [--elastic-agent-cert <string>]
                       [--elastic-agent-cert-key <string>]
+                      [--elastic-agent-cert-key-passphrase <string>]
                       [--fleet-server-cert <string>] <1>
                       [--fleet-server-cert-key <string>]
                       [--fleet-server-cert-key-passphrase <string>]
@@ -679,6 +689,12 @@ 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 <string>`::
 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
@@ -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
@@ -37,6 +37,18 @@ 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.
+
+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[]
+
 // =============================================================================
 
 // tag::elastic-agent-tag[]

diff --git 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/passphrase-file \
    --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,10 @@ 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
@@ -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 <<m
 
 |`--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]

diff --git a/docs/en/ingest-management/security/tls-overview.asciidoc b/docs/en/ingest-management/security/tls-overview.asciidoc
@@ -52,6 +52,7 @@ elastic-agent install --url=https://your-fleet-server.elastic.co:443 \
 --certificate-authorities=/path/to/fleet-ca,/path/to/agent-ca \
 --elastic-agent-cert=/path/to/agent-cert \
 --elastic-agent-cert-key=/path/to/agent-cert-key \
+--elastic-agent-cert-key=/path/to/agent-cert-key-passphrase \
 --fleet-server-es=https://es.elastic.com:443 \
 --fleet-server-es-ca=/path/to/es-ca \
 --fleet-server-es-cert=/path/to/fleet-es-cert \