Centralized configuration (agent.conf)
Introduction
Agents can be configured remotely by using the agent.conf file. The following capabilities can be configured remotely:
File Integrity monitoring (syscheck)
Rootkit detection (rootcheck)
Log data collection (localfile)
Remote commands (wodle name="command")
Labels for agent alerts (labels)
System inventory (syscollector)
Avoid events flooding (client_buffer)
Configure osquery wodle (wodle name="osquery")
force_reconnect_interval setting (client)
Amazon Web Services (wodle name="aws-s3")
Microsoft Azure (wodle name="azure-logs")
Google Cloud Pub/Sub (gcp-pubsub)
Google Cloud Storage (gcp-bucket)
GitHub (github)
Office 365 (office365)
Microsoft Graph (ms-graph)
Docker listener (wodle name="docker-listener")
Output sockets (socket)
Note
When setting up remote commands in the shared agent configuration, you must enable remote commands for Agent Modules. This is enabled by adding the following line to the /var/ossec/etc/local_internal_options.conf file in the agent:
wazuh_command.remote_commands=1
Logcollector commands and sockets have the same requirement. To accept command and full_command log sources, <socket> blocks, and socket targets from the shared configuration, add the following line to the /var/ossec/etc/local_internal_options.conf file in the agent:
logcollector.remote_commands=1
Agent groups
Agents can be grouped together in order to send them a unique centralized configuration that is group specific. Each agent can belong to more than one group, and unless otherwise configured, all agents belong to a group called default.
Note
Check the agent_groups manual to learn how to add groups and assign agents to them.
The manager pushes all files included in the group folder to the agents belonging to this group. For example, all files in /var/ossec/etc/shared/default will be pushed to all agents belonging to the default group.
In case an agent is assigned to multiple groups, all the files contained in each group folder will be merged into one, and subsequently sent to the agents, being the last one the group with the highest priority.
The file ar.conf (Active Response status) will always be sent to agents even if it is not present in the group folder.
The agent will store the shared files in /var/ossec/etc/shared, not in a group folder.
Below are the files that would be found in this folder on an agent assigned to the debian group. Notice that these files are pushed to the agent from the manager /var/ossec/etc/shared/debian folder.
Manager |
Agent (Group: 'debian') |
/var/ossec/etc/shared/
├── ar.conf
├── debian
│ ├── agent.conf
│ ├── cis_debian_linux_rcl.txt
│ ├── cis_rhel5_linux_rcl.txt
│ ├── cis_rhel6_linux_rcl.txt
│ ├── cis_rhel7_linux_rcl.txt
│ ├── cis_rhel_linux_rcl.txt
│ ├── cis_sles11_linux_rcl.txt
│ ├── cis_sles12_linux_rcl.txt
│ ├── custom_rootcheck.txt
│ ├── debian_ports_check.txt
│ ├── debian_test_files.txt
│ ├── merged.mg
│ ├── rootkit_files.txt
│ ├── rootkit_trojans.txt
│ ├── system_audit_rcl.txt
│ ├── system_audit_ssh.txt
│ ├── win_applications_rcl.txt
│ ├── win_audit_rcl.txt
│ └── win_malware_rcl.txt
└── default
├── agent.conf
├── cis_debian_linux_rcl.txt
├── cis_rhel5_linux_rcl.txt
├── cis_rhel6_linux_rcl.txt
├── cis_rhel7_linux_rcl.txt
├── cis_rhel_linux_rcl.txt
├── cis_sles11_linux_rcl.txt
├── cis_sles12_linux_rcl.txt
├── merged.mg
├── rootkit_files.txt
├── rootkit_trojans.txt
├── system_audit_rcl.txt
├── system_audit_ssh.txt
├── win_applications_rcl.txt
├── win_audit_rcl.txt
└── win_malware_rcl.txt
|
/var/ossec/etc/shared/
├── ar.conf
├── agent.conf
├── cis_debian_linux_rcl.txt
├── cis_rhel5_linux_rcl.txt
├── cis_rhel6_linux_rcl.txt
├── cis_rhel7_linux_rcl.txt
├── cis_rhel_linux_rcl.txt
├── cis_sles11_linux_rcl.txt
├── cis_sles12_linux_rcl.txt
├── custom_rootcheck.txt
├── debian_ports_check.txt
├── debian_test_files.txt
├── merged.mg
├── rootkit_files.txt
├── rootkit_trojans.txt
├── system_audit_rcl.txt
├── system_audit_ssh.txt
├── win_applications_rcl.txt
├── win_audit_rcl.txt
└── win_malware_rcl.txt
|
The proper syntax of agent.conf is shown below along with the process for pushing the configuration from the manager to the agent.
agent.conf
The agent.conf is only valid on server installations.
The agent.conf may exist in each group folder at /var/ossec/etc/shared.
For example, for the group1 group, it is in /var/ossec/etc/shared/group1. Each of these files should be readable by the wazuh user.
Limits for group files: the manager ignores a file whose path under /var/ossec/etc/shared/ is longer than 224 characters (200 before 4.14.10). From 4.14.10, Windows agents skip files whose names contain :, <, >, ", |, ? or *, end with a dot or a space, are device names such as CON or NUL, or look like 8.3 short names, and log invalid entry name. The Wazuh server API rejects a group configuration file larger than 10 MiB with HTTP 413. The manager builds each merged.mg file in memory, so very large group files need about twice their size in free memory.
Options
name |
Assigns the block to agents with specific names. |
|
Allowed values |
An sregex (OS_Match) pattern that matches the agent name. The match is
case-insensitive and isn't anchored unless the pattern uses |
|
os |
Assigns the block to agents on specific operating systems. |
|
Allowed values |
An sregex (OS_Match) pattern that matches the agent OS information. The
match is case-insensitive and isn't anchored unless the pattern uses |
|
profile |
Assigns the block to agents with specific profiles as defined in client configuration. Linux agent packages set a
profile list for the operating system, for example |
|
Allowed values |
An sregex (OS_Match) pattern that matches the agent profile list. The
match is case-insensitive and isn't anchored unless the pattern uses |
|
Centralized configuration process
Creating and validating the configuration
Create or edit the configuration file in the group directory.
Use a temporary file name that starts with a dot, such as
.agent.conf.tmp, while you edit. The manager doesn't distribute files whose names start with a dot, so agents don't receive an incomplete configuration. For example, run these commands for thedefaultgroup.# touch /var/ossec/etc/shared/default/.agent.conf.tmp # chown wazuh:wazuh /var/ossec/etc/shared/default/.agent.conf.tmp # chmod 660 /var/ossec/etc/shared/default/.agent.conf.tmp
Define one or more configuration blocks. Use filters such as
name,os, andprofileto target specific agents:<agent_config name="agent_name"> <localfile> <location>/var/log/my.log</location> <log_format>syslog</log_format> </localfile> </agent_config> <agent_config os="Linux"> <localfile> <location>/var/log/linux.log</location> <log_format>syslog</log_format> </localfile> </agent_config> <agent_config profile="database"> <localfile> <location>/var/log/database.log</location> <log_format>syslog</log_format> </localfile> </agent_config>
Note
The
profileoption uses values defined in the config-profile setting of the<client>configuration.Use the
verify-agent-conftool to validate the temporary configuration before making it active. For example:# /var/ossec/bin/verify-agent-conf -f /var/ossec/etc/shared/default/.agent.conf.tmp
Fix any issues before continuing.
Rename the validated file to make it active. For example:
# mv /var/ossec/etc/shared/default/.agent.conf.tmp /var/ossec/etc/shared/default/agent.conf
The manager will automatically detect the new configuration and distribute it to all agents in the group.
Note
Restarting the manager helps distribute the new agent.conf file to the agents more quickly.
Confirming that the configuration was applied
Agents automatically reload the configuration after receiving it. On Linux, wazuh-agentd keeps its connection to the manager while the other agent daemons restart. On Windows, the whole agent service restarts, so the agent shows as disconnected for a few seconds.
With every agent keepalive (notify_time, 20 seconds by default), the agent sends the checksum of its merged.mg file to the manager. If the checksums differ, the manager pushes the updated file to the agent. The agent applies the new configuration immediately after receiving it. No manual restart is required, regardless of the auto_restart setting.
If the configuration is successfully applied, the agent log includes entries similar to the following. On Linux, the other agent daemons restart between the first two lines. On Windows, the log shows Received exit signal. Starting exit process. and the agent service starts again instead of the agentd reload:
2025/07/11 08:42:24 wazuh-agentd: INFO: Agent is reloading due to shared configuration changes.
2025/07/11 08:42:34 wazuh-agentd: INFO: SIGNAL [(10)-(User defined signal 1)] Received. Reload agentd.
2025/07/11 08:42:34 wazuh-agentd: INFO: Buffer agent.conf updated, enable: 1 size: 30000
2025/07/11 08:42:34 wazuh-agentd: INFO: Client buffer resized from 20000 to 30000 elements.
Use the Wazuh server API endpoint GET /agents or the agent_groups tool to check the synchronization status of the group configuration on the agent. For example, for agent ID 001:
Wazuh server API
# 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 }
agent_groups tool
# /var/ossec/bin/agent_groups -S -i 001
Agent '001' is synchronized.
Precedence
It's important to understand which configuration file takes precedence between ossec.conf and agent.conf when the central configuration is used. When this configuration is utilized, the local and the shared configuration are merged, however, the ossec.conf file is read before the shared agent.conf and the last configuration of any setting will overwrite the previous. Also, if a file path for a particular setting is set in both of the configuration files, both paths will be included in the final configuration.
For example:
Let's say we have this configuration in the ossec.conf file:
<sca>
<enabled>no</enabled>
<scan_on_start>yes</scan_on_start>
<interval>12h</interval>
<skip_nfs>yes</skip_nfs>
<policies>
<policy>system_audit_rcl.yml</policy>
<policy>system_audit_ssh.yml</policy>
<policy>system_audit_pw.yml</policy>
</policies>
</sca>
and this configuration in the agent.conf file.
<sca>
<enabled>yes</enabled>
<policies>
<policy>cis_debian_linux_rcl.yml</policy>
</policies>
</sca>
The final configuration will enable the Security Configuration Assessment module. In addition, it will add the cis_debian_linux_rcl.yml to the list of scanned policies.
In other words, the configuration located at agent.conf will overwrite the one of the ossec.conf.
Download configuration files from remote location
The Wazuh manager can download configuration files such as merged.mg and other files to be merged for selected groups.
To use this feature, we need to put a yaml file named files.yml under the directory /var/ossec/etc/shared/. When the manager starts, it will read and parse the file.
The files.yml has the following structure as shown in the following example:
groups:
my_group_1:
files:
agent.conf: https://example.com/agent.conf
rootcheck.txt: https://example.com/rootcheck.txt
merged.mg: https://example.com/merged.mg
poll: 15
my_group_2:
files:
agent.conf: https://example.com/agent.conf
poll: 200
The groups block defines the group name from which to download the files.
If the group doesn't exist, it will be created.
If a file has the name
merged.mg, only this file will be downloaded. Then it will be validated.The
polllabel indicates the download rate in seconds of the specified files.
This configuration can be changed on the fly. The manager will reload the file and parse it again so there is no need to restart the manager every time.
The information about the parsing is shown on the /var/ossec/logs/ossec.log file. For example:
Parsing is successful:
INFO: Successfully parsed of yaml file: /etc/shared/files.yml
File has been changed:
INFO: File '/etc/shared/files.yml' changed. Reloading data
Parsing failed due to bad token:
INFO: Parsing file '/etc/shared/files.yml': unexpected identifier: 'group'
Download of file failed:
ERROR: Failed to download file from url: https://example.com/merged.mg
Downloaded
merged.mgfile is corrupted or not valid:ERROR: The downloaded file '/var/download/merged.mg' is corrupted.