As your Wazuh deployment grows from a handful of endpoints to thousands of servers, workstations, cloud instances, and containers, a single Wazuh manager can eventually become a bottleneck.

Increased event volume, larger File Integrity Monitoring (FIM) databases, vulnerability scans, and active response actions all place additional load on the manager.

A multi-node Wazuh cluster solves these challenges by distributing workloads across multiple servers while maintaining centralized management and synchronized configurations.

Unlike a standalone installation, a multi-node Wazuh cluster consists of one master node and one or more worker nodes that collaborate to process security events.

The master node coordinates cluster operations and synchronizes critical configuration data, while worker nodes handle agent communication and event processing.

This architecture improves scalability, fault tolerance, and operational flexibility for medium to large enterprise environments.

Organizations operating Security Operations Centers (SOCs), Managed Security Service Providers (MSSPs), and large enterprises commonly deploy clustered Wazuh environments to ensure consistent performance as their infrastructure expands.

According to the National Institute of Standards and Technology (NIST), designing systems with redundancy, resilience, and fault tolerance is a core principle for maintaining secure and available services.

Throughout this guide, you’ll learn how to build a production-ready multi-node Wazuh cluster, configure synchronization between nodes, verify cluster health, troubleshoot common deployment issues, and apply best practices for long-term stability.

If you’re new to the indexing layer, you may also want to read How to Build a Wazuh Indexer Cluster before configuring the manager cluster.

What Is a Multi-Node Wazuh Cluster?

A multi-node Wazuh cluster is a distributed deployment consisting of multiple Wazuh manager instances that work together as a single logical management system.

Instead of relying on one server to process every agent connection and security event, cluster members divide responsibilities while remaining synchronized.

The cluster always contains:

One master node
One or more worker nodes
Multiple connected Wazuh agents
A shared indexing layer (typically a Wazuh Indexer cluster)
A Wazuh Dashboard for management and visualization

The master node manages cluster synchronization and distributes configuration updates to worker nodes.

Worker nodes receive events from agents, execute analysis, and forward indexed data to the Wazuh Indexer.

Unlike traditional active/passive high availability systems where backup servers remain idle, Wazuh worker nodes actively participate in processing workloads, allowing organizations to scale horizontally by simply adding additional workers.

According to the official Wazuh documentation, clustering enables centralized management while distributing event processing across multiple managers.

Benefits of Clustering Wazuh

A clustered deployment provides significant advantages over running a single Wazuh manager.

Improved Scalability

Additional worker nodes allow the environment to support significantly more agents without overwhelming a single server.

Instead of upgrading one increasingly powerful server, organizations can scale horizontally by deploying additional workers.

Better Performance

Incoming events are distributed across multiple managers, reducing CPU utilization, memory pressure, and disk I/O on individual systems.

This becomes particularly valuable in environments processing:

Millions of daily events
Large FIM databases
High-frequency vulnerability scans
Heavy active response activity

Higher Availability

If one worker becomes unavailable, agents can reconnect to another available worker when supported by appropriate load balancing or failover mechanisms.

Although the master node remains essential for synchronization, worker redundancy minimizes service disruption during maintenance.

Simplified Management

Configuration changes, including rules, decoders, agent groups, and shared files, are maintained centrally and synchronized automatically.

Administrators no longer need to manually update every Wazuh manager.

Easier Maintenance

Clustered environments allow administrators to:

Upgrade nodes gradually
Perform maintenance without stopping the entire platform
Replace hardware with minimal downtime
Expand capacity without major architectural changes

When You Should Deploy a Multi-Node Cluster

A standalone Wazuh manager is sufficient for many small deployments.

However, larger environments benefit substantially from clustering.

Consider deploying a multi-node cluster if you:

Monitor thousands of endpoints
Collect logs from multiple geographic locations
Operate multiple data centers
Experience high CPU utilization on the manager
Require higher availability
Need easier horizontal scaling
Plan significant future infrastructure growth

A clustered architecture is especially valuable for:

Enterprise SOCs
MSSPs
Government agencies
Financial institutions
Healthcare organizations
Large cloud environments
Hybrid cloud deployments

If you’re primarily scaling your endpoint infrastructure, our Ultimate Wazuh Agent Deployment Guide complements this article.

What You’ll Learn in This Guide

By the end of this tutorial, you’ll understand how to:

Design a production-ready multi-node Wazuh cluster
Prepare your infrastructure before installation
Configure master and worker nodes correctly
Synchronize rules, decoders, agent groups, and shared files
Connect the cluster to a Wazuh Indexer deployment
Validate cluster synchronization
Troubleshoot common clustering issues
Apply security and operational best practices for long-term reliability

Whether you’re deploying your first clustered environment or expanding an existing installation, this guide provides the foundation needed to build a scalable and resilient Wazuh infrastructure.

Understanding Wazuh Cluster Architecture

A successful multi-node deployment begins with understanding how the various Wazuh components communicate.

Unlike a standalone installation where every service runs on a single server, a clustered deployment distributes responsibilities across multiple nodes while keeping configuration and management synchronized.

The architecture is designed to improve scalability without sacrificing centralized administration, allowing security teams to manage large numbers of agents through a unified platform.

What Is a Wazuh Cluster?

A Wazuh cluster is a collection of Wazuh manager nodes that operate together as one logical deployment.

Each node performs specific responsibilities while maintaining synchronization with the rest of the cluster.

A standard deployment includes:

One master manager
One or more worker managers
Wazuh agents
Wazuh Indexer cluster
Wazuh Dashboard

The cluster is responsible for ensuring that every manager shares identical detection logic, configuration files, agent information, and operational data.

Purpose of Clustering

The primary goal of clustering is to remove the limitations of a single Wazuh manager.

Rather than processing every event on one server, workloads can be distributed among multiple managers while maintaining centralized configuration.

This enables organizations to:

Support larger deployments
Improve processing performance
Simplify administration
Increase operational resilience
Expand infrastructure without redesigning the environment

High Availability vs Scalability

Although these terms are often used together, they solve different problems.

High Availability

High availability minimizes downtime by ensuring services remain accessible if one component becomes unavailable.

Examples include:

Redundant worker nodes
Load-balanced agent connections
Highly available indexer nodes

Scalability

Scalability focuses on increasing system capacity.

Instead of replacing hardware with larger servers, organizations add additional worker nodes as demand increases.

Horizontal scaling generally provides greater flexibility and lower long-term infrastructure costs.

Manager Synchronization

One of the most important responsibilities of the cluster is synchronization.

The master node distributes critical configuration changes so that every worker processes events using identical detection logic.

Without synchronization:

Rules may differ between managers.
Alerts become inconsistent.
Agent behavior becomes unpredictable.
Security investigations become unreliable.

Automatic synchronization ensures every node behaves consistently.

Components of a Multi-Node Wazuh Cluster

Several components work together to deliver a complete clustered deployment.

Master Node

The master node coordinates cluster operations.

Its responsibilities include:

Managing cluster membership
Synchronizing configuration files
Distributing rules and decoders
Maintaining shared agent information
Coordinating worker communication

Although the master participates in event processing, its primary responsibility is cluster management.

Worker Nodes

Worker nodes handle much of the operational workload.

Typical responsibilities include:

Receiving agent connections
Processing security events
Running decoders
Applying detection rules
Executing active responses
Forwarding alerts to the indexer

Additional workers can be added as infrastructure grows.

Wazuh Agents

Agents collect security data from monitored endpoints.

Common data sources include:

System logs
Windows Event Logs
Linux logs
File Integrity Monitoring
Security Configuration Assessment
Vulnerability Detection
Process monitoring

Agents communicate with available manager nodes rather than directly with the master.

For endpoint deployment guidance, see The Ultimate Wazuh Agent Deployment Guide.

Wazuh Indexer

The Wazuh Indexer stores alerts and indexed security data generated by managers.

It provides:

Fast searching
Long-term storage
Dashboard queries
Analytics
Correlation

Large environments commonly deploy the indexer itself as a separate cluster.

For more information, see How to Build a Wazuh Indexer Cluster.

Wazuh Dashboard

The Dashboard provides the graphical interface for administrators.

It communicates with:

Wazuh API
Wazuh Indexer

Administrators use it to:

Search alerts
View dashboards
Manage agents
Monitor cluster health
Configure rules
Investigate incidents

Filebeat/OpenSearch Communication

After managers generate alerts, Filebeat forwards the data to the Wazuh Indexer (OpenSearch-based).

The overall flow is:

Agent → Manager → Filebeat → Wazuh Indexer → Dashboard

This separation allows indexing to scale independently from event analysis.

How Cluster Synchronization Works

The master node periodically synchronizes important operational data with worker nodes.

