Install the Wazuh Agent on Linux

Wazuh is an open-source security platform that provides host-based intrusion detection, file integrity monitoring (FIM), vulnerability detection, and log analysis. The Wazuh Agent runs on monitored endpoints and ships data to a central Wazuh Manager. This guide walks through installing the agent, enrolling it with a manager, and verifying that log collection, FIM, and vulnerability scanning are all working.

Prerequisites

• A running Wazuh Manager (4.x) reachable from the endpoint — note its IP or hostname.
• Root or sudo access on the Linux host you are enrolling.
• Ports 1514 (UDP/TCP) and 1515 (TCP) open between agent and manager.
• A supported OS: the steps below cover Ubuntu/Debian, Fedora/RHEL/Rocky, and Arch.

Step 1: Add the Wazuh Repository

Wazuh publishes official packages for all major distributions. Use the vendor repository rather than distro-provided packages — distro repos often lag several major versions behind.

Debian / Ubuntu

curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH \
  | gpg --dearmor \
  | sudo tee /usr/share/keyrings/wazuh.gpg > /dev/null

echo "deb [signed-by=/usr/share/keyrings/wazuh.gpg] \
https://packages.wazuh.com/4.x/apt/ stable main" \
  | sudo tee /etc/apt/sources.list.d/wazuh.list

sudo apt update

Fedora / RHEL / Rocky / AlmaLinux

sudo rpm --import https://packages.wazuh.com/key/GPG-KEY-WAZUH

sudo tee /etc/yum.repos.d/wazuh.repo << 'EOF'
[wazuh]
gpgcheck=1
gpgkey=https://packages.wazuh.com/key/GPG-KEY-WAZUH
enabled=1
name=EL-$releasever - Wazuh
baseurl=https://packages.wazuh.com/4.x/yum/
protect=1
EOF

Arch Linux

Arch users should install via the AUR. Use your preferred AUR helper:

paru -S wazuh-agent

The AUR package sets up the agent binary and systemd unit. Skip to Step 3 for Arch after this.

Step 2: Install the Agent Package

Set the WAZUH_MANAGER environment variable before installation. The package scripts read it and pre-populate the manager address in the agent config, saving you a manual edit.

Debian / Ubuntu

WAZUH_MANAGER="your.manager.ip.or.hostname" \
  sudo -E apt install -y wazuh-agent

Fedora / RHEL / Rocky / AlmaLinux

WAZUH_MANAGER="your.manager.ip.or.hostname" \
  sudo -E dnf install -y wazuh-agent

If you skipped setting the variable, edit /var/ossec/etc/ossec.conf manually and set the correct address inside the <client> block:

sudo grep -A3 '<client>' /var/ossec/etc/ossec.conf

Step 3: Enable and Start the Agent

The package installs a systemd unit. Enable it so it survives reboots, then start it.

sudo systemctl daemon-reload
sudo systemctl enable --now wazuh-agent

Check it came up cleanly:

sudo systemctl status wazuh-agent

You should see active (running). The agent attempts automatic enrollment with the manager (port 1515) using the built-in auto-enrollment feature introduced in Wazuh 4.0.

Step 4: Verify Enrollment on the Manager

On the Wazuh Manager host, list registered agents to confirm the new endpoint appeared:

sudo /var/ossec/bin/agent_control -l

Output will list agent IDs, names, IP addresses, and statuses. Your new host should show status Active within a minute or two. If it shows Never connected, work through the Troubleshooting section below.

Step 5: Configure Log Collection

By default the agent collects /var/log/syslog (Debian/Ubuntu) or /var/log/messages (RHEL family) and auth logs. Add application-specific log files in /var/ossec/etc/ossec.conf on the agent:

sudo nano /var/ossec/etc/ossec.conf

Add a <localfile> block inside the <ossec_config> root element for each additional log source. Example for nginx:

cat /var/ossec/etc/ossec.conf | grep -c localfile  # count existing entries

Add blocks like the following using your editor:

