Skip to main content

Installing Wazuh Agent on Linux (Ubuntu/Debian)

Overview

This guide outlines the standard procedure for installing the Wazuh agent on Debian-based systems. It includes steps for repository setup, agent enrollment, and troubleshooting common networking hurdles like DNS resolution failures and VPN routing.

Prerequisites

  • Root or sudo privileges on the target Linux machine.
  • Connectivity to the Wazuh Manager (local IP: 192.168.0.153 or FQDN: wuzah.goonersnas.com).
  • Port 1514/tcp open on the Manager's firewall.

1. Repository Configuration

First, import the Wazuh GPG key and add the official repository to your package manager's sources.

curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | sudo gpg --no-default-keyring --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg --import && sudo chmod 644 /usr/share/keyrings/wazuh.gpg

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-get update

2. Agent Installation & Enrollment

Install the agent while passing the Manager's address as an environment variable. This automatically populates the ossec.conf file with the correct destination.

sudo WAZUH_MANAGER='wuzah.goonersnas.com' apt-get install wazuh-agent

3. Service Activation

Enable the agent to start on boot and initiate the service immediately.

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

Troubleshooting & Network Edge Cases

Issue: "Could not resolve host" (DNS Failure)

If the device is on a restricted network (e.g., forced VPN) and cannot resolve the repository or manager:

  • Check Connectivity: Run ping -c 4 1.1.1.1 to see if raw IP traffic is passing.
  • Temporary DNS Override: Edit /etc/resolv.conf and add nameserver 1.1.1.1 at the top.
  • Local Manager Resolution: If the manager is on the local LAN but DNS is being routed through a VPN, force a local record:
echo "192.168.0.153 wuzah.goonersnas.com" | sudo tee -a /etc/hosts

Issue: Permission Denied during Curl/GPG Pipe

When piping curl into gpg, ensure sudo is used on both sides of the pipe where file writing occurs.

Verification

To confirm the agent has successfully established a handshake with the manager, check the local logs:

sudo grep -i "connected to the server" /var/ossec/logs/ossec.log

Expected Output: INFO: (4102): Connected to the server ([wuzah.goonersnas.com]:1514/tcp)

Back to top