Synchronization is automatic and minimizes administrative overhead.

Rules Synchronization

Custom detection rules created on the master are copied to workers.

This guarantees identical alert generation throughout the cluster.

If you plan to customize detections, see How to Create Custom Detection Rules in Wazuh (With Examples).

Decoders

Custom decoders are synchronized so every node parses logs consistently.

Without synchronized decoders, identical logs could generate different alerts depending on the worker processing them.

Agent Information

Agent metadata, including registration details and keys, is synchronized across managers to maintain consistent endpoint management.

Group Configurations

Agent group assignments are replicated throughout the cluster.

This ensures centralized configuration changes are applied consistently regardless of which worker an agent contacts.

Shared Configuration Files

Additional shared resources, including configuration files and cluster-managed content, are synchronized automatically from the master.

Communication Between Nodes

Reliable communication between cluster members is essential for synchronization and healthy operation.

Cluster Protocol

Cluster nodes communicate using Wazuh’s built-in synchronization protocol over dedicated cluster connections.

This protocol transfers:

Configuration updates
Agent metadata
Cluster status
Synchronization information

Ports Used

A typical clustered deployment requires ports for:

Agent communication
Cluster synchronization
Wazuh API
Filebeat
OpenSearch
Dashboard access

Always verify the required ports for your installed Wazuh version using the official documentation before deployment.

Authentication

Cluster members authenticate using a shared cluster key configured within the Wazuh cluster configuration.

Only trusted nodes possessing the correct credentials are permitted to join the cluster.

Certificates and Secure Communication

Production environments should always encrypt communication between cluster components.

This includes:

Manager-to-worker communication
Filebeat to Indexer
Dashboard to Indexer
Dashboard to API

Security experts, including guidance from the Center for Internet Security (CIS), recommend encrypting management traffic and implementing strong authentication for distributed infrastructure to reduce the risk of interception and unauthorized access.

Prerequisites

Proper planning before installation significantly reduces deployment issues later.

Every node should meet the same baseline requirements to ensure reliable synchronization, predictable performance, and smooth upgrades.

Hardware Requirements

Hardware requirements vary depending on:

Number of monitored endpoints
Daily event volume
Enabled Wazuh modules
Retention policies
Indexing workload

At a minimum, every manager should have:

Multi-core CPU
Adequate RAM (8 GB minimum for small deployments; considerably more for production environments)
Fast SSD storage
Reliable network connectivity

Large environments should size infrastructure according to expected event rates rather than only the number of agents.

Supported Operating Systems

All manager nodes should run supported Linux distributions listed in the Wazuh compatibility matrix.

Using identical operating systems across nodes simplifies administration and troubleshooting.

Supported platforms commonly include:

Ubuntu Server
Debian
Red Hat Enterprise Linux
Rocky Linux
AlmaLinux
Oracle Linux

Always verify support before deployment.

Network Requirements

Reliable networking is essential because cluster synchronization depends on constant communication.

Recommendations include:

Low latency between managers
Stable network connectivity
Static IP addresses
Reliable DNS resolution
Minimal packet loss

Deploy cluster nodes within trusted internal networks whenever possible.

DNS and Hostname Configuration

Every node should have:

Unique hostname
Static hostname
Forward DNS resolution
Reverse DNS resolution (recommended)

Consistent hostname resolution simplifies cluster configuration and troubleshooting.

Firewall Ports

Firewalls must permit communication between:

Agents and managers
Managers and workers
Managers and Indexer
Dashboard and Indexer
Dashboard and API

Blocking cluster communication often results in synchronization failures or disconnected workers.

Time Synchronization (NTP)

Accurate system time is critical.

Clock drift between managers can cause synchronization problems, inconsistent timestamps, and authentication issues.

Configure every node to synchronize with the same reliable NTP source before building the cluster.

This recommendation aligns with security guidance from both NIST and industry best practices for distributed systems.

If you’ve experienced synchronization problems before, see Fixing Wazuh Cluster Desync Caused by Master-Worker Time Drift.

Installing the Same Wazuh Version on Every Node

Every manager in the cluster must run the exact same Wazuh version.

Mixing versions can introduce:

Synchronization failures
Configuration incompatibilities
API differences
Unexpected cluster behavior

Before joining nodes to the cluster:

Install the identical Wazuh release on every manager.
Verify package versions.
Confirm all dependencies match.
Apply the latest supported patches consistently across every node.

If you’re upgrading an existing deployment before clustering, review How to Upgrade a Wazuh Agent for endpoint compatibility considerations.

Planning Your Multi-Node Deployment

Careful planning is the foundation of a reliable multi-node Wazuh cluster.

Decisions made before installation, such as the number of manager nodes, network layout, and load balancing strategy, have a significant impact on scalability, availability, and long-term maintenance.

A well-designed deployment should not only meet your current requirements but also provide enough flexibility to accommodate future growth without requiring a complete redesign.

Choosing the Number of Manager Nodes

The optimal number of manager nodes depends on several factors, including:

Number of monitored endpoints
Expected daily event volume
Geographic distribution of endpoints
High availability requirements
Future growth projections

A common deployment pattern is:

Deployment Size	Recommended Cluster
Small (up to ~2,000 agents)	1 Master + 1 Worker
Medium (2,000–10,000 agents)	1 Master + 2–3 Workers
Large Enterprise	1 Master + Multiple Workers (scaled as needed)

Rather than sizing your cluster solely based on the number of agents, estimate the expected events per second (EPS).

A few hundred high-volume servers can generate significantly more load than thousands of lightly used workstations.

As a general best practice, begin with the minimum number of worker nodes needed for current workloads and add additional workers as utilization increases.

Selecting Master and Worker Roles

Each Wazuh manager must be assigned a specific role within the cluster.

Master Node

The master node is responsible for:

Managing cluster synchronization
Maintaining cluster membership
Synchronizing rules and decoders
Distributing shared configuration files
Coordinating worker communication

Although the master can process events, production environments typically avoid routing the majority of agent traffic directly to it.

Reserving resources for synchronization helps improve overall cluster stability.

Worker Nodes

Worker nodes perform the bulk of operational processing, including:

Receiving agent connections
Collecting endpoint events
Applying decoders and rules
Executing active responses
Forwarding alerts to the Wazuh Indexer

Adding worker nodes is the primary method of horizontally scaling a Wazuh deployment.

Designing for High Availability

High availability (HA) ensures that your monitoring infrastructure remains operational even if an individual component becomes unavailable.

For a resilient deployment, consider the following:

Deploy multiple worker nodes.
Eliminate single points of failure where possible.
Use redundant network paths.
Deploy multiple Wazuh Indexer nodes.
Back up configuration files regularly.
Monitor cluster health continuously.

It’s important to understand that the Wazuh manager cluster improves resilience but is only one part of the overall architecture.

For true high availability, you should also build redundancy into supporting components such as the Wazuh Indexer, Dashboard, and load balancers.

The Center for Internet Security (CIS) recommends designing security infrastructure with redundant services to minimize operational disruption during hardware failures or maintenance windows.

Load Balancing Options

In a clustered deployment, agents typically connect through a load balancer instead of being manually assigned to individual worker nodes.

Common load balancing solutions include:

HAProxy

HAProxy is one of the most widely used TCP load balancers for Wazuh deployments.

Advantages include:

Excellent performance
Health checks
Session persistence
SSL termination support
Open-source

NGINX

NGINX can also perform TCP load balancing using its stream module.

It provides:

High throughput
Flexible routing
TLS support
Easy integration with existing infrastructure

Cloud Load Balancers

Cloud deployments may use managed load balancers such as:

AWS Network Load Balancer
Azure Load Balancer
Google Cloud Load Balancer

Managed services simplify scaling while reducing infrastructure management overhead.

Regardless of the solution you choose, configure health checks so unhealthy worker nodes are automatically removed from the pool.

Storage Considerations

Storage performance directly affects indexing speed, event processing, and overall cluster responsiveness.

Best practices include:

Use SSD or NVMe storage.
Separate operating system and data volumes when practical.
Allocate sufficient disk space for logs and alerts.
Plan for future storage growth.
Monitor disk utilization proactively.

Remember that the majority of alert storage occurs within the Wazuh Indexer rather than the manager itself, making storage planning important for both components.

If you’re also deploying the indexing layer, see How to Build a Wazuh Indexer Cluster.

Network Topology Recommendations

An efficient network design minimizes latency and reduces synchronization delays.

Recommended practices include:

Place manager nodes on the same high-speed network whenever possible.
Minimize latency between managers and indexers.
Avoid unnecessary firewall inspection between cluster nodes.
Use dedicated management networks for administrative traffic when feasible.
Ensure reliable DNS resolution for every node.

