# wazuh-agent-disconnected

Companion files for the lesson [Wazuh Agent Disconnected or Never Connected: Fix It](https://maheshtata.com/wazuh/wazuh-agent-disconnected/).

Tested against the Wazuh 5.0 beta5 documentation (September 2026). Wazuh 5.0 is
still in beta, so treat every value as subject to change at GA.

| File | What it is | Where it goes |
| --- | --- | --- |
| `check-agent-connection.sh` | Read-only triage script for a Linux or macOS endpoint | run on the endpoint: `sudo ./check-agent-connection.sh <MANAGER_IP>` |
| `wazuh-manager.conf.fragment.xml` | The `<global>`, `<remote>` and `<auth>` sections that decide connectivity | merge into `/var/wazuh-manager/etc/wazuh-manager.conf` |

The script changes nothing. It collects the ten pieces of evidence the lesson
asks for, in the order the lesson asks for them, and prints the manager-side
commands to run next.

The XML file is a fragment. The manager rejects unknown elements at startup,
so merge the sections into the existing configuration rather than replacing it.

## The four checks that resolve most cases

1. **The URL prefix, not the listener.** Verified on 5.0.0-beta5: `bind_addr`
   ships as `0.0.0.0`, so loopback binding is not the usual cause. What does
   catch people is `<global_prefix>`: `https://manager:1517/` answers
   `{"error":"not_found"}` and `https://manager:1517/wazuh-manager/` answers
   `{"status":"ok","module":"remoted"}`. Probe the prefix.
2. **Enrolment password.** `use_password` is set to `yes` by the installer.
   The agent needs `authd.pass` with the manager's value. A wrong value gives
   `ERROR: Enrollment rejected by the manager: invalid or missing
   authentication. Invalid client authentication` and the agent stays
   `pending`.
3. **Missing group.** An agent declaring a group that does not exist on the
   manager has its enrolment rejected outright: `ERROR: Enrollment rejected by
   the manager: invalid request. Invalid Group(s) Name(s)` on the agent, and
   `wazuh-manager-authd: ERROR: Invalid group: <name>` on the manager. Create
   groups first.
4. **Clock skew.** Authentication uses a 60-second JWT with roughly 30 seconds
   of tolerated skew. A drifted clock produces a generic 401.

## Port summary

| Agent version | Ports needed from agent to manager |
| --- | --- |
| Wazuh 5.0 | `1517/TCP` (enrolment and communication), `55000/TCP` only for API enrolment |
| Wazuh 4.x | `1514/TCP` communication, `1515/TCP` enrolment, `55000/TCP` for API enrolment |