# Wazuh with Puppet - Configuration Management

> Deploy Wazuh 4.14 with Puppet - wazuh-puppet module installation, class parameters, agent rollout, Hiera integration, and troubleshooting common issues

Source: https://opennix.org/en/docs/wazuh/deployment/wazuh-puppet-deployment/


The wazuh-puppet module provides classes for installing and configuring all Wazuh 4.14 components through Puppet. It covers the manager, agent, indexer, and dashboard, with full Hiera support for centralized parameter management.

## Prerequisites

### Puppet infrastructure

- Puppet Server 7.x or 8.x
- Puppet Agent 7.x or 8.x on target nodes
- PuppetDB (recommended for exported resource management)
- r10k or Code Manager for module management

### Target nodes

- A 64-bit OS from the [supported list](/docs/wazuh/installation/)
- Internet access for downloading packages (or an [offline repository](/docs/wazuh/deployment/wazuh-offline-installation/))
- Open ports: 1514, 1515, 9200, 443, 55000

## Module installation

### From Puppet Forge

```bash
puppet module install wazuh-wazuh
```

### Via Puppetfile (r10k)

Add to your `Puppetfile`:

```ruby
mod 'wazuh-wazuh',
  :git => 'https://github.com/wazuh/wazuh-puppet.git',
  :tag => 'v4.14.3'
```

Deploy the environment:

```bash
r10k deploy environment production
```

### Module dependencies

The wazuh-puppet module depends on the following modules:

| Module | Purpose |
|---|---|
| `puppetlabs-stdlib` | Standard functions and types |
| `puppetlabs-apt` | APT repository management (Debian/Ubuntu) |
| `puppetlabs-concat` | Configuration file assembly |
| `puppetlabs-firewall` | Firewall rule management (optional) |

Install dependencies:

```bash
puppet module install puppetlabs-stdlib
puppet module install puppetlabs-apt
puppet module install puppetlabs-concat
```

## Module classes

### Class overview

| Class | Purpose |
|---|---|
| `wazuh::manager` | Install and configure the Wazuh Manager |
| `wazuh::agent` | Install and configure the Wazuh Agent |
| `wazuh::indexer` | Install and configure the Wazuh Indexer |
| `wazuh::dashboard` | Install and configure the Wazuh Dashboard |
| `wazuh::repo` | Configure the Wazuh package repository |

## Manager deployment

### Basic configuration

```puppet
class { 'wazuh::manager':
  ossec_manager_config => {
    'global' => {
      'jsonout_output' => 'yes',
      'logall'         => 'no',
    },
    'cluster' => {
      'disabled'  => 'yes',
      'name'      => 'wazuh-cluster',
      'node_name' => 'manager-master',
      'node_type' => 'master',
      'key'       => 'MyClusterSecretKey',
    },
    'api' => {
      'bind_addr' => '0.0.0.0',
      'port'      => '55000',
    },
  },
  ossec_manager_authd => {
    'enabled'      => 'yes',
    'use_password' => 'no',
    'purge'        => 'no',
  },
}
```

### Manager cluster configuration

For the master node:

```puppet
node 'manager-master.example.com' {
  class { 'wazuh::manager':
    ossec_manager_config => {
      'cluster' => {
        'disabled'  => 'no',
        'name'      => 'wazuh-cluster',
        'node_name' => 'manager-master',
        'node_type' => 'master',
        'key'       => 'MyClusterSecretKey',
        'port'      => '1516',
        'bind_addr' => '0.0.0.0',
        'nodes'     => ['manager-master.example.com'],
      },
    },
  }
}
```

For a worker node:

```puppet
node 'manager-worker.example.com' {
  class { 'wazuh::manager':
    ossec_manager_config => {
      'cluster' => {
        'disabled'  => 'no',
        'name'      => 'wazuh-cluster',
        'node_name' => 'manager-worker',
        'node_type' => 'worker',
        'key'       => 'MyClusterSecretKey',
        'port'      => '1516',
        'bind_addr' => '0.0.0.0',
        'nodes'     => ['manager-master.example.com'],
      },
    },
  }
}
```

## Agent deployment

### Basic deployment

```puppet
class { 'wazuh::agent':
  wazuh_manager_address => '192.168.1.20',
  agent_name            => $facts['hostname'],
  agent_group           => 'default',
  manage_repo           => true,
}
```

### Deployment with password-based enrollment

```puppet
class { 'wazuh::agent':
  wazuh_manager_address       => '192.168.1.20',
  agent_name                  => $facts['hostname'],
  agent_group                 => 'linux-servers',
  ossec_agent_enrollment      => {
    'enabled'         => 'yes',
    'manager_address' => '192.168.1.20',
    'auth_password'   => 'AgentEnrollmentPassword',
  },
}
```

### Bulk deployment via site.pp

```puppet
node /^web-server-\d+\.example\.com$/ {
  class { 'wazuh::agent':
    wazuh_manager_address => '192.168.1.20',
    agent_group           => 'web-servers',
  }
}

node /^db-server-\d+\.example\.com$/ {
  class { 'wazuh::agent':
    wazuh_manager_address => '192.168.1.20',
    agent_group           => 'database-servers',
  }
}
```

## Class parameters

