How to add a secret to a Filebeat keystore

Keeping output passwords or API keys inside /etc/filebeat/filebeat.yml makes them easy to leak through backups, support bundles, copied snippets, or version control. A Filebeat keystore keeps the secret out of the main YAML while still allowing the configuration to reference it by name.

Filebeat stores keystore values under the path.data directory and references them with the same ${KEY} placeholder syntax used for environment variables. When Filebeat unpacks the configuration, it resolves keystore keys before environment variables and other variable sources, so the stored secret can be used directly in output and processor settings without exposing the plain-text value in the config file.

The keystore command must run as the same user that starts Filebeat, and it must target the same path.data location used by the running service. On DEB and RPM installs managed by systemd, the service unit typically points path.data at /var/lib/filebeat, so adding a key under another data directory creates a different keystore that the service will not read. Keystore changes are picked up on the next start, so restart filebeat after updating a secret.

Steps to add a secret to a Filebeat keystore:

Add the secret value to the Filebeat keystore.
```
$ printf 'strong-password' | sudo filebeat keystore add ES_PWD --stdin
Successfully updated the keystore
```
Run the command as the same user that runs Filebeat and append --path.data /path/to/data when the service uses a non-default data directory.

Use --force with the same command when rotating an existing key non-interactively, for example sudo filebeat keystore add ES_PWD --stdin --force.
List the keystore keys to confirm the new entry exists.
```
$ sudo filebeat keystore list
ES_PWD
```
filebeat keystore list shows key names only and never prints the secret value.
Reference the keystore key in the Filebeat output configuration.
```
output.elasticsearch:
  hosts: ["https://es.example.net:9200"]
  username: "filebeat_writer"
  password: "${ES_PWD}"
```
The placeholder must match the keystore key exactly, including case. Keeping "${ES_PWD}" quoted avoids YAML parsing problems.
Test the Filebeat configuration after replacing the plain-text secret.
```
$ sudo filebeat test config -c /etc/filebeat/filebeat.yml
Config OK
```
Related: How to test a Filebeat configuration
Restart the Filebeat service so it reloads the updated keystore.
```
$ sudo systemctl restart filebeat
```
Restarting Filebeat briefly pauses log shipping until the service is back in an active (running) state.

Related: How to manage the Filebeat service with systemctl in Linux

Test the configured output and confirm the new secret works.

$ sudo filebeat test output -c /etc/filebeat/filebeat.yml
elasticsearch: https://es.example.net:9200...
  parse url... OK
  connection...
    parse host... OK
    dns lookup... OK
    addresses: 203.0.113.25
    dial up... OK
  TLS...
    security: server's certificate chain verification is enabled
    handshake... OK
    TLS version: TLSv1.3
    dial up... OK
  talk to server... OK

Use the active config file after -c when the output settings live outside the default /etc/filebeat/filebeat.yml path.

Author: Mohd Shakir Zakaria
Mohd Shakir Zakaria is a cloud architect with deep roots in software development and open-source advocacy. Certified in AWS, Red Hat, VMware, ITIL, and Linux, he specializes in designing and managing robust cloud and on-premises infrastructures.