Learn Wazuh - Agent Deployment & Enrollment

#Introduction

In episode 3, your Wazuh server is fully running — manager, indexer, and dashboard are active. But without agents, the server is just waiting. Now it's time to install sensors on endpoints.

Episode 4 covers agent deployment and enrollment: installing the Wazuh Agent on various operating systems, connecting it to the manager, and verifying its status. By the end of this episode, your target VM will appear as an active agent in the dashboard.

We'll distinguish two things that are often confused: installation puts the agent software on the machine, while enrollment registers that machine to the manager and gives it a unique key for encrypted communication.

#Enrollment Preparation

Before installing the agent, prepare two pieces of information from the Wazuh server:

• Server IP or hostname — used by the agent to connect.
• API credentials — the admin user and password from the episode 3 installer output, used when requesting a key.

Enrollment keys can be requested through the manager API running on port 55000. The general flow: generate an authentication token, then use that token to request an agent key:

TOKEN=$(curl -u admin:KATA_SANDI -k -X POST "https://IP_SERVER:55000/security/user/authenticate?raw=true")
curl -k -X POST -d '{"name":"agent-01"}' "https://IP_SERVER:55000/agents?pretty=true" -H "Content-Type:application/json" -H "Authorization: Bearer $TOKEN"

The second response contains the agent ID and a long key string. That key is what gives the agent the right to connect securely. Keep it safe — without the key, the agent will never show up as active.

#Installing the Agent on Linux

Good news: the most common approach doesn't require managing keys manually. The Linux agent package can be installed directly with environment variables that register the agent at the same time. From the wazuh-agent VM, run:

curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | sudo gpg --no-default-keyring --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg --import
echo "deb [signed-by=/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/4.x/apt/ stable main" | sudo tee -a /etc/apt/sources.list.d/wazuh.list
sudo apt update

For RPM-based distributions like RHEL, register the official repository first in a similar way. Once the repository is ready, install the agent with the enrollment variables:

sudo WAZUH_MANAGER="IP_SERVER" WAZUH_AGENT_NAME="agent-01" apt install wazuh-agent
sudo systemctl enable wazuh-agent
sudo systemctl start wazuh-agent

Replace IP_SERVER with your manager's address. When the service starts, the agent automatically enrolls to the manager on port 1515, receives a key, then starts sending data on port 1514. Important note: the agent does not need to be reinstalled if you change managers — just change the address and restart.

#Installing the Agent on Windows

For Windows, Wazuh provides an MSI installer. There are two paths: a graphical wizard or the command line. For a single machine, just download the MSI from the Wazuh repository, run the wizard, and fill in the manager address and agent name.

For mass deployment, PowerShell as administrator is more efficient:

Invoke-WebRequest -Uri https://packages.wazuh.com/4.x/windows/wazuh-agent-4.x.msi -OutFile wazuh-agent.msi
./wazuh-agent-4.x.msi /q WAZUH_MANAGER="IP_SERVER" WAZUH_AGENT_NAME="agent-win-01"

When it finishes, the Wazuh service is automatically registered and running. The configuration on Windows is named ossec.conf and lives in the installation directory under the Program Files folder — the file structure is the same as Linux, only the location differs.

#Installing the Agent on macOS

For macOS, use the pkg package. Make sure the manager variable is set before running the installer:

sudo installer -pkg wazuh-agent-4.x.pkg -target /
sudo /Library/Ossec/bin/wazuh-control start

If the variables aren't set during installation, set the manager address in /Library/Ossec/etc/ossec.conf before running wazuh-control start. The enrollment concept is identical to Linux and Windows.

#Understanding ossec.conf

All agent configuration lives in the ossec.conf file. The two most important blocks for connectivity:

<ossec_config>
  <client>
    <server>
      <address>IP_SERVER</address>
      <protocol>tcp</protocol>
      <port>1514</port>
    </server>
  </client>
  <enrollment>
    <enabled>yes</enabled>
    <manager_address>IP_SERVER</manager_address>
    <port>1515</port>
  </enrollment>
</ossec_config>

The client block configures the data destination: manager address, protocol, and port. The protocol can be tcp or udp — TCP is more reliable, UDP is lighter. The enrollment block configures registration. After changing ossec.conf, restart the agent so the changes take effect.

#Centralized Management with agent.conf

In large-scale deployments, editing ossec.conf on every machine is impractical. Wazuh provides centralized configuration: the agent.conf file on the manager side that is pushed to all agents.

sudo nano /var/ossec/etc/shared/agent.conf

With agent.conf, you can apply different configuration groups per agent name or per operating system without touching every endpoint. Changes are applied when the agent receives the next configuration polling — no reinstallation required.

#Verifying Agent Status

Once the agent is installed, verify from two sides.

From the agent side, check its process status:

/var/ossec/bin/wazuh-control status

From the manager side, list all agents along with their status:

sudo /var/ossec/bin/agent_control -l

The expected status is Active — meaning the agent is enrolled and sending data. Disconnected status means the agent was connected before but the connection dropped, usually due to a firewall or a stopped service. Never connected means enrollment never happened — check port 1515 and the enrollment variables. In the dashboard, open the Agents management menu and make sure the agent shows up green.

#Conclusion

Episode 4 is complete. Your target VM is now an active agent sending data to the manager.

Key takeaways:

• Installation puts the software in place, enrollment registers the key — two mandatory steps.
• The Linux agent can be installed and enrolled at once via the WAZUH_MANAGER variable.
• Windows uses MSI, macOS uses pkg, with the same configuration structure.
• The client and enrollment blocks in ossec.conf configure the agent connection.
• agent.conf on the manager enables centralized configuration without touching endpoints.
• The Active, Disconnected, and Never connected statuses lead you to the root cause.

Next, in episode 5 we dive into the heart of SIEM: log monitoring and analysis — how logcollector reads local logs, the decoder-to-rules-to-alert flow, and how to see it all in the dashboard. See you there!