Skip to main content

Wazuh Agent Deployment & Troubleshooting Guide

Wazuh Agent Deployment: Authentik & Bookstack-LXC

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.
Back to top