Skip to main content

​
Introduction

The Wazuh Dashboard provides a comprehensive interface for viewing and managing agent configurations. Configuration can be applied at the individual agent level or through group-based policies, enabling centralized management of agent settings across your infrastructure.

​
Accessing Agent Configuration

Agent configuration can be accessed through multiple paths:

​
Individual Agent Configuration

  1. Navigate to the Endpoints section
  2. Select an agent from the table
  3. Click on the “Configuration” tab
Navigation path: /agents?tab=configuration&agent={agent_id}

​
Configuration View

The configuration interface displays:
  • Current active configuration
  • Configuration source (local or group-based)
  • Module-specific settings
  • Synchronization status
Component implementation: configuration-main.js:1

​
Configuration Hierarchy

​
Configuration Sources

Agent configuration is determined by the following hierarchy (in order of precedence):
  1. Local Agent Configuration: Settings in the agent’s local ossec.conf file
  2. Group Configuration: Settings from assigned groups (most specific to least specific)
  3. Default Group: Settings from the “default” group
  4. Manager Defaults: Built-in default values

​
Group-Based Configuration

Groups enable centralized configuration management:
  • Agents can belong to multiple groups
  • Configuration from all groups is merged
  • More specific groups override less specific ones
  • Group assignments can be modified through the Dashboard

​
Managing Agent Groups

​
Viewing Group Assignments

Agent group memberships are displayed:
  • In the agents table (“Group” column)
  • In the agent details view
  • In the agent welcome screen

​
Modifying Group Assignments

​
Single Agent

  1. Select an agent from the agents table
  2. Click the “Actions” menu
  3. Select “Edit groups”
  4. Modify group assignments
  5. Save changes
Component implementation: edit-groups-modal.tsx:1

​
Multiple Agents (Bulk Operation)

  1. Select multiple agents using checkboxes
  2. Click “Edit groups” from the global actions menu
  3. Choose operation:
    • Add groups: Add groups to selected agents
    • Remove groups: Remove groups from selected agents
    • Set groups: Replace all groups with specified groups
  4. Confirm changes
Component implementation: edit-groups-modal.tsx:1 (global actions)

​
Group Assignment Permissions

Modifying group assignments requires:
  • Action: group:modify_assignments
  • Resource: group:id:*
Users without this permission will see disabled actions or authorization prompts.

​
Configuration Modules

The Wazuh agent supports configuration for various security modules:

​
Log Collector

Configures which log files and sources the agent monitors: 
<localfile>
  <location>/var/log/syslog</location>
  <log_format>syslog</log_format>
</localfile>
Settings include:
  • Log file locations
  • Log format specifications
  • Filtering rules
  • Frequency of log reading

​
File Integrity Monitoring (FIM)

Defines files and directories to monitor for changes: 
<syscheck>
  <directories check_all="yes">/etc</directories>
  <directories check_all="yes">/bin</directories>
  <frequency>43200</frequency>
</syscheck>
Settings include:
  • Monitored directories and files
  • Check frequency
  • Attributes to monitor (permissions, ownership, content)
  • File exclusions

​
Security Configuration Assessment (SCA)

Configures policy scans and compliance checks: 
<sca>
  <enabled>yes</enabled>
  <scan_on_start>yes</scan_on_start>
  <interval>12h</interval>
</sca>
Settings include:
  • Enabled policies
  • Scan frequency
  • Scan on start behavior
  • Custom policy files

​
Vulnerability Detection

Configures vulnerability scanning behavior: 
<vulnerability-detection>
  <enabled>yes</enabled>
  <interval>5m</interval>
</vulnerability-detection>
Settings include:
  • Detection enablement
  • Scan intervals
  • Package managers to monitor
  • CVE database updates

​
System Inventory (Syscollector)

Configures system inventory data collection: 
<wodle name="syscollector">
  <disabled>no</disabled>
  <interval>1h</interval>
  <scan_on_start>yes</scan_on_start>
</wodle>
Collects:
  • Hardware information (CPU, memory, serial numbers)
  • Operating system details
  • Installed packages
  • Network interfaces
  • Running processes
  • Open ports
Data is displayed in the System Inventory panel: syscollector-metrics.tsx:1

​
Rootcheck

Configures rootkit and malware detection: 
<rootcheck>
  <disabled>no</disabled>
  <frequency>43200</frequency>
</rootcheck>
Settings include:
  • Scan frequency
  • Rootkit databases
  • System audit checks

​
Command Monitoring

Configures periodic command execution and monitoring: 
<localfile>
  <log_format>command</log_format>
  <command>df -P</command>
  <frequency>360</frequency>
</localfile>
Settings include:
  • Commands to execute
  • Execution frequency
  • Output handling

​
Configuration Synchronization

​
Sync Mechanism

Configuration synchronization ensures agents receive updates:
  1. Configuration Change: Administrator modifies group or shared configuration
  2. Manager Notification: Manager marks affected agents for synchronization
  3. Sync Request: Agent requests updated configuration on next connection
  4. Download: Agent downloads and applies new configuration
  5. Restart: Agent modules reload with new settings

​
Sync Status Monitoring

Monitor configuration synchronization:
  • Synced: Agent has the latest configuration
  • Not Synced: Agent has pending configuration updates
  • Syncing: Synchronization in progress
Sync status is displayed:
  • In the agents table
  • In the agent details view
  • Through the agent sync component: agent-synced.tsx:1

​
Forcing Synchronization

To force configuration synchronization:
  1. Restart the agent service
  2. Wait for the next keep-alive interval
  3. Verify sync status in the Dashboard
Alternatively, trigger synchronization through the manager: 
/var/ossec/bin/agent_control -R -u <agent_id>