# Example fragment — add inside <ossec_config> in ossec.conf
# <localfile>
#   <log_format>syslog</log_format>
#   <location>/var/log/nginx/error.log</location>
# </localfile>

Wazuh supports formats including syslog, json, apache, mysql_log, and command (run a command and ingest its output). After editing, restart the agent:

sudo systemctl restart wazuh-agent

Step 6: Configure File Integrity Monitoring

FIM is enabled by default and watches /etc, /usr/bin, and /usr/sbin. Add or modify monitored paths in ossec.conf under the <syscheck> block.

To add a custom directory with real-time monitoring and SHA-256 checksums:

# Fragment to add inside <syscheck> in /var/ossec/etc/ossec.conf
# <directories realtime="yes" check_all="yes">/opt/myapp/config</directories>

Key <syscheck> tunables:

• frequency: How often a full scan runs, in seconds. Default is 43200 (12 hours).
• realtime: Uses Linux inotify for immediate change alerts — recommended for sensitive paths.
• whodata: Requires audit daemon; captures the user and process responsible for each change.
• ignore: Regex or path patterns to exclude from monitoring.

To enable whodata on a directory (requires auditd installed and running):

sudo apt install auditd     # Debian/Ubuntu
sudo dnf install audit      # Fedora/RHEL
sudo systemctl enable --now auditd

Then in ossec.conf:

# <directories whodata="yes">/etc/ssh</directories>

Restart the agent after any syscheck changes:

sudo systemctl restart wazuh-agent

Step 7: Enable Vulnerability Detection

Vulnerability detection is driven by the manager, not the agent — the agent reports installed packages and the manager correlates them against the Wazuh vulnerability database (sourced from NVD and vendor feeds). Confirm the agent is sending syscollector data, which is on by default.

Verify the syscollector module is active in ossec.conf:

grep -A5 'syscollector' /var/ossec/etc/ossec.conf

You should see <disabled>no</disabled>. Syscollector harvests hardware, OS, network, package, port, and process information on a configurable interval (default: every hour). This data feeds the Wazuh vulnerability detector on the manager side.

On the manager, enable the vulnerability detector if it is not already active by editing /var/ossec/etc/ossec.conf on the manager host and ensuring <enabled>yes</enabled> is set inside the <vulnerability-detector> block, then restarting the manager service.

Step 8: Verify Everything Is Working

Run the agent control tool to check the agent status and last keepalive:

sudo /var/ossec/bin/wazuh-control status

Tail the agent log for errors or successful event shipping:

sudo tail -f /var/ossec/logs/ossec.log

Trigger a test FIM alert by modifying a monitored file:

sudo touch /etc/wazuh-fim-test && sudo rm /etc/wazuh-fim-test

Within seconds (if realtime is enabled) or at the next scan cycle, an alert should appear in the Wazuh dashboard under the agent's Integrity Monitoring tab.

Troubleshooting

• Agent stuck in "Pending" or "Never connected": Confirm ports 1514 and 1515 are open in both directions using nc -zv manager-ip 1515. Check firewall rules on both sides — with firewalld: sudo firewall-cmd --list-all; with nftables: sudo nft list ruleset; with ufw: sudo ufw status.
• Enrollment failing: Auto-enrollment requires the agent to reach port 1515 and for the manager to have <use_password>no</use_password> (or a matching password configured). Check /var/ossec/logs/ossec.log on the agent for TLS or auth errors.
• No FIM alerts appearing: Confirm <disabled>no</disabled> inside the <syscheck> block. With realtime monitoring, verify inotify limits are sufficient: cat /proc/sys/fs/inotify/max_user_watches — raise it with sudo sysctl fs.inotify.max_user_watches=524288 and persist in /etc/sysctl.d/.
• No vulnerability data: Check syscollector is enabled and the manager's vulnerability detector feed has been downloaded (/var/ossec/queue/vulnerabilities/ should be populated). Initial feed download can take several minutes after manager restart.
• SELinux blocking on RHEL family: Run sudo ausearch -m avc -ts recent to find denials. The Wazuh RPM ships an SELinux policy module; confirm it loaded with sudo semodule -l | grep wazuh.