A simplified production architecture looks like this:

                 +----------------+
                 | Wazuh Dashboard|
                 +--------+-------+
                          |
                 +--------v--------+
                 | Wazuh Indexer   |
                 |     Cluster     |
                 +--------+--------+
                          |
                 +--------v--------+
                 | Load Balancer   |
                 +---+---------+---+
                     |         |
          +----------+         +----------+
          |                               |
+---------v--------+             +--------v---------+
| Master Manager   |<----------->| Worker Manager   |
+---------+--------+             +--------+---------+
          |                               |
      Agents                         Agents

This design separates management, indexing, and event processing while allowing the cluster to scale horizontally.

Installing Wazuh on Each Node

Once the infrastructure has been planned, install the required Wazuh components on each server.

Every manager should run the same Wazuh version to ensure proper cluster synchronization and compatibility.

The installation order typically follows this sequence:

Install the master manager.
Install each worker manager.
Deploy the Wazuh Indexer cluster.
Install the Wazuh Dashboard.
Verify communication between components.

Install the Master Manager

Begin by provisioning the server designated as the master node.

Install the Wazuh manager packages using the official installation method for your Linux distribution.

After installation:

Verify the Wazuh manager service is running.
Confirm package versions.
Record the server hostname and IP address.
Ensure DNS resolution is functioning correctly.

Do not configure clustering until every manager has been installed.

For complete installation instructions, refer to the official Wazuh documentation.

Install Worker Managers

Repeat the installation process for every worker server.

Ensure that:

The same Wazuh version is installed.
Required dependencies match the master.
Hostnames are unique.
Each server has reliable network connectivity to the master.

At this stage, each worker operates as an independent Wazuh manager until cluster configuration is completed.

Install the Wazuh Indexer Cluster

Production deployments should use a clustered Wazuh Indexer rather than a single indexing node.

Benefits include:

Improved availability
Better search performance
Increased storage capacity
Fault tolerance

The indexer cluster stores alerts generated by all manager nodes and serves data to the Wazuh Dashboard.

For a complete walkthrough, see How to Build a Wazuh Indexer Cluster.

Install the Wazuh Dashboard

Install the Wazuh Dashboard after the indexer is operational.

The Dashboard connects to:

Wazuh API
Wazuh Indexer

Once installed, verify that:

The web interface loads successfully.
Authentication works.
Alerts appear in the dashboard.
Cluster status is accessible.

If you encounter dashboard startup issues, these troubleshooting guides may help:

Verify Basic Connectivity

Before configuring the cluster, verify communication between every component.

Check the following:

Managers can reach each other over the network.
Managers can resolve hostnames.
Managers can communicate with the Wazuh Indexer.
Dashboard can connect to the Indexer.
Dashboard can reach the Wazuh API.
Firewalls permit required traffic.
Time synchronization is functioning correctly.

Useful verification commands include:

ping worker1.example.com

ping master.example.com

curl https://indexer.example.com:9200

curl https://master.example.com:55000

Resolving connectivity issues now will prevent more difficult synchronization problems later in the deployment.

Configuring the Master Node

After installing every cluster component, the next step is configuring the master manager.

Most cluster settings are defined within the manager’s ossec.conf file.

The master node acts as the authoritative source for cluster synchronization, making accurate configuration essential.

Edit ossec.conf

Cluster settings are stored in the manager configuration file:

/var/ossec/etc/ossec.conf

Before making changes:

Create a backup.
Validate existing XML syntax.
Edit the file using your preferred text editor.

For example:

sudo cp /var/ossec/etc/ossec.conf \
/var/ossec/etc/ossec.conf.bak

sudo nano /var/ossec/etc/ossec.conf

If you encounter XML validation problems, see How to Fix ossec.conf Syntax Errors in Wazuh Agents.

Configure the Cluster Section

Within ossec.conf, locate (or create) the <cluster> section.

This section defines how the manager participates in the Wazuh cluster, including synchronization settings and node identity.

A basic example looks like:

<cluster>
  <name>wazuh-production</name>
  <node_name>master-node</node_name>
  <node_type>master</node_type>
  <key>YourSharedClusterKey</key>
  <port>1516</port>
  <bind_addr>0.0.0.0</bind_addr>
  <disabled>no</disabled>
</cluster>

The exact options may vary slightly between Wazuh releases, so always verify the syntax against the documentation for your installed version.

Set Cluster Name

The cluster name uniquely identifies the deployment.

Example:

<name>wazuh-production</name>

Every manager participating in the cluster must use the same cluster name.

Changing the cluster name later requires updating every participating node.

Configure Node Name

Assign a unique name to the master node.

Example:

<node_name>master-node</node_name>

Node names should:

Be unique
Match DNS naming conventions where practical
Clearly identify each server’s role

Examples include:

master-node
worker-01
worker-02
worker-east
worker-west

Define Node Type

Specify the node’s role.

For the master manager:

<node_type>master</node_type>

Worker managers will later be configured with:

<node_type>worker</node_type>

This setting determines how the manager participates in synchronization.

Configure Shared Key

Every node must use the same shared cluster key.

Example:

<key>ReplaceWithALongRandomSharedSecret</key>

Recommendations:

Generate a long random value.
Store it securely.
Never reuse weak or default keys.
Keep the key identical across every cluster member.

Treat this key as sensitive infrastructure credentials.

Configure Cluster Port

The cluster synchronization service listens on a dedicated TCP port.

Example:

<port>1516</port>

Ensure:

The port is open between managers.
Firewalls permit inbound and outbound traffic.
No other services are using the same port.

Configure Bind Address

Specify the interface used for cluster communication.

Examples:

Bind to all interfaces:

<bind_addr>0.0.0.0</bind_addr>

Bind to a specific interface:

<bind_addr>192.168.10.10</bind_addr>

Using a dedicated management interface is recommended for production environments to isolate cluster synchronization traffic from general network traffic.

Restart the Wazuh Manager

After saving the configuration, restart the manager service so the new cluster settings take effect.

sudo systemctl restart wazuh-manager

Then verify that the service starts successfully:

sudo systemctl status wazuh-manager

Finally, review the manager logs for any configuration or XML parsing errors before proceeding to configure the worker nodes.

Early validation makes it much easier to troubleshoot cluster synchronization in later steps.

Configuring Worker Nodes

Once the master node has been configured, the next step is to configure each worker manager.

Every worker must use the same cluster settings as the master while maintaining its own unique node identity.

With the exception of the node name and node type, the cluster configuration should remain consistent across all manager nodes.

Configure Cluster Settings

Open the ossec.conf file on each worker node:

/var/ossec/etc/ossec.conf

Locate the <cluster> section and configure it similarly to the master.

Example:

<cluster>
  <name>wazuh-production</name>
  <node_name>worker-01</node_name>
  <node_type>worker</node_type>
  <key>ReplaceWithALongRandomSharedSecret</key>
  <port>1516</port>
  <bind_addr>0.0.0.0</bind_addr>
  <nodes>
    <node>master.example.com</node>
  </nodes>
  <disabled>no</disabled>
</cluster>

The <nodes> section tells the worker which master node it should contact during cluster initialization.

Always verify the configuration syntax against the documentation for your installed Wazuh version, as configuration options may vary slightly between releases.

Connect Workers to the Master

Each worker must be able to communicate with the master node over the cluster synchronization port.

Before restarting the worker, verify:

The worker can resolve the master’s hostname.
Firewalls allow cluster traffic.
The master’s cluster service is running.
Network latency is stable.

Useful connectivity tests include:

ping master.example.com

nc -zv master.example.com 1516

If hostname resolution is unavailable, you can temporarily use the master’s IP address, although DNS-based configurations are generally easier to maintain over time.

Configure Shared Authentication Key

Every cluster member must use the exact same shared cluster key.

Example:

<key>ReplaceWithALongRandomSharedSecret</key>

If the key differs, even by a single character, the worker will fail authentication and will not join the cluster.

For production deployments:

Generate a long random secret.
Store it securely.
Rotate the key as part of your credential management policy.
Avoid embedding secrets in publicly accessible configuration repositories.

Set Worker Node Names

Each worker requires a unique node name.

Examples include:

<node_name>worker-01</node_name>

<node_name>worker-02</node_name>

<node_name>worker-east</node_name>

Good naming conventions make troubleshooting much easier, particularly in environments with many worker nodes spread across multiple regions or data centers.

A common naming pattern is:

worker-01
worker-02
worker-03
worker-us-east
worker-eu-west

Restart Worker Services

After saving the configuration, restart the Wazuh manager on every worker.

sudo systemctl restart wazuh-manager

Verify that the service starts correctly:

