> ## 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 Deployment Best Practices

> Learn how to deploy, configure, and manage Wazuh agents effectively across your infrastructure for comprehensive security monitoring

## Overview

Wazuh agents are lightweight security monitoring components deployed on endpoints, servers, and cloud instances. This guide covers deployment strategies, configuration best practices, and ongoing management to maximize your security monitoring coverage.

## Understanding Wazuh Agents

### What is a Wazuh Agent?

A Wazuh agent is a small program installed on monitored systems that:

* **Collects Security Data**: Logs, file changes, system configurations
* **Runs Active Response**: Executes automated responses to threats
* **Performs Integrity Monitoring**: Tracks file and registry changes
* **Detects Vulnerabilities**: Scans for security weaknesses
* **Assesses Configurations**: Validates security settings against benchmarks
* **Monitors System Inventory**: Tracks installed software and hardware

### Agent Architecture

```
Endpoint → Agent → Manager/Cluster → Indexer → Dashboard
```

* **Agent**: Collects data locally
* **Manager**: Processes and correlates events
* **Indexer**: Stores data for analysis
* **Dashboard**: Visualization and management interface

### Supported Platforms

Wazuh agents support:

> **Linux**
>
> * Ubuntu/Debian
> * RHEL/CentOS/Rocky/Alma
> * Amazon Linux
> * SUSE/OpenSUSE
> * Fedora

> **Windows**
>
> * Windows Server 2012-2025
> * Windows 10/11
> * Windows workstations

> **macOS**
>
> * macOS 10.15+
> * Intel and Apple Silicon

> **Unix**
>
> * Solaris
> * AIX
> * HP-UX

> **Containers**
>
> * Docker containers
> * Kubernetes pods

> **Cloud**
>
> * AWS instances
> * Azure VMs
> * Google Cloud VMs

## Agent Deployment Wizard

### Using the Dashboard Deployment Wizard

The easiest way to deploy agents is through the dashboard wizard.

**1. Access the Wizard**

1. Navigate to **Agents** in the main menu
2. Click **Deploy New Agent**
3. The deployment wizard opens

**2. Select Operating System**

Choose the target platform:

* Linux (RPM-based)
* Linux (DEB-based)
* Windows
* macOS

The wizard updates installation commands accordingly.

**3. Configure Server Address**

Enter your Wazuh manager information:

* **Manager Address**: IP or FQDN of your Wazuh manager
* **Manager Port**: Default is 1514 (can be customized)

> [!NOTE]
>
> Use a fully qualified domain name (FQDN) when possible for easier infrastructure changes.

**4. Assign Agent Name (Optional)**

Specify a custom agent name:

* If not specified, uses the hostname
* Use descriptive names: `web-prod-01`, `db-staging-02`
* Consider naming conventions for your organization

**5. Assign to Group (Optional)**

Add the agent to a group:

* Groups enable shared configurations
* Examples: `webservers`, `databases`, `production`
* Can be changed after deployment

**6. Copy Installation Command**

The wizard generates a command like:

**Linux (Ubuntu/Debian)**:

```bash theme={null}
curl -so wazuh-agent.deb https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-agent/wazuh-agent_5.0.0-1_amd64.deb && \
sudo WAZUH_MANAGER='10.0.1.5' WAZUH_AGENT_NAME='web-server-01' dpkg -i ./wazuh-agent.deb
```

**Linux (RHEL/CentOS)**:

```bash theme={null}
curl -so wazuh-agent.rpm https://packages.wazuh.com/4.x/yum/wazuh-agent-5.0.0-1.x86_64.rpm && \
sudo WAZUH_MANAGER='10.0.1.5' WAZUH_AGENT_NAME='web-server-01' rpm -ihv wazuh-agent.rpm
```

**Windows (PowerShell)**:

```powershell theme={null}
Invoke-WebRequest -Uri https://packages.wazuh.com/4.x/windows/wazuh-agent-5.0.0-1.msi -OutFile wazuh-agent.msi
msiexec.exe /i wazuh-agent.msi /q WAZUH_MANAGER='10.0.1.5' WAZUH_AGENT_NAME='win-server-01'
```

