Wazuh with Puppet - Configuration Management

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
Internet access for downloading packages (or an offline repository )
Open ports: 1514, 1515, 9200, 443, 55000

Module installation

From Puppet Forge

puppet module install wazuh-wazuh

Via Puppetfile (r10k)

Add to your Puppetfile:

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

Deploy the environment:

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:

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

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:

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:

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

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

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

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:

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:

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:

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:

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:

Verify the module installation:

puppet module list | grep wazuh

Confirm that modulepath in puppet.conf includes the directory containing the module
When using r10k, redeploy:

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:

Check the service status:

systemctl status wazuh-agent

Review agent logs:

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

Verify that wazuh_manager_address points to a reachable manager

Module version conflicts

Symptoms: dependency errors during module installation.

Solution:

Force-update dependencies:

puppet module install wazuh-wazuh --force

Check version compatibility in the module’s metadata.json
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:

Inspect the Hiera hierarchy:

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

Verify that hiera.yaml contains correct data file paths
Validate YAML syntax in data files

Additional resources

Last updated on 8, April 2026

Wazuh with Ansible - Automated Deployment Guide