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

> Learn how to deploy Wazuh agents across different operating systems using the Dashboard's deployment wizard.

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

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

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

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

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

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

```bash theme={null}
sudo /var/ossec/bin/agent_control -l
```

**Windows (PowerShell):**

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

```bash theme={null}
#!/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](/agents/overview)
* [Agent Monitoring](/agents/monitoring)
* [Agent Configuration](/agents/configuration)
* [System Inventory](/agents/system-inventory)


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