Wazuh: agent installation (workstations)

How to install and enroll the Wazuh agent on employee workstations (Ubuntu / macOS), plus common agent troubleshooting. For the reasoning behind rolling Wazuh out to endpoints, see the playbook's Endpoint Security page.

Registration password: <WAZUH_REGISTRATION_PASSWORD> below is a placeholder. Fetch the current Wazuh agent registration password from HashiCorp Vault (or ask the DevOps Team Leader) at install time. Never paste the real password into this document, the playbook, or any repo.

Ubuntu workstations

Open the terminal and run:

wget https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-agent/wazuh-agent_4.7.3-1_amd64.deb && \
sudo WAZUH_MANAGER='wazuh-agent.aholadigital.com' \
WAZUH_REGISTRATION_PASSWORD=$'<WAZUH_REGISTRATION_PASSWORD>' \
WAZUH_AGENT_GROUP='comp-fi' WAZUH_AGENT_NAME='Name' dpkg -i ./wazuh-agent_4.7.3-1_amd64.deb

Put your own name in the Name field.

Activate and start the service:

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

macOS (Apple Silicon / ARM)

Open the terminal (Launchpad → type Terminal → click Terminal) and run:

curl -so wazuh-agent.pkg https://packages.wazuh.com/4.x/macos/wazuh-agent-4.7.3-1.arm64.pkg && echo "WAZUH_MANAGER='wazuh-agent.aholadigital.com' && WAZUH_AGENT_GROUP='comp-fi' && WAZUH_AGENT_NAME='Name'WAZUH_REGISTRATION_PASSWORD='<WAZUH_REGISTRATION_PASSWORD>'\n" > /tmp/wazuh_envs && sudo installer -pkg ./wazuh-agent.pkg -target /

Put your own name in the NAME field.

Activate and start the service:

sudo /Library/Ossec/bin/wazuh-control start

macOS (Intel — older systems)

Open the terminal and run:

curl -so wazuh-agent.pkg https://packages.wazuh.com/4.x/macos/wazuh-agent-4.7.3-1.intel64.pkg && echo "WAZUH_MANAGER='wazuh-agent.aholadigital.com' && WAZUH_AGENT_GROUP='comp-fi' && WAZUH_AGENT_NAME='Name'WAZUH_REGISTRATION_PASSWORD='<WAZUH_REGISTRATION_PASSWORD>'\n" > /tmp/wazuh_envs && sudo installer -pkg ./wazuh-agent.pkg -target /

Put your own name in the NAME field.

Activate and start the service:

sudo /Library/Ossec/bin/wazuh-control start

Troubleshooting

Wazuh agent won't appear in the system / admin page

1. Test that the connection to the Wazuh server is open — run telnet:

telnet wazuh-agent.aholadigital.com 1515

If the connection is OK it should read:

Trying 37.27.41.231...
Connected to wazuh-agent.aholadigital.com.

If the connection is OK, the problem is probably in the config files. The easiest fix is to remove the agent and re-install it. On Linux use a purge uninstall: apt-get remove --purge wazuh-agent.

2. Check the config files. The most common errors are a missing agent name in ossec.conf and a missing registration password.

Check ossec.conf:

# linux
sudo cat /var/ossec/etc/ossec.conf
# macos
sudo cat /Library/Ossec/etc/ossec.conf

Make sure these lines are present:

<agent_name>YourName</agent_name>
<address>wazuh-agent.aholadigital.com</address>
<authorization_pass_path>etc/authd.pass</authorization_pass_path>

Check the registration-password file:

# linux
sudo cat /var/ossec/etc/authd.pass
# macos
sudo cat /Library/Ossec/etc/authd.pass

Make sure it contains the same password used in the installation script (from Vault).