Deploying Wazuh agents on Linux endpoints

The Wazuh agent runs on the endpoint you want to monitor. It sends data to the Wazuh manager in near real time through an encrypted and authenticated channel. For the supported versions, see Requirements.

Install the Wazuh agent from the Wazuh repository. The WAZUH_ENROLLMENT_TOKEN and WAZUH_AGENT_NAME variables in the install command enroll the agent with the Wazuh manager when it first starts. To download the package instead, see Packages list.

Before you start, create an enrollment token on the Wazuh manager, as described in Generate the enrollment token. You can also create it in the Wazuh dashboard, under Agents management > Enrollment tokens. The endpoint must reach the Wazuh manager on port 1517/TCP.

Note

Run the commands below as root. If you use sudo, put the variables after it, because sudo doesn't pass your environment variables to the command. For example, sudo WAZUH_ENROLLMENT_TOKEN='<ENROLLMENT_TOKEN>' WAZUH_AGENT_NAME='<AGENT_NAME>' apt-get install -y wazuh-agent. A token in the command also stays in the shell history. To keep it out, install without the variables, then enroll the agent from a token file as the end of this section describes.

Add the Wazuh repository

Add the Wazuh repository to download the official packages.

Use the tab of your system's package manager: Use DNF on Red Hat Enterprise Linux 8 or later and compatible systems, and Yum on systems without DNF. Use ZYpp on SUSE, and APT on Debian and Ubuntu.

  1. Install the following packages if missing:

    # apt-get update && apt-get install -y gnupg apt-transport-https curl

  2. Install the GPG key:

    # curl -s https://packages-staging.xdrsiem.wazuh.info/key/GPG-KEY-WAZUH | gpg --no-default-keyring --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg --import && chmod 644 /usr/share/keyrings/wazuh.gpg

  3. Add the repository:

    # echo "deb [signed-by=/usr/share/keyrings/wazuh.gpg] https://packages-staging.xdrsiem.wazuh.info/pre-release/5.x/apt/ unstable main" | tee /etc/apt/sources.list.d/wazuh.list

  4. Update the package information:

    # apt-get update

Deploy a Wazuh agent

Follow these steps to deploy the Wazuh agent on your Linux endpoint.

  1. Select your package manager and run the following command. Replace <ENROLLMENT_TOKEN> with the token you created in Generate the enrollment token. Replace <AGENT_NAME> with a name that no other agent uses, for example, the endpoint's host name. If you omit WAZUH_AGENT_NAME, the agent enrolls under the host name. The Wazuh manager refuses a name that another agent already uses.

    # WAZUH_ENROLLMENT_TOKEN='<ENROLLMENT_TOKEN>' WAZUH_AGENT_NAME='<AGENT_NAME>' apt-get install -y wazuh-agent

  2. For additional deployment options such as agent group, see the Deployment variables section. Enable and start the Wazuh agent service:

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

  3. Check that the Wazuh agent is enrolled and connected:

    # grep ^status /var/ossec/var/run/wazuh-agentd.state
# grep 'Token bootstrap: enrollment succeeded' /var/ossec/logs/ossec.log

    The first command prints status='connected'. If it prints status='pending' or status='disconnected', wait 30 seconds and run it again. The second prints a line that ends in Token bootstrap: enrollment succeeded; the manager's CA is now the agent's trust anchor. In the Wazuh dashboard, Agents management > Summary lists the agent as Active. Its first findings can take a few minutes to appear on a new deployment.

The deployment process is now complete, and the Wazuh agent is successfully running on your Linux endpoint.

Troubleshooting Wazuh agent installation and startup

Right after enrolling, the Wazuh agent can be refused once and log credential rejected (401); re-enrolling. and Manager unreachable. It enrolls again by itself and connects.

If systemctl start wazuh-agent failed or the agent didn't enroll, the cause is one of these:

  • The install command printed no manager configured [INFO_NO_MANAGER]: the token didn't reach the installer, for example because sudo dropped it.

  • The install command printed deployment variables refused [ERR_BAD_TOKEN]: the token changed when you copied it.

  • /var/ossec/logs/ossec.log shows Enrollment-token bootstrap failed. The Wazuh manager refused the enrollment. For example, the token was revoked, expired, or used up, or another agent already uses the name.

In each case, save a valid token to a file, enroll the agent, delete the file, and start the agent. In the first two cases, the installer kept no agent name, so the agent enrolls under the endpoint's host name. Replace <TOKEN_FILE_PATH> with a file path, for example, /root/wazuh-token. The first command waits for the token. Paste it, press Enter, and then press Ctrl+D.

# (umask 077 && cat > <TOKEN_FILE_PATH>)
# /var/ossec/bin/wazuh-agent-auth --token-file <TOKEN_FILE_PATH>
# rm -f <TOKEN_FILE_PATH>
# systemctl start wazuh-agent

Disable Wazuh updates

Compatibility between the Wazuh agent and the Wazuh manager is guaranteed when the Wazuh manager version is later than or equal to that of the Wazuh agent. Therefore, we recommend disabling the Wazuh repository to prevent accidental upgrades. To do so, use the following command:

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

Alternatively, you can set the package state to hold. This action stops updates. To upgrade or uninstall the Wazuh agent later, run apt-mark unhold wazuh-agent first.

# echo "wazuh-agent hold" | dpkg --set-selections