Wazuh Agent Deployment & Troubleshooting Guide

This guide documents the procedures for maintaining Wazuh agents on Ubuntu 22.04/24.04, with specific instructions for Docker monitoring and manual ID preservation.
1. Agent Version Control (Critical)
Constraint: The Wazuh Manager version must always be equal to or higher than the Agent version.
Manager Version: v4.9.0
Target Agent Version: v4.9.0
# Download the specific matching version
wget 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
2. Preserving Existing Agent IDs (e.g., ID 015)
Use this process when reinstalling an agent to ensure it keeps its historical data and ID.
Step A: Extract Key from Manager
Run this on the Wazuh Manager terminal:
sudo /var/ossec/bin/manage_agents -e 015
Copy the long alphanumeric string provided.
Step B: Import Key to Agent
Run this on the Bookstack-LXC terminal:
sudo /var/ossec/bin/manage_agents -i [PASTE_KEY_HERE]
3. Monitoring Authentik & Docker Containers
To populate the Docker dashboard and monitor Authentik logs, three components are required.
Step A: Python Dependencies (Ubuntu 24.04 Fix)
Ubuntu 24.04 prevents global pip installs by default. Use 
--break-system-packages to allow the agent's internal scripts to run.
sudo apt update && sudo apt install python3-pip -y
pip3 install docker==7.1.0 requests==2.32.2 --break-system-packages
sudo usermod -aG docker wazuh
Step B: Config Changes (ossec.conf)
Open 
/var/ossec/etc/ossec.conf and add these blocks before the final 
</ossec_config>.
<!-- Monitor Container Events (Starts/Stops) -->
<wodle name="docker-listener">
  <interval>1m</interval>
  <attempts>5</attempts>
  <run_on_start>yes</run_on_start>
  <disabled>no</disabled>
</wodle>
<!-- Monitor Authentik Container Logs -->
<localfile>
  <log_format>syslog</log_format>
  <location>/var/lib/docker/containers/*/*-json.log</location>
</localfile>
4. Troubleshooting Checklist
Error in ossec.log
Fix Action
Invalid server address: 'MANAGER_IP'
Update 
<address> in ossec.conf to 
wazuh.msls.tech.
Error reading XML file (line 0)
Check for nested or unclosed 
<ossec_config> tags.
Handling Duplicate Agents for the Same VM
If a VM appears twice (e.g., with two different IDs), follow these steps to keep the ID with historical data:
Identify: Find the ID you want to keep (ID_KEEP) and the one to delete (ID_DEL).
Delete on Manager: 
sudo /var/ossec/bin/manage_agents -r [ID_DEL].
Stop Agent Service: 
sudo systemctl stop wazuh-agent on the VM.
Refresh Key: Extract the key for ID_KEEP from the manager (
-e) and import it to the agent (
-i).
Restart: 
sudo systemctl restart wazuh-agent.