Wazuh Agent 4.14 Installation - Linux, Windows, macOS

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

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

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

With additional parameters:

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

Start the service

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):

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):

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

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

Or using DNF:

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

Start the service

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

For systems without systemd:

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)

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

With additional parameters:

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)

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

Start the service

CMD:

NET START WazuhSvc

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:

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

Intel:

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

With additional parameters:

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

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:

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:

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):

<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:

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

Group Policy (Windows)

For GPO-based deployment:

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

SCCM / Intune

Create a deployment package with the following command line:

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:

#!/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

# 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

/var/ossec/bin/agent_control -l

Or through the REST API:

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

Verify port accessibility on the manager:

nc -zv <MANAGER_IP> 1514
nc -zv <MANAGER_IP> 1515

Check the agent log:

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

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:
```
/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:

# 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:

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:

systemctl restart wazuh-agent   # Linux
NET STOP WazuhSvc && NET START WazuhSvc  # Windows

Disabling Automatic Updates

Ubuntu / Debian:

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

CentOS / RHEL:

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

Next Steps

Wazuh Architecture - understand component interactions
Wazuh Components - detailed agent and server descriptions
Uninstalling Wazuh - proper agent removal

Last updated on 8, April 2026

Wazuh 4.14 Quickstart - Install in Under 10 Minutes Wazuh Dashboard 4.14 Installation - Step-by-Step Guide