How to configure a Filebeat file output

Writing Filebeat events to local disk is useful when checking harvested log data before it reaches Elasticsearch, Logstash, or another remote destination. A local dump makes it easier to inspect the exact event payload, keep a short sample for offline troubleshooting, and compare processor changes without involving the rest of the shipping pipeline.

The output.file backend writes each published event as newline-delimited JSON inside a chosen directory. It uses the configured filename as the base name, appends a date-based suffix with the .ndjson extension, and rotates files automatically according to rotate_every_kb and number_of_files.

Only one output.* block can be active at a time, so enabling output.file requires disabling the current destination first. On DEB and RPM installs, the main config file is usually /etc/filebeat/filebeat.yml/ and the packaged systemd unit applies UMask=0027, which ignores file permissions more permissive than 0640. Output files appear only after an enabled input publishes events, so an idle input or a tiny test file on a filestream input can leave the directory empty at first.

1. Open the Filebeat configuration file.

   $ sudo nano /etc/filebeat/filebeat.yml

   Use the packaged Linux path shown here unless the deployment uses an archive or container layout with a different config location.

2. Create a directory for the output files.

   $ sudo install -d -o root -g root -m 0750 /var/lib/filebeat/file-output

   The directory must be writable by the account running Filebeat. Keeping it separate from /var/log/filebeat/ avoids mixing captured events with Filebeat's own logs.

3. Disable other outputs and enable the file output.

   #output.elasticsearch:
   #  hosts: ["https://es.example.net:9200"]
   
   output.file:
     path: "/var/lib/filebeat/file-output"
     filename: "filebeat-events"
     rotate_every_kb: 10240
     number_of_files: 7
     permissions: 0600
     rotate_on_startup: true

   Filebeat supports only one enabled output.* block, so comment out any existing output.elasticsearch, output.logstash, output.kafka, output.redis, or output.console section before enabling output.file.

   rotate_every_kb defaults to 10240, number_of_files defaults to 7, permissions defaults to 0600, and rotate_on_startup defaults to true, so the explicit values above mainly document the intended rotation behavior.

   On packaged Linux services, the shipped systemd unit uses UMask=0027, so configured file permissions more permissive than 0640 are ignored.

4. Test the configuration for errors.

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

   Current 9.x builds can print JSON log lines before the final Config OK line. Related: How to test a Filebeat configuration

5. Restart the Filebeat service.

   $ sudo systemctl restart filebeat

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

6. Verify that Filebeat starts creating output files.

   $ sudo ls -l /var/lib/filebeat/file-output
   total 24
   -rw------- 1 root root 23970 Apr  2 11:26 filebeat-events-20260402.ndjson

   The generated file name uses the configured filename plus a date-based suffix and the .ndjson extension. No file appears until an enabled input actually publishes events.

7. View a sample event from the output file.

   $ sudo head -n 1 /var/lib/filebeat/file-output/filebeat-events-*.ndjson
   {"@timestamp":"2026-04-02T11:26:48.968Z","@metadata":{"beat":"filebeat","type":"_doc","version":"9.3.2"},"log":{"offset":0,"file":{"fingerprint":"b8fbeeed0c56dc90683af6ca60f513172004c6a8c446f1e227c6540e6edf7334","path":"/var/log/app.log"}},"message":"example log line","input":{"type":"filestream"},"ecs":{"version":"8.0.0"},"host":{"name":"loghost01"},"agent":{"type":"filebeat","version":"9.3.2","id":"61567892-4f52-4e27-9674-9cacf133075f","name":"loghost01"}}

   Each line in the output file is one JSON event. Exact fields vary by input, processors, and the source data being harvested.