**7. Execute on Target System**

Run the command on the system you want to monitor:

1. SSH/RDP to the target system
2. Paste and execute the command
3. Wait for installation to complete

**8. Start the Agent**

Enable and start the agent service:

**Linux (systemd)**:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl enable wazuh-agent
sudo systemctl start wazuh-agent
```

**Windows**:

```powershell theme={null}
NET START WazuhSvc
```

**macOS**:

```bash theme={null}
sudo /Library/Ossec/bin/wazuh-control start
```

**9. Verify Agent Connection**

Return to the dashboard:

1. Navigate to **Agents > Overview**
2. Your new agent should appear within 1-2 minutes
3. Status should show **Active** (green)
4. Click the agent to view details

## Deployment at Scale

### Automated Deployment Strategies

For large environments, automate agent deployment:

> **Configuration Management Tools**
>
> Use existing infrastructure automation:
>
> **Ansible Example**:
>
> ```yaml theme={null}
> - name: Deploy Wazuh Agent
>   hosts: all
>   tasks:
>     - name: Install Wazuh agent
>       package:
>         name: wazuh-agent
>         state: present
>
>     - name: Configure manager address
>       lineinfile:
>         path: /var/ossec/etc/ossec.conf
>         regexp: '<address>.*</address>'
>         line: '    <address>{{ wazuh_manager }}</address>'
>
>     - name: Start Wazuh agent
>       service:
>         name: wazuh-agent
>         state: started
>         enabled: yes
> ```
>
> **Puppet, Chef, SaltStack**: Similar approaches available

> **Cloud Auto-Scaling Integration**
>
> Deploy agents automatically to new cloud instances:
>
> **AWS User Data Script**:
>
> ```bash theme={null}
> #!/bin/bash
> curl -so wazuh-agent.deb https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-agent/wazuh-agent_5.0.0-1_amd64.deb
> WAZUH_MANAGER='wazuh-manager.example.com' dpkg -i ./wazuh-agent.deb
> systemctl enable wazuh-agent
> systemctl start wazuh-agent
> ```
>
> **Azure VM Extensions**: Use custom script extensions
>
> **GCP Startup Scripts**: Add to instance metadata

> **Container Deployment**
>
> Deploy agents in containerized environments:
>
> **Docker Compose**:
>
> ```yaml theme={null}
> version: '3'
> services:
>   wazuh-agent:
>     image: wazuh/wazuh-agent:5.0.0
>     environment:
>       - WAZUH_MANAGER=wazuh-manager.example.com
>       - WAZUH_AGENT_NAME=docker-host-01
>     volumes:
>       - /:/rootfs:ro
>       - /var/run/docker.sock:/var/run/docker.sock
> ```
>
> **Kubernetes DaemonSet**: Deploy agent to every node

> **Golden Image Integration**
>
> Pre-install agents in base images:
>
> 1. Install agent in image template
> 2. Configure manager address
> 3. Do NOT start the service (will auto-register on first boot)
> 4. Deploy image across infrastructure
>
> **Benefit**: New systems automatically monitored from first boot

### Batch Registration

Register multiple agents programmatically:

```bash theme={null}
# Using agent_control utility
/var/ossec/bin/agent_control -a

# Using Wazuh API
curl -k -X POST "https://wazuh-manager:55000/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-server-01",
    "ip": "any"
  }'
