Deploying Wazuh agents
on Linux endpoints

1. Scope and prerequisites

The Linux agent runs on the monitored endpoint and sends telemetry to an existing Wazuh manager. It is separate from the central manager, indexer, and dashboard. If those components are not ready, begin with Wazuh all-in-one installation and validation. For Windows hosts, use Deploying Wazuh agents on Windows endpoints.

Verify the selected Wazuh release supports the distribution, release, and CPU architecture. The package examples below deliberately require an explicit version: the manager must be the same version as or newer than the agent. Repository availability alone does not establish compatibility.

cat /etc/os-release
uname -m
hostname
timedatectl status

Use a unique endpoint name and synchronized clocks. Confirm you have administrative access, outbound access to the Wazuh package service, and the enrollment settings for the intended manager. For an existing agent, use the vendor upgrade procedure and preserve its identity and configuration instead of treating it as a fresh installation.

2. Check connectivity before installation

From the Linux endpoint, substitute the reachable manager address. The following checks use netcat (nc); install the distribution's netcat package if it is unavailable.

MANAGER="192.168.56.101"
nc -vz -w 5 "$MANAGER" 1514
nc -vz -w 5 "$MANAGER" 1515

Use the host's published address when the manager runs in Docker, and verify the container publishes both ports on an accessible interface. An open port proves network reachability, not successful authentication. TCP 55000 is used for API-based enrollment and management; it is not necessary for the default 1515 enrollment flow here. Do not point the agent at the dashboard or indexer port.

3. Deploy on Debian or Ubuntu with APT

Run this section in a Bash root shell. Check existing repository entries before writing the dedicated Wazuh source file; keep one active entry for this repository.

sudo -i
apt-get update
apt-get install -y ca-certificates curl gnupg
install -d -m 0755 /usr/share/keyrings
curl --fail --show-error --silent --location \
  https://packages.wazuh.com/key/GPG-KEY-WAZUH \
  --output /tmp/wazuh-repository-key.asc
gpg --batch --yes --dearmor \
  --output /usr/share/keyrings/wazuh.gpg /tmp/wazuh-repository-key.asc
chmod 0644 /usr/share/keyrings/wazuh.gpg
printf '%s\n' 'deb [signed-by=/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/4.x/apt/ stable main' \
  > /etc/apt/sources.list.d/wazuh.list
apt-get update
apt-cache madison wazuh-agent

Stop if key retrieval or repository refresh fails. Select an available version compatible with your manager; replace the version placeholder with the exact APT version string listed above.

MANAGER="192.168.56.101"
AGENT_NAME="linux-lab-01"
AGENT_VERSION='REPLACE_WITH_APT_VERSION'

env WAZUH_MANAGER="$MANAGER" \
    WAZUH_REGISTRATION_SERVER="$MANAGER" \
    WAZUH_AGENT_NAME="$AGENT_NAME" \
    apt-get install -y "wazuh-agent=$AGENT_VERSION"

dpkg-query -W -f='${Package} ${Version}\n' wazuh-agent
apt-mark hold wazuh-agent

Check the package manager exit status and installed version before continuing. The hold prevents routine APT upgrades from advancing this agent unexpectedly. For a planned upgrade, review manager compatibility, unhold the package, install the approved version, and hold it again. Exit the root shell before moving to the shared validation commands.

4. Deploy on an RPM-based system with DNF

Use this alternative on a supported DNF-based distribution. The examples use a repository that is disabled by default and explicitly enabled for the selected install transaction.

sudo -i
rpm --import https://packages.wazuh.com/key/GPG-KEY-WAZUH
cat > /etc/yum.repos.d/wazuh.repo <<'EOF'
[wazuh]
name=Wazuh agent packages
baseurl=https://packages.wazuh.com/4.x/yum/
enabled=0
gpgcheck=1
gpgkey=https://packages.wazuh.com/key/GPG-KEY-WAZUH
protect=1
EOF
dnf --enablerepo=wazuh --showduplicates list wazuh-agent

Do not continue after a signing-key import or repository error. Set the exact version-release string displayed for your architecture, then install:

MANAGER="192.168.56.101"
AGENT_NAME="linux-lab-01"
AGENT_VERSION='REPLACE_WITH_RPM_VERSION_RELEASE'

env WAZUH_MANAGER="$MANAGER" \
    WAZUH_REGISTRATION_SERVER="$MANAGER" \
    WAZUH_AGENT_NAME="$AGENT_NAME" \
    dnf --enablerepo=wazuh install -y "wazuh-agent-$AGENT_VERSION"

rpm -q wazuh-agent

The repository remains disabled for later routine DNF transactions. Ensure no second enabled Wazuh repository bypasses that control. For Yum, ZYpp/SUSE, or non-systemd systems, follow the matching branch of the official Linux installation guide. Exit the root shell when the installation completes.

