Skip to main content

​
Introduction

The Wazuh Dashboard provides a comprehensive agent deployment wizard that guides administrators through the process of registering and deploying agents on various operating systems. The deployment interface generates platform-specific installation commands with all necessary parameters preconfigured.

​
Accessing the Deployment Wizard

The agent deployment wizard is accessed from the Endpoints section:
  1. Navigate to the Endpoints section in the Wazuh Dashboard
  2. Click the “Deploy new agent” button
  3. The deployment wizard interface will open
Navigation path: /agents-preview → “Deploy new agent” Component implementation: register-agent.tsx:1

​
Deployment Prerequisites

​
Permissions

Deploying new agents requires the following authorization:
  • Action: agent:create
  • Resource: *:*:*
Users without this permission will see an authorization prompt and will be unable to access the deployment wizard.

​
Manager Configuration

Before deploying agents, ensure the following manager configurations are in place:
  • 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

The wizard supports the following operating system and architecture combinations:

​
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
Each operating system option displays the appropriate package download URL and installation commands. OS definitions: os-commands-definitions.ts:1

​
Step 2: Configure Server Address

Specify the Wazuh manager’s server address that agents will use to connect:
  • Default DNS Address: Pre-populated from the manager configuration (enrollment.dns)
  • Custom Address: Enter a custom IP address or fully qualified domain name (FQDN)
The server address must be:
  • A valid hostname or FQDN
  • A valid IPv4 address
  • A valid IPv6 address
Validation is performed using: SettingsValidator.serverAddressHostnameFQDNIPv4IPv6

​
Step 3: Configure Agent Name (Optional)

Specify a custom name for the agent:
  • Default Behavior: If no name is provided, the agent will use the system hostname
  • Custom Name: Enter a descriptive name for easy identification
Agent name validation ensures:
  • Names do not contain invalid characters
  • Names are unique within the manager
  • Names follow Wazuh naming conventions
Validation implementation: validations.ts (validateAgentName)

​
Step 4: Assign Agent Groups (Optional)

Assign the agent to one or more groups:
  • 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
Groups enable:
  • Centralized configuration management
  • Policy-based agent organization
  • Bulk operations on groups of agents
Groups are retrieved using: getGroups() service function Component implementation: group-input.tsx:1

​
Step 5: Optional Parameters

Configure additional deployment parameters:

​
Protocol Selection

  • TCP: Default and recommended protocol for agent-manager communication
  • UDP: Alternative protocol, used when TCP is not available
Protocol availability is determined by the manager’s remote configuration.

​
Authentication Password

If the manager has password authentication enabled (authd.pass configured):
  • 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
Password handling:
  • 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

The deployment wizard supports the following environment variables:

​
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

The deployment wizard provides:
  • 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
Component implementation: command-output.tsx:1

​
Deployment Verification

After running the installation commands on the target system:

​
Check Agent Status

Linux/macOS: 
sudo /var/ossec/bin/agent_control -l
Windows (PowerShell): 
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

Possible causes:
  • Firewall blocking communication (default ports: 1514, 1515)
  • Incorrect manager address
  • Authentication password mismatch
  • Network connectivity issues
Resolution:
  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”

Component prompt: prompt-agent-never-connected.tsx:1 Resolution steps:
  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

Symptoms:
  • Agent appears as “Pending” indefinitely
  • Authentication errors in agent logs
Resolution:
  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

Symptoms:
  • Agent connects intermittently
  • Connection drops frequently
Resolution:
  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)
Remote configuration retrieval: getRemoteConfiguration() service

​
Bulk Deployment

For deploying multiple agents:

​
Using Configuration Management Tools

The generated commands can be integrated with:
  • Ansible playbooks
  • Puppet manifests
  • Chef recipes
  • SaltStack states

​
Script-Based Deployment

Create deployment scripts using the wizard-generated commands as templates: 
#!/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