Wazuh Filebeat: A Step-by-Step Setup Guide

Wazuh Filebeat Architecture

Understanding the Wazuh Filebeat architecture makes it easier to troubleshoot connectivity issues, optimize performance, and scale your deployment.

Filebeat sits between the Wazuh Manager and the Wazuh Indexer, acting as the secure transport layer that delivers processed security events for indexing and visualization.

A typical deployment consists of four primary components.

Wazuh Manager

The Wazuh Manager is the central processing engine of the platform.

It receives logs from Wazuh agents, syslog sources, cloud services, and third-party integrations before analyzing them through decoders and detection rules.

Its responsibilities include:

• Collecting events from endpoints
• Decoding raw logs
• Matching events against detection rules
• Assigning severity levels
• Mapping events to MITRE ATT&CK techniques
• Performing compliance checks
• Writing alerts to JSON log files

Filebeat does not analyze logs itself, it simply forwards the alerts that the Wazuh Manager has already processed.

To learn more about the manager’s internal components, see Understanding the Wazuh DB Architecture.

Filebeat

Filebeat acts as the event shipper within the Wazuh architecture.

It continuously monitors files such as:

• /var/ossec/logs/alerts/alerts.json
• /var/ossec/logs/archives/archives.json (optional)

Whenever new alerts are written, Filebeat:

1. Detects the new entries.
2. Reads only the newly appended data.
3. Optionally enriches the events with metadata.
4. Compresses and batches the events.
5. Encrypts the connection using TLS.
6. Sends the events to the Wazuh Indexer.

Because Filebeat tracks file offsets internally, it resumes where it left off after restarts, minimizing duplicate or lost events.

Wazuh Indexer

The Wazuh Indexer stores and indexes the events received from Filebeat.

Its primary responsibilities include:

• Indexing JSON documents
• Managing searchable indices
• Supporting full-text search
• Handling aggregations
• Storing historical security events
• Replicating indices across cluster nodes (when clustered)

The indexer enables rapid searches across millions of alerts, making investigations significantly faster.

If you’re deploying multiple indexer nodes, see How to Build a Wazuh Indexer Cluster.

Wazuh Dashboard

The Wazuh Dashboard provides the graphical interface used by administrators, SOC analysts, and security engineers.

Once alerts are indexed, the dashboard allows users to:

• Search alerts
• Filter by severity
• View dashboards
• Investigate incidents
• Analyze MITRE ATT&CK mappings
• Review compliance reports
• Build custom visualizations

The dashboard never communicates directly with Filebeat.

Instead, it queries the Wazuh Indexer, which stores the indexed security data.

Data Flow Between Components

A simplified event flow looks like this:

Endpoint
   │
   ▼
Wazuh Agent
   │
   ▼
Wazuh Manager
(Log decoding & rule matching)
   │
   ▼
alerts.json
archives.json
   │
   ▼
Filebeat
(TLS encrypted)
   │
   ▼
Wazuh Indexer
   │
   ▼
Wazuh Dashboard

This separation of responsibilities provides several advantages:

• Independent scaling of each component
• Improved fault tolerance
• Better performance
• Easier troubleshooting
• Flexible clustered deployments

Elastic recommends separating data collection, storage, and visualization into dedicated services for larger deployments to improve scalability and operational resilience.

Typical Deployment Diagram

A production deployment often looks like the following:

                +----------------------+
                |    Linux Server      |
                |   Windows Server     |
                |     Cloud VM         |
                +----------+-----------+
                           |
                     Wazuh Agents
                           |
                           ▼
                +----------------------+
                |    Wazuh Manager     |
                | Rules & Decoders     |
                +----------+-----------+
                           |
                    alerts.json
                           |
                           ▼
                +----------------------+
                |      Filebeat        |
                | Secure TLS Shipping  |
                +----------+-----------+
                           |
                           ▼
                +----------------------+
                |    Wazuh Indexer     |
                | OpenSearch Engine    |
                +----------+-----------+
                           |
                           ▼
                +----------------------+
                |   Wazuh Dashboard    |
                +----------------------+

In enterprise environments, multiple Wazuh Managers and Indexer nodes may be deployed behind load balancers to provide high availability and horizontal scalability.

For larger infrastructures, see How to Set Up a Multi-Node Wazuh Cluster.

Prerequisites

Before installing Filebeat, verify that your Wazuh deployment satisfies the following requirements.

Supported Wazuh Version

Use a supported Wazuh release that matches the version of your Filebeat package and Wazuh Indexer.

Mixing incompatible component versions can lead to:

• Index template errors
• Authentication failures
• Dashboard issues
• Unsupported APIs
• Data ingestion failures

Always consult the official Wazuh compatibility matrix before upgrading components.

Filebeat Compatibility

Although Filebeat is developed by Elastic, Wazuh packages a version that is tested and validated for its platform.

