RUNBOOK: Wazuh Agent Group Management¶
Version: 1.0.0 Last Updated: 2026-02-17 Applies to: Wazuh Manager (all versions from 4.x) Operating System: Linux (Ubuntu, CentOS, RHEL, etc.)
📋 Table of Contents¶
0) Non-Negotiable Rules¶
⚠️ STOP Conditions – These conditions are absolute STOP signals:
| Rule | Description | Check Command |
|---|---|---|
| Wazuh Manager must be running | The Manager service must be active | systemctl status wazuh-manager |
| Backup before changes | Create a backup before major group changes | tar -czf /tmp/wazuh-groups-backup-$(date +%F).tar.gz /var/ossec/etc/shared/ |
| No concurrent changes | Only one administrator may modify groups at a time | Coordinate within the team |
| Valid group names | Only alphanumeric characters, underscores, and hyphens allowed | [a-zA-Z0-9_-]+ |
Overview¶
What Are Wazuh Agent Groups?¶
Wazuh agent groups enable centralized management of agent configurations. Agents can be assigned to one or more groups and automatically receive the combined configurations of all their groups.
Key Features:¶
- Centralized configuration management: Configurations are managed by the Manager and automatically distributed to agents
- Multi-group support: An agent can belong to multiple groups simultaneously
- Automatic synchronization: Changes are automatically propagated to all affected agents
- Persistence: Group memberships are retained upon agent re-registration
Key Files¶
1. merged.mg¶
Path: /var/ossec/etc/shared/<agent-id>/merged.mg
Description:
The merged.mg file is generated by the Wazuh Manager and contains the consolidated configuration of all groups an agent belongs to. This file plays a central role in agent configuration.
How it works: - Automatically created and updated by the Manager - Contains the merged configuration from all groups the agent belongs to - Regenerated with every configuration change or group assignment - Automatically transmitted to the agent - Viewable via the dashboard, but not editable
Important Properties: - Ensures agents always receive the current configuration - Supports automatic reassignment after re-registration - Conflict resolution for overlapping configurations follows a defined priority
Example Structure:
<!-- merged.mg -->
<agent_config>
<!-- Configuration from group "linux-servers" -->
<localfile>
<location>/var/log/syslog</location>
<log_format>syslog</log_format>
</localfile>
<!-- Configuration from group "web-servers" -->
<localfile>
<location>/var/log/apache2/access.log</location>
<log_format>apache</log_format>
</localfile>
</agent_config>
2. ar.conf¶
Path: /var/ossec/etc/shared/<group-name>/ar.conf
Description:
The ar.conf file (Active Response Configuration) defines commands that can be executed on agents within a group.
Use Cases: - List of commands for Active Response - Scripts or programs for maintenance tasks - Commands for troubleshooting - Service restart instructions
Example Content:
# ar.conf - Active Response Commands
# Restart Wazuh Agent (Linux)
restart-wazuh0 - restart-wazuh - 0
# Restart Wazuh Agent (Windows)
restart-wazuh-windows - restart-wazuh.exe - 0
# Restart OSSEC service
restart-ossec0 - restart-ossec - 0
# Firewall block
firewall-block - firewall-block.sh - default-firewall-drop
# Host deny
host-deny - host-deny.sh - default-ossec-deny
Command Format:
Important Notes: - Commands must be available on the agent system - Execution permissions must be set correctly - Viewable via the dashboard, but not editable - Changes require a Manager restart
3. agent.conf¶
Path: /var/ossec/etc/shared/<group-name>/agent.conf
Description: Contains the specific configuration for all agents in this group.
Example:
<agent_config>
<client_buffer>
<disabled>no</disabled>
<queue_size>5000</queue_size>
</client_buffer>
<localfile>
<location>/var/log/syslog</location>
<log_format>syslog</log_format>
</localfile>
</agent_config>
Command-Line Management¶
The agent_groups tool allows complete management of agent groups from the command line.
Create Groups¶
Create a new agent group:
Examples:
# Create Linux server group
/var/ossec/bin/agent_groups -a -g linux-servers
# Create web server group
/var/ossec/bin/agent_groups -a -g web-servers
# Create database server group
/var/ossec/bin/agent_groups -a -g db-servers
# Create development environment group
/var/ossec/bin/agent_groups -a -g dev-environment
Notes:
- Group names should be descriptive
- Use hyphens or underscores (no spaces)
- No special characters other than - and _
List Groups¶
List all groups:
List groups with details:
Example Output:
Groups:
- linux-servers (5 agents)
- web-servers (3 agents)
- db-servers (2 agents)
- default (0 agents)
Add Agents to Groups¶
Add an agent to a group:
Add an agent to multiple groups:
Examples:
# Add agent 001 to the linux-servers group
/var/ossec/bin/agent_groups -a -i 001 -g linux-servers
# Add agent 002 to linux-servers and web-servers
/var/ossec/bin/agent_groups -a -i 002 -g linux-servers,web-servers
# Add agent 003 to multiple groups
/var/ossec/bin/agent_groups -a -i 003 -g linux-servers,db-servers,prod-environment
Remove Agents from Groups¶
Remove an agent from a group:
Remove an agent from all groups:
Examples:
# Remove agent 001 from web-servers
/var/ossec/bin/agent_groups -r -i 001 -g web-servers
# Remove agent 003 from all groups
/var/ossec/bin/agent_groups -r -i 003
View Group Members¶
List all agents in a group:
Detailed agent info with groups:
Example Output:
Available agents:
ID: 001, Name: web-server-01, IP: 10.0.1.10, Groups: linux-servers,web-servers
ID: 002, Name: db-server-01, IP: 10.0.1.20, Groups: linux-servers,db-servers
ID: 003, Name: app-server-01, IP: 10.0.1.30, Groups: linux-servers
Delete a Group¶
Caution: Agents must be removed from the group first!
# Step 1: Remove all agents from the group
/var/ossec/bin/agent_groups -r -g <group-name>
# Step 2: Delete the group (remove directory)
rm -rf /var/ossec/etc/shared/<group-name>
# Step 3: Refresh Manager cache
systemctl restart wazuh-manager
Example:
# Completely remove the "old-servers" group
/var/ossec/bin/agent_groups -r -g old-servers
rm -rf /var/ossec/etc/shared/old-servers
systemctl restart wazuh-manager
Group Configuration¶
Create Group Configuration¶
1. Create group directory (done automatically when creating the group):
2. Create configuration file:
3. Example configuration:
<agent_config>
<!-- Logging configuration -->
<localfile>
<location>/var/log/syslog</location>
<log_format>syslog</log_format>
</localfile>
<localfile>
<location>/var/log/auth.log</location>
<log_format>syslog</log_format>
</localfile>
<!-- Rootcheck configuration -->
<rootcheck>
<frequency>43200</frequency>
</rootcheck>
<!-- SCA configuration -->
<sca>
<enabled>yes</enabled>
<scan_on_start>yes</scan_on_start>
<interval>12h</interval>
</sca>
</agent_config>
4. Configure Active Response Commands (optional):
# Example ar.conf
restart-wazuh0 - restart-wazuh - 0
firewall-block - firewall-block.sh - default-firewall-drop
5. Validate configuration:
6. Reload Manager:
Best Practices¶
1. Naming Conventions¶
Recommended naming structure:
<environment>-<function>-<location>
Examples:
- prod-web-servers
- dev-database-servers
- test-app-servers
- prod-linux-eu-west
2. Group Hierarchy¶
Base groups:
linux-base → Base configuration for all Linux systems
windows-base → Base configuration for all Windows systems
Function groups:
web-servers → Specific configuration for web servers
db-servers → Specific configuration for database servers
app-servers → Specific configuration for application servers
Environment groups:
Agent assignment (multi-group):
# Example: Production Web Server
/var/ossec/bin/agent_groups -a -i 001 -g linux-base,web-servers,prod
3. Configuration Management¶
Version control: - Manage all group configurations in Git - Review changes via Pull Requests - Ensure rollback capability
Backup strategy:
# Create backup before changes
tar -czf /backup/wazuh-groups-$(date +%F-%H%M).tar.gz /var/ossec/etc/shared/
# Regular backups (cron)
0 2 * * * tar -czf /backup/wazuh-groups-$(date +\%F).tar.gz /var/ossec/etc/shared/
4. Testing¶
Use a test group:
# Create test group
/var/ossec/bin/agent_groups -a -g test-config
# Assign test agent
/var/ossec/bin/agent_groups -a -i 999 -g test-config
# Test configuration
# ... observe changes ...
# On success, roll out to all agents
5. Documentation¶
Document for each group: - Purpose of the group - Included configurations - Assigned agents - Change history - Responsible person
Example documentation:
group: web-servers
purpose: Configuration for Apache/Nginx web servers
configurations:
- Apache access/error logs
- Nginx access/error logs
- ModSecurity monitoring
- SSL/TLS certificate monitoring
agent_count: 12
created: 2026-01-15
responsible: security-team@company.com
Troubleshooting¶
Problem: Agent receives no configuration¶
Symptom:
Diagnosis:
# 1. Check group membership
/var/ossec/bin/agent_groups -l -g <group-name>
# 2. Check merged.mg
ls -la /var/ossec/etc/shared/<agent-id>/merged.mg
# 3. Check Manager logs
tail -f /var/ossec/logs/ossec.log | grep "group"
# 4. Check agent connection
/var/ossec/bin/agent_control -l
Solution:
# Re-add agent to group
/var/ossec/bin/agent_groups -a -i <agent-id> -g <group-name>
# Restart Manager
systemctl restart wazuh-manager
# Force agent synchronization
/var/ossec/bin/agent_control -R <agent-id>
Problem: merged.mg is not updated¶
Symptom:
Diagnosis:
# 1. Check file permissions
ls -la /var/ossec/etc/shared/<group-name>/
# 2. Check Manager process
ps aux | grep wazuh-remoted
# 3. Check queue
ls -la /var/ossec/queue/rids/
Solution:
# 1. Fix permissions
chown -R wazuh:wazuh /var/ossec/etc/shared/<group-name>/
chmod 750 /var/ossec/etc/shared/<group-name>/
chmod 640 /var/ossec/etc/shared/<group-name>/*
# 2. Restart Manager
systemctl restart wazuh-manager
# 3. Force agent synchronization
/var/ossec/bin/agent_control -R -a
Problem: Group cannot be deleted¶
Symptom:
Diagnosis:
# 1. Check agents in the group
/var/ossec/bin/agent_groups -l -g <group-name>
# 2. Check filesystem locks
lsof | grep /var/ossec/etc/shared/<group-name>
Solution:
# 1. Remove all agents from the group
/var/ossec/bin/agent_groups -r -g <group-name>
# 2. Stop Manager
systemctl stop wazuh-manager
# 3. Delete group
rm -rf /var/ossec/etc/shared/<group-name>
# 4. Start Manager
systemctl start wazuh-manager
Problem: ar.conf commands do not work¶
Symptom:
Diagnosis:
# 1. Check ar.conf syntax
cat /var/ossec/etc/shared/<group-name>/ar.conf
# 2. Is the command present on the agent?
# (on the agent system)
ls -la /var/ossec/active-response/bin/
# 3. Check agent logs
# (on the agent system)
tail -f /var/ossec/logs/active-responses.log
Solution:
# 1. Fix ar.conf
vi /var/ossec/etc/shared/<group-name>/ar.conf
# 2. Set permissions
chmod 750 /var/ossec/active-response/bin/*
# 3. Restart Manager
systemctl restart wazuh-manager
# 4. Force agent synchronization
/var/ossec/bin/agent_control -R <agent-id>
Health Check Commands¶
Check Group Status¶
# All groups with agent count
/var/ossec/bin/agent_groups -l
# Specific group with details
/var/ossec/bin/agent_groups -l -g <group-name>
# All agents with group membership
/var/ossec/bin/manage_agents -l | grep -i "group"
# Check group directories
ls -la /var/ossec/etc/shared/
# Check configuration files
find /var/ossec/etc/shared/ -name "agent.conf" -o -name "ar.conf" -o -name "merged.mg"
Synchronization Status¶
# Agent connection status
/var/ossec/bin/agent_control -l
# Last agent synchronization
/var/ossec/bin/agent_control -i <agent-id>
# Queue status
ls -la /var/ossec/queue/rids/
# Manager logs for group events
grep -i "group" /var/ossec/logs/ossec.log | tail -n 50
Useful Scripts¶
Script: List All Agents in a Group¶
#!/bin/bash
# list-group-agents.sh
GROUP_NAME="$1"
if [ -z "$GROUP_NAME" ]; then
echo "Usage: $0 <group-name>"
exit 1
fi
echo "=== Agents in group: $GROUP_NAME ==="
/var/ossec/bin/manage_agents -l | grep "Groups:.*$GROUP_NAME"
Script: Create Group Backup¶
#!/bin/bash
# backup-groups.sh
BACKUP_DIR="/backup/wazuh-groups"
TIMESTAMP=$(date +%F-%H%M%S)
mkdir -p "$BACKUP_DIR"
tar -czf "$BACKUP_DIR/groups-backup-$TIMESTAMP.tar.gz" \
/var/ossec/etc/shared/
echo "Backup created: $BACKUP_DIR/groups-backup-$TIMESTAMP.tar.gz"
ls -lh "$BACKUP_DIR/groups-backup-$TIMESTAMP.tar.gz"
Script: Apply Configuration to All Groups¶
#!/bin/bash
# apply-config-to-all.sh
CONFIG_FILE="$1"
if [ ! -f "$CONFIG_FILE" ]; then
echo "Config file not found: $CONFIG_FILE"
exit 1
fi
for group_dir in /var/ossec/etc/shared/*/; do
group_name=$(basename "$group_dir")
if [ "$group_name" != "default" ]; then
echo "Applying to: $group_name"
cp "$CONFIG_FILE" "$group_dir/agent.conf"
fi
done
systemctl restart wazuh-manager
echo "Configuration applied to all groups"
Further Documentation¶
- Wazuh Official Docs - Agent Groups: https://documentation.wazuh.com/current/user-manual/agent-enrollment/agent-enrollment.html
- Wazuh Official Docs - Centralized Configuration: https://documentation.wazuh.com/current/user-manual/reference/centralized-configuration.html
- Wazuh Official Docs - Active Response: https://documentation.wazuh.com/current/user-manual/capabilities/active-response/index.html
Last Updated: 2026-02-17 Next Review: 2026-05-17 Responsible: Security Operations Team