Wazuh Agent Deployment & Troubleshooting Guide

Wazuh Agent Deployment: Authentik & Bookstack-LXC

This guide documents the installation,procedures configuration,for and troubleshooting ofmaintaining Wazuh agents on Ubuntu 22.0404/24.04, with specific instructions for Docker monitoring and 24.04manual endpoints,ID specifically focusing on fixing version mismatches and enabling Docker monitoring.preservation.

---

1. StandardAgent Version Control (Critical)

Constraint: The Wazuh Manager version must always be equal to or higher than the Agent Installationversion.

&

Connection
• Manager

  ToVersion: installv4.9.0

an
• Target agentAgent andVersion: connectv4.9.0
it to the central manager, use the following commands:

# InstallDownload the agentspecific (Replacematching WAZUH_MANAGERversion
with actual IP)
curl -sOwget 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. EnablingPreserving DockerExisting MonitoringAgent IDs (Authentike.g., Server)ID 015)

ToUse reportthis Dockerprocess containerwhen eventsreinstalling an agent to ensure it keeps its historical data and logs to Wazuh, follow these steps:ID.

Step A: InstallExtract 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 requiresprevents theglobal pip installs by default. Use --break-system-packages flagto forallow pipthe installations: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: ConfigureConfig DockerChanges Listener(ossec.conf)

Add the following module toOpen /var/ossec/etc/ossec.conf and add these blocks before the final </ossec_config> tag:.

<!-- 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>

<!--

StepMonitor C:Authentik GrantContainer Permissions

sudo usermodLogs -aG->
docker<localfile>
  wazuh<log_format>syslog</log_format>
  sudo chmod 755 <location>/var/lib/docker/containerscontainers/*/*-json.log</location>
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
localfile>

---

4. CommonTroubleshooting Maintenance CommandsChecklist

ActionError in ossec.log	CommandFix Action
CheckInvalid Serviceserver Statusaddress: 'MANAGER_IP'	Update sudo<address> systemctlin statusossec.conf wazuh-agentto wazuh.msls.tech.
View Error Logsreading XML file (line 0)	Check for nested or unclosed sudo<ossec_config> tail -f /var/ossec/logs/ossec.log | grep -i errortags.
Test Network Port	nc -zv [MANAGER_IP] 1514
Verify Connection	sudo grep "status='connected'" /var/ossec/var/run/wazuh-agentd.state