Using an arbitrary upstream Filebeat release may result in:

• Module incompatibilities
• Incorrect index templates
• Unsupported configuration options
• Version conflicts

For this reason, it is generally recommended to install the Filebeat package provided by Wazuh rather than downloading a newer release directly from Elastic.

Wazuh Manager Installed

Filebeat depends on the Wazuh Manager because it reads the alert files generated by the manager.

Before continuing, verify that:

• The Wazuh Manager is running.
• Alerts are being generated.
• alerts.json exists.
• The manager has no startup errors.

You can confirm the service status with:

sudo systemctl status wazuh-manager

Wazuh Indexer Configured

Filebeat requires a functioning Wazuh Indexer before alerts can be forwarded.

Verify that:

• The indexer service is running.
• HTTPS is enabled.
• Authentication credentials are available.
• TLS certificates are installed.
• The cluster is healthy.

If your deployment uses multiple nodes, ensure all indexer hosts are reachable.

Root or sudo Privileges

Installing and configuring Filebeat requires administrative permissions because you’ll be:

• Installing packages
• Editing system configuration files
• Accessing certificate directories
• Restarting services
• Reading protected log files

Most commands throughout this guide should be executed using sudo.

Network Connectivity

The Wazuh Manager must be able to communicate with every configured Wazuh Indexer.

Verify:

• DNS resolution
• IP connectivity
• Firewall rules
• Routing
• TLS communication

Testing connectivity before configuration helps eliminate many common installation problems.

Required Ports

Depending on your deployment, the following ports are commonly required.

Your environment may use different ports if customized.

TLS Certificates Available

Secure communication between Filebeat and the Wazuh Indexer relies on TLS certificates.

Typically, you’ll need:

• Root CA certificate
• Client certificate (if required)
• Client private key
• Server certificate validation

Store certificates securely and ensure Filebeat has permission to read them.

The Center for Internet Security (CIS) recommends encrypting communications between infrastructure components to protect sensitive operational data.

How to Install Wazuh Filebeat

The installation process varies slightly depending on your Linux distribution, but the overall workflow remains the same.

Install on Linux

Begin by updating your system packages.

Debian/Ubuntu

sudo apt update
sudo apt upgrade -y

RHEL/CentOS/Rocky/AlmaLinux

sudo dnf update -y

or on older systems:

sudo yum update -y

Debian/Ubuntu

Install the Wazuh Filebeat package after adding the official Wazuh repository.

sudo apt install filebeat

Depending on your Wazuh installation method, additional configuration files and certificates may also be installed.

Refer to the official installation documentation for repository configuration instructions.

RHEL/CentOS/Rocky/AlmaLinux

Install Filebeat using DNF or YUM.

sudo dnf install filebeat

or

sudo yum install filebeat

Once installed, verify that the configuration files exist under:

/etc/filebeat/

Install on Offline Systems

Air-gapped environments require manually downloading the installation packages from a connected system.

A common workflow is:

1. Download the required RPM or DEB packages.
2. Transfer them using removable media.
3. Install using the local package manager.
4. Copy the required TLS certificates.
5. Configure Filebeat manually.
6. Validate connectivity.

Offline deployments should also verify package integrity before installation using published checksums whenever available.

Verify the Installation

Confirm that Filebeat has been installed successfully.

Check the installed version:

filebeat version

Verify the service exists:

sudo systemctl status filebeat

Expected output should indicate that the service is installed, even if it has not yet been started.

Configure Wazuh Filebeat

After installation, configure Filebeat to securely forward alerts to the Wazuh Indexer.

The primary configuration file is typically located at:

/etc/filebeat/filebeat.yml

Configure the Filebeat Output

The output section tells Filebeat where to send collected events.

A basic configuration resembles:

output.elasticsearch:
  hosts: ["https://indexer.example.com:9200"]

Production deployments commonly specify multiple indexer nodes for redundancy.

Indexer Hosts

For clustered environments, configure multiple hosts.

Example:

hosts:
  - https://indexer1.example.com:9200
  - https://indexer2.example.com:9200
  - https://indexer3.example.com:9200

Filebeat will automatically attempt alternative hosts if one becomes unavailable.

Authentication

Provide credentials that have permission to write indices.

Example:

username: admin
password: your_password

Consider using secure secrets management rather than storing plaintext credentials whenever possible.

SSL Certificates

Enable encrypted communication using TLS certificates.

Typical configuration:

ssl.certificate_authorities:
  - /etc/filebeat/certs/root-ca.pem

ssl.certificate: /etc/filebeat/certs/filebeat.pem

ssl.key: /etc/filebeat/certs/filebeat-key.pem

Proper certificate validation helps prevent man-in-the-middle attacks.

Configure Wazuh Modules

Wazuh supplies Filebeat modules optimized for ingesting Wazuh alerts.