​
Configuration Validation

​
Server-Side Validation

The Wazuh manager validates configuration before distribution:
  • XML syntax validation
  • Schema validation
  • Value range checks
  • Dependency verification

​
Agent-Side Validation

Agents validate received configuration:
  • XML parsing
  • Module compatibility checks
  • Permission verification
  • Resource availability
Invalid configurations are:
  • Rejected by the agent
  • Logged in agent logs
  • Reported to the manager

​
Agent Module Version Support

​
Version Compatibility

Different agent versions support different modules and features:
  • The Dashboard checks agent version before displaying module options
  • Unsupported modules display version requirement prompts
  • Feature availability is validated: prompt-agent-feature-version.tsx:1

​
Module Support Detection

The Dashboard uses the hasAgentSupportModule() service to:
  • Detect supported modules based on agent version
  • Hide unsupported features from the interface
  • Display appropriate prompts when features are unavailable
Component implementation: prompt-agent-no-support-module.tsx:1

​
Configuration Best Practices

​
Group Organization

Organize agents into logical groups:
  • By Function: web-servers, database-servers, workstations
  • By Environment: production, staging, development
  • By Location: datacenter1, office-ny, cloud-aws
  • By Compliance: pci-dss, hipaa, gdpr

​
Configuration Management

  • Use group-based configuration for consistency
  • Avoid agent-local configuration when possible
  • Document group purposes and settings
  • Test configuration changes on a subset before wide deployment

​
Security Considerations

  • Restrict configuration modification permissions
  • Audit configuration changes
  • Use least privilege for agent permissions
  • Validate configurations before deployment

​
Performance Tuning

  • Adjust scan frequencies based on system load
  • Balance security coverage with performance impact
  • Monitor agent resource usage after configuration changes
  • Use interval settings appropriate for the environment

​
Common Configuration Scenarios

​
Web Server Configuration

Group: webservers Key settings:
  • Monitor web server logs (Apache, Nginx)
  • FIM on web root directories
  • SCA policies for web server hardening
  • Command monitoring for web service status

​
Database Server Configuration

Group: database-servers Key settings:
  • Monitor database logs (MySQL, PostgreSQL, Oracle)
  • FIM on database configuration files
  • SCA policies for database hardening
  • Rootcheck for database-specific threats

​
Workstation Configuration

Group: workstations Key settings:
  • Monitor system logs (Windows Event Log, syslog)
  • FIM on critical system directories
  • SCA policies for workstation compliance
  • Vulnerability detection for installed software

​
Cloud Instance Configuration

Group: cloud-instances Key settings:
  • Monitor cloud provider logs (CloudTrail, Azure Activity)
  • FIM on application directories
  • Syscollector for inventory tracking
  • Vulnerability detection for package updates

​
Configuration Troubleshooting

​
Configuration Not Applied

Symptoms:
  • Agent sync status: “Not Synced”
  • Expected settings not active
  • Modules not functioning as configured
Resolution:
  1. Check agent sync status
  2. Verify group assignments
  3. Review agent logs for configuration errors
  4. Manually trigger synchronization
  5. Restart agent service

​
Module Not Working

Symptoms:
  • Module appears disabled
  • No data from configured module
  • Module prompt displayed
Resolution:
  1. Verify agent version supports the module: prompt-agent-feature-version.tsx:1
  2. Check module configuration syntax
  3. Review agent logs for module errors
  4. Verify required permissions (file access, command execution)
  5. Check resource availability (disk space, memory)

​
Configuration Conflicts

Symptoms:
  • Unexpected configuration behavior
  • Settings differ from group configuration
  • Modules behaving inconsistently
Resolution:
  1. Review configuration hierarchy
  2. Check for local agent configuration overrides
  3. Verify group assignment order
  4. Examine merged configuration on agent
  5. Remove conflicting local settings

​
Permission Issues

Symptoms:
  • Cannot modify group assignments
  • Configuration changes rejected
  • “Edit groups” button disabled
Resolution:
  1. Verify user has group:modify_assignments permission
  2. Check resource-level permissions
  3. Review RBAC configuration
  4. Contact administrator for permission grants

​
Advanced Configuration

​
Labels

Assign labels to agents for better organization: 
<labels>
  <label key="environment">production</label>
  <label key="region">us-east</label>
</labels>
Labels enable:
  • Enhanced filtering in the Dashboard
  • Custom reporting and analytics
  • Integration with external systems

​
Client Buffer

Configure agent buffering for network resilience: 
<client_buffer>
  <disabled>no</disabled>
  <queue_size>5000</queue_size>
  <events_per_second>500</events_per_second>
</client_buffer>
Settings:
  • Buffer enablement
  • Queue size
  • Event rate limiting
Monitored through statistics: agent-stats.tsx:1

​
Enrollment Configuration

Configure agent enrollment behavior: 
<client>
  <enrollment>
    <enabled>yes</enabled>
    <manager_address>manager.example.com</manager_address>
    <port>1515</port>
    <agent_name>custom-name</agent_name>
    <groups>group1,group2</groups>
  </enrollment>
</client>

​
Configuration Export and Backup

​
Exporting Configurations

While not directly available in the Dashboard, configurations can be:
  • Backed up from the manager filesystem
  • Version controlled (Git)
  • Exported through API calls
  • Documented in external systems

​
Configuration Locations

On the Wazuh manager:
  • Shared Configuration: /var/ossec/etc/shared/
  • Group Configurations: /var/ossec/etc/shared/<group_name>/
  • Agent Configuration: /var/ossec/etc/shared/<group_name>/agent.conf

Build docs developers (and LLMs) love

Get started for freeTalk to us