```

## Agent Configuration

### Configuration File Location

* **Linux**: `/var/ossec/etc/ossec.conf`
* **Windows**: `C:\Program Files (x86)\ossec-agent\ossec.conf`
* **macOS**: `/Library/Ossec/etc/ossec.conf`

### Essential Configuration Sections

> **Manager Connection**
>
> Configure how agents connect to the manager:
>
> ```xml theme={null}
> <client>
>   <server>
>     <address>wazuh-manager.example.com</address>
>     <port>1514</port>
>     <protocol>tcp</protocol>
>   </server>
>   <enrollment>
>     <enabled>yes</enabled>
>     <agent_name>web-server-01</agent_name>
>   </enrollment>
> </client>
> ```
>
> **Parameters**:
>
> * `address`: Manager IP or FQDN
> * `port`: Communication port (default 1514)
> * `protocol`: tcp or udp

> **Log Collection**
>
> Specify which logs to monitor:
>
> ```xml theme={null}
> <localfile>
>   <log_format>syslog</log_format>
>   <location>/var/log/syslog</location>
> </localfile>
>
> <localfile>
>   <log_format>apache</log_format>
>   <location>/var/log/apache2/access.log</location>
> </localfile>
>
> <!-- Windows Event Log -->
> <localfile>
>   <log_format>eventchannel</log_format>
>   <location>Security</location>
> </localfile>
> ```
>
> **Supported Formats**: syslog, apache, json, snort, eventchannel, multi-line

> **File Integrity Monitoring**
>
> Monitor files and directories for changes:
>
> ```xml theme={null}
> <syscheck>
>   <disabled>no</disabled>
>   <frequency>43200</frequency> <!-- 12 hours -->
>   <scan_on_start>yes</scan_on_start>
>
>   <!-- Linux -->
>   <directories check_all="yes">/etc</directories>
>   <directories check_all="yes">/usr/bin</directories>
>   <directories check_all="yes">/usr/sbin</directories>
>
>   <!-- Windows -->
>   <directories check_all="yes">C:\Program Files</directories>
>   <windows_registry>HKEY_LOCAL_MACHINE\Software</windows_registry>
> </syscheck>
> ```
>
> **Options**: `check_all`, `check_sum`, `check_sha256`, `realtime`, `report_changes`

> **Rootkit Detection**
>
> Enable rootkit and malware detection:
>
> ```xml theme={null}
> <rootcheck>
>   <disabled>no</disabled>
>   <check_unixaudit>yes</check_unixaudit>
>   <check_files>yes</check_files>
>   <check_trojans>yes</check_trojans>
>   <check_dev>yes</check_dev>
>   <check_sys>yes</check_sys>
>   <check_pids>yes</check_pids>
>   <check_ports>yes</check_ports>
>   <check_if>yes</check_if>
> </rootcheck>
> ```

> **Security Configuration Assessment**
>
> Enable CIS and compliance scanning:
>
> ```xml theme={null}
> <sca>
>   <enabled>yes</enabled>
>   <scan_on_start>yes</scan_on_start>
>   <interval>12h</interval>
>   <skip_nfs>yes</skip_nfs>
> </sca>
> ```

> **Vulnerability Detection**
>
> Enable vulnerability scanning:
>
> ```xml theme={null}
> <vulnerability-detector>
>   <enabled>yes</enabled>
>   <index-status>yes</index-status>
>   <feed-update-interval>60m</feed-update-interval>
> </vulnerability-detector>
> ```

### Centralized Configuration Management

Manage configurations from the dashboard:

**1. Access Agent Configuration**

1. Navigate to **Server Management > Settings**
2. Select **Agent Configuration**
3. Choose a group or create new one

**2. Edit Group Configuration**

Modify settings for all agents in the group:

* Log collection rules
* File integrity monitoring paths
* Security configuration policies
* Active response rules

**3. Assign Agents to Groups**

1. Go to **Agents > Overview**
2. Select agents
3. Click **Manage Groups**
4. Assign to appropriate group

**4. Verify Configuration**

Changes are pushed automatically:

* Agents receive updates within minutes
* No agent restart required for most changes
* View effective configuration in agent details

## Agent Groups and Organization

### Best Practices for Group Structure

> **By Function**
>
> Group by system role:
>
> * `webservers`
> * `databases`
> * `application-servers`
> * `file-servers`

> **By Environment**
>
> Group by deployment stage:
>
> * `production`
> * `staging`
> * `development`
> * `testing`

> **By Location**
>
> Group by geography:
>
> * `us-east`
> * `eu-west`
> * `asia-pacific`

> **By Compliance**
>
> Group by regulatory requirements:
>
> * `pci-environment`
> * `hipaa-systems`
> * `gdpr-processing`

### Managing Groups

> **Create a New Group**
>
> 1. Navigate to **Server Management > Settings**
> 2. Go to **Agent Configuration**
> 3. Click **Add New Group**
> 4. Name the group descriptively
> 5. Configure group-specific settings

> **Assign Agents to Groups**
>
> **Via Dashboard**:
>
> 1. Agents > Overview
> 2. Select agents (checkbox)
> 3. Actions > Manage Groups
> 4. Select target group
>
> **Via Command Line**:
>
> ```bash theme={null}
> /var/ossec/bin/agent_groups -a -i 001 -g webservers
> ```
>
> **Via API**:
>
> ```bash theme={null}
> curl -k -X PUT "https://manager:55000/agents/001/group/webservers" \
>   -H "Authorization: Bearer $TOKEN"
> ```

> **Multi-Group Assignment**
>
> Agents can belong to multiple groups:
>
> ```bash theme={null}
> /var/ossec/bin/agent_groups -a -i 001 -g webservers,production,us-east
> ```
>
> **Configuration Precedence**:
>
> 1. Agent-specific configuration (highest)
> 2. Group configuration (in order assigned)
> 3. Default configuration (lowest)

## Monitoring Agent Health

### Agent Status Indicators

In the **Agents > Overview** dashboard:

> **Active (Green)**
>
> Agent is connected and reporting normally.
>
> * Sending events regularly
> * Responsive to manager requests
> * All modules functioning
>
> **Action**: No action needed

> **Disconnected (Red)**
>
> Agent is not communicating with manager.
>
> **Common Causes**:
>
> * System powered off
> * Network connectivity issues
> * Agent service stopped
> * Firewall blocking communication
>
> **Troubleshooting**:
>
> 1. Check if system is online
> 2. Verify agent service is running
> 3. Test network connectivity to manager
> 4. Review firewall rules
> 5. Check agent logs

> **Never Connected (Gray)**
>
> Agent was registered but never established connection.
>
> **Common Causes**:
>
> * Agent not started after installation
> * Incorrect manager address
> * Network configuration issues
> * Certificate/key problems
>
> **Troubleshooting**:
>
> 1. Verify agent service is running
> 2. Check manager address in ossec.conf
> 3. Ensure port 1514 is reachable
> 4. Review agent logs for errors

> **Pending (Orange)**
>
> Agent awaiting approval or configuration.
>
> **Action**: Review and approve agent registration

### Agent Details View

Click on an agent to view:

* **General Information**: OS, version, IP, registration date
* **Configuration**: Active modules and settings
* **Events**: Recent security events from this agent
* **Inventory**: Installed packages and hardware
* **Vulnerabilities**: Detected security issues
* **SCA Results**: Configuration compliance status
* **File Integrity**: Recent file changes

### Agent Logs

Review agent logs for troubleshooting:

**Linux**:

```bash theme={null}
tail -f /var/ossec/logs/ossec.log
```

**Windows**:

```
C:\Program Files (x86)\ossec-agent\ossec.log
```

**Common Log Messages**:

* `Connected to the server`: Successful connection
* `Unable to connect`: Network or configuration issue
* `Invalid server address`: Check manager address
* `ERROR`: Requires investigation

## Performance Optimization

### Resource Usage Considerations

> **CPU Usage**
>
> Typical agent CPU usage: \< 1-2%
>
> **High CPU Scenarios**:
>
> * Initial file integrity scan
> * Vulnerability scan execution
> * Processing large log volumes
>
> **Optimization**:
>
> * Adjust scan schedules to off-peak hours
> * Limit monitored directories
> * Increase scan intervals

> **Memory Usage**
>
> Typical agent memory: 50-200 MB
>
> **Factors Affecting Memory**:
>
> * Number of monitored files
> * Active modules enabled
> * Log processing volume
>
> **Optimization**:
>
> * Disable unused modules
> * Use log filters to reduce processing

> **Network Bandwidth**
>
> Typical bandwidth: 10-100 KB/s average
>
> **High Bandwidth Scenarios**:
>
> * High log volume systems
> * Frequent file changes
> * Large file change reports
>
> **Optimization**:
>
> * Use event compression (enabled by default)
> * Filter unnecessary logs
> * Adjust file integrity reporting

> **Disk I/O**
>
> Impact from:
>
> * Log file reading
> * File integrity scanning
> * Local event queuing
>
> **Optimization**:
>
> * Exclude high-churn directories from FIM
> * Use realtime monitoring selectively
> * Adjust scan schedules

### Configuration Tuning

**Reduce File Integrity Scan Frequency**:

```xml theme={null}
<syscheck>
  <frequency>86400</frequency> <!-- Daily instead of 12h -->
