# wazuh-agent-groups

Companion files for the lesson **Wazuh Agent Groups and Centralised Configuration**.

Lesson: https://maheshtata.com/wazuh/wazuh-agent-groups/

Tested against: Wazuh 5.0 (beta5 documentation, September 2026). `verified: false` until the lab pass.

## Files

| File | Purpose |
| --- | --- |
| `create-groups.sh` | Creates the groups on the manager before any agent enrols, either with the `agent_groups` tool or through the manager API on port 55000. |
| `linux-servers-agent.conf` | Shared configuration for a Linux group. Shows three `<agent_config>` blocks: one unrestricted, one narrowed with `os`, one narrowed with `profile`. |
| `windows-agent.conf` | Shared configuration for a Windows group, collecting two event channels and a narrow FIM scope. |

## Using them

1. Run `create-groups.sh cli` on the manager, or set `WAZUH_MANAGER`, `WAZUH_API_USER` and
   `WAZUH_API_PASSWORD` and run `create-groups.sh api`.
2. Copy the relevant `*-agent.conf` into `/var/wazuh-manager/etc/shared/<GROUP_NAME>/agent.conf.tmp`,
   set ownership to `wazuh-manager:wazuh-manager` and mode `660`.
3. Validate: `/var/wazuh-manager/bin/verify-agent-conf -f <path to the .tmp file>`.
4. Rename the `.tmp` file to `agent.conf`. The manager picks up the change and distributes it.

## Caveats

- Groups must exist before enrolment. An agent that declares a missing group in
  `<enrollment><groups>` is rejected with
  `wazuh-agentd: ERROR: Invalid group: <group>. Unable to add agent (from manager)`.
- `<active-response><repeated_offenders>` cannot be distributed through `agent.conf`; it has to
  be set in the agent's local configuration file.
- Group membership is written at enrolment. Assigning a group afterwards through the API or the
  dashboard adds it to the existing list rather than replacing it.

## Sources

- https://documentation.wazuh.com/5.0-beta/user-manual/reference/centralized-configuration.html
- https://documentation.wazuh.com/5.0-beta/user-manual/agent/agent-management/grouping-agents.html
- https://documentation.wazuh.com/5.0-beta/user-manual/reference/ossec-conf/agent.html
- https://github.com/wazuh/wazuh/blob/main/docs/guide/migration/agent-groups-migration.md