Skip to content

Latest commit

 

History

History
264 lines (227 loc) · 9.17 KB

fleet-server-secrets.asciidoc

File metadata and controls

264 lines (227 loc) · 9.17 KB

{fleet-server} Secrets

{fleet-server} configuration can contain secret values. You may specify these values directly in the configuration or through secret files. You can use command line arguments to pass the values or file paths when you are running under {agent}, or you can use environment variables if {agent} is running in a container.

For examples of how to deploy secret files, refer to our Secret files guide.

Note
 Stand-alone {fleet-server} is under active development.

Secret values

The following secret values may be used when configuring {fleet-server}.

Note that the configuration fragments shown below are specified either in the UI as part of the output specification or as part of the {fleet-server} integration settings.

service_token

The service_token is used to communicate with {es}.

It may be specified in the configuration directly as:

output.elasticsearch.service_token: my-service-token

Or by a file with:

output.elasticsearch.service_token_path: /path/to/token-file

When you are running {fleet-server} under {agent}, you can specify it with either the --fleet-server-service-token or the --fleet-server-service-token-path flag. See {agent} command reference for more details.

If you are running {fleet-server} under {agent} in a container, you can use the environment variables FLEET_SERVER_SERVICE_TOKEN or FLEET_SERVER_SERVICE_TOKEN_PATH.

TLS private key

Use the TLS private key to encrypt communications between {fleet-server} and {agent}. See [secure-connections] for more details.

Although it is not recommended, you may specify the private key directly in the configuration as:

inputs:
  - type: fleet-server
    ssl.key: |
      ----BEGIN CERTIFICATE----
      ....
      ----END CERTIFICATE----

Alternatively, you can provide the path to the private key with the same attribute:

inputs:
  - type: fleet-server
    ssl.key: /path/to/cert.key

When you are running {fleet-server} under {agent}, you can provide the private key path using with the --fleet-server-cert-key flag. See {agent} command reference for more details.

If you are running {fleet-server} under {agent} in a container, you can use the environment variable FLEET_SERVER_CERT_KEY to specify the private key path.

TLS private key passphrase

The private key passphrase is used to decrypt an encrypted private key file.

You can specify the passphrase as a secret file in the configuration with:

inputs:
  - type: fleet-server
    ssl.key_passphrase_path: /path/to/passphrase

When you are running {fleet-server} under {agent}, you can provide the passphrase path using the --fleet-server-cert-key-passphrase flag. See {agent} command reference for more details.

If you are running {fleet-server} under {agent} in a container, you can use the environment variable FLEET_SERVER_CERT_KEY_PASSPHRASE to specify the file path.

APM API Key

The APM API Key may be used to gather APM data from {fleet-server}.

You can specify it directly in the instrumentation segment of the configuration:

inputs:
  - type: fleet-server
    instrumentation.api_key: my-apm-api-key

Or by a file with:

inputs:
  - type: fleet-server
    instrumentation.api_key_file: /path/to/apmAPIKey

You may specify the API key by value using the environment variable ELASTIC_APM_API_KEY.

APM secret token

The APM secret token may be used to gather APM data from {fleet-server}.

You can specify the secret token directly in the instrumentation segment of the configuration:

inputs:
  - type: fleet-server
    instrumentation.secret_token: my-apm-secret-token

Or by a file with:

inputs:
  - type: fleet-server
    instrumentation.secret_token_file: /path/to/apmSecretToken

You may also specify the token by value using the environment variable ELASTIC_APM_SECRET_TOKEN.

Secret files guide

This guide provides step-by-step examples with best practices on how to deploy secret files directly on a host or through the Kubernetes secrets engine.

Secrets on filesystem

Secret files can be provisioned as plain text files directly on filesystems and referenced or passed through {agent}.

We recommend these steps to improve security.

File permissions

File permissions should not allow for global read permissions.

On MacOS and Linux, you can set file ownership and file permissions with the chown and chmod commands, respectively. {fleet-server} runs as the root user on MacOS and Linux, so given a file named mySecret, you can alter it with:

