Skip to main content

Wazuh Agent Deployment & Troubleshooting Guide


This guide documents the installation, configuration, and troubleshooting of Wazuh agents on Ubuntu 22.04 and 24.04 endpoints, specifically focusing on fixing version mismatches and enabling Docker monitoring.

1. Standard Agent Installation & Connection

To install an agent and connect it to the central manager, use the following commands:

# Install the agent (Replace WAZUH_MANAGER with actual IP)
curl -sO https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-agent/wazuh-agent_4.9.0-1_amd64.deb
sudo dpkg -i wazuh-agent_4.9.0-1_amd64.deb

# Configure the manager address
sudo nano /var/ossec/etc/ossec.conf

Ensure the <client> section in /var/ossec/etc/ossec.conf contains the correct manager IP:

<client>
  <server>
    <address>wazuh.msls.tech</address>
    <port>1514</port>
    <protocol>tcp</protocol>
  </server>
</client>

2. Enabling Docker Monitoring (Authentik Server)

To report Docker container events and logs to Wazuh, follow these steps:

Step A: Install Dependencies

Ubuntu 24.04 requires the --break-system-packages flag for pip installations:

sudo apt update && sudo apt install python3-pip -y
pip3 install docker==7.1.0 requests==2.32.2 --break-system-packages

Step B: Configure Docker Listener

Add the following module to /var/ossec/etc/ossec.conf before the final </ossec_config> tag:

<wodle name="docker-listener">
  <interval>1m</interval>
  <attempts>5</attempts>
  <run_on_start>yes</run_on_start>
  <disabled>no</disabled>
</wodle>

Step C: Grant Permissions

sudo usermod -aG docker wazuh
sudo chmod 755 /var/lib/docker/containers
sudo systemctl restart wazuh-agent

3. Troubleshooting: Version Mismatch & Manual ID Assignment

If an agent shows "Disconnected" with the error "Agent version must be lower or equal to manager version", you must downgrade the agent to match the manager's version (e.g., v4.9.0).

Assigning a Permanent Agent ID

To preserve a specific ID (like Agent 015), extract the key from the Wazuh Manager first:

# On Wazuh Manager
sudo /var/ossec/bin/manage_agents -e [AGENT_ID]

Then, import it on the Agent Endpoint:

# On Agent Endpoint
sudo /var/ossec/bin/manage_agents -i [PASTE_EXTRACTED_KEY]
sudo systemctl restart wazuh-agent

4. Common Maintenance Commands

Action Command
Check Service Status sudo systemctl status wazuh-agent
View Error Logs sudo tail -f /var/ossec/logs/ossec.log | grep -i error
Test Network Port nc -zv [MANAGER_IP] 1514
Verify Connection sudo grep "status='connected'" /var/ossec/var/run/wazuh-agentd.state
Back to top