sudo systemctl status wazuh-manager

If the manager fails to start, inspect the logs for XML syntax errors or cluster configuration issues before continuing.

If configuration errors are reported, refer to How to Fix ossec.conf Syntax Errors in Wazuh Agents.

Verify Cluster Membership

Once all workers have restarted, verify that they successfully joined the cluster.

The cluster should report:

One master
One or more worker nodes
Healthy synchronization
No authentication errors

You can verify membership using the Wazuh cluster utilities or by reviewing the manager logs.

Look for messages indicating that:

The worker connected successfully.
Synchronization completed.
The node joined the cluster.
Configuration files were synchronized.

If workers repeatedly disconnect or fail to synchronize, check:

Cluster key mismatches
Firewall rules
DNS resolution
Clock synchronization
Network connectivity

If synchronization issues occur after deployment, see Fixing Wazuh Cluster Desync Caused by Master-Worker Time Drift.

Configuring the Wazuh Indexer Cluster

After the manager cluster is operational, configure the Wazuh Indexer cluster.

The indexer stores alerts generated by every manager and provides the search capabilities used by the Wazuh Dashboard.

A production deployment should use multiple indexer nodes to improve availability and prevent a single point of failure.

For a complete installation walkthrough, see How to Build a Wazuh Indexer Cluster.

Configure Indexer Discovery

Each indexer node must be able to discover the other members of the cluster during startup.

Discovery settings define how nodes locate one another and establish cluster membership.

Typical discovery configuration includes:

Seed hosts
Node names
Cluster name
Network addresses

Every node should reference the same discovery configuration to ensure consistent cluster formation.

Refer to the official Wazuh Indexer documentation for the exact configuration parameters used by your version.

Configure Cluster Initial Manager Nodes

During initial cluster creation, designate the initial manager (cluster manager) nodes responsible for establishing the cluster.

These bootstrap settings are only required when the cluster is first created.

Recommendations include:

Use stable hostnames.
Ensure every listed node is reachable.
Keep the configuration identical where required.
Remove bootstrap settings if recommended after successful cluster formation, following your version’s documentation.

Improper bootstrap configuration is one of the most common causes of indexer cluster formation failures.

Configure Certificates

Communication between indexer nodes should always be encrypted.

Configure TLS certificates for:

Node-to-node communication
Administrative access
Dashboard connections

Certificates should be:

Issued by a trusted internal Certificate Authority (CA) or trusted external CA
Stored securely
Rotated before expiration
Protected with appropriate filesystem permissions

The National Institute of Standards and Technology (NIST) recommends encrypting communications between distributed infrastructure components to protect confidentiality and integrity.

Start Indexer Services

Once configuration is complete, start the Wazuh Indexer service on every node.

For systems using systemd:

sudo systemctl enable wazuh-indexer
sudo systemctl start wazuh-indexer

Repeat the process on every indexer node.

After startup, verify that each service is running without errors before proceeding to dashboard configuration.

Verify Cluster Health

Confirm that the indexer cluster formed successfully before connecting the dashboard.

A healthy cluster should report:

All expected nodes online
Green cluster status (or yellow during initial replica allocation)
No shard allocation failures
Successful node discovery

Review the indexer logs for warnings related to:

Certificate validation
Discovery failures
Network connectivity
Memory allocation
Disk space

If the cluster remains in a yellow state after initialization, see How to Fix a Yellow Cluster Status in Wazuh Indexer.

Configuring the Wazuh Dashboard

The Wazuh Dashboard provides centralized access to alerts, agent management, dashboards, and cluster monitoring.

In a production environment, it should be configured to communicate with multiple indexer nodes so that the interface remains available even if an individual indexer becomes unavailable.

Connect Dashboard to Multiple Indexers

Rather than pointing the dashboard to a single indexer, configure multiple indexer endpoints.

Benefits include:

Improved availability
Automatic failover
Better load distribution
Simplified maintenance

Depending on your deployment, the dashboard may connect directly to multiple indexers or to a load balancer positioned in front of the indexer cluster.

Using a load balancer often simplifies future scaling because new indexer nodes can be added without changing dashboard configuration.

Configure Authentication

Configure secure authentication between the dashboard and the indexer.

Recommended best practices include:

Use dedicated service accounts.
Apply the principle of least privilege.
Store credentials securely.
Enable TLS encryption.
Rotate passwords periodically.
Protect certificate private keys.

Avoid using highly privileged administrative accounts for routine dashboard operations whenever possible.

The Center for Internet Security (CIS) recommends using dedicated service accounts with only the permissions necessary for their intended function.

Enable Failover

Failover allows the dashboard to continue operating if one indexer node becomes unavailable.

Depending on your architecture, failover can be provided by:

Multiple configured indexer endpoints
DNS-based redundancy
HAProxy
NGINX
Cloud load balancers

When planning failover, ensure that health checks automatically remove unavailable nodes from the pool so that client requests are redirected only to healthy indexers.

This minimizes downtime during maintenance or unexpected outages.

Test Dashboard Connectivity

After completing the configuration, verify that the dashboard can successfully communicate with the entire environment.

Validate the following:

Dashboard login succeeds.
Alerts are displayed correctly.
Index searches return results.
Agent information loads successfully.
Cluster health is visible.
API requests complete successfully.

Also test failure scenarios by temporarily removing an indexer node or simulating maintenance to confirm that failover behaves as expected.

If the dashboard cannot connect or displays startup errors, these troubleshooting guides may help:

Configuring Agent Connections

After the cluster has been deployed, configure your Wazuh agents to communicate with the clustered environment instead of an individual manager.

Using a centralized connection point, typically a load balancer, simplifies administration and allows agents to continue communicating even if a worker node becomes unavailable.

If you’re deploying a large number of endpoints, combining clustering with automated deployment provides the best long-term scalability.

Related Guide: The Ultimate Wazuh Agent Deployment Guide

Point Agents to the Load Balancer

Rather than configuring every agent to communicate directly with a specific worker, point them to the load balancer’s hostname or virtual IP address.

For example:

<client>
  <server>
    <address>wazuh.example.com</address>
    <port>1514</port>
    <protocol>tcp</protocol>
  </server>
</client>

Using a load balancer provides several advantages:

Simplifies agent configuration
Eliminates the need to assign agents manually
Distributes connections across worker nodes
Supports maintenance without reconfiguring endpoints
Improves availability

If new worker nodes are added later, only the load balancer configuration typically needs to be updated.

Configure Failover Servers

Although a load balancer is the preferred approach, Wazuh agents can also be configured with multiple manager addresses for redundancy, depending on your deployment requirements and Wazuh version.

A failover strategy should ensure that agents can reconnect automatically if their primary destination becomes unavailable.

Best practices include:

Define a primary connection endpoint.
Configure secondary endpoints where supported.
Minimize reconnection delays.
Test failover regularly.
Avoid pointing agents directly to the master unless required by your architecture.

Always verify the supported failover options for your installed Wazuh version in the official documentation.

Register New Agents

Once connectivity has been configured, register new agents with the cluster.

Typical registration methods include:

Manual registration
Authentication daemon (authd)
Agent auto-enrollment
Configuration management tools
Automation platforms

For large environments, automated registration significantly reduces deployment time and administrative effort.

If you’re deploying hundreds or thousands of endpoints, these guides provide detailed instructions:

Verify Agent Connectivity

After registration, confirm that agents successfully communicate with the cluster.

Verify that:

Agents appear in the dashboard.
Agents report as Active.
Events are being received.
Heartbeats are updating.
Alerts are generated normally.

If some agents fail to connect, check:

Firewall rules
DNS resolution
Manager availability
Registration keys
Network routing

If agents cannot register successfully, these troubleshooting guides may help:

Load Balancing the Cluster

Load balancing is one of the most important components of a production-ready multi-node Wazuh cluster.

Without it, administrators must manually distribute agent connections across worker nodes, making the environment harder to manage and less resilient to failures.

A properly configured load balancer distributes incoming agent traffic across available workers while automatically removing unhealthy nodes from service.

Why Load Balancing Matters

Load balancing provides both operational and performance benefits.

Key advantages include:

Distributes agent connections evenly
Prevents individual workers from becoming overloaded
Improves scalability
Supports rolling maintenance
Reduces downtime
Simplifies infrastructure expansion

Instead of updating thousands of agents whenever new worker nodes are added, administrators only update the load balancer configuration.

Using HAProxy

HAProxy is one of the most common load balancers used in enterprise Wazuh deployments.

Advantages include:

High performance
TCP load balancing
Health monitoring
Session persistence
SSL/TLS support
Extensive production adoption

A simple HAProxy architecture might look like:

               HAProxy
                  |
      +-----------+-----------+
      |                       |
