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 stepsthe standard repository method for repositorylocal setup,LAN agentdevices, enrollment,as andwell troubleshootingas commona networkingdirect hurdlespackage likeinstallation method for devices on restricted networks (e.g., forced OpenVPN tunnels) where standard DNS resolutionor failuresAPT andupdates VPN routing.fail.

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).Manager.
  • Port 1514/tcp open on the Manager's firewall.

Method 1: Standard APT Installation (Main Network)

Use this method for standard servers that have unrestricted outbound internet access to resolve and update package lists.

1. Repository Configuration

First, importImport 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 addressFQDN 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.Method 2: Direct Package Installation (VPN/Restricted Networks)

Use this method if the host is behind a strict VPN (like NordVPN) that blocks or fails to resolve standard APT update servers. This bypasses the package manager entirely by downloading the installer directly and pointing it to the Manager's local IP address.

1. Download the Package

Fetch the specific .deb installer directly from the Wazuh servers.

wget https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-agent/wazuh-agent_4.14.4-1_amd64.deb

2. Force Installation via DPKG

Install the downloaded package, passing the local IP address instead of the domain name to bypass local DNS resolution failures.

sudo WAZUH_MANAGER='192.168.0.153' dpkg -i wazuh-agent_4.14.4-1_amd64.deb

Service Activation & Verification

EnableOnce the agent is installed using either method above, enable it 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)Verification

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)server...

    Back to top