# Installing Wazuh Agent on Linux (Ubuntu/Debian)

### Overview

This guide outlines the procedure for installing the Wazuh agent on Debian-based systems. It includes the standard repository method for local LAN devices, as well as a direct package installation method for devices on restricted networks (e.g., forced OpenVPN tunnels) where standard DNS or APT updates fail.

### Prerequisites

- Root or **sudo** privileges on the target Linux machine.
- Connectivity to the Wazuh Manager.
- Port **1514/tcp** (data) and **1515/tcp** (enrollment) 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

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

Install the agent while passing the Manager's FQDN as an environment variable.

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

---

### Method 2: Direct Package Installation (VPN/Restricted Networks)

Use this method if the host is behind a strict VPN that blocks or fails to resolve standard APT update servers. This bypasses the package manager entirely.

#### 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.5-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.5-1_amd64.deb
```

---

### Service Activation & Verification

Once the agent is installed, enable it to start on boot and initiate the service.

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

---

### Troubleshooting Common Issues

#### 1. Error: "Job for wazuh-agent.service failed because a timeout was exceeded"

On newer Linux kernels or slower hardware, the systemd default timeout is often too short for the Wazuh initialization process. Extend the timeout with an override file:

```
sudo mkdir -p /etc/systemd/system/wazuh-agent.service.d/
echo -e "[Service]\nTimeoutStartSec=300" | sudo tee /etc/systemd/system/wazuh-agent.service.d/timeout.conf
sudo systemctl daemon-reload
sudo systemctl restart wazuh-agent
```

#### 2. Manual Enrollment (If client.keys is empty)

If the agent installs but fails to retrieve a key from the manager, trigger enrollment manually:

```
sudo /var/ossec/bin/agent-auth -m 192.168.0.153
```

#### 3. Fix: Agent Stuck in "Pending" or "Never Connected" Status

If the agent shows as registered in the dashboard but is "never connected", or if checking the local state (`sudo grep ^status /var/ossec/var/run/wazuh-agentd.state`) shows `status='pending'`, the agent cannot resolve or reach the Manager's address. Update the configuration to use the static IP.

**Step A: Edit the configuration file**

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

**Step B: Locate the <client> block and update the <address> to the Manager's IP**

```
<client>
  <server>
    <address>192.168.0.153</address>
    <port>1514</port>
    <protocol>tcp</protocol>
  </server>
</client>
```

**Step C: Restart the agent to apply changes**

```
sudo systemctl restart wazuh-agent
```