Grouping agents
There are two methods for configuring registered agents. They can either be configured locally with the ossec.conf file or remotely using the centralized configuration. If the centralized configuration is used, agents may be assigned to groups where each group possesses a unique configuration. This greatly simplifies the overall configuration process.
Note
Read the Agent groups and centralized configuration document for more information.
Unless otherwise assigned, all new connected agents automatically belong to the 'default' group. This group is created during the installation process with the configuration files placed in the /var/ossec/etc/shared/default/
folder. These files will be pushed from the manager to all agents belonging to this group.
Below are the steps to assign agents to a group with a specific configuration:
Once an agent has been added and connected to the manager, assign it to a group using the agent_groups tool or the Wazuh API. Below are examples of how to assign an agent with ID 002 to the group 'dbms' using these methods:
Using agent_groups:
Note
The group must be created and configured before assigning agents.
Note
This behavior corresponds to
v3.7.0
and later.Note
The group name can only contain upper/lower case letters, numbers, dots, underscores, and hyphens.
# /var/ossec/bin/agent_groups -a -i 002 -g dbms
Using the Wazuh API endpoint PUT /agents/{agent_id}/group/{group_id}:
# curl -k -X PUT "https://localhost:55000/agents/002/group/dbms?pretty=true" -H "Authorization: Bearer $TOKEN"
{ "data": { "affected_items": ["002"], "total_affected_items": 1, "total_failed_items": 0, "failed_items": [], }, "message": "All selected agents were assigned to dbms", "error": 0, }
An agent's group assignment can be checked using one of the following commands:
Using agent_groups:
# /var/ossec/bin/agent_groups -l -g dbms
5 agent(s) in group 'dbms': ID: 002 Name: agent-dbms-e1. ID: 003 Name: agent-dbms-e2. ID: 004 Name: agent-dbms-a1. ID: 005 Name: agent-dbms-a2. ID: 006 Name: agent-dbms-a3.
Using the Wazuh API endpoint GET /groups/{group_id}/agents:
# curl -k -X GET "https://localhost:55000/groups/dbms/agents?pretty=true&select=id,name" -H "Authorization: Bearer $TOKEN"
{ "data": { "affected_items": [ {"name": "agent-dbms-e1", "id": "002"}, {"name": "agent-dbms-e2", "id": "003"}, {"name": "agent-dbms-a1", "id": "004"}, {"name": "agent-dbms-a2", "id": "005"}, {"name": "agent-dbms-a3", "id": "006"}, ], "total_affected_items": 5, "total_failed_items": 0, "failed_items": [], }, "message": "All selected agents information was returned", "error": 0, }
Once a group is created, its
agent.conf
file can be edited to include the specific configuration you wish to assign to this group. For this example, the file to be edited is located at/var/ossec/etc/shared/dbms/agent.conf
and each agent belonging to this group will receive this file.Within 20 minutes of connecting to the manager, each agent assigned to a group will receive the files contained in the 'dbms' folder from the manager, including the
agent.conf
file that was modified in the previous step. The length of time it takes for the manager to push these files to the agents depends on the size of the files, the number of agents in the group and the connection protocol used. For example, depending on network bandwidth and performance, it may take 8 minutes to receive a 10 MB folder (excluding merged.mg file) on 100 agents using UDP. However, if TCP is used, this may move along much faster.Once a specific agent belongs to a group, it will be automatically reassigned to this group even if it is registered under another name or ID. This happens because, when the agent is re-registered, the checksum of
merged.mg
sent by the agent is compared with that of the other agents registered with the manager. However, this is not the default behavior, and, if needed, it must be explicitly activated by the user inlocal_internal_options.conf
by adding the optionremoted.guess_agent_group=1
(see sectionremoted
in internal options).
Multiple groups
Since Wazuh v3.7.0, agents have the ability to belong to multiple groups. The agents will receive all the configuration files from each group. Configuration received from the last assigned group has more priority than the other ones.
Managing multiple groups
This capability is focused to customize the agents' configuration with a higher level of granularity. The Wazuh API and agent_groups help to manage groups by listing them and also by allowing to assign/change/unassign groups to agents. Let see three use cases where managing multiple groups over existing agents.
Assigning multiple groups to an agent
Setting multiple groups to an agent is simple. There are three different ways to assign an agent to one or more groups: Registration, CLI and API.
In this example, the agent 001 has been added to webserver and apache groups. First of all, using the Wazuh API endpoint PUT /agents/{agent_id}/group/{group_id}:
# curl -k -X PUT "https://localhost:55000/agents/001/group/webserver?pretty=true" -H "Authorization: Bearer $TOKEN"{ "data": { "affected_items": ["001"], "total_affected_items": 1, "total_failed_items": 0, "failed_items": [], }, "message": "All selected agents were assigned to webserver", "error": 0, }# curl -k -X PUT "https://localhost:55000/agents/001/group/apache?pretty=true" -H "Authorization: Bearer $TOKEN"{ "data": { "affected_items": ["001"], "total_affected_items": 1, "total_failed_items": 0, "failed_items": [], }, "message": "All selected agents were assigned to apache", "error": 0, }
After that, we can ask about groups to which an agent belongs using the Wazuh API endpoint GET /agents:
# curl -k -X GET "https://localhost:55000/agents?pretty=true&agents_list=001&select=group" -H "Authorization: Bearer $TOKEN"{ "data": { "affected_items": [{"group": ["default", "webserver", "apache"], "id": "001"}], "total_affected_items": 1, "total_failed_items": 0, "failed_items": [], }, "message": "All selected agents information was returned", "error": 0, }
In this case, the remote configuration for the group apache is the most priority of the three groups when there exist conflicts on any configuration parameter.
With the agent_groups CLI, agents can be registered to groups on the same way:
$ /var/ossec/bin/agent_groups -a -i 001 -g webserverDo you want to add the group 'webserver' to the agent '001'? [y/N]: y Group 'webserver' added to agent '001'.$ /var/ossec/bin/agent_groups -a -i 001 -g apacheDo you want to add the group 'apache' to the agent '001'? [y/N]: y Group 'apache' added to agent '001'.
To assign the agent to one or more groups during the registration process, register the agent by setting the groups where the agent will be included with the -G option:
# /var/ossec/bin/agent-auth -m MANAGER_IP -G webserver,apache
Listing groups and configuration
It is possible to know agents belonging to groups in real-time, as well as the configuration and shared files applied to each one depending on which groups it belongs.
For example, to list the groups available for now, we could run the following query to agent_groups:
# /var/ossec/bin/agent_groups -l -g webserver3 agent(s) in group 'webserver': ID: 001 Name: ag-windows-12. ID: 003 Name: ag-windows-east. ID: 004 Name: centos-7-apache
Same easy to query which groups are assigned to the agent 001:
# /var/ossec/bin/agent_groups -s -i 001The agent 'ag-windows-12' with ID '001' has the group: '[u'webserver', u'apache']'.
The priority of the groups increases from the left to the right, being the last one the highest priority one.
Making changes on multiple groups
The same way it is possible to assign multiple groups to agents, it is possible to revert assignments and switch between available groups. Below is shown how to unset the group apache for the agent 001:
# /var/ossec/bin/agent_groups -r -i 001 -g apache -qGroup 'apache' unset for agent '001'.# /var/ossec/bin/agent_groups -s -i 001The agent 'ag-windows-12' with ID '001' has the group: '[u'webserver']'.
It is also possible to switch between groups overwriting the existing assignment:
# /var/ossec/bin/agent_groups -s -i 001The agent 'ag-windows-12' with ID '001' has the group: '[u'default', u'webserver']'.# /var/ossec/bin/agent_groups -a -f -i 001 -g apacheGroup 'apache' set to agent '001'.# /var/ossec/bin/agent_groups -s -i 001The agent 'ag-windows-12' with ID '001' has the group: '[u'apache']'.
The -f
parameter resets groups assigned to the agent and forces it to only belong to the new group.
Finally, to check the synchronization status of the group configuration for agents, both following methods are available, agent_groups and Wazuh API endpoint GET /agents:
# /var/ossec/bin/agent_groups -S -i 001Agent '001' is synchronized.# curl -k -X GET "https://localhost:55000/agents?agents_list=001&select=group_config_status&pretty=true" -H "Authorization: Bearer $TOKEN"{ "data": { "affected_items": [ { "group_config_status": "synced", "id": "001" } ], "total_affected_items": 1, "total_failed_items": 0, "failed_items": [] }, "message": "All selected agents information was returned", "error": 0 }
The rest of the capabilities of agent_groups can be found at its reference section. The same for the Wazuh API, which offers calls with similar behavior.