How to configure Filebeat for TLS

TLS secures Filebeat traffic by encrypting events in transit and validating the identity of the upstream endpoint. Protecting the log pipeline prevents passive interception of sensitive telemetry and reduces the risk of active man-in-the-middle attacks that can tamper with or redirect data. A consistent TLS baseline also simplifies compliance requirements for centralized logging.

Filebeat enables TLS on outputs by using the https scheme for Elasticsearch or by enabling ssl options for the Logstash output. A trusted CA certificate is used to validate the server certificate chain, and mutual TLS can be enabled by supplying a client certificate and private key. Certificate verification is based on the host name in the output configuration, so DNS names should align with the certificate subjectAltName entries.

TLS settings are configured in /etc/filebeat/filebeat.yml and are loaded by both the filebeat test commands and the running service. YAML indentation and key permissions are common failure points, especially when the configured host name does not match the server certificate or when private keys are readable by unintended accounts. Apply changes safely by validating configuration first, testing the TLS handshake, and restarting the Filebeat service only after checks succeed.

1. Create a directory for TLS assets.

   $ sudo install -d -m 750 /etc/filebeat/certs

2. Install the CA certificate used to validate the upstream server.

   $ sudo install -m 644 /tmp/elastic-ca.crt /etc/filebeat/certs/elastic-ca.crt

   CA certificates are typically distributed as PEM-encoded .crt files.

3. Install the client certificate when mutual TLS is required.

   $ sudo install -m 644 /tmp/filebeat.crt /etc/filebeat/certs/filebeat.crt

4. Install the client private key when mutual TLS is required.

   $ sudo install -m 640 /tmp/filebeat.key /etc/filebeat/certs/filebeat.key

   Private keys should be readable only by the account that runs Filebeat, or startup fails with permission errors.

5. Confirm permissions for the TLS assets directory.

   $ sudo ls -l /etc/filebeat/certs
   total 12
   -rw-r--r-- 1 root root 1164 Jan  7 04:00 elastic-ca.crt
   -rw-r--r-- 1 root root 1111 Jan  7 03:54 filebeat.crt
   -rw-r----- 1 root root 1704 Jan  7 03:55 filebeat.key

6. Configure TLS options in /etc/filebeat/filebeat.yml.

   output.elasticsearch:
     hosts: ["https://node-01-secure:9200"]
     username: "elastic"
     password: "password"
     ssl.certificate_authorities: ["/etc/filebeat/certs/elastic-ca.crt"]
     # ssl.certificate: "/etc/filebeat/certs/filebeat.crt"
     # ssl.key: "/etc/filebeat/certs/filebeat.key"

   Uncomment ssl.certificate and ssl.key only when the upstream requires mutual TLS client authentication.

   The host in hosts must match a name in the server certificate subjectAltName, or the TLS handshake fails with certificate name errors.

7. Test the Filebeat configuration for syntax errors.

   $ sudo filebeat test config
   Config OK

   Related: How to test a Filebeat configuration

8. Test the TLS connection to the configured output.

   $ sudo filebeat test output
   elasticsearch: https://node-01-secure:9200...
     parse url... OK
     connection...
       parse host... OK
       dns lookup... OK
       addresses: 172.18.0.4
       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
     version: 8.12.2

9. Restart the Filebeat service to apply the TLS settings.

   $ sudo systemctl restart filebeat

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

10. Verify the Filebeat service is running without TLS errors.

    $ sudo systemctl status filebeat --no-pager
    ● filebeat.service - Filebeat sends log files to Logstash or directly to Elasticsearch.
         Loaded: loaded (/usr/lib/systemd/system/filebeat.service; enabled; preset: enabled)
        Drop-In: /etc/systemd/system/filebeat.service.d
                 └─env.conf
         Active: active (running) since Wed 2026-01-07 04:00:59 UTC; 5s ago
           Docs: https://www.elastic.co/beats/filebeat
    ##### snipped #####
    Jan 07 04:01:19 host filebeat[11992]: {"log.level":"info","@timestamp":"2026-01-07T04:01:19.823Z","log.logger":"publisher_pipeline_output","log.origin":{"function":"github.com/elastic/beats/v7/libbeat/publisher/pipeline.(*netClientWorker).run","file.name":"pipeline/client_worker.go","file.line":146},"message":"Connection to backoff(elasticsearch(https://node-01-secure:9200)) established","service.name":"filebeat","ecs.version":"1.6.0"}