+-----v------+         +------v------+
| Worker-01  |         | Worker-02   |
+------------+         +-------------+

HAProxy is an excellent choice for both on-premises and cloud deployments due to its reliability and mature feature set.

Using NGINX

NGINX also supports TCP load balancing through its Stream module.

Benefits include:

Lightweight deployment
Excellent performance
Flexible routing
TLS support
Broad platform compatibility

Organizations already using NGINX for reverse proxy services often extend it to balance Wazuh manager traffic as well.

DNS Round Robin

DNS round robin distributes client connections by returning multiple IP addresses for a single hostname.

For example:

wazuh.example.com

→ Worker-01
→ Worker-02
→ Worker-03

Although simple to implement, DNS round robin has several limitations:

No built-in health checks
Slow failover due to DNS caching
Uneven connection distribution
Limited visibility into node health

Because of these limitations, DNS round robin is generally less suitable than dedicated load balancers for production environments.

Cloud Load Balancers

Cloud providers offer managed load balancing services that integrate with their networking infrastructure.

Popular options include:

AWS Network Load Balancer
Azure Load Balancer
Google Cloud Load Balancer

Advantages include:

Automatic scaling
Built-in redundancy
Managed health checks
Simplified administration
Native cloud integration

Managed load balancers reduce operational overhead by eliminating the need to maintain dedicated load-balancing servers.

Health Checks

Health checks ensure that traffic is only directed to healthy worker nodes.

Typical health checks verify:

Manager service availability
Network connectivity
TCP port responsiveness
Application health
Response latency

When a worker becomes unavailable, the load balancer should automatically stop sending new agent connections to that node until it recovers.

Regularly test health-check behavior during maintenance windows to ensure the cluster responds as expected.

Verifying Cluster Synchronization

After completing the cluster configuration, verify that synchronization is functioning correctly.

Successful synchronization ensures every manager shares the same configuration, rules, agent information, and operational data.

Detecting synchronization issues early helps prevent inconsistent detections and difficult troubleshooting later.

Check Cluster Status

Begin by checking the overall cluster status.

A healthy cluster should indicate:

Cluster enabled
Master node online
Worker nodes connected
Synchronization active
No communication errors

Review the cluster status using the available Wazuh management tools or by examining the manager logs for startup and synchronization messages.

Verify Connected Nodes

Confirm that every expected node appears in the cluster.

Verify:

Master is present.
All workers are connected.
Node names are correct.
No duplicate entries exist.
No nodes are repeatedly disconnecting.

If a worker does not appear, investigate:

Cluster configuration
Shared authentication key
Firewall rules
DNS resolution
Network connectivity

Confirm Rule Synchronization

One of the easiest ways to verify synchronization is by testing custom detection rules.

Create or modify a test rule on the master node, then confirm that it is automatically replicated to every worker.

Verify that:

The rule exists on each worker.
Rule IDs remain consistent.
Alerts generated by different workers produce identical results.

For more information about creating and testing custom rules, see:

Verify Agent Synchronization

Agent information should remain synchronized across the cluster.

Confirm that:

Newly registered agents appear consistently.
Agent groups are identical.
Registration keys are synchronized.
Agent status matches across managers.
No duplicate agents exist.

If inconsistencies appear after registration, review synchronization logs before adding more endpoints.

Test Configuration Replication

Configuration changes made on the master should automatically propagate to worker nodes.

You can verify replication by modifying a non-production configuration item, such as:

Agent group configuration
Decoder
Rule
Shared configuration file

Then confirm that the change appears on every worker after synchronization completes.

If you’re using centralized agent management, you can also verify that shared configurations are replicated correctly.

Check Synchronization Logs

Finally, review the cluster logs to confirm that synchronization is completing successfully.

Look for messages indicating:

Successful node joins
Completed synchronization cycles
Configuration replication
Agent synchronization
Cluster heartbeat activity

Also investigate any warnings or errors related to:

Authentication failures
Time drift
Network interruptions
Synchronization delays
Version mismatches

According to Wazuh documentation, regular monitoring of cluster logs is an important operational practice because synchronization issues often appear in the logs before they become visible through missing rules or inconsistent agent behavior.

If synchronization problems occur, these troubleshooting guides can help:

Monitoring Cluster Health

A multi-node Wazuh cluster requires continuous monitoring to ensure that all components remain available, synchronized, and capable of handling incoming security events.

A cluster can appear operational while still experiencing hidden problems such as uneven agent distribution, delayed synchronization, high resource consumption, or indexing bottlenecks.

Regular health monitoring helps identify these issues before they impact detection capabilities.

Monitor Node Status

The first step in maintaining cluster health is regularly checking the status of every manager node.

A healthy cluster should have:

One active master node
All worker nodes connected
No disconnected nodes
Successful synchronization
Consistent configuration across members

Administrators should monitor:

Node availability
Cluster membership changes
Worker connection status
Last synchronization timestamps

Unexpected node changes may indicate:

Network failures
Service crashes
Authentication problems
Resource exhaustion
Configuration errors

For environments with many managers, consider integrating Wazuh monitoring data with external observability platforms to create automated alerts.

Check Cluster Logs

Cluster logs provide valuable insight into synchronization activity and communication problems.

Review the Wazuh manager logs:

/var/ossec/logs/ossec.log

Look for messages related to:

Worker connections
Synchronization events
Authentication failures
Configuration replication
Communication errors

Common warning signs include:

Repeated worker reconnect attempts
Failed synchronization cycles
Cluster key mismatches
Timeout errors
Unexpected node disconnects

Log monitoring should be part of your normal operational workflow, similar to monitoring authentication failures or security alerts.

For additional troubleshooting, see:

Fixing Wazuh Cluster Desync Caused by Master-Worker Time Drift

Monitor Resource Utilization

Cluster performance depends heavily on available system resources.

Monitor every manager node for:

CPU Usage

High CPU consumption may indicate:

Too many incoming events
Heavy rule processing
Excessive FIM monitoring
Large decoder workloads

Memory Usage

Memory pressure can cause:

Slow event processing
Service instability
Queue buildup
Manager crashes

Disk Usage

Monitor:

/var/ossec
Log directories
Database files
Temporary files

Insufficient disk space can prevent normal operation and cause unexpected failures.

Network Usage

High network utilization may indicate:

Too many agent connections
Large log volumes
Synchronization overhead
Indexer communication issues

For indexer-related resource problems, see:

How to Tune OpenSearch Heap Size to Stop Wazuh High Memory Crashes

Detect Synchronization Delays

Synchronization delays occur when workers cannot receive updates from the master quickly enough.

Common causes include:

Network latency
High CPU usage
Large configuration changes
Disk bottlenecks
Too many simultaneous updates

Symptoms include:

Workers using outdated rules
Missing configuration updates
Different alert behavior between nodes
Delayed agent information updates

To prevent synchronization delays:

Keep cluster nodes geographically close when possible.
Maintain sufficient CPU and memory resources.
Avoid large unnecessary configuration changes.
Monitor cluster communication latency.

Monitor Agent Distribution

A properly balanced cluster should distribute agents and workloads evenly across worker nodes.

Uneven distribution can cause:

One worker becoming overloaded
Increased alert processing latency
Higher CPU utilization
Reduced fault tolerance

Monitor:

Number of agents connected to each worker
Events processed per node
CPU usage by worker
Alert generation rates

If one worker consistently handles significantly more traffic than others, review:

Load balancer configuration
Agent connection patterns
Worker availability
Network routing

A balanced distribution ensures predictable performance and easier scaling.

Performance Tuning

A default Wazuh cluster configuration works for many environments, but larger deployments often require additional tuning.

Performance optimization focuses on reducing bottlenecks across:

Manager processing
Agent communication
Cluster synchronization
Indexing
Network communication

Optimize Worker Distribution

Worker nodes should receive workloads according to their available resources.

Avoid situations where:

One worker handles most agents.
High-volume servers are concentrated on one node.
Low-capacity workers receive enterprise workloads.

Optimization strategies include:

Using load balancing.
Adding additional workers.
Separating high-volume endpoints.
Monitoring event processing rates.

For example, servers generating large amounts of authentication logs or application logs should not overload the same worker handling thousands of lightweight endpoints.

Increase File Descriptor Limits

Large Wazuh deployments require many simultaneous connections.

Linux systems have default file descriptor limits that may be insufficient for enterprise workloads.

Increase limits to support:

More agent connections
More open log files
More network sockets

Check current limits:

ulimit -n

For production systems, configure higher limits through:

systemd service settings
/etc/security/limits.conf
Operating system tuning parameters

Higher limits reduce connection failures caused by resource exhaustion.

