> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wazuh/wazuh-dashboard-plugins/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Configuration

> Configure Wazuh agents through the Dashboard, including group-based configuration, module settings, and policy management.

## 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:

```xml theme={null}
<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:

```xml theme={null}
<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:

```xml theme={null}
<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:

```xml theme={null}
<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:

```xml theme={null}
<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:

```xml theme={null}
<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:

```xml theme={null}
<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:

```bash theme={null}
/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:

```xml theme={null}
<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:

```xml theme={null}
<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:

```xml theme={null}
<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`

## Related Documentation

* [Agent Management Overview](/agents/overview)
* [Agent Deployment](/agents/deployment)
* [Agent Monitoring](/agents/monitoring)
* [System Inventory](/agents/system-inventory)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.