### wazuh::manager parameters

| Parameter | Type | Description | Default |
|---|---|---|---|
| `ossec_manager_config` | Hash | Core ossec.conf configuration | See module |
| `ossec_manager_authd` | Hash | Authd settings | `{'enabled' => 'yes'}` |
| `manage_repo` | Boolean | Manage the package repository | `true` |
| `manage_service` | Boolean | Manage the systemd service | `true` |
| `service_ensure` | String | Service state | `running` |
| `service_enable` | Boolean | Enable service at boot | `true` |
| `manage_firewall` | Boolean | Manage firewall rules | `false` |

### wazuh::agent parameters

| Parameter | Type | Description | Default |
|---|---|---|---|
| `wazuh_manager_address` | String | Manager address | - |
| `agent_name` | String | Agent name | `$facts['hostname']` |
| `agent_group` | String | Agent group | `default` |
| `manage_repo` | Boolean | Manage the repository | `true` |
| `manage_service` | Boolean | Manage the service | `true` |
| `ossec_agent_enrollment` | Hash | Auto-enrollment settings | `{}` |
| `ossec_agent_config` | Hash | Agent ossec.conf configuration | See module |

### wazuh::indexer parameters

| Parameter | Type | Description | Default |
|---|---|---|---|
| `indexer_cluster_name` | String | Cluster name | `wazuh-cluster` |
| `indexer_node_name` | String | Node name | `wazuh-indexer-1` |
| `indexer_node_master` | Boolean | Master-eligible role | `true` |
| `indexer_node_data` | Boolean | Data role | `true` |
| `indexer_network_host` | String | Bind address | `0.0.0.0` |
| `indexer_admin_password` | String | Admin password | `SecretPassword` |
| `indexer_jvm_xms` | String | JVM Heap min | `1g` |
| `indexer_jvm_xmx` | String | JVM Heap max | `1g` |

## Hiera integration

### Hiera data structure

File `data/common.yaml`:

```yaml
wazuh::manager::ossec_manager_config:
  global:
    jsonout_output: 'yes'
    logall: 'no'
  cluster:
    disabled: 'yes'
  api:
    bind_addr: '0.0.0.0'
    port: '55000'

wazuh::manager::ossec_manager_authd:
  enabled: 'yes'
  use_password: 'no'

wazuh::agent::wazuh_manager_address: '192.168.1.20'
wazuh::agent::agent_group: 'default'
wazuh::agent::manage_repo: true
```

### Per-environment overrides

File `data/environments/production.yaml`:

```yaml
wazuh::manager::ossec_manager_config:
  cluster:
    disabled: 'no'
    name: 'prod-wazuh-cluster'
    key: '%{lookup("wazuh_cluster_key")}'

wazuh::indexer::indexer_admin_password: '%{lookup("wazuh_indexer_password")}'
```

### Per-role overrides

File `data/roles/web-server.yaml`:

```yaml
wazuh::agent::agent_group: 'web-servers'
wazuh::agent::ossec_agent_config:
  syscheck:
    frequency: '43200'
    directories:
      - path: '/var/www'
        check_all: 'yes'
        realtime: 'yes'
```

### Secrets via Hiera eyaml

Protect passwords using hiera-eyaml:

```yaml
wazuh_cluster_key: >
  ENC[PKCS7,MIIBiQYJKoZIhvcNAQcDoIIBejCCAXYCAQAx...]
wazuh_indexer_password: >
  ENC[PKCS7,MIIBiQYJKoZIhvcNAQcDoIIBejCCAXYCAQAx...]
```

## Troubleshooting

### Module not found

**Symptoms:** error `Could not find class wazuh::manager`.

**Solution:**

1. Verify the module installation:

```bash
puppet module list | grep wazuh
```

2. Confirm that `modulepath` in `puppet.conf` includes the directory containing the module

3. When using r10k, redeploy:

```bash
r10k deploy environment production -pv
```

### Agent service does not start after catalog application

**Symptoms:** Puppet reports a successful run, but the wazuh-agent service is not running.

**Solution:**

1. Check the service status:

```bash
systemctl status wazuh-agent
```

2. Review agent logs:

```bash
tail -50 /var/ossec/logs/ossec.log
```

3. Verify that `wazuh_manager_address` points to a reachable manager

### Module version conflicts

**Symptoms:** dependency errors during module installation.

**Solution:**

1. Force-update dependencies:

```bash
puppet module install wazuh-wazuh --force
```

2. Check version compatibility in the module's `metadata.json`

3. When using a Puppetfile, pin specific versions for all dependencies

### Hiera data not applied

**Symptoms:** parameters from Hiera are ignored; defaults are used instead.

**Solution:**

1. Inspect the Hiera hierarchy:

```bash
puppet lookup --explain wazuh::agent::wazuh_manager_address
```

2. Verify that `hiera.yaml` contains correct data file paths

3. Validate YAML syntax in data files

## Additional resources

- [Deployment options overview](/docs/wazuh/deployment/)
- [Wazuh Ansible deployment](/docs/wazuh/deployment/wazuh-ansible-deployment/)
- [Wazuh installation guide](/docs/wazuh/installation/)
- [Official wazuh-puppet module](https://github.com/wazuh/wazuh-puppet)