Tune Queue Sizes

Wazuh uses internal queues to handle incoming events and processing workloads.

Large environments may require queue tuning to prevent:

Dropped messages
Processing delays
Backlogs during traffic spikes

Queue optimization depends on:

Event volume
Number of agents
Detection complexity
Available memory

Increasing queue sizes can improve resilience during temporary traffic spikes but requires additional memory allocation.

Optimize Indexer Performance

The Wazuh Indexer is often the limiting factor in large deployments because it stores and searches security data.

Performance improvements include:

Proper JVM heap allocation
Fast SSD storage
Adequate RAM
Correct shard allocation
Index lifecycle management
Cluster sizing based on ingestion rate

Avoid allocating excessive heap memory because OpenSearch requires system memory outside the JVM for caching and operating system functions.

For more information:

Improve Network Performance

Network performance directly impacts:

Agent communication
Cluster synchronization
Indexer ingestion
Dashboard queries

Recommended improvements:

Use high-speed internal networking.
Minimize latency between cluster components.
Avoid routing cluster traffic through unnecessary security devices.
Use dedicated interfaces when possible.
Monitor packet loss and retransmissions.

Distributed security platforms rely heavily on reliable communication, making network design a critical part of Wazuh performance tuning.

Reduce Synchronization Overhead

Large clusters can experience unnecessary synchronization overhead if configuration changes occur too frequently.

Reduce overhead by:

Limiting unnecessary rule changes.
Reviewing unused decoders.
Avoiding excessive shared configuration updates.
Scheduling large changes during maintenance windows.

A well-maintained cluster synchronizes only necessary changes, reducing CPU and network consumption.

Scaling the Cluster

One of the primary advantages of a multi-node Wazuh deployment is the ability to scale as security requirements grow.

Organizations can expand capacity by adding manager workers, increasing indexer resources, or improving existing infrastructure.

Adding Additional Worker Nodes

Adding worker nodes is the most common way to scale Wazuh manager capacity.

New workers provide:

More event processing capacity
Additional agent connection capacity
Improved fault tolerance
Better workload distribution

The general process involves:

Provision a new server.
Install the same Wazuh version.
Configure cluster settings.
Assign the worker role.
Add the node to the load balancer.
Verify synchronization.

After joining the cluster, the new worker automatically receives synchronized configuration from the master.

Expanding the Indexer Cluster

As alert volume grows, the Wazuh Indexer may require additional nodes.

Expanding the indexer cluster improves:

Storage capacity
Search performance
Query speed
Availability

Consider adding indexer nodes when:

Disk usage continuously increases.
Searches become slower.
Indexing latency grows.
Cluster resources remain consistently high.

For large environments, scale manager nodes and indexer nodes independently because they solve different performance problems.

Migrating Agents

When expanding a cluster, existing agents may need to be redistributed.

Migration strategies include:

Load Balancer Migration

The simplest approach is allowing the load balancer to distribute new connections automatically.

Manual Migration

Administrators can update agent configurations to point toward new endpoints.

DNS Migration

Changing a DNS record allows many agents to move without manually editing every endpoint.

When migrating large numbers of agents:

Perform changes gradually.
Monitor connection status.
Keep rollback procedures available.

For automated deployment methods, see How to Automate Bulk Wazuh Agent Deployment with Ansible and SCCM.

Capacity Planning

Capacity planning prevents unexpected performance problems as the environment grows.

Important metrics include:

Number of agents
Events per second (EPS)
Daily indexed data volume
Alert generation rate
CPU utilization
Memory usage
Disk growth rate
Network throughput

Plan future capacity based on growth projections rather than current usage.

For example:

A company adding 500 servers annually should size for future endpoints.
A SOC expanding detection rules should account for increased processing requirements.
Compliance requirements requiring longer retention should influence storage planning.

Horizontal vs Vertical Scaling

Wazuh environments can scale in two primary ways.

Vertical Scaling

Vertical scaling means increasing resources on existing servers.

Examples:

More CPU cores
Additional RAM
Faster storage

Advantages:

Simple implementation
No architecture changes
Easier management

Disadvantages:

Hardware limits
Higher costs at large scale
Single-node dependency remains

Horizontal Scaling

Horizontal scaling means adding additional nodes.

Examples:

Additional worker managers
More indexer nodes
Additional dashboard instances

Advantages:

Better fault tolerance
Easier expansion
Improved availability
Better workload distribution

Disadvantages:

More infrastructure management
Requires careful architecture planning

For enterprise Wazuh deployments, horizontal scaling is usually the preferred approach because it provides both capacity growth and improved resilience.

A properly designed multi-node architecture allows organizations to expand security monitoring capabilities without replacing their entire platform.

Common Multi-Node Wazuh Cluster Problems

Although a multi-node Wazuh cluster provides scalability and improved availability, incorrect configuration, networking problems, and resource limitations can prevent the cluster from operating correctly.

Understanding common failure scenarios helps administrators quickly identify problems and restore normal operation.

Worker Node Cannot Join the Cluster

One of the most common deployment issues is a worker node failing to join the master cluster.

Common symptoms include:

Worker does not appear in cluster status.
Worker repeatedly attempts to connect.
Synchronization never completes.
Cluster logs show connection failures.

Common causes include:

Incorrect master hostname or IP address
Invalid cluster configuration
Incorrect node type
Firewall restrictions
Network connectivity problems
Incorrect shared authentication key

Troubleshooting steps:

Verify the worker configuration:

cat /var/ossec/etc/ossec.conf

Confirm the cluster section contains:

Correct cluster name
Correct master node address
Correct node type
Matching authentication key

Test connectivity:

nc -zv master.example.com 1516

Restart the worker service:

systemctl restart wazuh-manager

Review the manager logs for additional details:

tail -f /var/ossec/logs/ossec.log

If the worker still fails to connect, verify time synchronization and DNS resolution between nodes.

Cluster Synchronization Fails

Synchronization failures occur when the master and worker nodes cannot exchange configuration or operational data.

Symptoms include:

Rules not appearing on workers
Decoder changes not replicated
Agent information differs between nodes
Configuration files become inconsistent

Common causes include:

Network interruptions
Clock drift
Large synchronization queues
Incorrect cluster settings
Resource exhaustion

Troubleshooting steps:

Check cluster logs.
Verify network connectivity.
Confirm all nodes use the same Wazuh version.
Review CPU and memory usage.
Restart affected worker services.

If synchronization failures continue, review Fixing Wazuh Cluster Desync Caused by Master-Worker Time Drift.

Authentication Key Mismatch

Every cluster node must use the same shared authentication key.

A mismatch prevents workers from joining the cluster.

Typical symptoms:

Authentication failures in logs
Worker repeatedly reconnects
Master rejects the worker connection

Example log message:

Authentication failed for cluster node

Resolution:

Generate a secure shared key.
Update the <key> value on all nodes.
Restart the Wazuh manager service.

Example:

<key>YourSecureRandomClusterKey</key>

Security best practice:

Never use default keys.
Store cluster credentials securely.
Rotate keys periodically.

Node Version Mismatch

All Wazuh manager nodes in a cluster should run the same version.

Version mismatches can cause:

Synchronization failures
Unsupported configuration behavior
API compatibility problems
Unexpected cluster instability

Example:

Master: Wazuh 4.x.x

Worker: Wazuh 4.y.y

Resolution:

Check installed versions:

apt list --installed | grep wazuh

or:

rpm -qa | grep wazuh

Upgrade or downgrade nodes until versions match.

When upgrading clustered environments:

Upgrade according to Wazuh’s recommended order.
Test changes on non-production nodes first.
Maintain configuration backups.

Firewall Blocks Cluster Traffic

Firewalls frequently prevent workers from communicating with the master.

Required communication includes:

Manager cluster synchronization
Agent communication
Indexer communication
Dashboard communication

Common symptoms:

Workers cannot join.
Nodes randomly disconnect.
Synchronization delays occur.

Troubleshooting:

Check whether the cluster port is reachable:

nc -zv master.example.com 1516

Review firewall rules:

iptables -L

or:

firewall-cmd --list-all

Ensure internal cluster traffic is permitted between trusted nodes.

Dashboard Cannot Reach Indexer

The Wazuh Dashboard depends on the Wazuh Indexer for storing and retrieving alert data.

Common symptoms:

Dashboard fails to load.
No alerts appear.
Search requests fail.
Dashboard displays connection errors.

Common causes:

Incorrect indexer hostname
Certificate problems
Authentication failures
Indexer service stopped
Network restrictions

Troubleshooting steps:

Verify indexer availability:

curl https://indexer.example.com:9200

Check:

TLS certificates
Dashboard configuration
Indexer health
Network connectivity

