Agent Deployment

​

Introduction

​

Accessing the Deployment Wizard

1. Navigate to the Endpoints section in the Wazuh Dashboard
2. Click the “Deploy new agent” button
3. The deployment wizard interface will open

​

Deployment Prerequisites

​

Permissions

• Action: agent:create
• Resource: *:*:*

​

Manager Configuration

• Remote Configuration: The manager must have remote enrollment configured
• Connection Protocol: TCP or UDP protocol must be enabled
• Server Address: A resolvable DNS name or IP address must be configured
• Authentication: Optional password authentication may be configured

​

Deployment Wizard Steps

​

Step 1: Select Operating System

​

Linux Options

• DEB amd64: Debian-based distributions (Ubuntu, Debian) on x86_64
• DEB aarch64: Debian-based distributions on ARM64
• RPM amd64: Red Hat-based distributions (RHEL, CentOS, Fedora) on x86_64
• RPM aarch64: Red Hat-based distributions on ARM64

​

Windows Options

• MSI 32/64 bits: Windows systems (supports both 32-bit and 64-bit)

​

macOS Options

• Intel: macOS systems running on Intel processors
• Apple Silicon: macOS systems running on Apple M1/M2/M3 processors

​

Step 2: Configure Server Address

• Default DNS Address: Pre-populated from the manager configuration (enrollment.dns)
• Custom Address: Enter a custom IP address or fully qualified domain name (FQDN)

• A valid hostname or FQDN
• A valid IPv4 address
• A valid IPv6 address

​

Step 3: Configure Agent Name (Optional)

• Default Behavior: If no name is provided, the agent will use the system hostname
• Custom Name: Enter a descriptive name for easy identification

• Names do not contain invalid characters
• Names are unique within the manager
• Names follow Wazuh naming conventions

​

Step 4: Assign Agent Groups (Optional)

• Available Groups: Displayed from the manager’s configured groups
• Default Group: Agents are automatically assigned to the “default” group if no groups are specified
• Multiple Groups: Agents can belong to multiple groups simultaneously

• Centralized configuration management
• Policy-based agent organization
• Bulk operations on groups of agents

​

Step 5: Optional Parameters

​

Protocol Selection

• TCP: Default and recommended protocol for agent-manager communication
• UDP: Alternative protocol, used when TCP is not available

​

Authentication Password

• The deployment wizard will automatically include the password in installation commands
• Password is required for agent registration when authentication is enabled
• Passwords are properly escaped for each operating system’s command interpreter

• Linux: scapeSpecialCharsForLinux()
• macOS: scapeSpecialCharsForMacOS()
• Windows: scapeSpecialCharsForWindows()

​

Generated Installation Commands

​

Linux (Debian/Ubuntu) - DEB amd64

# Download the Wazuh agent package
wget https://packages.wazuh.com/4.x/apt/pool/main/w/wazuh-agent/wazuh-agent_4.x.x-1_amd64.deb

# Install the agent with configuration parameters
WAZUH_MANAGER='manager.example.com' WAZUH_AGENT_NAME='web-server-01' \
WAZUH_AGENT_GROUP='webservers' dpkg -i wazuh-agent_4.x.x-1_amd64.deb

# Start the Wazuh agent service
systemctl daemon-reload
systemctl enable wazuh-agent
systemctl start wazuh-agent

​

Linux (RHEL/CentOS) - RPM amd64

# Download the Wazuh agent package
curl -o wazuh-agent-4.x.x-1.x86_64.rpm \
https://packages.wazuh.com/4.x/yum/wazuh-agent-4.x.x-1.x86_64.rpm

# Install the agent with configuration parameters
WAZUH_MANAGER='manager.example.com' WAZUH_AGENT_NAME='web-server-01' \
WAZUH_AGENT_GROUP='webservers' rpm -i wazuh-agent-4.x.x-1.x86_64.rpm

# Start the Wazuh agent service
systemctl daemon-reload
systemctl enable wazuh-agent
systemctl start wazuh-agent

​

Windows - MSI

# Download and install the Wazuh agent
Invoke-WebRequest -Uri https://packages.wazuh.com/4.x/windows/wazuh-agent-4.x.x-1.msi `
  -OutFile wazuh-agent.msi