Ensure the Wazuh module configuration matches:

• Index names
• Pipelines
• Templates
• TLS settings
• Authentication

Using the provided module reduces manual configuration and helps maintain compatibility with future upgrades.

Configure Inputs

Inputs specify which files Filebeat should monitor.

Typical examples include:

alerts.json
archives.json

Each input defines:

• File paths
• JSON parsing
• Multiline handling (if required)
• State tracking

Avoid configuring duplicate inputs for the same files, as this can result in duplicate indexed events.

Configure Processors

Processors enrich or modify events before they are sent.

Common processors include:

• add_host_metadata
• add_cloud_metadata
• add_fields
• drop_fields
• rename
• decode_json_fields

Processors should remain lightweight to preserve Filebeat’s performance advantages.

Enable the Wazuh Filebeat Module

Enable the Wazuh module if it is not already active.

Example:

sudo filebeat modules enable wazuh

After enabling the module, reload or restart Filebeat to apply the changes.

Validate the Configuration

Before starting Filebeat, validate the configuration syntax.

sudo filebeat test config

If successful, you should receive output similar to:

Config OK

Next, test connectivity to the Wazuh Indexer:

sudo filebeat test output

Finally, start the service:

sudo systemctl enable --now filebeat

If you encounter connectivity or authentication issues during validation, reviewing Resolving Filebeat Connection Refused Errors in Wazuh Deployments can help identify common causes and solutions.

Start and Enable the Filebeat Service

After configuring Filebeat, the next step is to start the service and verify that it can successfully communicate with the Wazuh Indexer.

Performing these validation steps immediately after installation helps identify configuration or connectivity problems before they impact production monitoring.

Start Filebeat

Start the Filebeat service using your system’s service manager.

sudo systemctl start filebeat

If you’re using a distribution that relies on the older SysV init system, use:

sudo service filebeat start

After starting the service, Filebeat immediately begins monitoring the configured Wazuh alert files and attempts to establish a secure connection to the configured Wazuh Indexer.

Enable Automatic Startup

To ensure Filebeat starts automatically after a system reboot, enable the service.

sudo systemctl enable filebeat

Expected output:

Created symlink /etc/systemd/system/multi-user.target.wants/filebeat.service

Automatic startup is particularly important for production environments, as it prevents interruptions in log forwarding after maintenance windows or unexpected server restarts.

Verify Service Status

Confirm that Filebeat is running correctly.

sudo systemctl status filebeat

A healthy service typically displays output similar to:

Active: active (running)

If the service fails to start, review the error messages shown by systemd before checking the Filebeat logs.

Common startup issues include:

• YAML syntax errors
• Invalid certificate paths
• Incorrect authentication credentials
• Missing permissions
• Network connectivity problems
• Incorrect output configuration

Confirm Successful Connection

Once Filebeat is running, verify that it can successfully communicate with the Wazuh Indexer.

Use the built-in output test:

sudo filebeat test output

A successful result resembles:

elasticsearch:
  parse url... OK
  connection... OK
  TLS... OK
  version... OK

If the connection test fails, verify:

• Indexer hostname
• DNS resolution
• Firewall rules
• TLS certificates
• Username and password
• Indexer availability

If you receive connection errors, see Resolving Filebeat Connection Refused Errors in Wazuh Deployments.

Verify That Wazuh Filebeat Is Working

Even if Filebeat starts successfully, it’s important to verify that events are actually reaching the Wazuh Indexer and appearing in the dashboard.

Check Filebeat Logs

The Filebeat logs provide detailed information about startup, configuration loading, connection attempts, and event forwarding.

On most Linux systems:

sudo journalctl -u filebeat -f

or

sudo tail -f /var/log/filebeat/filebeat

Look for messages indicating:

• Successful startup
• Output connection established
• Events published
• Bulk indexing completed
• No dropped events

Watch for recurring errors such as:

• TLS handshake failures
• Authentication errors
• Connection refused
• Certificate validation failures
• YAML parsing errors

Elastic recommends reviewing Filebeat logs first whenever troubleshooting ingestion problems.

Verify Index Creation

Next, verify that Filebeat has successfully created or written to the expected indices.

Using the Wazuh Indexer API:

curl -k -u admin:password https://INDEXER_IP:9200/_cat/indices?v

You should see Wazuh indices similar to:

wazuh-alerts-4.x-*

If no indices appear:

• Confirm Filebeat is publishing events.
• Verify output credentials.
• Ensure index templates were installed.
• Check Indexer health.

Problems related to index creation may also indicate cluster health issues. See How to Build a Wazuh Indexer Cluster.

Confirm Alerts Appear in the Wazuh Dashboard

Log in to the Wazuh Dashboard and navigate to:

Security Events or Threat Hunting (depending on your version).

Confirm that:

• New alerts appear.
• Timestamps are current.
• Agent information is populated.
• Severity levels are displayed.
• Searches return expected results.

If alerts exist in the Indexer but not the dashboard, investigate dashboard-specific issues such as:

• Missing index patterns
• Dashboard connectivity
• User permissions
• Data view configuration

If necessary, review Wazuh Dashboard Not Loading? Complete Troubleshooting Guide.

Test with Sample Security Events

One of the best ways to validate your configuration is to generate a known security event.

Examples include:

• Failed SSH login attempts
• Multiple failed Windows logins
• Creating a monitored file
• Triggering File Integrity Monitoring (FIM)
• Running wazuh-logtest
• Executing a custom detection rule

For example, on Linux:

ssh invaliduser@localhost

This should generate an authentication failure that appears in the Wazuh Dashboard within a few seconds.

Additional testing guides:

• How to Test Wazuh Rules
• How to Monitor Failed SSH Login Attempts Using Wazuh

Validate Data Ingestion

Finally, verify that data is flowing continuously rather than only during startup.

Indicators of healthy ingestion include:

• Increasing document counts
• New alerts arriving in real time
• Stable Filebeat service
• No indexing errors
• Low retry counts
• Healthy Indexer status

Long-term monitoring of ingestion rates can help detect performance bottlenecks before they become operational issues.

Configuring TLS Between Filebeat and the Wazuh Indexer

By default, communication between Filebeat and the Wazuh Indexer should be encrypted using Transport Layer Security (TLS).

Encryption protects sensitive security telemetry from interception while ensuring Filebeat communicates only with trusted Indexer nodes.

Proper TLS configuration is considered a security best practice for production deployments.

Certificate Requirements

A standard TLS deployment typically requires:

• Root Certificate Authority (CA)
• Server certificate
• Server private key
• Client certificate (optional or required depending on configuration)
• Client private key

These certificates establish trust between Filebeat and the Wazuh Indexer.

CA Certificates

Filebeat uses the Certificate Authority certificate to verify the identity of the Wazuh Indexer.

Example:

ssl.certificate_authorities:
  - /etc/filebeat/certs/root-ca.pem

Without the correct CA certificate, Filebeat cannot verify that it is communicating with a trusted server.

Client Certificates

Some deployments require mutual TLS (mTLS), where both the client and server authenticate each other.

Example:

ssl.certificate: /etc/filebeat/certs/filebeat.pem

ssl.key: /etc/filebeat/certs/filebeat-key.pem

Mutual TLS provides stronger authentication than username/password authentication alone.

The OWASP Transport Layer Security Cheat Sheet recommends mutual authentication for sensitive internal services when practical.

Certificate Verification Modes

Filebeat supports several certificate verification modes.

For production environments, always use:

ssl.verification_mode: full

Disabling verification exposes your deployment to potential man-in-the-middle attacks.

Common SSL Configuration Options

A typical secure configuration includes:

output.elasticsearch:
  hosts: ["https://indexer.example.com:9200"]

  ssl.certificate_authorities:
    - /etc/filebeat/certs/root-ca.pem

  ssl.certificate:
    /etc/filebeat/certs/filebeat.pem

  ssl.key:
    /etc/filebeat/certs/filebeat-key.pem

  ssl.verification_mode: full

Always protect private keys with appropriate file permissions to prevent unauthorized access.

Testing Encrypted Connections

After configuring TLS, verify the encrypted connection.

sudo filebeat test output

You can also inspect the certificate presented by the Wazuh Indexer using OpenSSL:

openssl s_client -connect INDEXER_IP:9200

Successful validation confirms:

• TLS negotiation succeeds.
• The certificate chain is trusted.
• Hostname validation passes.
• Authentication completes successfully.

Customizing Wazuh Filebeat

Although the default Filebeat configuration works well for most deployments, organizations often customize it to improve performance, reduce storage consumption, or enrich indexed security events.

Adjust Logging Levels

Filebeat supports multiple logging levels.

Common values include:

• error
• warning
• info
• debug

Example:

logging.level: info

Use debug temporarily when troubleshooting configuration or connectivity issues, as verbose logging can significantly increase disk usage.

Configure Index Naming

Organizations may customize index names to support:

• Multiple environments
• Business units
• Geographic regions
• Compliance requirements
• Separate retention policies

Example:

output.elasticsearch.index: "wazuh-alerts-production-%{+yyyy.MM.dd}"

Be sure that any custom naming scheme is accompanied by appropriate index templates and lifecycle policies.

Modify Output Settings

Filebeat allows you to tune how events are sent to the Wazuh Indexer.

Common output parameters include:

• Bulk size
• Compression level
• Worker threads
• Timeout values
• Retry intervals
• Load balancing

These settings can improve indexing performance in high-volume environments but should be adjusted based on testing rather than guesswork.