</syscheck>
```

**Exclude High-Activity Directories**:

```xml theme={null}
<syscheck>
  <ignore>/var/cache</ignore>
  <ignore>/tmp</ignore>
  <ignore type="regex">\.log$</ignore>
</syscheck>
```

**Filter Logs**:

```xml theme={null}
<localfile>
  <log_format>syslog</log_format>
  <location>/var/log/syslog</location>
  <ignore>DEBUG</ignore>
  <ignore>INFO</ignore>
</localfile>
```

## Troubleshooting Common Issues

### Agent Won't Connect

**1. Verify Service Status**

Check if agent is running:

**Linux**:

```bash theme={null}
systemctl status wazuh-agent
```

**Windows**:

```powershell theme={null}
Get-Service WazuhSvc
```

**2. Check Configuration**

Verify manager address:

```bash theme={null}
grep -A 3 '<server>' /var/ossec/etc/ossec.conf
```

Ensure address is correct and reachable.

**3. Test Network Connectivity**

```bash theme={null}
telnet wazuh-manager.example.com 1514
# or
nc -zv wazuh-manager.example.com 1514
```

Should connect successfully.

**4. Review Firewall Rules**

Ensure outbound TCP/UDP 1514 is allowed from agent.
Ensure inbound TCP/UDP 1514 is allowed to manager.

**5. Check Agent Logs**

Look for specific error messages:

```bash theme={null}
tail -100 /var/ossec/logs/ossec.log | grep ERROR
```

### Agent Showing as Disconnected

**Possible Causes**:

1. **Agent stopped**: Restart the service
2. **Network issue**: Check connectivity
3. **High load**: Agent can't process events fast enough
4. **Time sync**: Ensure agent and manager clocks are synchronized
5. **Certificate issue**: Regenerate agent keys if necessary

### Events Not Appearing in Dashboard

**1. Verify Agent is Active**

Check agent status in Agents > Overview.

**2. Check Index Patterns**

Ensure `wazuh-events-*` index pattern exists and has recent data.

**3. Verify Time Range**

Ensure dashboard time picker includes the event timeframe.

**4. Check Agent Configuration**

Verify logs are configured for collection in ossec.conf.

**5. Review Manager Logs**

Check if manager is receiving and processing events:

```bash theme={null}
tail -f /var/ossec/logs/ossec.log | grep "agent-name"
```

## Security Best Practices

> **Secure Agent-Manager Communication**
>
> * Use encrypted communication (default)
> * Implement network segmentation
> * Restrict manager access with firewalls
> * Rotate agent keys periodically
> * Use DNS names for flexibility

> **Principle of Least Privilege**
>
> * Agent runs with minimal required privileges
> * Use dedicated service account for agent
> * Limit configuration file access
> * Restrict active response capabilities

> **Regular Maintenance**
>
> * Keep agents updated to latest version
> * Review and update configurations
> * Remove decommissioned agents
> * Audit agent group memberships
> * Monitor agent health regularly

> **Change Management**
>
> * Test configuration changes in non-production
> * Document agent deployment standards
> * Version control group configurations
> * Implement rollback procedures

## Next Steps

Now that you understand agent deployment:

* Use agents for [Threat Analysis](/guides/threat-analysis) workflows
* Monitor [Compliance](/guides/compliance-monitoring) across your infrastructure
* Review [Getting Started](/guides/getting-started) for dashboard features

> [!TIP]
>
> Start with a small pilot deployment to test configurations and workflows before rolling out to your entire infrastructure.


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