Agent Deployment Best Practices - Wazuh Dashboard Plugins

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.

Access the Wizard

Navigate to Agents in the main menu
Click Deploy New Agent
The deployment wizard opens

Select Operating System

Choose the target platform:

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

The wizard updates installation commands accordingly.

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)

Use a fully qualified domain name (FQDN) when possible for easier infrastructure changes.

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

Assign to Group (Optional)

Add the agent to a group:

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

Copy Installation Command

The wizard generates a command like:Linux (Ubuntu/Debian):

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

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

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'

Execute on Target System

Run the command on the system you want to monitor:

SSH/RDP to the target system
Paste and execute the command
Wait for installation to complete

Start the Agent

Enable and start the agent service:Linux (systemd):

sudo systemctl daemon-reload
sudo systemctl enable wazuh-agent
sudo systemctl start wazuh-agent

Windows:

NET START WazuhSvc

macOS:

sudo /Library/Ossec/bin/wazuh-control start

Verify Agent Connection

Return to the dashboard:

Navigate to Agents > Overview
Your new agent should appear within 1-2 minutes
Status should show Active (green)
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:

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

#!/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 extensionsGCP Startup Scripts: Add to instance metadata

Container Deployment

Deploy agents in containerized environments:Docker Compose:

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:

Install agent in image template
Configure manager address
Do NOT start the service (will auto-register on first boot)
Deploy image across infrastructure

Benefit: New systems automatically monitored from first boot

Batch Registration

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

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

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

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

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

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

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

Access Agent Configuration

Navigate to Server Management > Settings
Select Agent Configuration
Choose a group or create new one

Edit Group Configuration

Modify settings for all agents in the group:

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

Assign Agents to Groups

Go to Agents > Overview
Select agents
Click Manage Groups
Assign to appropriate group

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

Navigate to Server Management > Settings
Go to Agent Configuration
Click Add New Group
Name the group descriptively
Configure group-specific settings

Assign Agents to Groups

Via Dashboard:

Agents > Overview
Select agents (checkbox)
Actions > Manage Groups
Select target group

Via Command Line:

/var/ossec/bin/agent_groups -a -i 001 -g webservers

Via API:

curl -k -X PUT "https://manager:55000/agents/001/group/webservers" \
  -H "Authorization: Bearer $TOKEN"

Multi-Group Assignment

Agents can belong to multiple groups:

/var/ossec/bin/agent_groups -a -i 001 -g webservers,production,us-east

Configuration Precedence:

Agent-specific configuration (highest)
Group configuration (in order assigned)
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:

Check if system is online
Verify agent service is running
Test network connectivity to manager
Review firewall rules
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:

Verify agent service is running
Check manager address in ossec.conf
Ensure port 1514 is reachable
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:

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 MBFactors 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 averageHigh 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:

<syscheck>
  <frequency>86400</frequency> <!-- Daily instead of 12h -->
</syscheck>

Exclude High-Activity Directories:

<syscheck>
  <ignore>/var/cache</ignore>
  <ignore>/tmp</ignore>
  <ignore type="regex">\.log$</ignore>
</syscheck>

Filter Logs:

<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

Verify Service Status

Check if agent is running:Linux:

systemctl status wazuh-agent

Windows:

Get-Service WazuhSvc

Check Configuration

Verify manager address:

grep -A 3 '<server>' /var/ossec/etc/ossec.conf

Ensure address is correct and reachable.

Test Network Connectivity

telnet wazuh-manager.example.com 1514
# or
nc -zv wazuh-manager.example.com 1514

Should connect successfully.

Review Firewall Rules

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

Check Agent Logs

Look for specific error messages:

tail -100 /var/ossec/logs/ossec.log | grep ERROR

Agent Showing as Disconnected

Possible Causes:

Agent stopped: Restart the service
Network issue: Check connectivity
High load: Agent can’t process events fast enough
Time sync: Ensure agent and manager clocks are synchronized
Certificate issue: Regenerate agent keys if necessary

Events Not Appearing in Dashboard

Verify Agent is Active

Check agent status in Agents > Overview.

Check Index Patterns

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

Verify Time Range

Ensure dashboard time picker includes the event timeframe.

Check Agent Configuration

Verify logs are configured for collection in ossec.conf.

Review Manager Logs

Check if manager is receiving and processing events:

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 workflows
Monitor Compliance across your infrastructure
Review Getting Started for dashboard features

Start with a small pilot deployment to test configurations and workflows before rolling out to your entire infrastructure.

User Guides

Operations

Advanced

​Overview

​Understanding Wazuh Agents

​What is a Wazuh Agent?

​Agent Architecture

​Supported Platforms

Linux

Windows

macOS

Unix

Containers

Cloud

​Agent Deployment Wizard

​Using the Dashboard Deployment Wizard

​Deployment at Scale

​Automated Deployment Strategies

​Batch Registration

​Agent Configuration

​Configuration File Location

​Essential Configuration Sections

​Centralized Configuration Management

​Agent Groups and Organization

​Best Practices for Group Structure

By Function

By Environment

By Location

By Compliance

​Managing Groups

​Monitoring Agent Health

​Agent Status Indicators

​Agent Details View

​Agent Logs

​Performance Optimization

​Resource Usage Considerations

​Configuration Tuning

​Troubleshooting Common Issues

​Agent Won’t Connect

​Agent Showing as Disconnected

​Events Not Appearing in Dashboard

​Security Best Practices

​Next Steps

Build docs developers (and LLMs) love

Overview

Understanding Wazuh Agents

What is a Wazuh Agent?

Agent Architecture

Supported Platforms

Agent Deployment Wizard

Using the Dashboard Deployment Wizard

Deployment at Scale

Automated Deployment Strategies

Batch Registration

Agent Configuration

Configuration File Location

Essential Configuration Sections

Centralized Configuration Management

Agent Groups and Organization

Best Practices for Group Structure

Managing Groups

Monitoring Agent Health

Agent Status Indicators

Agent Details View

Agent Logs

Performance Optimization

Resource Usage Considerations

Configuration Tuning

Troubleshooting Common Issues

Agent Won’t Connect

Agent Showing as Disconnected

Events Not Appearing in Dashboard

Security Best Practices

Next Steps