Tune Queue Settings

Filebeat uses internal queues to buffer events before sending them.

Important queue parameters include:

• Queue type
• Queue size
• Flush interval
• Batch size
• Retry behavior

Larger queues can improve throughput during traffic spikes but also increase memory usage.

Monitor system resources when making changes.

Add Custom Processors

Processors can enrich or modify events before they are indexed.

Frequently used processors include:

• add_host_metadata
• add_cloud_metadata
• add_fields
• drop_fields
• rename
• decode_json_fields
• timestamp

Keep processor chains as simple as possible to preserve Filebeat’s lightweight design.

Exclude Unnecessary Events

Forwarding every available event may consume unnecessary storage and processing resources.

You can reduce noise by:

• Dropping low-value events
• Excluding test environments
• Filtering debug logs
• Ignoring temporary files
• Removing unused fields

Reducing unnecessary ingestion also helps lower storage requirements and improve search performance.

For additional strategies, see How to Reduce False Positives in Wazuh.

Optimize Performance

For high-volume deployments, consider the following best practices:

• Increase bulk indexing sizes gradually.
• Use multiple Indexer nodes for load distribution.
• Monitor Filebeat CPU and memory usage.
• Keep Filebeat and Wazuh versions compatible.
• Regularly review queue utilization and retry counts.
• Avoid unnecessary processors and duplicate inputs.
• Test configuration changes in a staging environment before deploying to production.

Elastic advises monitoring ingestion metrics and tuning Filebeat incrementally, as overly aggressive performance settings can reduce stability rather than improve throughput.

Performance Optimization Best Practices

A default Filebeat configuration works well for many environments, but organizations processing hundreds of thousands, or even millions, of events per day can benefit from additional tuning.

Optimizing Filebeat helps improve throughput, reduce latency, and maintain reliable event delivery without overwhelming the Wazuh Indexer.

As with any performance tuning, make changes incrementally and monitor the impact before applying them across production systems.

Tune Memory Queue Settings

Filebeat uses an internal memory queue to temporarily store events before they are sent to the Wazuh Indexer.

A larger queue can:

• Improve throughput during traffic spikes
• Reduce the number of network requests
• Buffer events during short Indexer slowdowns

However, increasing queue sizes also consumes additional memory.

Example configuration:

queue.mem:
  events: 8192
  flush.min_events: 2048
  flush.timeout: 5s

Choose queue sizes based on your available system resources and expected event volume.

Configure Bulk Indexing

Rather than sending every event individually, Filebeat batches multiple events into bulk requests.

Advantages include:

• Reduced network overhead
• Faster indexing
• Lower CPU usage
• Improved overall throughput

Common tuning parameters include:

• Bulk size
• Flush interval
• Compression
• Worker count

Increasing batch sizes can improve performance, but batches that are too large may increase memory usage and retry times if failures occur.

Optimize Worker Threads

Filebeat can use multiple worker threads to send events concurrently.

For high-volume deployments:

• Increase workers gradually.
• Monitor CPU utilization.
• Observe Indexer performance.
• Avoid creating more workers than the Indexer can efficiently process.

Adding workers improves throughput only when the receiving infrastructure has sufficient capacity.

Adjust Backoff Settings

When Filebeat cannot communicate with the Wazuh Indexer, it uses an exponential backoff algorithm before retrying.

Properly tuning backoff settings can:

• Reduce unnecessary connection attempts
• Lower network congestion
• Improve recovery during temporary outages

Typical parameters include:

• Initial retry delay
• Maximum retry delay
• Retry intervals

Aggressive retry settings generally provide little benefit and may increase load during outages.

Minimize Unnecessary Processing

Filebeat is intentionally lightweight.

Avoid adding excessive processors or complex transformations unless absolutely necessary.

Examples of unnecessary processing include:

• Multiple field renames
• Large processor chains
• Repeated JSON decoding
• Complex conditional filtering

If extensive event transformation is required, consider introducing Logstash into the pipeline instead of overloading Filebeat.

Monitor Throughput

Performance tuning should always be guided by measurable metrics.

Monitor:

• Events per second
• Published events
• Retry counts
• Queue utilization
• CPU usage
• Memory consumption
• Indexing latency
• Network throughput

Tracking these metrics over time makes it easier to identify bottlenecks before they affect data ingestion.

Elastic provides built-in monitoring capabilities for Beats that can help visualize publishing rates and resource utilization.

Plan for High-Volume Environments

Large enterprise deployments require planning beyond Filebeat itself.

Consider:

• Multiple Wazuh Managers
• Load-balanced Filebeat outputs
• Clustered Wazuh Indexers
• Fast SSD storage
• Dedicated monitoring networks
• Adequate CPU and RAM
• Index lifecycle management

Capacity planning should account for both current and projected event volumes to avoid unexpected performance bottlenecks.

