How to test a Filebeat configuration

Testing a Filebeat configuration catches YAML mistakes and invalid settings before log shipping is interrupted. Validating changes early prevents silent data gaps when pipelines depend on Filebeat as the primary collector.

The filebeat test config subcommand parses the main .yml file (commonly /etc/filebeat/filebeat.yml), loads module and input fragments, and validates the resulting configuration tree. Includes from /etc/filebeat/modules.d (and any configured input includes) are handled the same way as during a normal start.

The configuration test checks structure and syntax, not downstream reachability. Output destinations, TLS trust, and authentication problems require a separate output check, and overly-permissive file modes can block startup due to strict.perms protections.

1. Run the configuration test.

   $ sudo filebeat test config -c /etc/filebeat/filebeat.yml
   Config OK

   Config OK indicates YAML parsing and config loading completed without errors.

2. Correct any reported YAML or setting errors.

   $ sudo filebeat test config -c /etc/filebeat/filebeat.yml
   Exiting: error loading config file: yaml: line 9: did not find expected node content

   Filebeat fails to start with an invalid configuration, stopping event shipping until the file is fixed.

3. Remove group and other write permissions if the error mentions strict.perms.

   $ sudo chmod go-w /etc/filebeat/filebeat.yml

   Filebeat requires configuration files to be owned by the running user and not writable by group or others.

4. Repeat the configuration test until it reports Config OK.

   $ sudo filebeat test config -c /etc/filebeat/filebeat.yml
   Config OK

5. Export the resolved configuration to inspect merged inputs, modules, and outputs.

   $ sudo filebeat export config -c /etc/filebeat/filebeat.yml | head -n 40
   filebeat:
     inputs:
     - id: app-log
       paths:
       - /var/log/app.log
       type: filestream
   output:
     logstash:
       hosts:
       - localhost:5044
   path:
     config: /etc/filebeat
   ##### snipped #####

   The exported configuration may include expanded values from the main config, environment variables, or plaintext credentials when set directly in the .yml file.

6. Test the configured output connection when output settings have changed.

   $ sudo filebeat test output -c /etc/filebeat/filebeat.yml
   logstash: localhost:5044...
     connection...
       parse host... OK
       dns lookup... OK
       addresses: 127.0.0.1, ::1
       dial up... OK
     TLS... WARN secure connection disabled
     talk to server... OK

   filebeat test output validates reachability and authentication for the configured output type.