Related troubleshooting:

Duplicate Agent Entries

Duplicate agents occur when multiple registrations exist for the same endpoint.

Symptoms include:

Multiple agents with identical names.
Conflicting IP addresses.
Incorrect agent status.
Duplicate alerts.

Common causes:

Reinstalling agents without removing old registrations.
Cloning virtual machines.
Restoring system images.
Lost agent keys.

Resolution:

Remove inactive agents.
Re-register affected endpoints.
Verify unique agent identities.

If agent registration issues occur, see Why Is client.keys File Empty? Restoring Lost Wazuh Agents.

Split-Brain Scenarios

A split-brain condition occurs when cluster nodes incorrectly believe they are operating independently.

This can create:

Conflicting cluster states
Duplicate processing
Configuration inconsistencies

Common causes:

Network partitions
Incorrect failover procedures
Multiple nodes configured as master
DNS failures

Prevention strategies:

Maintain a clear master role.
Monitor cluster connectivity.
Avoid manual configuration drift.
Use reliable networking.
Implement proper operational procedures.

Regular cluster monitoring helps identify split-brain conditions before they affect security operations.

High CPU Usage on Master Node

The master node may experience high CPU usage when:

Synchronizing large configurations
Processing too many events
Managing excessive worker communication
Running resource-intensive modules

Symptoms include:

Slow synchronization
Delayed configuration updates
Increased event processing latency

Solutions:

Move agent traffic to workers.
Add additional workers.
Optimize rules and decoders.
Reduce unnecessary monitoring.
Increase available resources.

Related troubleshooting:

Why Is Wazuh Using High CPU? Troubleshooting Guide

Indexer Cluster Health Turns Yellow or Red

The Wazuh Indexer cluster health status indicates whether data is being stored correctly.

Yellow Status

A yellow status usually means:

Primary shards are available.
Replica shards are unavailable.

Common causes:

Insufficient indexer nodes
Replica allocation problems
Node failures

Red Status

A red status indicates:

Missing primary shards
Data availability problems
Serious cluster issues

Common causes:

Disk failures
Corrupted indexes
Insufficient resources

Troubleshooting:

Check indexer node status.
Review allocation errors.
Verify available disk space.
Check OpenSearch logs.

Security Best Practices

A Wazuh cluster contains sensitive security data, including alerts, endpoint information, authentication keys, and detection logic.

Protecting communication and administrative access is essential for maintaining a secure monitoring platform.

Secure Cluster Communications

All communication between Wazuh components should be protected.

Secure:

Manager-to-worker communication
Agent-to-manager communication
Dashboard-to-indexer communication
API communication

Recommended practices:

Encrypt network traffic.
Use trusted certificates.
Restrict internal communication paths.
Monitor unexpected connections.

Encryption prevents attackers from intercepting security telemetry or modifying detection data.

Use Strong Authentication Keys

Cluster authentication keys protect communication between manager nodes.

Best practices:

Generate random keys.
Avoid predictable values.
Store keys securely.
Rotate keys periodically.
Restrict access to configuration files.

Never commit cluster credentials to public repositories or unsecured storage systems.

Restrict Cluster Ports

Only required systems should access cluster communication ports.

Recommended firewall practices:

Allow cluster traffic only between trusted managers.
Block unnecessary external access.
Restrict administrative interfaces.
Monitor firewall logs.

Reducing exposed services decreases the attack surface.

Implement TLS Certificates

TLS certificates provide encryption and authentication between components.

Use certificates for:

Wazuh Indexer communication
Dashboard connections
API access
Management interfaces

Certificate management practices:

Use a trusted CA.
Monitor expiration dates.
Protect private keys.
Replace compromised certificates immediately.

Separate Management Networks

Where possible, separate:

Agent traffic
Cluster synchronization traffic
Administrative access
User dashboard access

Benefits include:

Reduced attack surface
Better traffic control
Easier troubleshooting
Improved performance

A dedicated management network is especially valuable for large enterprise deployments.

Monitor Cluster Logs

Continuous monitoring of cluster logs helps identify:

Authentication failures
Configuration changes
Synchronization problems
Unexpected node activity

Forwarding Wazuh operational logs into your monitoring platform allows security teams to detect infrastructure problems early.

Keep All Nodes Updated

Maintain consistent versions across:

Manager nodes
Indexer nodes
Dashboard nodes
Agents

Update regularly to receive:

Security fixes
Bug fixes
Performance improvements
New features

Before upgrades:

Back up configurations.
Test changes.
Follow the recommended upgrade sequence.

Back Up Cluster Configuration

Regular backups should include:

ossec.conf
Custom rules
Custom decoders
Agent group configurations
Certificates
Authentication keys
Indexer configuration

Backups allow faster recovery after:

Hardware failures
Configuration mistakes
Accidental deletion
Security incidents

Apply Least Privilege

Follow the principle of least privilege across the deployment.

Recommendations:

Limit administrator access.
Use role-based access control.
Avoid shared accounts.
Restrict filesystem permissions.
Separate operational and administrative roles.

Least privilege reduces the impact of compromised credentials.

Real-World Example

Scenario

An enterprise security team manages more than 25,000 endpoints distributed across multiple data centers.

The organization originally operated a single Wazuh manager responsible for:

Agent communication
Security event analysis
File Integrity Monitoring
Vulnerability detection
Alert processing

As the environment expanded, the security team experienced:

Increased CPU utilization during peak ingestion periods
Delayed event processing
Slower agent registration
Limited maintenance flexibility
A single point of failure

The organization needed a more scalable architecture that could support continued growth.

Solution

The security team deployed a multi-node Wazuh architecture consisting of:

One master Wazuh manager
Multiple worker managers
Three-node Wazuh Indexer cluster
Redundant Wazuh Dashboard instances
HAProxy load balancing layer

The new architecture separated responsibilities:

Manager Cluster

Worker managers handled endpoint communication and security event processing.

The master node managed:

Cluster synchronization
Rules
Decoders
Shared configurations
Agent metadata

Indexer Cluster

The three-node Wazuh Indexer deployment provided:

Increased storage capacity
Better search performance
Higher availability

Load Balancing

HAProxy distributed agent connections across worker nodes.

Agents connected to a single endpoint instead of individual managers, simplifying future scaling.

Results

After migrating to the clustered architecture, the organization achieved:

Eliminated the Single Point of Failure

Multiple worker managers ensured that maintenance or individual node failures did not stop security monitoring.

Improved Log Processing Throughput

Distributed event processing reduced resource pressure on individual managers and allowed the environment to handle higher ingestion volumes.

Faster Agent Registration and Management

Centralized load balancing simplified endpoint onboarding and reduced administrative effort.

Better Resilience During Maintenance Windows

Security teams could perform maintenance on individual components without taking the monitoring platform offline.

Simplified Horizontal Scaling

As the organization continued growing, administrators could add additional worker managers or indexer nodes without redesigning the entire deployment.

This architecture demonstrates why multi-node Wazuh clustering is the preferred approach for large-scale security monitoring environments requiring scalability, reliability, and operational flexibility.

Frequently Asked Questions (FAQ)

Question: What is a multi-node Wazuh cluster?

A multi-node Wazuh cluster is a distributed deployment where multiple Wazuh manager nodes operate together as a single security monitoring platform.

Instead of relying on one manager to process all endpoint events, workloads are distributed across multiple nodes.

A typical multi-node architecture includes:

One master manager
Multiple worker managers
Wazuh agents
Wazuh Indexer cluster
Wazuh Dashboard

The cluster improves scalability by distributing event processing while maintaining centralized configuration management through synchronization.

Question: What is the difference between a master and a worker node?

The main difference is the responsibility each node performs.

Master Node

The master node manages cluster coordination.

Responsibilities include:

Synchronizing configurations
Distributing rules and decoders
Managing cluster membership
Maintaining shared agent information

Worker Node

Worker nodes handle the majority of operational workloads.

Responsibilities include:

Receiving agent connections
Processing security events
Applying detection rules
Running analysis modules
Forwarding alerts to the Wazuh Indexer

In production environments, worker nodes typically handle most endpoint traffic while the master focuses on synchronization.

Question: How many worker nodes can a Wazuh cluster support?

The number of worker nodes depends on:

Hardware resources
Event ingestion volume
Network capacity
Number of monitored agents
Detection workload

There is no single recommended number for every deployment.

Small environments may only require:

1 master
1 worker

Large enterprise environments may deploy:

1 master
Multiple workers
Multiple indexer nodes

The best approach is to monitor resource utilization and add workers when existing nodes approach capacity limits.

Question: Can multiple master nodes exist in the same Wazuh cluster?