If your deployment is growing rapidly, review Step-by-Step Wazuh Manager Scaling Guide and How to Set Up a Multi-Node Wazuh Cluster.

Common Wazuh Filebeat Problems

Even with a correct installation, configuration errors, network issues, or infrastructure problems can prevent Filebeat from successfully forwarding events.

The following are some of the most common issues encountered in Wazuh deployments and how to resolve them.

Filebeat Service Fails to Start

If the Filebeat service will not start, begin by checking its status and recent log messages.

sudo systemctl status filebeat

Then review the service logs:

sudo journalctl -u filebeat -xe

Common causes include:

• Invalid YAML syntax
• Missing configuration files
• Incorrect file permissions
• Invalid module configuration
• Missing SSL certificates
• Unsupported configuration directives

Run a configuration validation before restarting the service:

sudo filebeat test config

Connection Refused to Wazuh Indexer

A “connection refused” error indicates that Filebeat cannot establish a TCP connection to the configured Indexer.

Possible causes include:

• Incorrect hostname
• Incorrect port
• Firewall restrictions
• Indexer service stopped
• Network routing issues
• DNS resolution failures

Verify connectivity with:

curl -k https://INDEXER_IP:9200

or

nc -vz INDEXER_IP 9200

For a detailed troubleshooting guide, see Resolving Filebeat Connection Refused Errors in Wazuh Deployments.

SSL Certificate Errors

TLS-related errors are among the most common Filebeat configuration issues.

Typical messages include:

• Unknown certificate authority
• Certificate expired
• Hostname mismatch
• Invalid certificate chain
• TLS handshake failure

Verify:

• Certificate paths
• File permissions
• Certificate expiration dates
• Hostname matching
• Trusted CA configuration

Avoid disabling certificate verification except for temporary testing.

Authentication Failures

Authentication errors usually occur when Filebeat cannot authenticate to the Wazuh Indexer.

Common causes include:

• Incorrect username
• Incorrect password
• Disabled account
• Missing privileges
• Authentication backend issues

Use the built-in connectivity test:

sudo filebeat test output

Successful authentication should complete without errors before Filebeat begins forwarding events.

Events Not Appearing in the Dashboard

If Filebeat reports successful publishing but no alerts appear in the Wazuh Dashboard, investigate the entire ingestion pipeline.

Check:

• Filebeat logs
• Index creation
• Dashboard index patterns
• User permissions
• Time filters
• Indexer health

Determine whether events are missing from the Indexer or only from the dashboard interface.

If necessary, consult Wazuh Dashboard Not Loading? Complete Troubleshooting Guide.

Index Not Being Created

When Filebeat cannot create indices, possible causes include:

• Missing templates
• Authentication failures
• Read-only indices
• Cluster health issues
• Insufficient permissions
• Disk watermark restrictions

Review the Indexer logs and verify cluster health using:

curl -k -u admin:password https://INDEXER_IP:9200/_cluster/health?pretty

A yellow or red cluster state may indicate underlying infrastructure issues that prevent successful indexing.

High CPU or Memory Usage

Although Filebeat is lightweight, excessive resource usage can occur when:

• Too many processors are configured
• Very large queues are used
• Debug logging is enabled
• Massive log volumes are processed
• Numerous files are monitored simultaneously

Monitor resource consumption using tools such as:

top

or

htop

If the bottleneck lies elsewhere in the deployment, also review Why Is Wazuh Using High CPU? Troubleshooting Guide.

Duplicate Events

Duplicate alerts are often caused by configuration errors rather than Filebeat itself.

Typical causes include:

• Duplicate inputs
• Multiple Filebeat instances
• Incorrect registry handling
• Shared log directories
• Misconfigured log rotation

Carefully review your input definitions to ensure each log file is monitored only once.

Configuration Validation Errors

Filebeat validates its configuration before startup.

Run:

sudo filebeat test config

Frequent validation errors include:

• Incorrect indentation
• Invalid YAML syntax
• Unsupported options
• Typographical errors
• Missing required fields

Using a YAML-aware editor with syntax validation can help prevent many configuration mistakes.

Wazuh Filebeat Best Practices

Following established operational and security best practices helps ensure Filebeat remains reliable, secure, and easy to maintain as your Wazuh deployment grows.

Always Use TLS Encryption

All communication between Filebeat and the Wazuh Indexer should be encrypted using TLS.

Benefits include:

• Protecting sensitive security events in transit
• Preventing man-in-the-middle attacks
• Verifying server identity
• Supporting compliance requirements

Use full certificate verification whenever possible.

Rotate Certificates Regularly

Certificates should be rotated before they expire.

Establish a documented certificate management process that includes:

• Renewal schedules
• Automated monitoring
• Secure key storage
• Revocation procedures
• Testing after certificate replacement

