Why this matters beyond the homelab: SIEM deployment and alert pipeline design are core to enterprise SOC and security engineering roles.

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

VLAN Subnet Purpose

1 (Management) 192.168.1.0/24 Proxmox hosts, network gear

20 (Services) 192.168.20.0/24 VMs, application services

30 (IoT) 192.168.30.0/24 IoT devices

40 (DMZ) 192.168.40.0/24 External-facing services

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:

Port Protocol Service Purpose

1515 TCP Wazuh-authd Initial enrollment - RSA key exchange

1514 TCP Wazuh-remoted Ongoing data stream - logs, FIM, inventory

55000 TCP Wazuh-API API access for n8n integration and management

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

Agent ID Name Host VLAN Method

001 Millennium Falcon Node-A (FCM2250) 1 Manual - dependency fix required

002 Gozanti Cruiser Node-C (OptiPlex7050) 1 Renamed post-enrollment

003 CR90 Corvette Node-B (QCM1255) 1 lsb-release fix, then script

004 AdGuard LXC on Node-C 20 Script

005 Phoenix-Nest VM on Node-B 20 Script

006 Home One VM on Node-B 20 Script

007 Tantive-III VM on Node-A 20 Script

008+ Additional containers Various 20 Script

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.