No. A Wazuh cluster uses a single master node responsible for coordination and synchronization.

Multiple masters managing the same cluster state can create conflicts and inconsistent configurations.

For high availability, organizations typically protect against master failure through:

Reliable backups
Disaster recovery procedures
Monitoring
Well-defined recovery processes

Worker nodes provide the primary scalability and workload redundancy.

Question: Do agents connect directly to worker nodes?

Agents can communicate with worker nodes, but production deployments commonly place a load balancer between agents and managers.

The recommended architecture is:

Agents
   |
   |
Load Balancer
   |
+----------+----------+
|                     |
Worker 1          Worker 2

This approach provides:

Automatic workload distribution
Easier scaling
Improved availability
Simplified agent configuration

When new workers are added, agents do not need to be manually reconfigured.

Question: Does the Wazuh Dashboard need to be clustered?

The Wazuh Dashboard itself does not participate in manager cluster synchronization.

However, production environments often deploy multiple dashboard instances for high availability.

A highly available architecture may include:

Multiple Dashboard nodes
Load balancing
Multiple Wazuh Indexer nodes
Redundant manager workers

Clustering the dashboard prevents the visualization layer from becoming a single point of failure.

Question: How do I add a new worker node to an existing cluster?

Adding a worker node generally involves:

Provisioning a new server.
Installing the same Wazuh version as existing nodes.
Configuring the worker cluster settings.
Adding the master node address.
Configuring the shared authentication key.
Starting the Wazuh manager service.
Verifying synchronization.
Adding the worker to the load balancer.

After joining successfully, the worker automatically receives synchronized cluster data.

For large-scale deployments, automated provisioning tools can simplify this process.

Question: Can I use a load balancer with Wazuh?

Yes. Load balancers are commonly used in production Wazuh deployments.

They distribute agent connections across worker nodes and provide automatic failover.

Common solutions include:

HAProxy
NGINX
Cloud load balancers

Benefits include:

Easier scaling
Better availability
Simplified agent configuration
Reduced maintenance impact

A load balancer allows administrators to add or remove worker nodes without modifying every endpoint.

Question: What ports are required for cluster communication?

A Wazuh deployment requires several communication channels depending on the architecture.

Common ports include:

Component	Port	Purpose
Agent communication	1514	Agent event communication
Agent registration	1515	Agent enrollment
Cluster communication	1516	Manager synchronization
Wazuh API	55000	API communication
Indexer	9200	Indexer communication
Dashboard	443	Web interface

Always verify required ports for your specific Wazuh version and deployment model.

Firewall rules should restrict access to trusted systems only.

Question: How do I verify that cluster synchronization is working?

You can verify synchronization by checking:

Cluster membership
Worker connection status
Synchronization logs
Rule replication
Decoder replication
Agent information consistency

Successful synchronization should show:

Connected worker nodes
No authentication errors
Consistent configurations
Updated agent metadata

You should also test configuration replication by creating a controlled change on the master and confirming it appears on workers.

Question: Can different Wazuh versions coexist in the same cluster?

No. All Wazuh manager nodes within the same cluster should run the same version.

Version mismatches may cause:

Synchronization failures
Configuration incompatibilities
Unexpected behavior
Unsupported deployments

Before upgrading:

Review the upgrade documentation.
Back up configurations.
Upgrade according to the recommended sequence.

Keeping all nodes aligned improves reliability and simplifies troubleshooting.

Question: What happens if the master node goes offline?

If the master node becomes unavailable:

Existing worker nodes may continue processing events.
Agent monitoring can continue.
Synchronization operations may be affected.
Configuration changes cannot be distributed normally.

Because the master manages synchronization, restoring master functionality should be prioritized.

Organizations should prepare recovery procedures that include:

Configuration backups
Documented recovery steps
Infrastructure monitoring
Tested restoration processes

Question: How do I secure communication between cluster nodes?

Secure cluster communication by implementing:

Strong authentication keys
TLS encryption
Firewall restrictions
Private management networks
Secure certificate management

Additional recommendations:

Restrict cluster ports to trusted nodes.
Protect configuration files.
Limit administrative access.
Monitor authentication failures.

Security controls should protect both the monitoring platform and the sensitive data it processes.

Question: How often is cluster data synchronized?

Wazuh continuously synchronizes important cluster information between the master and worker nodes.

Synchronization includes:

Rules
Decoders
Agent metadata
Shared configuration files
Group information

The exact synchronization behavior depends on:

Cluster activity
Configuration changes
Network conditions
System resources

Large environments should monitor synchronization performance to ensure updates propagate quickly.

Conclusion

A multi-node Wazuh cluster provides the scalability, availability, and resilience required for organizations monitoring large numbers of endpoints.

A single Wazuh manager can work well for smaller environments, but enterprise deployments often require a distributed architecture to handle increasing event volumes, growing endpoint counts, and higher availability requirements.

By deploying multiple manager nodes, organizations can distribute processing workloads while maintaining centralized control through cluster synchronization.

Key Advantages of Deploying a Multi-Node Wazuh Cluster

A properly designed cluster provides:

High Availability

Multiple worker nodes reduce dependency on a single manager and allow maintenance activities with minimal disruption.

Scalability

Organizations can expand monitoring capacity by adding:

Additional worker managers
More indexer nodes
Additional dashboard instances

This horizontal scaling approach supports long-term growth without replacing the entire platform.

Improved Resilience

A clustered architecture improves reliability by distributing workloads and reducing the impact of individual component failures.

Key Configuration Steps Reviewed

Throughout this guide, you learned how to:

Plan a multi-node Wazuh architecture.
Install Wazuh components across multiple servers.
Configure the master manager.
Configure worker managers.
Deploy and connect the Wazuh Indexer cluster.
Configure dashboard connectivity.
Connect agents through load balancing.
Verify cluster synchronization.
Monitor performance and troubleshoot common issues.
Scale the environment as requirements grow.

Following these steps provides a solid foundation for building a production-ready Wazuh deployment.

Maintain Continuous Monitoring and Testing

Deploying a Wazuh cluster is only the beginning.

Long-term reliability depends on continuous operational maintenance.

Recommended practices include:

Monitor cluster health regularly.
Review synchronization logs.
Test failover procedures.
Validate backups.
Apply updates consistently.
Review resource utilization.
Perform capacity planning as the environment grows.

Security monitoring infrastructure must evolve alongside the organization it protects.

By combining proper architecture, regular maintenance, and proactive monitoring, a multi-node Wazuh cluster can provide a scalable and reliable foundation for enterprise threat detection and security operations.

How to Set Up a Multi-Node Wazuh Cluster

What Is a Multi-Node Wazuh Cluster?

Benefits of Clustering Wazuh

Improved Scalability

Better Performance

Higher Availability

Simplified Management

Easier Maintenance

When You Should Deploy a Multi-Node Cluster

What You’ll Learn in This Guide

Understanding Wazuh Cluster Architecture

What Is a Wazuh Cluster?

Purpose of Clustering

High Availability vs Scalability

Manager Synchronization

Components of a Multi-Node Wazuh Cluster

Master Node

Worker Nodes

Wazuh Agents

Wazuh Indexer

Wazuh Dashboard

Filebeat/OpenSearch Communication

How Cluster Synchronization Works

Rules Synchronization

Decoders

Agent Information

Group Configurations

Shared Configuration Files

Communication Between Nodes

Cluster Protocol

Ports Used

Authentication

Certificates and Secure Communication

Prerequisites

Hardware Requirements

Supported Operating Systems

Network Requirements

DNS and Hostname Configuration

Firewall Ports

Time Synchronization (NTP)

Installing the Same Wazuh Version on Every Node

Planning Your Multi-Node Deployment

Choosing the Number of Manager Nodes

Selecting Master and Worker Roles

Master Node

Worker Nodes

Designing for High Availability

Load Balancing Options

HAProxy

NGINX

Cloud Load Balancers

Storage Considerations

Network Topology Recommendations

Installing Wazuh on Each Node

Install the Master Manager

Install Worker Managers

Install the Wazuh Indexer Cluster

Install the Wazuh Dashboard

Verify Basic Connectivity

Configuring the Master Node

Edit ossec.conf

Configure the Cluster Section

Set Cluster Name

Configure Node Name

Define Node Type

Configure Shared Key

Configure Cluster Port

Configure Bind Address

Restart the Wazuh Manager

Configuring Worker Nodes

Configure Cluster Settings

Connect Workers to the Master

Configure Shared Authentication Key

Set Worker Node Names

Restart Worker Services

Verify Cluster Membership

Configuring the Wazuh Indexer Cluster

Configure Indexer Discovery

Configure Cluster Initial Manager Nodes

Configure Certificates