# Wazuh Agent 4.14 Installation - Linux, Windows, macOS

> Install Wazuh Agent 4.14 on Linux (DEB/RPM), Windows (MSI), and macOS (pkg) - enrollment methods, group assignment, mass deployment, and troubleshooting

Source: https://opennix.org/en/docs/wazuh/installation/wazuh-agent-installation/


The Wazuh Agent is a lightweight component installed on monitored endpoints. It collects security event data, performs local checks, and forwards the results to the [Wazuh Server](/docs/wazuh/installation/wazuh-server-installation/) for analysis. This guide covers agent installation on Linux, Windows, and macOS.

## Version Compatibility

The agent version must be equal to or lower than the Wazuh Manager version. Agent 4.14 is compatible with manager 4.14 and later. Backward compatibility is not guaranteed - do not install an agent version higher than the manager version.

## Deployment Variables

Agent connection parameters can be specified through environment variables during installation:

| Variable | Description | Example |
|---|---|---|
| `WAZUH_MANAGER` | Manager IP address or hostname | `10.0.0.2` |
| `WAZUH_AGENT_NAME` | Agent name (displayed in the dashboard) | `web-server-01` |
| `WAZUH_AGENT_GROUP` | Agent group for centralized management | `linux-servers` |
| `WAZUH_REGISTRATION_PASSWORD` | Password for authorized enrollment | `MyPassword` |

## Linux Installation (DEB - Ubuntu/Debian)

### Add the repository

```bash
apt-get install gnupg apt-transport-https
curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | gpg --no-default-keyring \
  --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg --import && 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" \
  | tee -a /etc/apt/sources.list.d/wazuh.list
apt-get update
```

### Install the package

```bash
WAZUH_MANAGER="<MANAGER_IP>" apt-get install wazuh-agent
```

With additional parameters:

```bash
WAZUH_MANAGER="<MANAGER_IP>" \
WAZUH_AGENT_NAME="web-server-01" \
WAZUH_AGENT_GROUP="linux-servers" \
apt-get install wazuh-agent
```

### Start the service

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

## Linux Installation (RPM - CentOS/RHEL)

### Add the repository

**CentOS / RHEL 8 and earlier (YUM):**

```bash
rpm --import https://packages.wazuh.com/key/GPG-KEY-WAZUH
cat > /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
```

**RHEL 9+ / CentOS Stream 10 (DNF):**

```bash
rpm --import https://packages.wazuh.com/key/GPG-KEY-WAZUH
cat > /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/
priority=1
EOF
```

### Install the package

```bash
WAZUH_MANAGER="<MANAGER_IP>" yum install wazuh-agent
```

Or using DNF:

```bash
WAZUH_MANAGER="<MANAGER_IP>" dnf install wazuh-agent
```

### Start the service

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

For systems without systemd:

```bash
chkconfig --add wazuh-agent
service wazuh-agent start
```

## Windows Installation

### Download the package

Download the MSI installer:

```
https://packages.wazuh.com/4.x/windows/wazuh-agent-4.14.4-1.msi
```

### Silent installation (CMD)

```cmd
wazuh-agent-4.14.4-1.msi /q WAZUH_MANAGER="<MANAGER_IP>"
```

With additional parameters:

```cmd
wazuh-agent-4.14.4-1.msi /q WAZUH_MANAGER="<MANAGER_IP>" WAZUH_AGENT_NAME="win-desktop-01" WAZUH_AGENT_GROUP="windows-workstations"
```

### Silent installation (PowerShell)

```powershell
.\wazuh-agent-4.14.4-1.msi /q WAZUH_MANAGER="<MANAGER_IP>"
```

### Start the service

**CMD:**

```cmd
NET START WazuhSvc
```

**PowerShell:**

```powershell
Start-Service wazuhsvc
```

### Installation path

The agent installs to `C:\Program Files (x86)\ossec-agent\`.

## macOS Installation

### Download the package

**Apple Silicon (M1/M2/M3/M4):**

```
https://packages.wazuh.com/4.x/macos/wazuh-agent-4.14.4-1.arm64.pkg
```

**Intel:**

```
https://packages.wazuh.com/4.x/macos/wazuh-agent-4.14.4-1.intel64.pkg
```

### Installation

**Apple Silicon:**

```bash
echo "WAZUH_MANAGER='<MANAGER_IP>'" > /tmp/wazuh_envs && \
sudo installer -pkg wazuh-agent-4.14.4-1.arm64.pkg -target /
```

**Intel:**

```bash
echo "WAZUH_MANAGER='<MANAGER_IP>'" > /tmp/wazuh_envs && \
sudo installer -pkg wazuh-agent-4.14.4-1.intel64.pkg -target /
```

With additional parameters:

```bash
echo "WAZUH_MANAGER='<MANAGER_IP>' WAZUH_AGENT_NAME='mac-dev-01' WAZUH_AGENT_GROUP='macos-workstations'" > /tmp/wazuh_envs && \
sudo installer -pkg wazuh-agent-4.14.4-1.arm64.pkg -target /
```

### Start the service

```bash
sudo launchctl bootstrap system /Library/LaunchDaemons/com.wazuh.agent.plist
```

### Installation path

The agent installs to `/Library/Ossec/`.

## Enrollment Methods

### Manager IP enrollment

The primary method is specifying the manager IP address through the `WAZUH_MANAGER` variable during installation. The agent automatically connects to the manager and requests an authentication key.

### Password-based enrollment

To restrict enrollment to authorized agents only, configure a password on the manager:

```bash
echo "MyRegistrationPassword" > /var/ossec/etc/authd.pass
chmod 640 /var/ossec/etc/authd.pass
chown root:wazuh /var/ossec/etc/authd.pass
systemctl restart wazuh-manager
```

Specify the password during agent installation:

```bash
WAZUH_MANAGER="<MANAGER_IP>" \
WAZUH_REGISTRATION_PASSWORD="MyRegistrationPassword" \
apt-get install wazuh-agent
```

### Manual enrollment after installation

If the agent was installed without specifying a manager, configure the connection manually.

Edit `/var/ossec/etc/ossec.conf` (Linux/macOS) or `C:\Program Files (x86)\ossec-agent\ossec.conf` (Windows):

```xml
<client>
  <server>
    <address><MANAGER_IP></address>
    <port>1514</port>
    <protocol>tcp</protocol>
  </server>