Enrollment settings shared by both package paths

WAZUH_MANAGER identifies the telemetry destination; WAZUH_REGISTRATION_SERVER identifies the enrollment service. They can be different hosts. WAZUH_AGENT_NAME supplies the endpoint identity. Add group, password, CA, or client-certificate settings only as required by your manager's policy, using the Linux deployment-variable reference. Avoid placing enrollment secrets into shared scripts or shell history.

5. Start the service and verify enrollment

sudo systemctl daemon-reload
sudo systemctl enable --now wazuh-agent
sudo systemctl --no-pager --full status wazuh-agent
sudo journalctl -u wazuh-agent -n 50 --no-pager
sudo tail -n 80 /var/ossec/logs/ossec.log
sudo grep ^status /var/ossec/var/run/wazuh-agentd.state

Expect an active service and status='connected' after successful communication with the manager. The state file may not exist before the first connection; inspect ossec.log rather than assuming installation failed. Check the configured destination and active TCP sessions:

sudo sed -n '/<client>/,/<\/client>/p' /var/ossec/etc/ossec.conf
sudo ss -ntp | grep ':1514'

Correlate the remote address with your manager. In the dashboard agent inventory, match the configured name, agent ID, active state, and recent keepalive. On the manager, sudo /var/ossec/bin/agent_control -l provides a second view. For Docker, run the command inside the manager container. Keep /var/ossec/etc/client.keys private; it contains agent authentication material.

6. Inspect the Linux log sources

Linux telemetry depends on how the distribution routes logs. Some hosts use journald directly; others also write syslog files. Inspect the existing /var/ossec/etc/ossec.conf and assigned group configuration before adding collectors. Avoid collecting the same stream twice.

Systemd journal

On agent versions that support journald collection, this block selects the journal. Current documentation describes it as enabled by default; check the actual deployed configuration and release.

<localfile>
  <location>journald</location>
  <log_format>journald</log_format>
</localfile>

File-based syslog

If your host writes /var/log/syslog, the corresponding collector is:

<localfile>
  <location>/var/log/syslog</location>
  <log_format>syslog</log_format>
</localfile>

RPM-based distributions may use /var/log/messages and /var/log/secure; Debian-family authentication records may appear in /var/log/auth.log. These files are not universal. Confirm they exist and receive events before referencing them. Keep blocks inside the existing <ossec_config> element. If a local edit is necessary, back up the file, restart the agent, and inspect its diagnostics for syntax, path, and permission errors.

7. Validate event delivery

Generate a traceable event on the endpoint

Create a unique marker on the monitored Linux machine, then confirm it exists locally:

MARKER="Wazuh-Onboarding-$(date -u +%Y%m%dT%H%M%SZ)"
logger -p user.notice -t wazuh-onboarding -- "$MARKER"
printf 'Test marker: %s\n' "$MARKER"
sudo journalctl -t wazuh-onboarding --since '5 minutes ago' --no-pager

On a file-based host, search the configured syslog file for the exact marker instead. If the event is absent locally, investigate local logging first. If journal filters restrict collection to particular units or priorities, confirm this test falls within the collected stream.

Verify manager receipt separately from alert generation

A harmless syslog marker may not trigger an alert. The wazuh-alerts-* view therefore cannot serve as a complete received-event ledger. When JSON archiving is enabled, search the manager's /var/ossec/logs/archives/archives.json for the exact marker and match the agent ID and timestamp.

# On the manager: replace this example with the endpoint's exact marker.
sudo grep -F 'Wazuh-Onboarding-20261112T140000Z' \
  /var/ossec/logs/archives/archives.json

Archives are disabled by default. In a controlled validation window, enable <logall_json>yes</logall_json> in the existing manager <global> configuration and restart the manager before generating a new marker. For Docker, update the persistent manager configuration and inspect the archive inside the container. Plan storage and access controls, then restore the previous setting after a temporary test.

Dashboard archive searches additionally require Filebeat archive forwarding and a wazuh-archives-* data view. A matching archive record proves endpoint-to-manager delivery. To validate detection and alert indexing, use a separate approved test expected to match an enabled rule and find its resulting alert in the dashboard. Preserve the agent ID, marker, UTC timestamp, and receiving-stage evidence in the onboarding record.

8. Troubleshoot by stage

9. Official references

• Wazuh — deploying agents on Linux endpoints
• Wazuh — Linux deployment variables
• Wazuh — enrollment troubleshooting
• Wazuh — agent connection validation
• Wazuh — localfile configuration
• Wazuh — journald collection
• Wazuh — archives and event logging
• Linux manual — logger command

This technical procedure is based on the vendor documentation and includes explicit verification steps. It does not claim a new deployment was executed on a Linux endpoint. Validate commands against the selected release and local configuration.