A Wazuh load balancer becomes increasingly important as a Wazuh deployment grows beyond a single Wazuh server. Instead of sending every agent connection to one manager, a load balancer can distribute connections across multiple Wazuh server nodes in a cluster. This architecture helps organizations scale agent ingestion, improve availability, and reduce the impact of an individual worker failure.
Wazuh’s own documentation recommends using a load balancer when connecting agents to a Wazuh server cluster.
According to Wazuh, this approach distributes agent registration and reporting across worker nodes and allows agents to reconnect to another available worker when a node fails.
This architecture is particularly useful for organizations monitoring hundreds or thousands of endpoints, where concentrating agent traffic on one Wazuh server can create a scalability and availability bottleneck.
Why load balancing matters in Wazuh environments
A Wazuh deployment has several distinct components, including Wazuh agents, Wazuh servers, Wazuh indexers, and the Wazuh Dashboard.
The Wazuh server is responsible for receiving and analyzing security events from agents before forwarding relevant data to the indexer.
In a larger environment, multiple Wazuh server nodes can operate as a cluster.
A load balancer provides a consistent endpoint for agents while distributing their connections across those server nodes.
This has two important architectural benefits:
- Traffic distribution: Agent connections can be spread across multiple Wazuh server workers.
- Availability: If a worker becomes unavailable, agents can reconnect through the load balancer to another available server.
- Scalability: Additional Wazuh server nodes can be introduced without changing the destination configured on every agent.
- Simpler administration: Agents can use one load-balancer address rather than maintaining a list of individual Wazuh servers.
Wazuh explicitly describes its server-cluster architecture as supporting horizontal scalability, high availability, and improved performance.
For a deeper discussion of the underlying cluster architecture, see The Complete Wazuh Cluster Architecture Guide.
When a Wazuh load balancer is necessary
A load balancer is not required for every Wazuh installation.
A small environment with a single Wazuh server generally does not need one.
It becomes more valuable when you have:
- Multiple Wazuh server nodes.
- A large number of connected agents.
- High event volumes.
- Requirements for high availability.
- A need to add Wazuh server workers without reconfiguring agents.
- A requirement to minimize downtime when individual worker nodes fail.
- A production environment where the Wazuh server itself should not be a single point of failure.
Wazuh’s current architecture documentation describes multi-node deployments as appropriate for large environments with high event throughput or requirements for fault tolerance and high availability.
If you are planning to add Wazuh server nodes to handle increasing endpoint volume, see Step-by-Step Wazuh Manager Scaling Guide.
It is also important to distinguish load balancing from clustering.
A load balancer distributes network connections; the Wazuh server cluster provides the distributed server architecture and synchronization that allow multiple Wazuh server nodes to operate together.
What this guide covers
This guide focuses on configuring a load-balancing layer in front of a Wazuh server cluster.
The configuration process will cover the architecture of the load balancer, Wazuh server backends, the ports that need to be exposed, health checking, traffic distribution, and agent configuration.
It will also explain how to verify that traffic is being distributed correctly and how to troubleshoot common load-balancer problems.
The examples can be adapted to commonly used load-balancing technologies such as NGINX and HAProxy, both of which Wazuh documents for use with Wazuh server clusters.
What Is a Wazuh Load Balancer?
A Wazuh load balancer is a network component positioned between Wazuh agents and multiple Wazuh server nodes.
Its job is to accept incoming agent connections and distribute them among the available Wazuh servers.
Conceptually, the architecture looks like this:
Wazuh agents → Load balancer → Wazuh server cluster → Wazuh indexer cluster → Wazuh Dashboard
Instead of configuring agents to communicate directly with individual worker nodes, the agents can use the load balancer’s IP address or DNS name as their Wazuh server endpoint.
Wazuh specifically supports this architecture and states that agents can report to a load balancer, which then distributes incoming traffic among available Wazuh server nodes.
Definition of a Wazuh load balancer
A load balancer is a traffic-distribution layer that sits in front of multiple backend servers.
For Wazuh, those backend servers are generally Wazuh server nodes participating in a Wazuh server cluster.
The load balancer does not replace the Wazuh server cluster.
Instead, it provides the network entry point through which agents reach that cluster.
For example, an organization could have:
Wazuh Agent 1 ─┐
Wazuh Agent 2 ─┤
Wazuh Agent 3 ─┤
Wazuh Agent 4 ─┤──> Wazuh Load Balancer
Wazuh Agent 5 ─┤ │
Wazuh Agent 6 ─┘ ├──> Wazuh Worker 1
├──> Wazuh Worker 2
└──> Wazuh Worker 3
The agents only need to know the load balancer’s address.
The load balancer determines which backend Wazuh server should receive each connection.
How load balancing works with Wazuh
The load balancer listens for Wazuh agent traffic on the appropriate ports and forwards those connections to the Wazuh server nodes.
For example, Wazuh commonly uses:
- 1514/TCP for Wazuh agent connections.
- 1515/TCP for agent enrollment.
- 55000/TCP for the Wazuh server API.
- 1516/TCP for Wazuh cluster communication.
Not every Wazuh service should automatically be placed behind the same load-balancing configuration.
The architecture should account for the specific communication path being load balanced.
Wazuh’s documented load-balancer examples use TCP forwarding for agent traffic and enrollment.
A typical flow looks like this:
- An agent establishes a connection to the load balancer.
- The load balancer selects an available Wazuh server backend.
- The connection is forwarded to that Wazuh server.
- The Wazuh server receives and analyzes the agent’s events.
- Wazuh forwards appropriate data to the Wazuh indexer.
- The Wazuh Dashboard queries the resulting data for visualization and management.
This separation allows the load balancer to concentrate on traffic distribution, while Wazuh server nodes handle security event processing and agent management.
Wazuh Manager, Wazuh Indexer, and Wazuh Dashboard roles
Understanding the individual Wazuh components is important before configuring a load balancer.
Wazuh server
The Wazuh server receives security data from agents, analyzes events using Wazuh’s detection capabilities, manages agents, and forwards processed information to the Wazuh indexer.
In a multi-node architecture, multiple Wazuh server instances can operate as a Wazuh server cluster.
Wazuh indexer
The Wazuh indexer stores and indexes alerts, events, vulnerability information, inventory data, and other information generated by the Wazuh platform.
The indexer has its own clustering and scaling mechanisms. Therefore, a Wazuh server load balancer should not be confused with an indexer load-balancing architecture.
Wazuh Dashboard
The Wazuh Dashboard provides the web interface used to visualize security data and administer the Wazuh environment. It interacts with the Wazuh server API and Wazuh indexer.
Wazuh’s architecture documentation describes these three components as the central components of the platform and explains their respective communication paths.
For more information about indexing and storage, see The Ultimate Wazuh Indexer Guide.
Where the load balancer fits into the Wazuh architecture
The load balancer normally sits in front of the Wazuh server cluster, rather than between the Wazuh server and Wazuh indexer.
A simplified production architecture is:
┌──> Wazuh Server Worker 1 ──┐
Wazuh Agents ──> │ │
├──> Wazuh Server Worker 2 ──┼──> Wazuh Indexer Cluster
│ │
└──> Wazuh Server Worker 3 ──┘
▲
│
Load Balancer
The Wazuh server cluster handles synchronization between its nodes.
The load balancer handles the distribution of agent connections.
Wazuh explains that the server cluster uses a master-worker architecture and synchronizes information such as agent data, groups, rules, decoders, and other configuration information between nodes.
This distinction is critical because simply placing multiple independent Wazuh servers behind a load balancer does not automatically create a functional Wazuh cluster.
Load balancing vs. Wazuh clustering
Load balancing and clustering solve related but different problems.
Load balancing answers:
Which Wazuh server should receive this connection?
Wazuh clustering answers:
How do multiple Wazuh server nodes operate as a coordinated deployment?
A load balancer can distribute traffic among backend nodes, but it does not synchronize Wazuh configuration, agent information, rules, decoders, or cluster state.
Wazuh’s server-cluster mechanism provides that synchronization layer.
The load balancer then provides a common network endpoint and distributes agent connections across the cluster.
For detailed cluster deployment instructions, see How to Set Up a Multi-Node Wazuh Cluster.
This distinction also explains why a load balancer by itself does not provide Wazuh high availability.
If the backend Wazuh servers are not properly clustered and configured, distributing traffic among them can create inconsistent or unreliable behavior rather than a resilient deployment.
Why Use a Load Balancer With Wazuh?
The primary reason to introduce a Wazuh load balancer is to make a multi-node Wazuh server deployment easier to scale and more resilient.
Wazuh itself recommends using a load balancer for agent enrollment and connections because it distributes agents among worker nodes and allows agents to reconnect to another server when a worker becomes unavailable.
This design also aligns with broader availability engineering principles.
NIST guidance describes high availability as relying on redundancy and failover processes and emphasizes eliminating single points of failure where availability requirements justify the additional infrastructure.
High availability
High availability is one of the strongest reasons to deploy a Wazuh load balancer.
Without load balancing, agents may be configured to communicate with a particular Wazuh server.
If that server fails, those agents can lose their connection until another server becomes available through the configured failover mechanism.
With a load balancer, the agents can use a single endpoint while the load-balancing layer directs connections toward healthy Wazuh server nodes.
For example:
┌── Worker 1 ── Healthy
Agents ──> LB ──────┼── Worker 2 ── Failed
└── Worker 3 ── Healthy
The load balancer can stop sending new connections to an unavailable backend while continuing to use the remaining nodes.
However, high availability should be considered an end-to-end architectural property, not something created by the load balancer alone.
The Wazuh server cluster, indexer cluster, networking, storage, DNS, and load-balancer infrastructure can all introduce separate failure points.
NIST similarly notes that redundancy and failover must be considered as part of an overall high-availability strategy rather than treated as a substitute for other recovery controls.
Distributing agent connections
A large Wazuh environment can generate substantial continuous traffic from its agents.
Instead of directing all of that traffic toward one Wazuh server, a load balancer can distribute connections across multiple workers.
For example:
Load Balancer
│
┌──────────────┼──────────────┐
▼ ▼ ▼
Worker 1 Worker 2 Worker 3
33% 34% 33%
The exact distribution depends on the load-balancing algorithm and connection behavior.
Wazuh’s documentation provides examples using load-balancing configurations such as leastconn, which attempts to direct new connections toward the backend with fewer active connections.
This can help prevent one Wazuh worker from becoming disproportionately loaded while other workers have available capacity.
If high CPU usage is already affecting your Wazuh deployment, see Why Is Wazuh Using High CPU? Troubleshooting Guide.
Manager failover
A Wazuh load balancer can also provide a practical failover mechanism for agent connections.
Suppose a deployment contains three Wazuh workers:
Worker 1 → Online
Worker 2 → Online
Worker 3 → Offline
The load balancer can continue forwarding connections to Workers 1 and 2 while removing Worker 3 from service.
When Worker 3 becomes healthy again, it can potentially be returned to the backend pool.
This is particularly useful when performing maintenance.
Administrators can take a worker out of the load-balancing pool, perform maintenance, and return it to service without requiring every agent to be reconfigured.
Wazuh’s documentation specifically identifies the ability to reconnect agents to another available Wazuh server when a worker fails as one of the advantages of using a load balancer.
Horizontal scaling
A load balancer makes it easier to expand a Wazuh environment horizontally.
Instead of continually increasing the resources of one Wazuh server, you can add additional Wazuh server workers and place them behind the existing load balancer.
The architecture then becomes:
Agents
│
▼
Load Balancer
│
├── Wazuh Worker 1
├── Wazuh Worker 2
├── Wazuh Worker 3
└── Wazuh Worker 4
Wazuh describes this architecture as supporting horizontal scalability.
Its documentation notes that agents can communicate through a single load-balancer IP address, allowing new server nodes to be added without changing the agent configuration.
That can significantly simplify large-scale Wazuh administration.
For a detailed discussion of adding capacity through multiple Wazuh managers, see Step-by-Step Wazuh Manager Scaling Guide.
Reducing single points of failure
A single Wazuh server can become a single point of failure for agent processing.
If that server becomes unavailable, the organization may lose visibility into endpoint activity until service is restored or agents fail over to another configured destination.
A load-balanced Wazuh cluster reduces this dependency by distributing agent connectivity across multiple Wazuh server nodes.
However, there is an important caveat: the load balancer itself can become a single point of failure.
For production environments where availability is critical, consider deploying the load-balancing layer redundantly as well.
Otherwise, the architecture may simply move the single point of failure from the Wazuh server to the load balancer.
NIST’s reliability guidance describes redundancy as a way for systems to survive individual component failures and identifies parallel or redundant configurations as a fundamental mechanism for improving system reliability.
Supporting large Wazuh deployments
Large Wazuh deployments benefit from separating traffic distribution, event processing, indexing, and visualization into appropriate layers.
A mature architecture may therefore look like:
┌── Wazuh Server Worker 1 ──┐
├── Wazuh Server Worker 2 ──┤
Wazuh Agents ──> LB ─────┼── Wazuh Server Worker 3 ──┼──> Wazuh Indexer Cluster
└── Wazuh Server Worker 4 ──┘
│
▼
Wazuh Dashboard
Each layer has a distinct responsibility:
- Load balancer: Distributes agent connections.
- Wazuh server cluster: Receives, analyzes, and manages agent data.
- Wazuh indexer cluster: Stores and indexes Wazuh data.
- Wazuh Dashboard: Provides visualization and administration.
This layered architecture makes it possible to scale individual parts of the Wazuh platform according to their workload instead of treating the entire deployment as one server.
For the broader architecture behind this design, see The Complete Wazuh Cluster Architecture Guide.
The key point is that a Wazuh load balancer is an extension of a properly designed Wazuh server cluster, not a replacement for one.
When the two are designed together, the load balancer provides a stable agent-facing endpoint while the Wazuh cluster supplies the distributed processing and synchronization required for a scalable deployment.
Wazuh Load Balancer Architecture
A well-designed Wazuh load balancer sits between Wazuh agents and the Wazuh server cluster, providing a stable endpoint for agent connections while distributing traffic across available Wazuh worker nodes.
The load balancer should be designed as part of the overall Wazuh architecture rather than treated as an isolated networking component.
A typical production deployment separates the agent-facing connection layer from the Wazuh server, Wazuh indexer, and Wazuh Dashboard layers:
Wazuh Agents
│
▼
Wazuh Load Balancer
│
┌─────────────┼─────────────┐
▼ ▼ ▼
Wazuh Worker 1 Wazuh Worker 2 Wazuh Worker 3
│ │ │
└─────────────┼─────────────┘
│
▼
Wazuh Indexer Cluster
│
▼
Wazuh Dashboard
This architecture provides a single connection point for agents while allowing the Wazuh server tier to scale horizontally.
See The Complete Wazuh Cluster Architecture Guide for a deeper explanation of how Wazuh server, indexer, and dashboard components interact.
Basic Wazuh load-balancing topology
The simplest Wazuh load-balancing topology consists of one load balancer and two or more Wazuh server workers.
Wazuh Agent
│
│ TCP
▼
┌─────────────────┐
│ Load Balancer │
└────────┬────────┘
│
┌────┴────┐
▼ ▼
Worker 1 Worker 2
│ │
└────┬────┘
▼
Wazuh Indexer Cluster
The load balancer exposes a frontend address and maintains a backend pool containing the Wazuh server nodes.
For example:
wazuh.example.com
│
▼
192.168.10.10 Load Balancer
│
├── 192.168.10.21:1514 → Wazuh Worker 1
├── 192.168.10.22:1514 → Wazuh Worker 2
└── 192.168.10.23:1514 → Wazuh Worker 3
Agents connect to the load balancer rather than directly to 192.168.10.21, 192.168.10.22, or 192.168.10.23.
Wazuh documents this model for distributing agent connections among Wazuh server workers.
Load balancer → Wazuh Manager architecture
The most important load-balancing path is the connection between Wazuh agents and Wazuh server workers.
The load balancer receives connections on the Wazuh agent communication port and forwards them to the backend workers.
A simplified configuration might look like:
frontend wazuh_agents
bind *:1514
mode tcp
default_backend wazuh_workers
backend wazuh_workers
mode tcp
server worker1 10.0.10.21:1514 check
server worker2 10.0.10.22:1514 check
server worker3 10.0.10.23:1514 check
The exact syntax depends on the load-balancing platform.
For Wazuh, TCP load balancing is particularly important because agent communication does not require the load balancer to understand Wazuh application-layer data.
The load balancer can simply establish and forward TCP connections.
The Wazuh documentation provides HAProxy and NGINX examples for this purpose.
If you are troubleshooting connectivity between agents and managers, see Wazuh Agent Not Connecting to Manager? 12 Proven Fixes.
Load balancer → Wazuh Indexer considerations
The Wazuh indexer is a separate architectural layer and should not automatically be treated like the Wazuh server tier.
Wazuh server workers send data to the Wazuh indexer cluster, while the Wazuh Dashboard retrieves and displays information from the platform’s backend services.
For that reason, a load balancer placed in front of Wazuh agents does not eliminate the need to design the indexer layer correctly.
A large environment may therefore contain separate scaling domains:
Agent Traffic
│
▼
Wazuh Load Balancer
│
┌──────────┼──────────┐
▼ ▼ ▼
Manager Manager Manager
│ │ │
└──────────┼──────────┘
▼
Wazuh Indexer
Cluster
The indexer cluster has its own node roles, shard allocation, replication, and availability considerations.
See The Ultimate Wazuh Indexer Guide and How to Build a Wazuh Indexer Cluster when designing the indexer tier.
You should also avoid assuming that adding a load balancer to the agent-facing side automatically balances every Wazuh API or indexer request.
Each communication path should be evaluated independently.
Active/active vs. active/passive designs
A Wazuh load-balancing architecture can use either active/active or active/passive infrastructure.
In an active/active design, multiple Wazuh server workers actively process agent connections simultaneously.
Load Balancer
/ | \
/ | \
Worker 1 Worker 2 Worker 3
ACTIVE ACTIVE ACTIVE
This is generally the most useful model when the objective is to distribute agent connections and increase processing capacity.
In an active/passive design, one component handles traffic while another remains available as a standby.
Virtual IP
│
┌──────┴──────┐
▼ ▼
LB Primary LB Standby
ACTIVE PASSIVE
Active/passive can be useful for the load-balancer infrastructure itself.
For example, two HAProxy servers can use Keepalived to provide a highly available virtual IP.
However, active/passive load balancing is different from the Wazuh server cluster’s active/worker architecture.
Wazuh server workers can actively process agent traffic while the load-balancing layer distributes connections between them.
See How to Set Up a Multi-Node Wazuh Cluster for the Wazuh server clustering component of this architecture.
Agent traffic and manager communication
Agent traffic should be explicitly mapped before configuring the load balancer.
The primary agent communication path is generally:
Agent
│
│ 1514/TCP
▼
Load Balancer
│
├──> Wazuh Worker 1
├──> Wazuh Worker 2
└──> Wazuh Worker 3
Agent enrollment can use a separate connection path, commonly involving port 1515/TCP.
Wazuh server workers also communicate with one another through the Wazuh cluster communication mechanism.
That internal cluster traffic should normally remain on the cluster network rather than being sent through the agent-facing load balancer.
This produces an important architectural separation:
Agent Network
│
▼
Load Balancer
│
Agent Connections
│
┌────────────┴────────────┐
▼ ▼
Wazuh Worker 1 ←──cluster──→ Wazuh Worker 2
│ │
└───────────┬─────────────┘
▼
Wazuh Indexer
Required network ports
The exact ports required depend on which Wazuh services you expose through the load balancer.
Common Wazuh ports include:
| Port | Protocol | Typical purpose |
|---|---|---|
1514 | TCP/UDP | Wazuh agent communication |
1515 | TCP | Agent enrollment |
55000 | TCP | Wazuh server API |
1516 | TCP | Wazuh cluster communication |
443 | TCP | HTTPS/Wazuh Dashboard access |
9200 | TCP | Wazuh indexer API/HTTP access |
The important point is that not every port should necessarily be load balanced through the same frontend.
For example, agent traffic on 1514/TCP can have one frontend, while enrollment on 1515/TCP can have another.
Cluster communication on 1516/TCP is an internal Wazuh server-cluster function and should not be exposed to agents simply because a load balancer exists.
Verify the ports against the current Wazuh documentation before deploying the configuration.
DNS and IP address considerations
DNS provides a convenient abstraction between Wazuh agents and the load-balancing infrastructure.
Instead of configuring agents with:
10.0.10.21
you can use:
wazuh.example.com
The DNS record resolves to the load balancer’s frontend IP address.
This makes infrastructure changes easier because backend Wazuh server addresses can change without requiring every agent configuration to change.
For highly available load balancers, DNS can point to a virtual IP or other highly available frontend rather than an individual load-balancer node.
The DNS design should also account for:
- Internal versus external DNS resolution.
- Split-horizon DNS where required.
- TTL values.
- Certificate names.
- IPv4 versus IPv6.
- Failover behavior.
- Agent enrollment endpoints.
If you are configuring encrypted Wazuh communications, see How to Configure Wazuh SSL.
Prerequisites for Configuring a Wazuh Load Balancer
Before configuring the load balancer, verify that the Wazuh cluster itself is healthy.
A load balancer can distribute connections, but it cannot correct an incorrectly configured Wazuh cluster.
Wazuh Manager cluster requirements
You should have at least two appropriate Wazuh server nodes if the goal is high availability.
The nodes should:
- Belong to the same Wazuh server cluster.
- Have compatible Wazuh versions.
- Have appropriate cluster configuration.
- Be able to communicate with one another.
- Be able to communicate with the Wazuh indexer.
- Have the required agent ports available.
- Have synchronized system clocks.
- Have sufficient CPU, memory, and storage capacity.
See Fixing Wazuh Cluster Desync Caused by Master-Worker Time Drift if your cluster nodes are experiencing synchronization problems.
You should also verify that each worker can independently process agent traffic before placing it behind the load balancer.
Load balancer server requirements
The load balancer should have enough resources to handle the number of concurrent connections generated by your agents.
For HAProxy or NGINX, the resource requirements may be relatively modest compared with the Wazuh server and indexer nodes.
However, connection count, TLS processing, logging, and health checks can increase resource consumption.
For production deployments, consider using:
- A dedicated load-balancer host.
- Redundant load-balancer nodes.
- Static IP addressing.
- Reliable system time synchronization.
- Monitoring and alerting.
- Restricted administrative access.
- Sufficient network bandwidth.
The load balancer should also be located close to the Wazuh server cluster from a network perspective.
Network connectivity
Before configuring HAProxy, NGINX, or another platform, confirm connectivity from the load balancer to every Wazuh backend.
For example:
nc -vz 10.0.10.21 1514
nc -vz 10.0.10.22 1514
nc -vz 10.0.10.23 1514
You should also verify connectivity from representative agents to the load balancer.
A successful connection from the load balancer to one worker does not prove that all backend workers are reachable.
TLS certificates
TLS requirements depend on where encryption terminates.
A TCP load balancer can operate as a passthrough device, allowing encrypted traffic to travel directly from the client to the Wazuh server.
Alternatively, the load balancer can terminate TLS and establish a separate encrypted connection to the backend.
For Wazuh agent traffic, TCP passthrough is often attractive because it keeps the load balancer from needing to understand or terminate the application protocol.
If TLS terminates at the load balancer, carefully evaluate:
- Certificate validity.
- Certificate subject names and SANs.
- Private-key protection.
- Backend encryption.
- Certificate renewal.
- Trust relationships.
- TLS versions and cipher suites.
See How to Fix Wazuh Certificate Errors and How to Configure Wazuh SSL for certificate and TLS troubleshooting.
DNS configuration
Create the DNS record that agents will use to reach the load balancer.
For example:
wazuh.example.com → 10.0.10.10
The certificate used for the endpoint should correspond to the DNS name when TLS is involved.
Before onboarding agents, verify DNS resolution from the networks where those agents are located.
Firewall rules
The firewall must allow the required traffic at each layer.
For example:
Agent Network
│
│ TCP 1514
▼
Load Balancer
│
│ TCP 1514
▼
Wazuh Workers
If enrollment is being load balanced, the corresponding enrollment port must also be permitted.
The Wazuh workers should ideally accept agent traffic from the load balancer rather than unnecessarily exposing their service ports to every network segment.
This provides a cleaner security boundary:
Agents → Load Balancer → Wazuh Workers
rather than:
Agents → Worker 1
Agents → Worker 2
Agents → Worker 3
Health-check requirements
Health checks are essential because the load balancer needs a mechanism for determining whether a backend should receive new connections.
At minimum, the health check should verify that the relevant Wazuh service is reachable.
For example:
Load Balancer
│
├── TCP check → Worker 1:1514 → UP
├── TCP check → Worker 2:1514 → UP
└── TCP check → Worker 3:1514 → DOWN
The load balancer should then avoid sending new connections to Worker 3.
However, a successful TCP connection only proves that a port is accepting connections. It does not necessarily prove that every Wazuh component behind that port is functioning correctly.
For critical environments, combine load-balancer checks with Wazuh-specific monitoring and alerting.
See Wazuh Dashboard Not Loading? Complete Troubleshooting Guide for broader Wazuh service-health troubleshooting.
Backup and recovery considerations
Before changing production networking, back up the relevant Wazuh configurations and load-balancer configuration.
At minimum, document:
- Wazuh server configuration.
- Cluster configuration.
- Agent configuration.
- Load-balancer configuration.
- DNS records.
- Firewall rules.
- TLS certificates and renewal procedures.
- Backend server addresses.
- Health-check settings.
See How to Backup Wazuh Manager Configuration for Wazuh manager configuration backups.
For access-control configurations, also see How to Backup Wazuh RBAC Configurations.
The load balancer should be treated as part of the Wazuh disaster-recovery plan.
If the load balancer fails but the Wazuh cluster remains healthy, agents may still be unable to reach the cluster.
How to Choose a Wazuh Load Balancer
There is no single load-balancing product that is required for Wazuh.
The appropriate choice depends on deployment size, availability requirements, network architecture, operational expertise, and whether the organization is running Wazuh on-premises or in a cloud environment.
The most important requirement is that the selected solution supports the required Wazuh traffic patterns, particularly TCP forwarding for agent connections.
HAProxy
HAProxy is a strong choice for Linux-based Wazuh deployments.
It supports:
- Layer 4 TCP load balancing.
- Health checks.
- Multiple balancing algorithms.
- Connection limits.
- High availability when paired with Keepalived.
- Detailed logging.
- Lightweight operation.
A basic architecture is:
Agents
│
▼
HAProxy
│
├── Worker 1
├── Worker 2
└── Worker 3
HAProxy is particularly attractive when you want explicit control over backend servers and TCP connections without introducing a large application-delivery platform.
NGINX
NGINX can also provide TCP load balancing through its stream functionality.
A simplified configuration concept is:
stream {
upstream wazuh_workers {
server 10.0.10.21:1514;
server 10.0.10.22:1514;
server 10.0.10.23:1514;
}
server {
listen 1514;
proxy_pass wazuh_workers;
}
}
The exact production configuration should include appropriate health-check, timeout, logging, and security settings.
NGINX can be particularly convenient for organizations already using it as a reverse proxy or web infrastructure component.
Keepalived
Keepalived is not itself a Wazuh-aware load balancer.
Instead, it is commonly used to provide high availability for load-balancer nodes by managing a virtual IP through VRRP.
For example:
Virtual IP
10.0.10.10
│
┌───────┴───────┐
▼ ▼
HAProxy 1 HAProxy 2
ACTIVE STANDBY
If HAProxy 1 fails, Keepalived can move the virtual IP to HAProxy 2.
This prevents the load balancer from becoming the single point of failure.
A common Linux architecture is therefore:
Virtual IP
│
┌─────────┴─────────┐
▼ ▼
HAProxy + Keepalived HAProxy + Keepalived
│ │
└─────────┬─────────┘
▼
Wazuh Worker Pool
This approach is useful for on-premises environments that require high availability without relying on a cloud provider’s managed load-balancing service.
Cloud load balancers
Organizations running Wazuh in AWS, Azure, Google Cloud, or another cloud platform can consider the provider’s managed load-balancing services.
Cloud load balancers can reduce the operational burden associated with:
- Load-balancer patching.
- Hardware maintenance.
- Redundancy.
- Availability zones.
- Scaling.
- Monitoring.
However, verify that the selected service supports the required Wazuh traffic, especially raw TCP connections on the relevant ports.
You should also determine whether the cloud load balancer preserves source IP information, supports appropriate health checks, and provides the connection behavior required by Wazuh agents.
Hardware load balancers
Enterprise environments may already operate hardware or virtual application-delivery controllers such as F5 or similar platforms.
These solutions can provide:
- Highly available load balancing.
- Advanced health checks.
- TLS management.
- Centralized network policy.
- Traffic visibility.
- Enterprise support.
They can be appropriate when the organization already has an established load-balancing platform and operational expertise.
There is generally little benefit in deploying a separate HAProxy or NGINX layer solely for Wazuh if the organization’s existing load-balancing infrastructure can already handle the required TCP traffic.
Layer 4 vs. Layer 7 load balancing
One of the most important decisions is whether the Wazuh load balancer should operate at Layer 4 or Layer 7.
Layer 4 load balancing operates at the transport layer, primarily using IP addresses and TCP/UDP ports.
For example:
TCP 1514
│
▼
Load Balancer
│
├── Worker 1
├── Worker 2
└── Worker 3
Layer 7 load balancing operates at the application layer and can inspect protocols such as HTTP.
For agent traffic, Layer 4 is generally the natural choice because the load balancer does not need to parse Wazuh’s application-level data.
Layer 7 becomes more relevant for HTTP-based Wazuh services, such as web applications or APIs, but those paths should be evaluated separately from agent traffic.
When to use TCP passthrough
TCP passthrough is useful when you want the load balancer to distribute encrypted connections without terminating TLS.
The architecture looks like:
Wazuh Agent
│
│ Encrypted TCP
▼
Load Balancer
│
│ Encrypted TCP
▼
Wazuh Worker
The load balancer sees the TCP connection but does not decrypt the application traffic.
Advantages include:
- Simplified certificate management on the load balancer.
- End-to-end encryption.
- No need to decrypt and re-encrypt traffic at the load-balancer layer.
- Less application awareness required by the load balancer.
The trade-off is that the load balancer has less visibility into the application protocol and may have fewer options for application-aware health checks.
For Wazuh agent traffic, this can be an appropriate architecture when the goal is simply to distribute TCP connections among Wazuh server workers.
Choosing an appropriate load-balancing strategy
The load-balancing algorithm should reflect how Wazuh agents establish and maintain connections.
Common strategies include:
Round robin
Connections are distributed sequentially among backend workers.
Connection 1 → Worker 1
Connection 2 → Worker 2
Connection 3 → Worker 3
Connection 4 → Worker 1
This is simple and can work well when backend workers have similar capacity and connection behavior.
Least connections
New connections are directed toward the backend with the fewest active connections.
Worker 1 → 500 connections
Worker 2 → 300 connections
Worker 3 → 150 connections
New connection → Worker 3
This can be useful when connection counts vary substantially between Wazuh workers.
Wazuh’s own load-balancer examples use a least-connections strategy in their HAProxy configuration.
Source-IP persistence
Some environments may use source-based persistence so connections from a particular source consistently reach the same backend.
This should not be enabled automatically. Evaluate whether persistence is actually required by your Wazuh architecture before introducing it.
For most deployments, the goal should be to distribute agent connections across healthy Wazuh workers while allowing the cluster itself to provide the synchronization and state-management mechanisms.
Failover-aware balancing
Regardless of the algorithm, health checks should remove unavailable workers from the backend pool.
A production configuration should therefore prioritize:
- Reliable backend health checks.
- Appropriate TCP connection handling.
- Distribution across healthy Wazuh workers.
- Fast removal of failed backends.
- Automatic reintegration of recovered workers.
- Redundancy for the load-balancer layer itself.
The result should be a topology in which agents have one stable endpoint while the infrastructure underneath can evolve:
wazuh.example.com
│
▼
Highly Available LB
│
┌───────────────┼───────────────┐
▼ ▼ ▼
Wazuh Worker 1 Wazuh Worker 2 Wazuh Worker 3
│ │ │
└───────────────┼───────────────┘
▼
Wazuh Indexer Cluster
│
▼
Wazuh Dashboard
For most self-managed Wazuh deployments, HAProxy or NGINX operating at Layer 4 with TCP forwarding is a practical starting point.
If the load-balancer itself must remain highly available, pairing redundant HAProxy or NGINX instances with Keepalived and a virtual IP provides another layer of resilience.
For the next stage of implementation, see The Complete Wazuh Cluster Architecture Guide, How to Set Up a Multi-Node Wazuh Cluster, and Step-by-Step Wazuh Manager Scaling Guide.
How to Configure a Wazuh Load Balancer With HAProxy
HAProxy is a practical option for implementing a Wazuh load balancer because it supports Layer 4 TCP load balancing, backend health checks, connection management, and multiple balancing algorithms.
For Wazuh agent traffic, the load balancer can operate without understanding the application payload.
HAProxy accepts the TCP connection on the agent-facing port and forwards it to an available Wazuh server worker.
The basic architecture is:
Wazuh Agents
│
│ TCP 1514
▼
HAProxy
│
├── Wazuh Manager 1
├── Wazuh Manager 2
└── Wazuh Manager 3
Wazuh provides an official HAProxy example in its documentation.
Before implementing this configuration, see How to Set Up a Multi-Node Wazuh Cluster to ensure the backend Wazuh managers are correctly clustered.
Install HAProxy
On a Debian or Ubuntu-based load-balancer server, update the package repository and install HAProxy:
sudo apt update
sudo apt install haproxy
Verify the installed version:
haproxy -v
On RHEL, Rocky Linux, AlmaLinux, or another RPM-based distribution, use the appropriate package manager:
sudo dnf install haproxy
Then verify:
haproxy -v
Before proceeding, confirm that the HAProxy version available for your operating system is supported by your organization’s security and maintenance policies.
Define the Wazuh backend servers
The HAProxy backend identifies the Wazuh server workers that should receive agent connections.
Open the HAProxy configuration:
sudo nano /etc/haproxy/haproxy.cfg
Add a backend similar to:
backend wazuh_managers
mode tcp
balance leastconn
option tcp-check
server wazuh-manager-1 10.0.10.21:1514 check
server wazuh-manager-2 10.0.10.22:1514 check
server wazuh-manager-3 10.0.10.23:1514 check
Replace the example addresses with the actual addresses of your Wazuh server workers.
The mode tcp directive is appropriate for agent connections because HAProxy is forwarding TCP traffic rather than interpreting an HTTP request.
The leastconn algorithm directs new connections toward the backend with the fewest active connections.
Wazuh’s official HAProxy example uses TCP mode and a least-connections strategy for distributing agent connections.
Configure frontend listeners
The frontend defines the address and port on which HAProxy accepts incoming Wazuh agent connections.
For example:
frontend wazuh_agents
bind *:1514
mode tcp
default_backend wazuh_managers
This configuration means HAProxy listens on TCP port 1514 on its available interfaces and forwards connections to the wazuh_managers backend.
The resulting traffic path is:
Agent → HAProxy:1514 → Wazuh Manager:1514
If you are using a dedicated load-balancer IP, you can bind HAProxy specifically to that address:
frontend wazuh_agents
bind 10.0.10.10:1514
mode tcp
default_backend wazuh_managers
This can be preferable on a server with multiple network interfaces because it prevents HAProxy from unintentionally exposing the service on an unrelated interface.
Configure TCP load balancing
For Wazuh agent traffic, use TCP mode:
frontend wazuh_agents
mode tcp
bind *:1514
default_backend wazuh_managers
backend wazuh_managers
mode tcp
balance leastconn
server manager1 10.0.10.21:1514 check
server manager2 10.0.10.22:1514 check
server manager3 10.0.10.23:1514 check
Do not configure this as an HTTP reverse proxy simply because HAProxy can also proxy HTTP.
Wazuh agent traffic and Wazuh Dashboard traffic are separate communication paths. Agent traffic should be configured according to the Wazuh agent protocol and required transport.
See How to Configure a Wazuh Proxy for additional information about proxying Wazuh traffic.
Configure health checks
Health checks prevent HAProxy from continuously sending new connections to an unavailable Wazuh manager.
A basic TCP health check is:
backend wazuh_managers
mode tcp
option tcp-check
server manager1 10.0.10.21:1514 check
server manager2 10.0.10.22:1514 check
server manager3 10.0.10.23:1514 check
You can also tune health-check intervals when necessary.
For example:
backend wazuh_managers
mode tcp
option tcp-check
server manager1 10.0.10.21:1514 check inter 5s fall 3 rise 2
server manager2 10.0.10.22:1514 check inter 5s fall 3 rise 2
server manager3 10.0.10.23:1514 check inter 5s fall 3 rise 2
Here, HAProxy checks each backend every five seconds. The fall and rise parameters control how many failed or successful checks are required before the backend changes state.
Keep in mind that a TCP check only verifies that the backend accepts a TCP connection.
It does not guarantee that the entire Wazuh server is functioning correctly.
Configure session persistence when required
Wazuh agent connections can be long-lived, so you should understand the distinction between connection persistence and load-balancing persistence.
Once an established TCP connection has been assigned to a Wazuh manager, HAProxy does not normally move that established connection to another backend in the middle of the session.
If the backend fails, the connection must be re-established.
In many Wazuh deployments, explicit source-IP persistence is therefore unnecessary.
If your architecture specifically requires persistence, HAProxy supports options such as source-based balancing:
backend wazuh_managers
mode tcp
balance source
server manager1 10.0.10.21:1514 check
server manager2 10.0.10.22:1514 check
server manager3 10.0.10.23:1514 check
However, persistence can reduce the effectiveness of load distribution. Do not enable it simply because it is available.
For most deployments, use the Wazuh-recommended load-balancing approach and allow the Wazuh cluster and agent reconnection behavior to handle backend changes.
Enable TLS
TLS configuration depends on your Wazuh architecture.
With TCP passthrough, HAProxy does not terminate the encrypted Wazuh connection:
Wazuh Agent
│
│ Encrypted TCP
▼
HAProxy
│
│ Encrypted TCP
▼
Wazuh Manager
In this configuration, the Wazuh manager remains responsible for the TLS endpoint and certificate.
This is often a straightforward approach because HAProxy does not need access to the Wazuh private key.
If you instead terminate TLS on HAProxy, the configuration becomes more complex because you must manage certificates at the load-balancer layer and ensure that the backend connection remains appropriately protected.
For example, an HTTPS service can use HAProxy’s SSL termination features, but that should not automatically be applied to Wazuh agent traffic.
See How to Configure Wazuh SSL and How to Fix Wazuh Certificate Errors for certificate-management considerations.
Validate the HAProxy configuration
Never restart HAProxy blindly after modifying the configuration.
First validate the configuration:
sudo haproxy -c -f /etc/haproxy/haproxy.cfg
A successful validation should report that the configuration file is valid.
If HAProxy reports an error, fix the configuration before restarting the service.
You can also inspect the configuration for common problems such as:
- Incorrect backend IP addresses.
- Duplicate frontend bindings.
- Invalid directives.
- Incorrect indentation or syntax.
- Unavailable ports.
- Incorrect file permissions.
- Invalid TLS certificate paths.
Start and enable HAProxy
Once the configuration passes validation, start HAProxy:
sudo systemctl start haproxy
Enable it at boot:
sudo systemctl enable haproxy
Check its status:
sudo systemctl status haproxy
If HAProxy fails to start, inspect the system journal:
sudo journalctl -u haproxy -xe
You can also verify that HAProxy is listening on port 1514:
sudo ss -lntp | grep 1514
Test load balancing
First test connectivity from the load balancer to each Wazuh manager:
nc -vz 10.0.10.21 1514
nc -vz 10.0.10.22 1514
nc -vz 10.0.10.23 1514
Then test the load-balancer address:
nc -vz wazuh.example.com 1514
After connecting agents through the load balancer, monitor the HAProxy statistics or logs and verify that connections are being distributed among the expected backend managers.
You should also test failure handling.
For example:
- Confirm all Wazuh workers are healthy.
- Confirm agents are connected through the load balancer.
- Temporarily remove one worker from service.
- Verify HAProxy marks it unavailable.
- Confirm new connections use the remaining workers.
- Restore the worker.
- Confirm HAProxy detects it again.
If agents fail to reconnect after a backend failure, see Wazuh Agent Not Connecting to Manager? 12 Proven Fixes.
How to Configure a Wazuh Load Balancer With NGINX
NGINX can also be used as a Wazuh load balancer when its TCP stream functionality is enabled.
Unlike a conventional HTTP reverse proxy configuration, Wazuh agent traffic should be handled through NGINX’s stream module when you are forwarding raw TCP connections.
The basic topology is:
Wazuh Agents
│
│ TCP
▼
NGINX
│
├── Wazuh Manager 1
├── Wazuh Manager 2
└── Wazuh Manager 3
Install NGINX
On Ubuntu or Debian:
sudo apt update
sudo apt install nginx
Verify the installation:
nginx -v
On an RPM-based distribution:
sudo dnf install nginx
Then verify:
nginx -v
Before configuring TCP forwarding, verify that the installed NGINX build includes the required stream functionality.
You can inspect the compiled modules with:
nginx -V 2>&1
Configure the upstream Wazuh managers
NGINX uses an upstream block to define the Wazuh manager pool.
A basic configuration is:
stream {
upstream wazuh_managers {
server 10.0.10.21:1514;
server 10.0.10.22:1514;
server 10.0.10.23:1514;
}
server {
listen 1514;
proxy_pass wazuh_managers;
}
}
Replace the example addresses with the addresses of your Wazuh server workers.
NGINX will distribute incoming connections among the upstream servers.
The configuration should be placed in the appropriate NGINX configuration location for your distribution.
Configure TCP forwarding
The stream module handles TCP traffic at Layer 4.
A production-oriented example is:
stream {
upstream wazuh_managers {
least_conn;
server 10.0.10.21:1514;
server 10.0.10.22:1514;
server 10.0.10.23:1514;
}
server {
listen 1514;
proxy_connect_timeout 5s;
proxy_timeout 1h;
proxy_pass wazuh_managers;
}
}
The least_conn directive instructs NGINX to prefer upstream servers with fewer active connections.
The long proxy_timeout is important to evaluate because Wazuh agent connections may remain established for extended periods.
Do not blindly copy timeout values into production.
Tune them according to your agent connection behavior and operational requirements.
Configure health checks
Basic NGINX stream upstream configurations can detect certain backend failures during connection attempts, but health-check capabilities depend on the NGINX edition and modules being used.
This distinction matters because a basic upstream declaration is not equivalent to a comprehensive active health-monitoring system.
For example:
upstream wazuh_managers {
least_conn;
server 10.0.10.21:1514;
server 10.0.10.22:1514;
server 10.0.10.23:1514;
}
For environments requiring sophisticated active health checks, evaluate whether the NGINX edition and available modules provide the required functionality.
Alternatively, external monitoring can verify Wazuh backend health and integrate with the load-balancing configuration.
The health check should ultimately answer:
Can this Wazuh worker accept and process agent connections?
A simple TCP port check answers only the first part.
Configure TLS
NGINX can either forward encrypted TCP connections without decrypting them or terminate TLS, depending on the architecture.
For TCP passthrough:
Agent
│
│ TLS-encrypted TCP
▼
NGINX
│
│ TLS-encrypted TCP
▼
Wazuh Manager
NGINX does not need the Wazuh agent certificate’s private key in this design.
This is useful when you want the Wazuh managers to remain responsible for TLS.
If TLS termination occurs at NGINX, certificates and private keys must be installed and managed on the load-balancer server.
See How to Configure Wazuh SSL for a detailed discussion of Wazuh TLS configuration.
Validate the NGINX configuration
Before restarting NGINX, validate the configuration:
sudo nginx -t
A successful test should indicate that the syntax is valid and the configuration test was successful.
If the test fails, inspect:
- The
streammodule. - The configuration location.
- Upstream server addresses.
- Port conflicts.
- Certificate paths.
- File permissions.
- Syntax errors.
You can also display the complete loaded configuration:
sudo nginx -T
This is particularly useful when the stream configuration is distributed across multiple included files.
Restart NGINX
After successfully validating the configuration:
sudo systemctl restart nginx
Then verify:
sudo systemctl status nginx
Confirm that NGINX is listening on the expected Wazuh port:
sudo ss -lntp | grep 1514
If NGINX does not start, inspect:
sudo journalctl -u nginx -xe
Test connectivity
Test every backend directly from the NGINX host:
nc -vz 10.0.10.21 1514
nc -vz 10.0.10.22 1514
nc -vz 10.0.10.23 1514
Then test the load-balancer endpoint:
nc -vz wazuh.example.com 1514
Finally, test from a representative Wazuh agent.
You should verify both connectivity and actual Wazuh agent registration/reporting rather than relying exclusively on a successful TCP connection.
If the agent connects to the load balancer but does not appear correctly in Wazuh, see Resolving Duplicate Name or IP Errors in Wazuh Agent Registration and Why Is client.keys File Empty? Restoring Lost Wazuh Agents.
Configure Wazuh Agents to Use the Load Balancer
After deploying the load balancer, the Wazuh agents must use its address as their Wazuh server endpoint.
The goal is to change the architecture from:
Agent → Wazuh Manager 1
to:
Agent → Load Balancer → Wazuh Manager Cluster
This allows backend Wazuh managers to be added, removed, or replaced without changing the endpoint used by every agent.
Wazuh documents configuring agents to connect through a load balancer in its agent connection documentation.
Identify the Wazuh agent connection endpoint
Determine the DNS name or IP address that agents should use.
For example:
wazuh.example.com
If using a dedicated virtual IP:
10.0.10.10
A DNS name is generally preferable for long-term administration because the underlying load-balancer infrastructure can change without requiring a new endpoint on every agent.
Before changing an agent, verify DNS resolution:
nslookup wazuh.example.com
or:
dig wazuh.example.com
The returned address should correspond to the load-balancer frontend.
Update agent configuration
The Wazuh agent’s configuration is typically stored in:
/var/ossec/etc/ossec.conf
On Linux, locate the <client> section.
A typical configuration resembles:
<client>
<server>
<address>wazuh.example.com</address>
<port>1514</port>
<protocol>tcp</protocol>
</server>
</client>
The exact configuration should match the Wazuh version and transport configuration used by your deployment.
The important change is that <address> should reference the load balancer rather than an individual Wazuh manager.
For example, change:
<address>10.0.10.21</address>
to:
<address>wazuh.example.com</address>
See How to Configure ossec.conf for Log Monitoring in Wazuh for additional ossec.conf configuration guidance.
Configure the load balancer hostname
Using a DNS hostname provides an abstraction layer between the agents and Wazuh infrastructure.
For example:
wazuh.example.com
│
▼
10.0.10.10
│
▼
Load Balancer
│
┌───┼───┐
▼ ▼ ▼
M1 M2 M3
If the load-balancer IP changes, you can update DNS rather than editing every agent.
Make sure the hostname resolves consistently from all agent networks.
If TLS is used, ensure that the certificate’s SAN contains the hostname configured on the agent.
Configure the appropriate Wazuh ports
For normal agent communication, use the port configured by the Wazuh server and load balancer.
A common configuration is:
<server>
<address>wazuh.example.com</address>
<port>1514</port>
<protocol>tcp</protocol>
</server>
The load balancer must listen on the same frontend port:
Agent → wazuh.example.com:1514
and forward the connection to:
Manager 1:1514
Manager 2:1514
Manager 3:1514
If agent enrollment is also being placed behind the load balancer, configure and expose the enrollment endpoint separately according to the Wazuh deployment design.
Do not assume that changing the agent communication port automatically changes enrollment.
Restart the Wazuh agent
After modifying ossec.conf, restart the agent.
On Linux:
sudo systemctl restart wazuh-agent
Check its status:
sudo systemctl status wazuh-agent
Review the agent log if necessary:
sudo tail -f /var/ossec/logs/ossec.log
On Windows, restart the Wazuh service through Services or PowerShell.
For example:
Restart-Service -Name WazuhSvc
See How to Install a Wazuh Agent on Windows Server for Windows agent administration.
Verify agent connectivity
Verify that the agent can resolve and reach the load-balancer hostname:
getent hosts wazuh.example.com
Then test the TCP port:
nc -vz wazuh.example.com 1514
A successful TCP connection confirms network reachability, but you should also verify the Wazuh agent itself.
Check:
sudo systemctl status wazuh-agent
Then inspect:
sudo tail -f /var/ossec/logs/ossec.log
You should look for successful communication rather than repeated connection failures.
On the Wazuh Dashboard, verify that the agent remains active and continues reporting data.
Confirm agents are distributed across managers
The final step is verifying that the load balancer is actually distributing connections.
For example, with three Wazuh workers:
Load Balancer
│
├── Worker 1 → 34% of connections
├── Worker 2 → 33% of connections
└── Worker 3 → 33% of connections
The exact distribution will not necessarily be perfectly equal.
Factors such as:
- Long-lived TCP sessions.
- Connection timing.
- Existing connections.
- Load-balancing algorithm.
- Backend availability.
- Agent reconnect behavior.
can cause uneven connection counts.
For that reason, do not expect an exact one-third distribution simply because three workers exist.
Instead, verify that connections are reaching multiple healthy managers and that no unavailable backend continues receiving new connections.
You can inspect backend connection counts through the load balancer and correlate them with Wazuh manager logs and system-level network connections.
A useful validation procedure is:
- Connect several test agents through the load balancer.
- Record the backend Wazuh manager receiving each connection.
- Confirm multiple workers receive connections.
- Temporarily remove one worker from the load-balancer pool.
- Verify that new connections are directed to the remaining workers.
- Restore the worker.
- Confirm it returns to the healthy backend pool.
- Verify that agents continue reporting normally.
If the load balancer works but agents remain disconnected, see Wazuh Agent Not Connecting to Manager? 12 Proven Fixes.
A properly configured architecture should ultimately provide a single stable agent endpoint:
wazuh.example.com
│
▼
┌─────────────────┐
│ Load Balancer │
└────────┬────────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
Manager 1 Manager 2 Manager 3
│ │ │
└──────────────┼──────────────┘
▼
Wazuh Indexer Cluster
The agents remain unaware of which backend worker handles their connection.
The load balancer provides the stable entry point, while the Wazuh server cluster provides the distributed processing and synchronization layer underneath it.
Wazuh Load Balancer Health Checks
Health checks are a critical part of a production Wazuh load balancer.
The load balancer should not distribute new agent connections to a Wazuh manager that is offline, unreachable, or otherwise unable to accept agent traffic.
Wazuh specifically describes load balancing as a mechanism for distributing agents among worker nodes and allowing agents to reconnect to another node if a manager fails.
A typical health-check architecture looks like this:
Load Balancer
│
┌─────────────┼─────────────┐
│ │ │
Worker 1 Worker 2 Worker 3
│ │ │
HEALTHY HEALTHY FAILED
│ │ X
│ │
└─────────────┴─────────────┐
│
New connections only
go to healthy workers
Why health checks are important
Without health checks, a load balancer may continue sending connections to a failed backend.
For example:
Worker 1 → UP
Worker 2 → DOWN
Worker 3 → UP
If the load balancer does not know that Worker 2 is unavailable, some agents may repeatedly attempt to establish connections through a backend that cannot respond.
A properly configured health-check mechanism allows the load balancer to:
- Detect unavailable Wazuh managers.
- Remove failed managers from the backend pool.
- Send new connections to healthy workers.
- Detect recovered managers.
- Return recovered managers to service.
- Reduce connection failures during maintenance.
- Support predictable failover testing.
Wazuh’s documentation notes that agents can reconnect to another Wazuh server node when a worker fails, which is one of the primary benefits of using a load balancer with a Wazuh cluster.
If you are troubleshooting agents that cannot reconnect to a manager, see Wazuh Agent Not Connecting to Manager? 12 Proven Fixes.
Checking Wazuh Manager availability
The first health check should determine whether each Wazuh manager is reachable on the agent communication port.
By default, Wazuh uses TCP port 1514 for agent connections.
From the load-balancer server, test each backend:
nc -vz 10.0.10.21 1514
nc -vz 10.0.10.22 1514
nc -vz 10.0.10.23 1514
You can also verify that the Wazuh service is running directly on each manager:
sudo systemctl status wazuh-manager
And verify that the manager is listening:
sudo ss -lntp | grep 1514
These tests provide useful troubleshooting information, but they should not replace automated load-balancer health checks.
Wazuh also provides several ways to verify agent connection status, including the Dashboard, agent_control, and the agent state file.
TCP health checks
A TCP health check is the simplest option for Wazuh agent traffic.
For HAProxy, for example:
backend wazuh_managers
mode tcp
balance leastconn
option tcp-check
server manager1 10.0.10.21:1514 check
server manager2 10.0.10.22:1514 check
server manager3 10.0.10.23:1514 check
The load balancer attempts to establish a TCP connection to each backend.
If the connection succeeds, the backend is considered available for the purposes of that check.
If the connection repeatedly fails, HAProxy can mark the backend as unavailable.
Wazuh’s official load-balancer documentation uses TCP-based load balancing for agent traffic and provides HAProxy and NGINX examples.
A TCP health check is appropriate when the primary requirement is determining whether the Wazuh agent connection service is accepting connections.
Application-level health checks
A TCP check has an important limitation: an open TCP port does not necessarily mean that the Wazuh manager is fully healthy.
For example:
TCP port 1514 → OPEN
Wazuh manager → DEGRADED
Indexer → UNAVAILABLE
Cluster → DESYNCHRONIZED
The load balancer may still consider the backend healthy because the TCP connection succeeds.
For more sophisticated deployments, supplement TCP checks with application-level monitoring.
Possible signals include:
- Wazuh manager service status.
- Wazuh cluster health.
- Agent connection status.
- Wazuh server API availability.
- System CPU and memory utilization.
- Wazuh manager logs.
- Indexer connectivity.
- Cluster synchronization status.
This distinction is important because the load balancer should determine whether a node is suitable for new agent connections, while Wazuh monitoring should determine whether the broader security platform is healthy.
See Fixing Wazuh Cluster Desync Caused by Master-Worker Time Drift when cluster health is the underlying problem.
Removing failed managers from rotation
When a Wazuh manager fails its health check, the load balancer should remove it from the active backend pool.
For example:
Before failure:
Manager 1 → UP
Manager 2 → UP
Manager 3 → UP
After Manager 2 fails:
Manager 1 → UP
Manager 2 → DOWN
Manager 3 → UP
New connections should then be distributed between Managers 1 and 3.
Existing TCP connections require additional consideration.
A load balancer generally cannot magically transfer an established TCP session from one backend server to another.
If the backend fails, the affected agent must establish a new connection.
This is why the Wazuh agent’s reconnection behavior is an important part of the overall availability design.
Wazuh documents the agent connection as a persistent communication channel and provides mechanisms for verifying whether an agent is connected or disconnected.
Reintroducing recovered managers
A recovered manager should not necessarily be placed immediately back into production without validation.
A safer sequence is:
Manager fails
↓
Health check detects failure
↓
Manager removed from rotation
↓
Manager repaired
↓
Service restarted
↓
Health check succeeds
↓
Manager returned to rotation
Before returning the server to the pool, verify:
sudo systemctl status wazuh-manager
Then confirm that port 1514 is available:
sudo ss -lntp | grep 1514
You should also verify Wazuh cluster health and confirm that the node is properly synchronized.
This is especially important after maintenance involving configuration, certificates, networking, or cluster membership.
Testing failover behavior
Do not assume that failover works simply because the load balancer configuration passes a syntax check.
Perform an actual failure test in a controlled environment.
A useful test sequence is:
- Connect several test agents through the load balancer.
- Confirm all backend managers are healthy.
- Record the backend connection distribution.
- Stop the Wazuh manager service on one worker.
- Verify that the load balancer detects the failure.
- Confirm that new connections avoid the failed worker.
- Verify agent reconnection behavior.
- Restart the failed manager.
- Confirm that the health check detects recovery.
- Verify that the manager returns to the backend pool.
On an agent, Wazuh provides a state file that can be checked for the connection state:
grep ^status /var/ossec/var/run/wazuh-agentd.state
A healthy agent should report:
status='connected'
Wazuh also documents agent_control and the Dashboard as methods for verifying agent connectivity.
Configure High Availability for the Wazuh Load Balancer
A Wazuh server cluster can remain healthy while its load balancer becomes unavailable.
That creates an important architectural problem:
Load Balancer
│
┌──────────┼──────────┐
▼ ▼ ▼
Manager 1 Manager 2 Manager 3
If the single load balancer fails:
X
│
Load Balancer
│
X
Wazuh unreachable
The Wazuh managers may all be operational, but agents cannot reach them through the failed frontend.
Therefore, high availability should include the load-balancing tier itself.
Load balancer as a single point of failure
A single HAProxy or NGINX server is itself a single point of failure.
For a development environment, that may be acceptable.
For a production security-monitoring platform, it can undermine the availability benefits of the Wazuh cluster.
Consider:
Without LB redundancy:
Agents
│
▼
Single HAProxy
│
├── Manager 1
├── Manager 2
└── Manager 3
versus:
With LB redundancy:
Virtual IP
│
┌───────┴───────┐
▼ ▼
HAProxy 1 HAProxy 2
ACTIVE STANDBY
│ │
└───────┬───────┘
│
┌─────────┼─────────┐
▼ ▼ ▼
Manager 1 Manager 2 Manager 3
The second architecture removes the individual load-balancer host as a single point of failure.
Active/passive load balancers
An active/passive architecture uses two load-balancer instances.
One owns the production virtual IP while the second remains ready to assume ownership.
For example:
10.0.10.10
Virtual IP
│
┌────┴────┐
▼ ▼
HAProxy 1 HAProxy 2
ACTIVE STANDBY
If HAProxy 1 fails, the virtual IP moves to HAProxy 2.
Agents continue using:
wazuh.example.com
without needing to know which load-balancer host currently owns the address.
This is a straightforward design for on-premises Wazuh environments.
Keepalived and virtual IP addresses
Keepalived can be used to provide high availability through VRRP and a floating virtual IP.
The architecture becomes:
Virtual IP
10.0.10.10
│
┌─────────┴─────────┐
▼ ▼
Load Balancer 1 Load Balancer 2
MASTER BACKUP
Keepalived manages ownership of the virtual IP while HAProxy or NGINX handles the actual Wazuh traffic.
A health-check script can also be used to determine whether the local load-balancer service is functioning.
The important separation is:
- Keepalived: Determines which load balancer owns the virtual IP.
- HAProxy/NGINX: Distributes connections to Wazuh managers.
- Wazuh cluster: Synchronizes the Wazuh server nodes.
Do not confuse these responsibilities.
See The Complete Wazuh Cluster Architecture Guide for the distinction between Wazuh clustering and external load balancing.
Active/active configurations
An active/active design allows multiple load balancer instances to handle production traffic simultaneously.
For example:
DNS / Anycast / Cloud LB
│
┌───────┴───────┐
▼ ▼
LB Node 1 LB Node 2
│ │
└───────┬───────┘
▼
Wazuh Managers
Active/active architectures can increase capacity and eliminate dependence on a single active load-balancer node.
However, they are more complex to design because you need to determine:
- How clients discover each load balancer.
- How health is propagated.
- How connections are distributed.
- Whether source persistence is required.
- How failover occurs.
- How configuration changes are synchronized.
For many self-managed deployments, active/passive HAProxy plus Keepalived is simpler to operate.
DNS-based failover
DNS can also provide a failover mechanism.
For example:
wazuh.example.com
│
├── LB 1
└── LB 2
A DNS-based failover system can remove an unavailable endpoint from DNS responses.
However, DNS failover has limitations.
Existing TCP connections do not automatically move when a DNS record changes.
Agents that already have established connections may continue trying to use the existing connection until it fails.
DNS caching and resolver behavior can also delay failover.
For this reason, DNS failover should not be treated as equivalent to a virtual IP-based failover mechanism.
Cloud-native high availability
Cloud environments can use managed load-balancing services to avoid maintaining load-balancer hosts manually.
A cloud architecture might look like:
Cloud Load Balancer
│
┌───────────┼───────────┐
▼ ▼ ▼
Wazuh VM Wazuh VM Wazuh VM
Zone A Zone B Zone C
This can provide built-in redundancy across availability zones or equivalent infrastructure domains.
Before using a managed service, verify that it supports the Wazuh traffic requirements, particularly TCP forwarding for agent communication.
Wazuh documents TCP port 1514 as the default agent connection service and 1515/TCP as the default enrollment service.
Testing load balancer failover
Load-balancer failover should be tested independently from Wazuh manager failover.
For example:
- Confirm both load-balancer nodes are healthy.
- Confirm the virtual IP is owned by the active node.
- Connect test agents.
- Verify traffic reaches the Wazuh managers.
- Stop HAProxy or NGINX on the active node.
- Verify the virtual IP moves to the standby node.
- Confirm the DNS name still resolves correctly.
- Confirm new agent connections reach the Wazuh cluster.
- Verify agent reconnection behavior.
- Restore the original load-balancer node.
- Confirm the HA state returns to the intended configuration.
The test should include both new connections and existing agent sessions, because established TCP sessions may behave differently from new connections during a load-balancer failure.
Wazuh Load Balancer and TLS/SSL
Encryption is an important consideration when placing a load balancer between Wazuh agents and Wazuh managers.
The load balancer introduces another network hop, but it should not automatically become a point where encrypted traffic is decrypted.
Wazuh’s architecture documentation states that the agent communicates with the Wazuh server through a secure channel and that the default agent connection service uses TCP port 1514.
Wazuh also states that the Wazuh agent sends security data through an encrypted and authenticated channel.
Why Wazuh traffic should be encrypted
Wazuh agents can transmit sensitive security information, including:
- Authentication events.
- Process information.
- File-integrity events.
- Security configuration data.
- System inventory.
- Application logs.
- Network-related events.
Wazuh documents its agent-server communication as encrypted and authenticated, providing protection for data transmitted from monitored endpoints.
Encryption therefore needs to remain intact when introducing the load-balancing layer.
The preferred architecture should generally look like:
Agent
│
│ Encrypted
▼
Load Balancer
│
│ Encrypted
▼
Wazuh Manager
rather than:
Agent
│
│ Encrypted
▼
Load Balancer
│
│ Unencrypted
▼
Wazuh Manager
The second architecture creates a plaintext segment between the load balancer and Wazuh manager.
TLS termination vs. TLS passthrough
There are two primary approaches.
TLS passthrough
The load balancer forwards the encrypted TCP connection without decrypting it.
Agent
│
│ TLS / encrypted
▼
Load Balancer
│
│ TLS / encrypted
▼
Wazuh Manager
The Wazuh manager remains responsible for the TLS endpoint.
This approach minimizes certificate-management responsibilities on the load balancer and maintains encryption through the entire network path.
TLS termination
The load balancer decrypts the client connection:
Agent
│
│ TLS
▼
Load Balancer
│
│ New connection
▼
Wazuh Manager
If this model is used, the connection between the load balancer and Wazuh manager should normally be encrypted as well.
Otherwise, the architecture becomes:
Agent
│ TLS
▼
Load Balancer
│
│ PLAINTEXT
▼
Wazuh Manager
which creates an unnecessary security weakness.
For Wazuh agent traffic, TCP passthrough is often simpler because the load balancer can distribute connections without becoming part of the certificate trust chain.
Certificates for the load balancer
If TLS terminates at the load balancer, the load balancer requires a certificate and private key appropriate for the hostname used by agents.
For example:
Agent configuration:
wazuh.example.com
Certificate:
SAN = wazuh.example.com
The certificate should be issued by a CA trusted by the clients.
Private keys should be protected with appropriate filesystem permissions and operational controls.
If you use TLS passthrough, the Wazuh managers remain responsible for their certificates instead.
Wazuh supports manager identity verification using SSL certificates, allowing an agent to verify the identity of the Wazuh manager during enrollment.
See How to Configure Wazuh SSL for the broader certificate and TLS configuration process.
Certificate validation
Certificate validation should account for the hostname that the agent actually uses.
Suppose the agent connects to:
wazuh.example.com
but the backend manager certificate contains only:
manager01.internal.example.com
A strict hostname-validation model may reject that certificate because the requested identity does not match the certificate identity.
Wazuh’s manager identity verification documentation explicitly requires the manager certificate to identify the manager using an IP address or FQDN and uses the CA certificate to verify the manager’s identity.
Therefore, when introducing a load-balancer hostname, carefully determine where certificate identity validation occurs.
If the load balancer terminates TLS, the frontend certificate must match the load-balancer hostname.
If TLS passes through, the backend certificate and Wazuh agent verification behavior must be compatible with the endpoint the agent uses.
Backend TLS connections
If TLS terminates at the load balancer, consider encrypting the backend connection as well:
TLS
Agent ─────────────────> Load Balancer
│
│ TLS
▼
Manager
This creates encryption across both network segments.
The load balancer then performs two TLS functions:
- It terminates the client-side TLS connection.
- It establishes a separate TLS connection to the Wazuh manager.
The certificates and trust configuration for these two connections can be different.
This model provides strong transport protection but increases operational complexity.
You must manage:
- Frontend certificates.
- Backend certificates.
- CA trust.
- Certificate renewal.
- TLS versions.
- Cipher configuration.
- Private keys.
- Health checks.
- Certificate expiration monitoring.
Wazuh’s central components also use certificates to establish trust and confidentiality between components such as Filebeat, the Wazuh indexer, and the Wazuh Dashboard.
Avoiding insecure configurations
Avoid configurations that unintentionally disable certificate verification or introduce plaintext backend traffic.
For example, do not treat a successful TCP connection as proof that TLS is correctly configured.
A connection can be:
TCP → SUCCESS
TLS → FAILED
Certificate validation → FAILED
Wazuh authentication → FAILED
Each layer should be tested independently.
Also avoid disabling certificate validation simply to make a load-balanced deployment work.
Wazuh provides explicit certificate-based manager identity verification, including CA-based validation and hostname/IP identity checking.
A secure deployment should preserve those trust controls rather than bypassing them.
Relationship between Wazuh load balancing and Wazuh SSL/TLS
Load balancing and TLS solve different problems.
Load balancing determines:
Which Wazuh manager should receive this connection?
TLS determines:
How is the connection protected and how are identities verified?
They therefore operate together:
Wazuh Load Balancing
│
▼
Agent ──────── TLS ───────> Load Balancer
│
TCP distribution
│
┌────────────┼────────────┐
▼ ▼ ▼
Manager 1 Manager 2 Manager 3
Wazuh’s agent connection service uses a secure communication channel by default, and the manager configuration defines the secure agent connection service on TCP port 1514.
The load balancer should therefore be introduced without weakening the security properties of the underlying Wazuh connection.
For most deployments, a strong architecture is:
Wazuh Agents
│
│ Encrypted
▼
Highly Available
Wazuh Load Balancer
│
│ Encrypted
┌─────────┼─────────┐
▼ ▼ ▼
Manager 1 Manager 2 Manager 3
│ │ │
└─────────┼─────────┘
▼
Wazuh Indexer Cluster
This separates the responsibilities cleanly:
- Load balancer: Distributes agent connections.
- Health checks: Determine which managers can receive new connections.
- Keepalived or managed HA: Protects the load-balancer layer.
- TLS: Protects traffic and provides authentication where configured.
- Wazuh cluster: Coordinates the Wazuh server nodes.
- Wazuh indexer cluster: Stores and indexes Wazuh data.
The result is a Wazuh deployment where adding a load balancer improves availability and scalability without compromising the encrypted and authenticated communication that Wazuh agents use to communicate with Wazuh servers.
Load Balancing Wazuh Indexers
The Wazuh Indexer layer has a different role from the Wazuh server layer, so its load-balancing strategy should be designed separately.
Wazuh uses the Wazuh Indexer to store and search alerts and other security data generated by Wazuh servers.
In a multi-node deployment, the indexer can distribute shards across multiple nodes, providing redundancy and additional query capacity.
This means you can have two distinct load-balancing layers:
Do not assume that a load balancer placed in front of the Wazuh managers automatically load-balances Indexer traffic. These are separate communication paths.
When Wazuh Indexer load balancing is needed
A dedicated load-balancing layer for the Wazuh Indexer becomes more useful as the environment grows and multiple components need a stable endpoint for Indexer access.
However, a Wazuh Indexer cluster does not necessarily require an external load balancer.
Wazuh’s server configuration can contain multiple Indexer hosts.
When multiple hosts are configured, the Wazuh server prioritizes the first host and switches to another if the first becomes unavailable.
For example:
This provides a form of client-side failover without requiring a separate load balancer.
A dedicated Indexer load balancer may make sense when you need:
- A single stable Indexer endpoint.
- Centralized traffic distribution.
- A consistent endpoint for multiple clients.
- Infrastructure-level health checks.
- Integration with an existing enterprise load-balancing platform.
- A cloud-managed load-balancing service.
- Additional control over routing and failover.
For smaller deployments, using multiple Indexer hosts directly may be simpler.
See The Ultimate Wazuh Indexer Guide for broader guidance on designing and operating the Indexer layer.
Indexer cluster architecture
A Wazuh Indexer cluster distributes data across multiple nodes using shards.
For example:
The Indexer cluster itself provides redundancy and distributes indexing and search workloads.
Wazuh documents several Indexer node roles, including cluster-manager, data, ingest, and coordinating roles.
Every Indexer node can act as a coordinating node by default, while dedicated coordinating nodes can be configured when required.
This distinction matters when deciding where a load balancer should send requests.
A common architecture is:
The load balancer distributes client requests, while the Indexer cluster distributes those requests internally across shards.
Load balancing OpenSearch API traffic
The Wazuh Indexer exposes an OpenSearch-compatible API over HTTPS, commonly on TCP port 9200.
Wazuh’s architecture documentation identifies port 9200/TCP as the default Wazuh Indexer listening port.
A Layer 4 load balancer can therefore forward TCP connections:
Alternatively, a Layer 7 proxy can understand HTTPS and HTTP-level behavior.
For an OpenSearch-compatible API, Layer 7 routing can provide more sophisticated health checks and request-level controls, but it also introduces additional TLS and proxy configuration.
A basic HAProxy TCP configuration could look like:
This treats the Indexer API as encrypted TCP traffic and leaves TLS handling to the Indexer nodes.
OpenSearch’s client documentation also describes connection pools and node failover mechanisms for distributing requests across OpenSearch nodes.
Dashboard-to-Indexer connectivity
The Wazuh Dashboard queries the Wazuh Indexer to retrieve alerts, statistics, visualizations, and other security data.
Therefore, if you put a load balancer in front of the Indexer, the Dashboard can use the load-balancer endpoint instead of addressing an individual Indexer node.
The architecture becomes:
The Wazuh architecture separates the Dashboard, server, and Indexer roles.
Wazuh servers process events and forward data to the Indexer, while the Dashboard queries the Indexer for visualization and analysis.
This is different from agent traffic:
versus:
Each path should be configured and tested independently.
TLS considerations
Indexer traffic should remain encrypted.
Wazuh’s architecture documentation states that the Wazuh server uses Filebeat to send data to the Wazuh Indexer using TLS encryption.
A TCP passthrough architecture looks like:
The load balancer forwards encrypted traffic without terminating TLS.
If TLS is terminated at the load balancer, the backend connection should also be encrypted where the security requirements call for it:
Do not create an unnecessary plaintext segment simply because TLS termination is enabled at the frontend.
Wazuh’s server configuration includes CA, certificate, and private-key settings for secure Indexer communication.
See How to Configure Wazuh SSL for certificate and TLS configuration details.
Why Indexer load balancing differs from Manager load balancing
The most important distinction is the type of workload.
The Wazuh manager load balancer primarily distributes agent connections:
The Indexer layer handles indexing and search requests:
There is another major distinction: Wazuh explicitly recommends using a load balancer to distribute agent enrollment and reporting among Wazuh server nodes.
For Indexers, Wazuh already supports configuring multiple Indexer hosts directly in the Wazuh server configuration.
Consequently, an external Indexer load balancer is an architectural option rather than an automatic requirement.
See How to Build a Wazuh Indexer Cluster and How to Configure Wazuh Cross Cluster Search for additional Indexer architecture considerations.
How to Test a Wazuh Load Balancer
A Wazuh load balancer should be tested at multiple layers.
A successful TCP connection alone does not prove that Wazuh is functioning correctly.
Use this progression:
Verify the load balancer is listening
Start by checking whether the load balancer is listening on the expected port.
For Linux:
For HAProxy:
For NGINX:
You can also inspect the listening sockets:
The expected architecture is:
If nothing is listening, there is no reason to investigate the Wazuh backend yet.
Test TCP connectivity
From a Wazuh agent or another host on the same network:
You can also use:
if Telnet is installed.
For a successful connection, you should see an indication that the TCP connection was established.
Remember that this tests network connectivity, not Wazuh authentication.
Verify backend health
Test each Wazuh manager directly from the load-balancer server:
Then verify the Wazuh manager services:
Check the manager logs when necessary:
If one backend fails while the others work, the problem is likely isolated to that Wazuh manager or its network path.
Connect a Wazuh agent
Configure a test agent to use the load-balancer endpoint:
Then restart the agent:
Wazuh officially documents configuring agents to use a load balancer by replacing the server address in the agent’s <server> configuration with the load-balancer address.
Check manager distribution
After connecting several agents, determine which Wazuh managers are receiving connections.
The distribution may not be perfectly equal, particularly when agent connections are long-lived.
For example:
is not necessarily evidence of a problem.
The important question is whether multiple healthy managers are receiving connections according to the selected load-balancing algorithm.
Wazuh’s HAProxy example uses leastconn, and Wazuh also documents that the load balancer assigns manager nodes to agents to distribute the workload.
Simulate a manager failure
Perform failure testing in a controlled environment.
For example, stop one manager:
Then wait for the load balancer’s health check to detect the failure.
Verify that the failed backend is no longer receiving new connections.
Verify automatic failover
After the manager failure, restart or reconnect a test agent and verify that it reaches another healthy manager.
The expected behavior is:
Wazuh explicitly documents that agents connected through a load balancer can reconnect to another Wazuh server node when a worker fails.
Monitor logs for connection errors
Monitor the Wazuh agent:
Monitor the manager:
And monitor the load balancer.
For HAProxy, depending on your logging configuration:
For NGINX:
Look for:
- Connection refused.
- Connection timeout.
- Backend marked down.
- Backend recovery.
- TLS handshake failures.
- Connection resets.
- DNS resolution errors.
- Repeated agent reconnections.
Troubleshooting Wazuh Load Balancer Issues
Troubleshooting should proceed from the outside inward.
This prevents you from debugging Wazuh configuration when the actual problem is a blocked TCP port or incorrect DNS record.
Wazuh agents cannot connect
Start with DNS:
Then test the port:
If the port is unreachable, check:
- Agent firewall.
- Load-balancer firewall.
- Network ACLs.
- Cloud security groups.
- HAProxy/NGINX listener.
- Wazuh manager firewall.
- Routing.
If the port is reachable but the agent remains disconnected, inspect:
See Wazuh Agent Not Connecting to Manager? 12 Proven Fixes for a broader agent-connectivity troubleshooting workflow.
Agents connect but are not distributed
First verify the backend configuration.
For HAProxy:
Make sure every expected backend is actually configured.
Then check whether the backends are healthy.
A second issue is connection duration.
If agents establish long-lived TCP connections, a load balancer cannot redistribute existing sessions simply because you changed the balancing configuration.
Distribution therefore needs to be evaluated across new connections, not only existing sessions.
Backend servers appear unhealthy
Test each manager directly:
Then:
And:
If the service is running but the port is inaccessible, investigate:
- Firewall rules.
- Listen address.
- SELinux/AppArmor policy.
- Network ACLs.
- Routing.
- Incorrect IP addresses.
- Port configuration.
If the port is accessible but the health check still fails, inspect the load-balancer configuration.
TLS certificate errors
TLS failures can occur at several points:
Determine which connection is failing.
Common causes include:
- Expired certificate.
- Wrong hostname.
- Missing CA.
- Incorrect certificate chain.
- Wrong private key.
- Certificate/key mismatch.
- Unsupported TLS configuration.
- Incorrect trust store.
- Certificate SAN does not match the endpoint.
Check the certificate:
If TLS passthrough is being used, remember that the load balancer may not be the component validating the certificate.
See How to Fix Wazuh Certificate Errors and How to Configure Wazuh SSL.
Connection resets
A TCP reset can originate from the:
- Wazuh agent.
- Load balancer.
- Firewall.
- Wazuh manager.
- Intermediate network device.
Inspect the logs on both sides of the connection.
For HAProxy:
For the Wazuh manager:
You can also inspect active connections:
Repeated resets across multiple managers may indicate a load-balancer or network problem rather than a single unhealthy Wazuh worker.
Incorrect firewall rules
The firewall must permit the required traffic in both directions.
A simplified architecture is:
Therefore, allowing 1514/TCP from agents to the load balancer is insufficient if the load balancer cannot reach the managers on 1514/TCP.
Test from the load-balancer host:
Then test from the agent:
The two tests isolate the two network segments.
DNS resolution problems
Verify DNS from an affected agent:
or:
Confirm that the result is the expected load-balancer address.
Also verify that internal and external DNS clients are not receiving inappropriate records.
A useful test is:
from:
- Wazuh agents.
- Load balancer.
- Administrative workstation.
If different systems resolve the hostname differently, investigate split-horizon DNS, stale records, or incorrect DNS zones.
Port configuration errors
Verify the complete port path.
For agent reporting:
For agent enrollment, a separate service may be involved.
Wazuh documents TCP 1515 as the default enrollment service.
Do not assume that exposing 1514 automatically exposes enrollment.
Likewise, Indexer traffic is separate and commonly uses TCP 9200.
See How to Configure a Wazuh Proxy for additional Wazuh network and proxy considerations.
Load balancer fails to detect manager failures
First determine whether the TCP health check is actually running.
For HAProxy, check the backend configuration:
Then inspect HAProxy logs or statistics.
A common conceptual problem is expecting a TCP check to determine complete Wazuh application health.
For example:
A TCP health check can still mark the backend as healthy.
If deeper health detection is required, implement an application-aware monitoring mechanism in addition to the basic TCP check.
Agents reconnect repeatedly
Repeated reconnections can indicate:
- Wazuh manager instability.
- Network packet loss.
- Firewall timeouts.
- Load-balancer timeout settings.
- TLS problems.
- Backend failures.
- Incorrect cluster configuration.
- Resource exhaustion.
Start by examining the agent log:
Then inspect the manager:
Check system resources:
and:
Also examine the load-balancer logs for connection resets or backend state changes.
See Why Is Wazuh Using High CPU? Troubleshooting Guide if resource exhaustion is suspected.
Uneven traffic distribution
Uneven distribution does not automatically indicate a broken load balancer.
For example:
may be perfectly reasonable.
Wazuh specifically documents HAProxy support for algorithms including round-robin, leastconn, and source.
The selected algorithm affects the distribution.
leastconn is particularly useful when connections have different lifetimes because it considers the number of active connections.
Also consider the behavior of long-lived Wazuh agent connections.
A load balancer distributes new connections; it does not continually move established sessions between managers.
If distribution is severely skewed:
- Verify all backends are healthy.
- Confirm all managers are configured in the backend pool.
- Check the selected balancing algorithm.
- Check whether source-IP persistence is enabled.
- Check the number and duration of existing connections.
- Restart a controlled subset of test agents.
- Observe where the new connections land.
- Compare load-balancer statistics with Wazuh manager connection counts.
Wazuh’s current documentation also describes an optional HAProxy helper that can dynamically add or remove Wazuh server nodes and rebalance agents when the cluster changes or when an imbalance exceeds a configured tolerance.
See Step-by-Step Wazuh Manager Scaling Guide if uneven distribution is occurring because the Wazuh server cluster is being expanded.
The key troubleshooting principle is to distinguish between load-balancer distribution, Wazuh manager availability, and Wazuh cluster health.
A Wazuh load balancer can correctly route TCP connections while the underlying Wazuh cluster still has configuration, synchronization, or resource problems.
Wazuh Load Balancer Best Practices
A Wazuh load balancer should be treated as part of the security-monitoring infrastructure rather than simply as a network convenience.
A correctly configured load balancer can improve availability and distribute agent connections, but poor health checks, weak TLS configuration, or an unprotected load-balancer host can introduce new failure points.
Wazuh’s documentation recommends using a load balancer to distribute agent connections among Wazuh server nodes and documents HAProxy and NGINX-based approaches.
Use redundant load balancers
Avoid placing every Wazuh agent behind a single load-balancer server in production.
A more resilient architecture uses two load balancers:
HAProxy or NGINX can handle traffic distribution while Keepalived can provide a floating virtual IP for active/passive deployments.
This prevents a failure of the load-balancer host from making otherwise healthy Wazuh managers unreachable.
Use TLS for Wazuh communications
Wazuh agent communication should remain encrypted and authenticated.
When introducing a load balancer, avoid accidentally creating a plaintext segment between the load balancer and Wazuh managers.
A preferred architecture is:
TCP passthrough is often attractive because the load balancer can distribute connections without terminating the Wazuh TLS session.
If TLS is terminated at the load balancer, protect the backend connection as well when required by your security architecture.
See How to Configure Wazuh SSL for detailed Wazuh TLS configuration guidance.
Configure reliable health checks
Health checks determine whether a backend Wazuh manager should receive new connections.
At minimum, verify that the Wazuh agent communication port is accepting TCP connections.
For example:
The load balancer should remove Manager 3 from rotation.
However, remember that a TCP check only confirms TCP-level availability. For larger environments, supplement it with monitoring of Wazuh service status and cluster health.
Monitor backend health
Health checks should not be the only source of information about your Wazuh managers.
Monitor:
- CPU utilization.
- Memory utilization.
- Disk usage.
- Agent connection counts.
- Wazuh manager service status.
- Cluster synchronization.
- Network errors.
- Load-balancer backend states.
- Authentication failures.
- Connection resets.
This allows you to distinguish between a manager that is genuinely unavailable and one that is technically listening but experiencing an application-level problem.
See Why Is Wazuh Using High CPU? Troubleshooting Guide and Troubleshooting Wazuh Cluster Desync Caused by Master-Worker Time Drift.
Avoid unnecessary Layer 7 processing
Wazuh agent communication is fundamentally a TCP workload.
For agent traffic, Layer 4 TCP load balancing is generally preferable to introducing unnecessary HTTP-level processing.
The architecture should therefore look like:
A Layer 7 proxy is useful when you actually need HTTP-aware routing, TLS termination, HTTP health checks, or similar functionality.
Do not use HTTP reverse-proxy features merely because the chosen load-balancing product supports them.
Use stable DNS names
Agents should ideally connect to a stable DNS name rather than a specific Wazuh manager.
For example:
instead of:
The DNS name can point to the load balancer or virtual IP:
This abstraction makes future infrastructure changes easier.
You can replace, upgrade, or expand backend managers without changing the configured endpoint on every agent.
Document failover procedures
Document what happens when each infrastructure component fails.
At minimum, document procedures for:
- Wazuh Manager failure.
- Load-balancer failure.
- Virtual IP failure.
- DNS failure.
- Certificate expiration.
- Network failure.
- Firewall changes.
- Indexer failure.
- Agent reconnection problems.
Include actual commands, expected results, escalation procedures, and rollback steps.
A documented procedure is considerably more useful during an incident than an architecture diagram that only describes the intended state.
Monitor connection distribution
Monitor how many agents are connected to each Wazuh manager.
For example:
Small differences are normal.
Significant imbalance may indicate:
- An unhealthy backend.
- Incorrect load-balancing algorithm.
- Source-IP persistence.
- Existing long-lived sessions.
- Incorrect backend configuration.
- A manager being repeatedly removed and re-added.
- Different agent reconnect patterns.
Wazuh’s documentation describes HAProxy configurations using balancing methods such as leastconn, which can be useful when agent connections have different lifetimes.
Test failure scenarios regularly
Do not wait for a production outage to discover that failover does not work.
Periodically test:
Also test:
Record the expected recovery time and compare it against the actual result.
Keep the load balancer software updated
HAProxy, NGINX, Keepalived, and the underlying operating system should be maintained like any other production infrastructure.
Regular maintenance should include:
- Security updates.
- Supported software versions.
- Configuration backups.
- Certificate renewal.
- Log rotation.
- Configuration validation.
- Service-restart testing.
- Disaster-recovery testing.
Before upgrading a production load balancer, validate the configuration:
or:
Keep a known-good configuration available so the service can be restored quickly if an upgrade introduces a problem.
Wazuh Load Balancer vs. Wazuh Cluster
A Wazuh cluster and a Wazuh load balancer are complementary technologies, but they solve different problems.
Confusing the two can result in an architecture that appears redundant while still containing a single point of failure or an improperly configured communication path.
Purpose of a Wazuh cluster
A Wazuh cluster allows multiple Wazuh server nodes to operate together.
Wazuh server clustering provides coordination and synchronization between the manager nodes, allowing workloads to be distributed across multiple servers.
Wazuh identifies one node as the cluster master and other nodes as workers in its cluster architecture.
Conceptually:
The cluster is concerned with Wazuh server coordination and synchronization.
Purpose of a load balancer
The load balancer provides a network endpoint through which agents can reach the available Wazuh managers.
Its job is primarily:
It decides where new connections should go based on its configured balancing algorithm and backend health.
The load balancer does not replace Wazuh clustering.
How they work together
The two technologies operate at different layers:
The load balancer handles traffic distribution.
The Wazuh cluster handles manager coordination.
This separation of responsibilities is fundamental to designing a reliable Wazuh deployment.
Load balancing vs. manager synchronization
A load balancer does not synchronize Wazuh configuration, cluster state, or databases.
For example, if you have:
the load balancer does not make their configurations identical.
That is the responsibility of the Wazuh cluster architecture and its associated synchronization mechanisms.
Conversely, Wazuh clustering does not automatically provide a network endpoint that replaces the need for an external load-balancing strategy for agent connections.
This is why the two components should be considered separately.
See The Complete Wazuh Cluster Architecture Guide for a deeper discussion of manager clustering.
When you need both
A production environment with a large number of agents can benefit from both:
The load balancer provides:
- Stable agent endpoint.
- Connection distribution.
- Backend health detection.
- Manager failover.
The Wazuh cluster provides:
- Multiple Wazuh server nodes.
- Cluster coordination.
- Configuration synchronization.
- Distributed processing.
For small environments, a load balancer may be unnecessary. For large environments, using both can provide a much stronger availability architecture.
Common architecture patterns
Single manager
Suitable for small deployments where high availability is not required.
Cluster without external load balancer
This can be appropriate when agents are configured with appropriate server endpoints and failover behavior.
Cluster behind one load balancer
This simplifies the agent endpoint but leaves the load balancer as a potential single point of failure.
Highly available production architecture
This architecture addresses redundancy at both the load-balancing and Wazuh server layers.
Frequently Asked Questions
Question: What is a Wazuh load balancer?
A Wazuh load balancer is a network component that distributes Wazuh agent connections among multiple Wazuh Manager nodes.
It provides a stable endpoint for agents while allowing backend managers to be added, removed, or failed over without requiring every agent to connect directly to an individual manager.
Question: Does Wazuh support load balancing?
Yes. Wazuh documents load-balancing configurations for distributing agent connections across Wazuh server nodes and provides examples using technologies such as HAProxy and NGINX.
Question: Can I load balance Wazuh Manager nodes?
Yes.
A load balancer can distribute agent connections across Wazuh manager worker nodes.
A typical architecture is:
The managers should still be configured as an appropriate Wazuh cluster where clustering is required.
Question: Can HAProxy be used with Wazuh?
Yes.
HAProxy is a common choice for Wazuh agent load balancing because it supports TCP proxying, backend health checks, and multiple load-balancing algorithms.
Wazuh provides official documentation and configuration examples for HAProxy.
Question: Can NGINX be used as a Wazuh load balancer?
Yes.
NGINX can forward Wazuh TCP traffic using its stream functionality.
For Wazuh agent traffic, configure NGINX as a TCP proxy rather than treating the agent connection as ordinary HTTP traffic.
Question: What ports does a Wazuh load balancer need?
The required ports depend on which Wazuh services you place behind the load balancer.
For standard agent communication, Wazuh commonly uses:
| Service | Default port | Typical protocol |
|---|---|---|
| Wazuh agent connection | 1514 | TCP |
| Wazuh agent enrollment | 1515 | TCP |
| Wazuh Indexer API | 9200 | HTTPS/TCP |
| Wazuh Dashboard | 443 | HTTPS/TCP |
Wazuh identifies 1514/TCP as the default agent connection port, 1515/TCP as the default enrollment port, and 9200/TCP as the default Indexer port.
Only expose and load balance the services your architecture actually requires.
Question: Should Wazuh load balancing use TCP or HTTP?
For Wazuh agent communication, TCP Layer 4 load balancing is generally the appropriate approach.
The agent connection is not ordinary HTTP traffic, so an HTTP reverse-proxy configuration is unnecessary unless you have a specific reason to introduce application-layer processing.
For Indexer API traffic, HTTP-aware load balancing can be appropriate because the Indexer API uses HTTPS.
Question: Does a Wazuh load balancer require TLS?
The load balancer itself does not necessarily need to terminate TLS.
You can use TLS passthrough, where the load balancer forwards encrypted TCP traffic to the Wazuh manager.
For example:
If the load balancer terminates TLS, configure certificates appropriately and protect the backend connection as required.
Question: How do Wazuh agents connect through a load balancer?
The agent’s Wazuh server address is configured as the load-balancer hostname or IP.
For example:
The agent connects to wazuh.example.com, and the load balancer forwards the connection to an available Wazuh manager.
Wazuh specifically documents configuring agents to use a load-balancer endpoint for clustered Wazuh server deployments.
Question: Can a Wazuh load balancer provide high availability?
A load balancer can improve Wazuh availability by removing failed managers from the backend pool and directing new connections to healthy managers.
However, one load-balancer server is itself a single point of failure.
For stronger availability, deploy redundant load balancers using technologies such as Keepalived and a virtual IP, or use an appropriate managed cloud load-balancing service.
Question: What happens when a Wazuh Manager goes down?
The load balancer should detect that the manager has failed its health check and stop sending new connections to it.
Agents with existing connections to the failed manager may need to reconnect.
New or re-established connections can then be sent to another healthy Wazuh manager.
Wazuh documents this failover behavior for agents connected through a load balancer.
Question: Do I need a load balancer if I already have a Wazuh cluster?
Not necessarily.
A Wazuh cluster and load balancer solve different problems.
The cluster provides manager coordination and synchronization, while the load balancer provides a stable endpoint and distributes agent connections.
For larger production environments, using both can provide a more robust architecture.
Question: Can I load balance Wazuh Indexers?
Yes.
Wazuh Indexers can be placed behind a load balancer when a deployment requires a stable endpoint or centralized distribution of Indexer API traffic.
However, Wazuh also supports configuring multiple Indexer hosts directly, allowing the Wazuh server to fail over between configured Indexer endpoints.
Therefore, an external Indexer load balancer is an architectural choice rather than a universal requirement.
Question: How do I troubleshoot Wazuh load balancer failures?
Start at the network edge and work toward the Wazuh application:
Useful commands include:
and:
See Wazuh Agent Not Connecting to Manager? 12 Proven Fixes, How to Fix Wazuh Certificate Errors, and Wazuh Dashboard Not Loading? Complete Troubleshooting Guide for related troubleshooting workflows.
Conclusion
A Wazuh load balancer provides an important layer of availability and scalability for environments running multiple Wazuh Manager nodes.
Instead of configuring every agent to communicate directly with a specific manager, agents can use a stable load-balancer endpoint:
The load balancer then distributes new connections among healthy managers and removes failed backends from rotation.
Recap of Wazuh load balancing
The key concepts covered in this guide are:
- A Wazuh load balancer distributes agent connections among Wazuh managers.
- HAProxy and NGINX can provide TCP-based Wazuh load balancing.
- Layer 4 TCP forwarding is generally appropriate for agent traffic.
- Health checks prevent failed managers from receiving new connections.
- TLS should remain enabled across Wazuh communications.
- Wazuh Manager clustering and load balancing perform different functions.
- Indexer load balancing should be designed separately from manager load balancing.
- A single load balancer can become a single point of failure.
- Redundant load balancers can provide higher availability.
Importance of health checks and redundancy
The effectiveness of a Wazuh load balancer depends heavily on its health-check and failover configuration.
A load balancer that simply distributes connections without detecting failed managers can make troubleshooting more difficult rather than improving availability.
Similarly, a single load-balancer server can undermine an otherwise redundant Wazuh cluster.
For production deployments, consider redundancy at both levels:
Recommended architecture for production deployments
For a larger Wazuh environment, a strong starting architecture is:
- Deploy multiple Wazuh Manager nodes as a Wazuh cluster.
- Place redundant HAProxy or NGINX instances in front of the managers.
- Use a virtual IP or managed load-balancing service for the frontend.
- Configure agents to use a stable DNS hostname.
- Use TCP load balancing for agent traffic.
- Configure reliable backend health checks.
- Preserve Wazuh TLS encryption.
- Monitor manager and load-balancer health.
- Monitor connection distribution.
- Regularly test both manager and load-balancer failover.
See The Complete Wazuh Cluster Architecture Guide and Step-by-Step Wazuh Manager Scaling Guide when expanding the backend Wazuh infrastructure.
Next steps for scaling and securing a Wazuh environment
Once the load-balancing layer is operational, the next priority should be making the entire Wazuh platform resilient.
Consider expanding the architecture with:
- A multi-node Wazuh Manager cluster.
- A multi-node Wazuh Indexer cluster.
- Redundant load balancers.
- Centralized certificate management.
- Automated agent deployment.
- Indexer storage and retention policies.
- Monitoring for manager and Indexer health.
- Automated configuration backups.
- Disaster-recovery procedures.
- Regular failover testing.
See The Ultimate Wazuh Agent Deployment Guide, The Ultimate Wazuh Indexer Guide, and Wazuh Data Retention Guide for the next stages of building a scalable Wazuh environment.
Ultimately, the goal is not simply to put HAProxy or NGINX in front of Wazuh.
A production-ready architecture should eliminate avoidable single points of failure while preserving Wazuh’s encrypted communications, maintaining manager synchronization, and providing predictable recovery when infrastructure components fail.
Be First to Comment