Your agent package installed clean. No errors. You open the dashboard, expecting to see the new endpoint light up green. Instead? “Never connected.” Grey dot. Nothing.
Sound familiar? You’re not alone. Nine times out of ten, the install worked fine. The problem is enrollment, the step most guides gloss over in one line. That’s the gap this guide closes.
Here’s the deal. Installing a Wazuh agent and enrolling a Wazuh agent are two separate jobs. Install puts the software on the endpoint. Enroll registers that endpoint with your manager and hands it the key it needs to send data. Skip the second part, or get the ports wrong, and you get that dead grey dot every time.
By the end of this walkthrough, you’ll be able to install the Wazuh agent on Linux, Windows, and macOS, enroll it properly, and confirm it’s actually reporting. We’ll also fix the errors that trip people up. Want the full deployment picture, from server to multi-node cluster? Our live Wazuh XDR training course walks through all of it with hands-on labs. But you can get one agent talking to your manager today, right here.
Let’s go.
What the Wazuh Agent Actually Does
Quick answer first. The Wazuh agent is lightweight software you install on each endpoint you want to monitor. It collects logs, watches files for changes, scans for vulnerabilities, and runs active response scripts. Then it ships all that telemetry to the Wazuh server for analysis.
Think of the agent as a sensor. The server is the brain. Without agents feeding it data, your Wazuh deployment sees nothing.
The agent runs on a lot of systems. Linux, Windows 7 through 11 and Windows Server, macOS 10.14 and up, plus Solaris, AIX, and HP-UX (Source: Wazuh Documentation). One agent, most of your fleet covered.
As of mid-2026, the current stable release is Wazuh 4.14.5. Version 5.0 is on the way with clustering on by default and the Filebeat dependency removed (Source: Wazuh GitHub Releases). The install and enrollment steps below hold across the whole 4.x line, so you’re safe following them today.
Before You Install: Three Things to Check
Miss any of these and enrollment fails silently. So check them first.
1. You need a running Wazuh manager. The agent has to register with something. If you don’t have a manager yet, set that up before touching agents. The agent needs the manager’s IP address or hostname.
2. The right ports have to be open. This is the one people forget. The agent talks to the manager on three channels:
| Port | Protocol | Purpose |
|---|---|---|
| 1514 | TCP | Agent-to-manager communication (the data feed) |
| 1515 | TCP | Automatic enrollment requests |
| 55000 | TCP | API-based enrollment operations |
If port 1515 is blocked, automatic enrollment dies. If 1514 is blocked, the agent enrolls but never sends data. Grey dot city. Open these on your firewall and any security groups between the endpoint and the manager (Source: Wazuh Documentation).
3. You need root or admin on the endpoint. Installing packages and registering system services requires it. No way around that.
Got all three? Good. Time to install.
How to Install the Wazuh Agent on Linux
Most SOC monitoring starts with Linux servers, so we’ll begin here. The install process uses two variables that do the heavy lifting: WAZUH_MANAGER (your manager’s IP) and WAZUH_AGENT_NAME (whatever you want to call this endpoint). Set them at install time and the agent configures itself.
Debian and Ubuntu
First, add the Wazuh GPG key and repository:
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 updateNow install the agent with your manager details baked in:
WAZUH_MANAGER="10.0.0.2" WAZUH_AGENT_NAME="ubuntu-web-01" apt-get install wazuh-agentSwap 10.0.0.2 for your real manager IP and pick a name that tells you what the box is. “ubuntu-web-01” beats “agent1” when you’ve got fifty of them.
RHEL, CentOS, Rocky, and AlmaLinux
Same idea, different package manager. Add the repo:
rpm --import https://packages.wazuh.com/key/GPG-KEY-WAZUH
cat > /etc/yum.repos.d/wazuh.repo << EOFgpgcheck=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
Then install:
WAZUH_MANAGER="10.0.0.2" WAZUH_AGENT_NAME="rocky-db-01" yum install wazuh-agentStart the Service
Installing doesn’t start the agent. You have to enable and launch it:
systemctl daemon-reload
systemctl enable wazuh-agent
systemctl start wazuh-agentThat’s the Linux install done. When you pass WAZUH_MANAGER at install time, the agent tries to auto-enroll on first start using the daemon we’ll cover below. Often it just works. When it doesn’t, the next sections are your fix.
How to Install the Wazuh Agent on Windows
Windows endpoints are where a lot of threats actually land, so don’t skip these. You’ve got two ways in: the GUI wizard or the command line.
For a single machine, download the MSI installer from the Wazuh site and run it. The wizard asks for the manager IP and an agent name. Fill those in, click through, done.
For scripted deployment across many machines, PowerShell (run as Administrator) is faster:
.\wazuh-agent-4.14.5.msi /q WAZUH_MANAGER="10.0.0.2" WAZUH_AGENT_NAME="win-finance-03"Then start the service:
NET START WazuhSvcThe /q flag runs it quiet, no clicking. That’s what makes it Group Policy and SCCM friendly when you’re pushing to a whole department at once.
Here’s a real one. When Priya, an IT admin at a mid-size accounting firm, rolled Wazuh out to 40 Windows machines in March, she ran the MSI by hand on the first three, then scripted the rest through Group Policy in an afternoon. The manual boxes took her twenty minutes each. The scripted batch? Thirty-seven machines, one coffee. Scale changes everything.
How to Install the Wazuh Agent on macOS
macOS is quick. Download the agent package (.pkg) for your architecture, Intel or Apple Silicon, and either run the installer wizard or use the command line.
For a scripted install, set the manager variables in a config, then:
sudo installer -pkg wazuh-agent.pkg -target /
sudo /Library/Ossec/bin/wazuh-control startYou’ll set the manager IP in /Library/Ossec/etc/ossec.conf before starting if you didn’t pass it at install. Same enrollment rules apply. The Mac still has to register with the manager and get its key.
How to Enroll the Wazuh Agent (The Part People Get Wrong)
Now the important bit. Enrollment is how the agent proves who it is and receives a unique key to encrypt its traffic to the manager. No key, no connection. This is exactly where that “Never connected” grey dot comes from.
Wazuh gives you two main routes.
Method 1: Password-Based Enrollment with authd
The scalable way. Wazuh runs an enrollment daemon called authd on the manager. Turn it on, and agents can self-register over port 1515 the first time they start. Perfect when you’re deploying dozens or hundreds of agents and can’t register each one by hand.
For basic setups, authd accepts any agent that asks. For production, add a shared enrollment password so random hosts can’t join your manager. On the manager, drop your password into /var/ossec/etc/authd.pass, then reference the same password on the agent side. When the agent boots, it sends the password to the manager over 1515, gets its key back, and starts reporting.
Higher-assurance option: certificate-based enrollment. Each agent presents a certificate signed by a trusted CA, and the manager verifies it before issuing a key. More setup, much stronger. This is the model you’d use in a compliance-heavy environment where a strong security posture is non-negotiable.
Method 2: Manual Key Enrollment
When you want tight control, or you’re just testing one agent, register it by hand.
On the manager, run the agent manager tool:
/var/ossec/bin/manage_agentsPick A to add an agent, give it a name and the endpoint’s IP, then pick E to extract that agent’s key. You’ll get a long base64 string. Copy it.
On the agent, run the same tool:
/var/ossec/bin/manage_agentsPick I to import a key, paste the string, confirm. Restart the agent:
systemctl restart wazuh-agentThere’s also a one-shot command, agent-auth, that registers against a manager running authd:
/var/ossec/bin/agent-auth -m 10.0.0.2That reaches out to the manager on 1515, grabs a key, and writes it locally. Fast for one-off registration.
When Diego, a junior SOC analyst studying for his first security role, set up his home lab, he kept getting “Never connected” no matter how many times he reinstalled. The install was fine every time. His mistake? He never ran enrollment at all. He assumed the package handled it. One agent-auth -m command later, green dot, data flowing. He’d wasted two evenings on a step that takes ten seconds once you know it exists.
Don’t be early-lab Diego. Install, then enroll. Two steps. Always.
Verify the Agent Is Actually Connected
Never trust the install. Confirm it. Three ways to check.
On the agent, ask the control tool for status:
/var/ossec/bin/wazuh-control statusEvery process should read “is running.” If wazuh-agentd is stopped, it can’t talk to the manager.
On the manager, list your agents:
/var/ossec/bin/agent_control -lYour new endpoint should show “Active.” “Never connected” means enrollment or ports. “Disconnected” means it enrolled once but lost contact, usually a firewall or a stopped service.
In the dashboard, go to Agents management > Summary. Your agent should be green and active within a minute or two. This is also where the “Deploy new agent” button lives, which generates a ready-made install command for any platform if you’d rather not type the variables yourself.
Green dot? You did it. Data’s flowing. Now the real work begins: building detection rules, mapping alerts to MITRE ATT&CK, and catching threats. That’s the stuff that turns log noise into actual security, and it’s the heart of what we teach in the Wazuh XDR course.
Common Enrollment Errors and How to Fix Them
Most Wazuh agent problems land in this table. Save it.
| Symptom | Likely Cause | Fix |
|---|---|---|
| “Never connected” in dashboard | Agent never enrolled, or port 1515 blocked | Run enrollment, open 1515/TCP |
| Enrolls but no data | Port 1514 blocked | Open 1514/TCP on firewall and security groups |
| “Unable to add agent” | Duplicate agent name or IP on manager | Remove the old entry with manage_agents |
| Agent shows “Disconnected” | Service stopped or network dropped | Restart wazuh-agent, check connectivity |
| Wrong key error | Key mismatch after re-register | Re-extract and re-import the key |
| Auth password rejected | Password differs on agent and manager | Match authd.pass on both sides |
Nine times out of ten it’s ports or a skipped enrollment step. Check those two before you touch anything else.
Where Wazuh Fits Next to Splunk and Other SIEM Tools
Quick context, because people always ask. Wazuh is free and open-source. It does most of what commercial SIEM platforms do: log management, threat detection, compliance reporting, and incident response. No per-endpoint licensing. That’s why over 100,000 organisations run it (Source: Wazuh.com).
The trade-off? Wazuh asks for more hands-on configuration than a paid tool. Which, honestly, is the whole point of learning it. Those config skills are exactly what employers test for.
If your shop runs a paid stack too, it’s worth knowing how the pieces compare. Our breakdown of what Splunk Enterprise does covers the other side, and both skill sets show up in SOC job postings. Wazuh’s vulnerability detection also pairs naturally with staying on top of new threats, like the critical CVEs we track each month.
Frequently Asked Questions
Do I need to install the agent on every endpoint I want to monitor?
Yes, for full endpoint visibility. The agent collects the deep telemetry: file changes, running processes, vulnerabilities, and local logs. Wazuh can also monitor some devices agentlessly over syslog, but you lose the endpoint-level detail. For servers and workstations, install the agent.
What’s the difference between installing and enrolling a Wazuh agent?
Installing puts the agent software on the endpoint. Enrolling registers that endpoint with your manager and gives it a unique key to encrypt its data. Both are required. Install without enroll gives you a “Never connected” status every time.
Which ports does the Wazuh agent need open?
Three. 1514/TCP for agent-to-manager data, 1515/TCP for automatic enrollment, and 55000/TCP for API-based enrollment. Blocked ports are the number one cause of connection failures.
Can I deploy Wazuh agents automatically at scale?
Yes. Enable the authd enrollment daemon on the manager and agents self-register on first start. Pair that with Ansible, Group Policy, or your MDM, and you can push hundreds of agents without touching each one. The Wazuh dashboard also generates ready-made deployment commands per platform.
Is the Wazuh agent free?
Completely. Wazuh is open-source under GPL v2. No per-endpoint fees, no feature gating. You only invest time learning to deploy and manage it, which is what turns Wazuh into a career skill.
What if the agent still shows “Never connected” after enrollment?
Check port 1514 is open (the data channel), confirm the service is running with wazuh-control status, and make sure the agent’s key matches what the manager issued. Ninety percent of cases are one of those three.
Do I need Linux experience to run Wazuh?
Basic command-line comfort helps a lot, since the manager runs on Linux and most config is done in files. You don’t need to be an expert. If you’re building toward a security role, cybersecurity jobs are in strong demand and Wazuh skills sit right in the middle of what SOC teams hire for.
Bottom Line
Getting a Wazuh agent connected comes down to two steps people constantly blur together: install the software, then enroll it with your manager. Do both, open ports 1514, 1515, and 55000, and confirm the green dot. That’s the whole game for a single endpoint.
Here’s your quick recap:
- Install with
WAZUH_MANAGERandWAZUH_AGENT_NAMEset at install time - Enroll using
authdfor scale ormanage_agents/agent-authfor manual control - Open ports 1514, 1515, and 55000 between agent and manager
- Verify with
wazuh-control statusand the dashboard summary - Troubleshoot ports and skipped enrollment first, always
One agent working is the easy part. Building detection rules, tuning alerts, handling multi-node clusters, and running real incident response? That’s the skill set that gets you hired, and it’s hard to teach yourself from docs alone.
That’s where live training pays off. Our Wazuh XDR course runs instructor-led sessions with unlimited hands-on labs, so you practise on real deployments, not slides. Every student gets free 1-on-1 mentorship the whole way through. Book a free demo class and see how it works before you commit.
Want to practise the fundamentals on your own time too? Pair the course with the SOC and security workbook from SMEnode Labs for extra lab scenarios you can run at home.
Install today. Enroll today. Build a security career from there.
