Wazuh Agent Enrollment Across a Multi-VLAN Homelab

The Problem

Deploying Wazuh agents sounds simple: install the package, point it at the manager, start the service. In practice, every host in my cluster had a different reason to fail - missing dependencies, missing sudo, firewall rules silently blocking enrollment, and a Debian version that didn't ship lsb-release by default.

This post documents every failure I hit while enrolling 10 agents across a 3-node Proxmox cluster with 4-VLAN segmentation, and the reusable deployment script that came out of it.

The Environment

Wazuh Manager:  LXC 110 on Node-C (Gozanti Cruiser)
Manager IP:     192.168.20.30
Agent Targets:  Proxmox hosts, LXC containers, VMs across 4 VLANs
Network:        UniFi Dream Machine with inter-VLAN firewall rules

VLAN Layout

The Wazuh manager sits on VLAN 20. Agents on VLAN 1 (Proxmox hosts) and VLAN 20 (VMs) need to reach it - which means inter-VLAN firewall rules are required.

Port Requirements

Before any agent can enroll, these ports must be open from agent → manager:

In the UniFi firewall, these are explicit allow rules from VLAN 1 → VLAN 20 and within VLAN 20 itself. Without the 1515 rule, agent enrollment silently hangs with no error message - the agent just never appears in the dashboard.

UniFi Firewall Rule

Name:        Allow Wazuh Agent Communication
Action:      Allow
Source:      VLAN 1 (Management), VLAN 20 (Services)
Destination: 192.168.20.30
Ports:       1514, 1515, 55000
Protocol:    TCP

Failure #1: lsb-release Not Installed (QCM1255 / Node-B)

The first agent I tried to install was on the bare Proxmox host - Node-B (CR90 Corvette, QCM1255):

wget https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-agent/wazuh-agent_4.14.2-1_amd64.deb
WAZUH_MANAGER='192.168.20.30' WAZUH_AGENT_NAME='Node-B_QCM1255_CR-90Corvette' dpkg -i ./wazuh-agent_4.14.2-1_amd64.deb

dpkg: dependency problems prevent configuration of wazuh-agent:
 wazuh-agent depends on lsb-release; however:
  Package lsb-release is not installed.

Proxmox's base Debian doesn't ship lsb-release. The Wazuh agent .deb lists it as a hard dependency. The fix:

apt-get update
apt-get install -y lsb-release
dpkg --configure wazuh-agent

After installing the dependency and reconfiguring, the agent started normally.

Failure #2: sudo Not Found (Proxmox Host)

On a bare Proxmox host, you're root by default. Copy-pasting the Wazuh dashboard's enrollment commands includes sudo:

sudo systemctl daemon-reload
sudo systemctl enable wazuh-agent
sudo systemctl start wazuh-agent

-bash: sudo: command not found

Proxmox doesn't install sudo. Drop it and run directly:

systemctl daemon-reload
systemctl enable wazuh-agent
systemctl start wazuh-agent

Failure #3: Agent Service Fails to Start

Even after fixing the dependency, the first start attempt failed:

systemctl start wazuh-agent
# Job for wazuh-agent.service failed because the control process exited with error code.

The issue was that the agent was installed before lsb-release existed, so the initial configuration was incomplete. A clean reinstall with the environment variables set fixed it:

apt-get purge wazuh-agent -y
WAZUH_MANAGER='192.168.20.30' WAZUH_AGENT_NAME='Node-B_QCM1255_CR-90Corvette' dpkg -i ./wazuh-agent_4.14.2-1_amd64.deb
systemctl daemon-reload
systemctl enable wazuh-agent
systemctl start wazuh-agent

Verification:

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

wazuh-agentd: INFO: Connected to the server (192.168.20.30:1514/tcp).
sca: INFO: Loaded policy '/var/ossec/ruleset/sca/cis_debian13.yml'
sca: INFO: Starting Security Configuration Assessment scan.
wazuh-modulesd:syscollector: INFO: Evaluation finished.

The Standardized Deployment Script

After hitting variations of these issues across multiple hosts, I wrote a reusable script:

#!/bin/bash
# install-wazuh-agent.sh
# Usage: ./install-wazuh-agent.sh "AgentName"

MANAGER_IP="192.168.20.30"
AGENT_NAME="${1:?Usage: $0 <agent-name>}"

echo "[*] Installing Wazuh agent: ${AGENT_NAME} → ${MANAGER_IP}"

# Install dependencies
apt-get update -q
apt-get install -y lsb-release curl

# Clean any previous install
apt-get purge wazuh-agent -y 2>/dev/null

# Download and install
wget -q https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-agent/wazuh-agent_4.14.2-1_amd64.deb -O /tmp/wazuh-agent.deb
WAZUH_MANAGER="${MANAGER_IP}" WAZUH_AGENT_NAME="${AGENT_NAME}" dpkg -i /tmp/wazuh-agent.deb

# Harden configuration - force manager address
sed -i "s/<address>.*<\/address>/<address>${MANAGER_IP}<\/address>/g" /var/ossec/etc/ossec.conf

# Fix permissions and start
chown -R wazuh:wazuh /var/ossec
systemctl daemon-reload
systemctl enable wazuh-agent
systemctl start wazuh-agent

# Verify
sleep 3
if systemctl is-active --quiet wazuh-agent; then
    echo "[✓] Agent '${AGENT_NAME}' is running and connected to ${MANAGER_IP}"
else
    echo "[✗] Agent failed to start. Check: journalctl -xeu wazuh-agent.service"
    exit 1
fi

# Show last log entries
tail -5 /var/ossec/logs/ossec.log

Deploy to any new Debian/Ubuntu host:

scp install-wazuh-agent.sh root@<host>:/tmp/
ssh root@<host> "/tmp/install-wazuh-agent.sh 'Phoenix-Nest'"

Enrolled Agents

Verification From the Manager

Post-deployment health checks from the Wazuh Manager:

# Check API readiness
curl -u admin:admin -k -X GET "https://localhost:55000/ready?pretty=true"

# List all active agents with last keep-alive
/var/ossec/bin/agent_control -l

All agents should show status='connected' with keep-alive timestamps within 30 seconds. A stale timestamp means the inter-VLAN firewall rule for port 1514 isn't working - check the UniFi rule.

What I'd Do Differently

1. Install lsb-release before the agent - add it to your base image or post-install script for every Proxmox host and container.
2. Use the script from the start - don't manually copy-paste the dashboard commands. The script handles edge cases the dashboard doesn't mention.
3. Test the firewall rules first - before deploying any agent, verify port 1515 is open with nc -zv 192.168.20.30 1515 from the target host. Silent enrollment failures waste the most time.

Related: Post 008 - Wazuh: When to Stop Fighting and Use the Script covers the server-side installation journey.