The National Institute of Standards and Technology (NIST) recommends strong certificate and key management practices as part of secure system administration.

Keep Filebeat Updated

Regular updates provide:

• Security patches
• Bug fixes
• Performance improvements
• Compatibility with newer Wazuh releases

Before upgrading, verify compatibility with your installed Wazuh Manager and Wazuh Indexer versions.

Test upgrades in a staging environment before deploying to production.

Monitor Filebeat Health

Regularly monitor:

• Service status
• Published events
• Queue size
• Retry counts
• Resource utilization
• Connection health
• Error logs

Automated monitoring allows administrators to detect issues before they affect security visibility.

Use Least-Privilege Permissions

Run Filebeat with only the permissions required to:

• Read Wazuh alert files
• Access TLS certificates
• Communicate with the Wazuh Indexer

Avoid granting unnecessary administrative privileges, as limiting access reduces the potential impact of a compromised service.

Validate Configuration Before Deployment

Every configuration change should be validated before restarting the service.

Use:

sudo filebeat test config

and

sudo filebeat test output

Testing configuration changes before deployment helps reduce downtime and prevents avoidable production incidents.

Monitor Ingestion Rates

Regularly review ingestion metrics to ensure Filebeat is keeping pace with incoming events.

Monitor trends such as:

• Events published per second
• Bulk request latency
• Queue utilization
• Failed publishes
• Retry frequency

Unexpected changes may indicate infrastructure problems or configuration issues that require investigation.

Regularly Review Logs

Routine log reviews can reveal:

• Connection issues
• Authentication failures
• Configuration warnings
• TLS problems
• Resource constraints

Incorporating Filebeat log reviews into regular operational procedures helps identify emerging issues before they affect data collection.

Back Up Configuration Files

Maintain backups of important Filebeat configuration files, including:

• filebeat.yml
• Module configurations
• TLS certificates (stored securely)
• Custom processors
• Input definitions

Version-controlling configuration files and backing them up before making changes simplifies recovery and supports change management.

For broader disaster recovery planning, see How to Backup Wazuh Manager Configuration.

Real-World Example

Scenario

A global manufacturing company operates multiple production facilities across different regions, each running its own Wazuh Manager instance to monitor critical infrastructure.

The environment includes thousands of endpoints such as Windows servers, Linux systems, firewalls, network devices, and industrial control systems.

Each Wazuh Manager processes a large volume of security events every day, including:

• Failed authentication attempts
• Malware detection alerts
• File Integrity Monitoring (FIM) changes
• Privilege escalation attempts
• Suspicious network activity
• Compliance-related events

To ensure that security analysts have centralized visibility, the organization deploys Filebeat on every Wazuh Manager. Filebeat is configured to securely forward alerts and archived events to a centralized Wazuh Indexer cluster using TLS encryption.

The deployment architecture looks like this:

Production Facility 1
      |
      ▼
Wazuh Manager
      |
      ▼
Filebeat
      |
      |
      ▼
+--------------------+
| Wazuh Indexer      |
| Cluster            |
|                    |
| Node 1             |
| Node 2             |
| Node 3             |
+--------------------+
      |
      ▼
Wazuh Dashboard


Production Facility 2
      |
      ▼
Wazuh Manager
      |
      ▼
Filebeat
      |
      ▼
Central Indexer Cluster

Initially, the security team experienced delayed alert visibility during periods of increased activity.

Large security events, such as malware outbreaks or vulnerability scans, caused temporary spikes in event volume.

To improve reliability, the team implemented several Filebeat optimizations:

• Increased Filebeat memory queue capacity to handle traffic spikes.
• Enabled load balancing across multiple Wazuh Indexer nodes.
• Tuned bulk indexing parameters to improve ingestion speed.
• Configured TLS certificates for encrypted event transmission.
• Monitored Filebeat logs and ingestion metrics continuously.

After these improvements, the organization achieved near real-time security visibility across all production facilities.

During peak security events, Filebeat’s buffering and retry mechanisms prevented alert loss by temporarily storing events until the Wazuh Indexer could process the incoming workload.

The final deployment provided:

• Reliable centralized alert collection
• Faster incident investigation
• Reduced indexing delays
• Improved resilience during outages
• Lower resource consumption on Wazuh Managers

This example demonstrates why Filebeat is a critical component in large-scale Wazuh deployments where reliability, scalability, and secure event transport are required.

Frequently Asked Questions (FAQ)

Question: What Is Wazuh Filebeat?

Wazuh Filebeat is the log shipping component used to transfer security events from the Wazuh Manager to the Wazuh Indexer.

Filebeat monitors Wazuh-generated alert files, processes new events, and securely forwards them for indexing and visualization in the Wazuh Dashboard.

It acts as the communication layer between:

Wazuh Manager → Filebeat → Wazuh Indexer → Wazuh Dashboard