sudo chown root:root mySecret # set the user:group to root
sudo chmod 0600 mySecret      # set only the read/write permission flags for the user, clear group and global permissions.

On Windows, you can use icacls to alter the ACL list associated with the file:

Write-Output -NoNewline SECRET > mySecret          # Create the file mySecret with the contents SECRET
icacls .\mySecret /inheritance:d                   # Remove inherited permissions from file
icacls .\mySecret /remove:g BUILTIN\Administrators # Remove Administrators group permissions
icacls .\mySecret /remove:g $env:UserName          # Remove current user's permissions

Temporary filesystem

You can use a temporary filesystem (in RAM) to hold secret files in order to improve security. These types of filesystems are normally not included in backups and are cleared if the host is reset. If used, the filesystem and secret files need to be reprovisioned with every reset.

On Linux you can use mount with the tmpfs filesystem to create a temporary filesystem in RAM:

mount -o size=1G -t tmpfs none /mnt/fleet-server-secrets

On MacOS you can use a combination of diskutil and hdiutil to create a RAM disk:

diskutil erasevolume HFS+ 'RAM Disk' `hdiutil attach -nobrowse -nomount ram://2097152`

Windows systems do not offer built-in options to create a RAM disk, but several third party programs are available.

Example

Here is a step by step guide for provisioning a service token on a Linux system:

sudo mkdir -p /mnt/fleet-server-secrets
sudo mount -o size=1G -t tmpfs none /mnt/fleet-server-secrets
echo -n MY-SERVICE-TOKEN > /mnt/fleet-server-secrets/service-token
sudo chown root:root /mnt/fleet-server-secrets/service-token
sudo chmod 0600 /mnt/fleet-server-secrets/service-token
Note
 The -n flag is used with echo to prevent a newline character from being appended at the end of the secret. Be sure that the secret file does not contain the trailing newline character.

Secrets in containers

When you are using secret files directly in containers without using Kubernetes or another secrets management solution, you can pass the files into containers by mounting the file or directory. Provision the file in the same manner as it is in Secrets on filesystem and mount it in read-only mode. For example, when using Docker.

If you are using {agent} image:

docker run \
	-v /path/to/creds:/creds:ro \
        -e FLEET_SERVER_CERT_KEY_PASSPHRASE=/creds/passphrase \
        -e FLEET_SERVER_SERVICE_TOKEN_PATH=/creds/service-token \
        --rm docker.elastic.co/elastic-agent/elastic-agent

Secrets in Kubernetes

Kubernetes has a secrets management engine that can be used to provision secret files to pods.

For example, you can create the passphrase secret with:

kubectl create secret generic fleet-server-key-passphrase \
  --from-literal=value=PASSPHRASE

And create the service token secret with:

kubectl create secret generic fleet-server-service-token \
  --from-literal=value=SERVICE-TOKEN

Then include it in the pod specification, for example, when you are running {fleet-server} under {agent}:

spec:
  volumes:
  - name: key-passphrase
    secret:
      secretName: fleet-server-key-passphrase
  - name: service-token
    secret:
      secretName: fleet-server-service-token
  containers:
  - name: fleet-server
    image: docker.elastic.co/elastic-agent/elastic-agent
    volumeMounts:
    - name: key-passphrase
      mountPath: /var/secrets/passphrase
    - name: service-token
      mountPath: /var/secrets/service-token
    env:
    - name: FLEET_SERVER_CERT_KEY_PASSPHRASE
      value: /var/secrets/passphrase/value
    - name: FLEET_SERVER_SERVICE_TOKEN_PATH
      value: /var/secrets/service-token/value

{agent} Kubernetes secrets provider

When you are running {fleet-server} under {agent} in {k8s}, you can use {agent}'s [kubernetes_secrets-provider] to insert a {k8s} secret directly into {fleet-server}'s configuration. Note that due to how {fleet-server} is bootstrapped only the APM secrets (API key or secret token) can be specified with this provider.