# Install with parameters
msiexec.exe /i wazuh-agent.msi /q WAZUH_MANAGER='manager.example.com' `
  WAZUH_AGENT_NAME='web-server-01' WAZUH_AGENT_GROUP='webservers'

# Start the Wazuh agent service
NET START WazuhSvc

​

macOS - Intel

# Download the Wazuh agent package
curl -o wazuh-agent.pkg \
https://packages.wazuh.com/4.x/macos/wazuh-agent-4.x.x-1.intel64.pkg

# Install the agent
launchctl setenv WAZUH_MANAGER 'manager.example.com'
launchctl setenv WAZUH_AGENT_NAME 'web-server-01'
launchctl setenv WAZUH_AGENT_GROUP 'webservers'
installer -pkg wazuh-agent.pkg -target /

# Start the Wazuh agent service
/Library/Ossec/bin/wazuh-control start

​

macOS - Apple Silicon

# Download the Wazuh agent package
curl -o wazuh-agent.pkg \
https://packages.wazuh.com/4.x/macos/wazuh-agent-4.x.x-1.arm64.pkg

# Install the agent
launchctl setenv WAZUH_MANAGER 'manager.example.com'
launchctl setenv WAZUH_AGENT_NAME 'web-server-01'
launchctl setenv WAZUH_AGENT_GROUP 'webservers'
installer -pkg wazuh-agent.pkg -target /

# Start the Wazuh agent service
/Library/Ossec/bin/wazuh-control start

​

Installation Parameters

​

Required Parameters

• WAZUH_MANAGER: IP address or hostname of the Wazuh manager

​

Optional Parameters

• WAZUH_AGENT_NAME: Custom name for the agent
• WAZUH_AGENT_GROUP: Comma-separated list of groups
• WAZUH_REGISTRATION_PASSWORD: Password for agent authentication (if enabled)
• WAZUH_PROTOCOL: Communication protocol (TCP or UDP)

​

Command Output Display

• Copy to Clipboard: One-click command copying
• Command Breakdown: Step-by-step explanation of each command
• OS-Specific Warnings: Platform-specific notes and considerations
• Package URLs: Direct links to agent packages

​

Deployment Verification

​

Check Agent Status

sudo /var/ossec/bin/agent_control -l

Get-Service WazuhSvc

​

Verify Manager Connection

1. Return to the Endpoints section in the Wazuh Dashboard
2. Refresh the agent table
3. The newly deployed agent should appear with status:
   • “Pending” (initial registration)
   • “Active” (successfully connected)

​

Common Status Indicators

• Active: Agent is connected and reporting data
• Pending: Agent is registered but awaiting initial connection
• Never Connected: Agent registered but has not connected (check network/firewall)

​

Troubleshooting Deployment

​

Agent Not Appearing

• Firewall blocking communication (default ports: 1514, 1515)
• Incorrect manager address
• Authentication password mismatch
• Network connectivity issues

1. Verify network connectivity to the manager
2. Check firewall rules on both agent and manager
3. Review agent logs:
   • Linux/macOS: /var/ossec/logs/ossec.log
   • Windows: C:\Program Files (x86)\ossec-agent\ossec.log

​

Agent Status “Never Connected”

1. Verify the WAZUH_MANAGER parameter is correct
2. Check agent configuration: /var/ossec/etc/ossec.conf
3. Verify manager ports are accessible:
   telnet manager.example.com 1514
   
4. Restart the agent service
5. Review agent and manager logs

​

Authentication Failures

• Agent appears as “Pending” indefinitely
• Authentication errors in agent logs

1. Verify WAZUH_REGISTRATION_PASSWORD matches manager configuration
2. Check manager’s authd.pass setting
3. Re-register the agent with correct password

​

Protocol Mismatch

• Agent connects intermittently
• Connection drops frequently

1. Verify protocol settings match manager configuration
2. Check UDP/TCP availability in manager’s remote configuration
3. Use TCP protocol when possible (more reliable)

​

Bulk Deployment

​

Using Configuration Management Tools

• Ansible playbooks
• Puppet manifests
• Chef recipes
• SaltStack states

​

Script-Based Deployment

#!/bin/bash
MANAGER="manager.example.com"
GROUP="production"

# Generate unique agent name from hostname
AGENT_NAME=$(hostname -f)

# Run installation
WAZUH_MANAGER="$MANAGER" WAZUH_AGENT_NAME="$AGENT_NAME" \
WAZUH_AGENT_GROUP="$GROUP" dpkg -i wazuh-agent.deb

​

Best Practices

​

Planning

• Define group structure before deployment
• Use consistent naming conventions for agents
• Document server addresses and configuration parameters
• Test deployment on a single system before bulk rollout

​

Security

• Use password authentication in production environments
• Secure the deployment commands (they may contain passwords)
• Use HTTPS/secure channels for package downloads
• Verify package checksums when possible
• Rotate authentication passwords regularly

​

Network

• Ensure firewall rules allow agent-manager communication
• Use TCP protocol for reliability
• Configure network load balancing for high-availability setups
• Test connectivity before deployment

​

Maintenance

• Keep package repositories up to date
• Monitor agent registration success rates
• Document deployment procedures for team members
• Regularly review and update group assignments

​

Related Documentation

• Agent Management Overview
• Agent Monitoring
• Agent Configuration
• System Inventory