Question: Why Does Wazuh Use Filebeat?

Wazuh uses Filebeat because it provides a lightweight and reliable method for transferring security events.

Key advantages include:

• Low CPU and memory usage
• Secure TLS communication
• Automatic retry handling
• Event buffering
• Reliable log forwarding
• Native integration with Elasticsearch/OpenSearch-based indexing systems

Without Filebeat, Wazuh alerts would not be efficiently transported from the manager to the indexing layer.

Question: Does Every Wazuh Manager Require Filebeat?

In most standard Wazuh deployments, each Wazuh Manager that sends alerts to a Wazuh Indexer requires Filebeat.

For example:

Wazuh Manager 1
      |
   Filebeat
      |
      ▼
Wazuh Indexer


Wazuh Manager 2
      |
   Filebeat
      |
      ▼
Wazuh Indexer

However, deployment designs may vary depending on architecture, such as clustered managers, centralized log forwarding, or custom ingestion pipelines.

Question: Can Filebeat Send Data to Multiple Wazuh Indexers?

Yes.

Filebeat can be configured with multiple Wazuh Indexer hosts.

Example:

output.elasticsearch:
  hosts:
    - https://indexer1.example.com:9200
    - https://indexer2.example.com:9200
    - https://indexer3.example.com:9200

Using multiple Indexer nodes improves:

• High availability
• Fault tolerance
• Load distribution
• Recovery during node failures

For large deployments, combining Filebeat with a Wazuh Indexer cluster provides better scalability.

See How to Build a Wazuh Indexer Cluster.

Question: How Do I Verify That Filebeat Is Sending Alerts?

You can verify Filebeat operation using several methods.

Check the service:

sudo systemctl status filebeat

Test Indexer connectivity:

sudo filebeat test output

Review logs:

sudo journalctl -u filebeat -f

You can also confirm that alerts are appearing in the Wazuh Dashboard.

Question: Where Is the Filebeat Configuration File Located?

The primary Filebeat configuration file is normally located at:

/etc/filebeat/filebeat.yml

Additional configuration files may exist under:

/etc/filebeat/modules.d/

These files control:

• Outputs
• Inputs
• Modules
• Processors
• Logging options
• TLS configuration

Question: How Do I Restart Wazuh Filebeat?

Restart Filebeat using:

sudo systemctl restart filebeat

After restarting, verify that it started successfully:

sudo systemctl status filebeat

For troubleshooting, check:

sudo journalctl -u filebeat -xe

Question: Can I Customize What Filebeat Sends?

Yes.

Filebeat can be customized to control:

• Which files are monitored
• Which fields are included
• Which events are filtered
• Output destinations
• Processing rules
• Index naming

Examples of customization include:

• Excluding low-value events
• Adding custom metadata
• Removing unnecessary fields
• Creating custom ingestion workflows

However, avoid excessive processing inside Filebeat because complex transformations can reduce performance.

Question: Is Filebeat Required in the Latest Versions of Wazuh?

Yes, Filebeat remains an important component in traditional Wazuh deployments that use the Wazuh Indexer architecture.

It provides the transport layer between the Wazuh Manager and the indexing backend.

However, deployment requirements may change between Wazuh versions, so administrators should always review the official Wazuh documentation when planning upgrades or new installations.

Question: How Do I Troubleshoot Filebeat Connection Issues?

Start troubleshooting by checking the Filebeat service:

sudo systemctl status filebeat

Then validate the configuration:

sudo filebeat test config

Test connectivity:

sudo filebeat test output

Common causes of connection problems include:

• Incorrect Indexer hostname
• Firewall restrictions
• Invalid TLS certificates
• Incorrect credentials
• Indexer service failures
• Network connectivity issues

For detailed troubleshooting steps, see Resolving Filebeat Connection Refused Errors in Wazuh Deployments.

Conclusion

Wazuh Filebeat plays a critical role in delivering security events from the Wazuh Manager to the Wazuh Indexer.

By acting as a secure and reliable transport layer, Filebeat enables organizations to centralize security monitoring, investigate threats faster, and maintain visibility across large environments.

A successful Wazuh Filebeat deployment requires several key steps:

• Installing Filebeat on Wazuh Managers
• Configuring Indexer connectivity
• Setting up TLS encryption
• Enabling the Wazuh module
• Validating event ingestion
• Monitoring Filebeat health
• Optimizing performance for expected workloads

For production environments, security teams should prioritize encrypted communication, proper certificate management, regular configuration backups, and continuous monitoring of ingestion performance.

Organizations managing larger deployments should also tune Filebeat carefully by adjusting queue settings, optimizing bulk indexing, and distributing workloads across multiple Wazuh Indexer nodes.

By following these best practices, administrators can build a scalable and resilient Wazuh logging pipeline that provides reliable alert delivery and consistent security visibility across the entire infrastructure.