</client>
```

Restart the agent after modifying the configuration.

## Key Agent Configuration Sections

The agent `ossec.conf` file contains the primary operational parameters:

| Section | Description |
|---|---|
| `<client>` | Manager address, port, and connection protocol |
| `<syscheck>` | File integrity monitoring - directories, frequency, exclusions |
| `<rootcheck>` | Rootkit detection |
| `<localfile>` | Local log files to monitor |
| `<active-response>` | Automated response settings |
| `<labels>` | Custom agent labels |

## Mass Deployment

### Ansible

Use the `wazuh-agent` role from the official collection:

```yaml
- hosts: all
  roles:
    - role: wazuh-agent
      wazuh_manager_ip: "<MANAGER_IP>"
      wazuh_agent_group: "linux-servers"
```

### Group Policy (Windows)

For GPO-based deployment:

1. Place the MSI package in a network share accessible to target machines
2. Create a GPO with software installation assignment (Computer Configuration - Software Installation)
3. Use an MST transform to specify `WAZUH_MANAGER` and `WAZUH_AGENT_GROUP` parameters

### SCCM / Intune

Create a deployment package with the following command line:

```cmd
msiexec /i wazuh-agent-4.14.4-1.msi /q WAZUH_MANAGER="<MANAGER_IP>" WAZUH_AGENT_GROUP="windows-workstations"
```

### Mass deployment script (Linux)

Example script for SSH-based deployment:

```bash
#!/bin/bash
MANAGER_IP="10.0.0.2"
HOSTS="host1 host2 host3"

for HOST in $HOSTS; do
  ssh root@$HOST "
    curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | gpg --no-default-keyring \
      --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg --import && \
      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' \
      | tee /etc/apt/sources.list.d/wazuh.list && \
    apt-get update && \
    WAZUH_MANAGER='$MANAGER_IP' apt-get -y install wazuh-agent && \
    systemctl daemon-reload && systemctl enable wazuh-agent && systemctl start wazuh-agent
  "
done
```

## Verifying the Connection

### On the agent

```bash
# Linux / macOS
/var/ossec/bin/wazuh-control status

# Windows (CMD, run as administrator)
"C:\Program Files (x86)\ossec-agent\wazuh-control.exe" status
```

### On the server

```bash
/var/ossec/bin/agent_control -l
```

Or through the REST API:

```bash
TOKEN=$(curl -sk -u wazuh-wui:<WUI_PASSWORD> \
  -X POST "https://localhost:55000/security/user/authenticate?raw=true")

curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/agents?status=active&limit=10" | python3 -m json.tool
```

## Troubleshooting

### Agent does not connect to the manager

1. Verify port accessibility on the manager:
   ```bash
   nc -zv <MANAGER_IP> 1514
   nc -zv <MANAGER_IP> 1515
   ```

2. Check the agent log:
   ```bash
   cat /var/ossec/logs/ossec.log | tail -30    # Linux/macOS
   type "C:\Program Files (x86)\ossec-agent\ossec.log"  # Windows
   ```

3. Confirm the manager IP is correctly specified in `ossec.conf`

### Authentication errors

- Verify the enrollment password matches on both agent and manager
- Check the manager log: `cat /var/ossec/logs/ossec.log | grep -i "error\|auth"`
- If needed, remove the agent from the manager and re-enroll:
  ```bash
  /var/ossec/bin/manage_agents -r <AGENT_ID>
  ```

### Version mismatch

If the agent version is higher than the manager version, the agent may behave incorrectly. Check versions:

```bash
# On the agent
/var/ossec/bin/wazuh-control info | grep version

# On the manager
/var/ossec/bin/wazuh-control info | grep version
```

### Agent does not forward data

- Check the service status:
  ```bash
  systemctl status wazuh-agent    # Linux
  sc query WazuhSvc               # Windows
  ```
- Confirm the agent is enrolled: verify the file `/var/ossec/etc/client.keys` exists
- Restart the agent:
  ```bash
  systemctl restart wazuh-agent   # Linux
  NET STOP WazuhSvc && NET START WazuhSvc  # Windows
  ```

## Disabling Automatic Updates

**Ubuntu / Debian:**

```bash
sed -i "s/^deb /#deb /" /etc/apt/sources.list.d/wazuh.list
apt-get update
```

**CentOS / RHEL:**

```bash
sed -i "s/^enabled=1/enabled=0/" /etc/yum.repos.d/wazuh.repo
```

## Next Steps

- [Wazuh Architecture](/docs/wazuh/getting-started/wazuh-architecture/) - understand component interactions
- [Wazuh Components](/docs/wazuh/getting-started/wazuh-components/) - detailed agent and server descriptions
- [Uninstalling Wazuh](/docs/wazuh/installation/wazuh-uninstalling/) - proper agent removal