Deploying Wazuh

All-in-one deployment

The all-in-one deployment installs the Wazuh indexer, Wazuh dashboard, and Wazuh manager on a single endpoint. You can use predefined playbooks from the Wazuh Ansible repository to deploy these components. Ensure the Ansible control node has SSH access to this endpoint.

Perform the following to deploy the Wazuh manager, indexer, and dashboard:

[aio]
aio_node ansible_host=<AIO_PUBLIC_IP> private_ip=<AIO_PRIVATE_IP>

[aio:vars]
ansible_user=<USERNAME>
ansible_ssh_common_args='-o StrictHostKeyChecking=no'
ansible_ssh_private_key_file=<PATH_TO_PRIVATE_KEY_FILE>

Wazuh cluster deployment

A Wazuh cluster is a distributed deployment where multiple Wazuh manager and indexer nodes work together to provide horizontal scalability, performance, and high availability. In a clustered setup, data and workloads are shared across nodes, ensuring redundancy and load balancing.

You can deploy a Wazuh cluster using Ansible playbooks from the Wazuh Ansible repository.

To install a Wazuh cluster, perform the following steps:

# cd /etc/ansible/roles/wazuh-ansible/
# tree roles -d

roles
├── package-urls
│   ├── defaults
│   └── tasks
├── vars
├── wazuh-agent
│   ├── defaults
│   └── tasks
├── wazuh-credentials
│   ├── defaults
│   └── tasks
├── wazuh-dashboard
│   ├── defaults
│   └── tasks
├── wazuh-indexer
│   ├── defaults
│   └── tasks
└── wazuh-manager
    ├── defaults
    └── tasks

# ls

CHANGELOG.md  LICENSE  README.md  SECURITY.md  VERSION.json  docs  requirements.yml  roles  tools  wazuh-agent.yml  wazuh-aio.yml  wazuh-distributed.yml

# cat wazuh-distributed.yml

---

- name: Configure package URLs
  hosts: localhost
  roles:
    - role: package-urls
  run_once: true
  become: false

- name: Configure Wazuh Indexer cluster
  hosts: wi_cluster
  roles:
    - role: wazuh-indexer
  become: true
  vars:
    # generate_certs: false                    # Set to false if you are using your own certificates
    instances:
      wi1:                                     # Must be same as inventory hostname
        name: indexer
        ip: "{{ hostvars.wi1.private_ip }}"
        role: indexer
      wi2:
        name: indexer-2
        ip: "{{ hostvars.wi2.private_ip }}"
        role: indexer
      wi3:
        name: indexer-3
        ip: "{{ hostvars.wi3.private_ip }}"
        role: indexer
      manager:
        name: manager
        ip: "{{ hostvars.manager.private_ip }}"
        role: manager
        node_type: master
        # extra_ips: ["<manager-public-ip>"]  # optional, unique to this node
      worker:
        name: manager-2
        ip: "{{ hostvars.worker.private_ip }}"
        role: manager
        node_type: worker
        # extra_ips: ["<worker-public-ip>"]   # optional, unique to this node
      dashboard:
        name: dashboard
        ip: "{{ hostvars.dashboard.private_ip }}"
        role: dashboard

- name: Configure Wazuh Manager
  hosts: manager
  roles:
    - role: wazuh-manager
  become: true
  vars:
    node_type: "master"
    manager_node_name: "manager"
    wazuh_indexer_hosts:
      - host: "{{ hostvars.wi1.private_ip }}"
        port: 9200
      - host: "{{ hostvars.wi2.private_ip }}"
        port: 9200
      - host: "{{ hostvars.wi3.private_ip }}"
        port: 9200

- name: Configure Wazuh Worker
  hosts: worker
  roles:
    - role: wazuh-manager
  become: true
  vars:
    node_type: "worker"
    manager_node_name: "manager-2"
    wazuh_indexer_hosts:
      - host: "{{ hostvars.wi1.private_ip }}"
        port: 9200
      - host: "{{ hostvars.wi2.private_ip }}"
        port: 9200
      - host: "{{ hostvars.wi3.private_ip }}"
        port: 9200

- name: Configure Wazuh Dashboard
  hosts: dashboard
  roles:
    - role: wazuh-dashboard
  become: true
  vars:
    dashboard_node_name: "dashboard"
    wazuh_manager_master_address: "{{ hostvars.manager.private_ip }}"
    indexer_cluster_nodes:
      - "{{ hostvars.wi1.private_ip }}"
      - "{{ hostvars.wi2.private_ip }}"
      - "{{ hostvars.wi3.private_ip }}"

[all]
wi1 ansible_host=<WI1_PUBLIC_IP> private_ip=<WI1_PRIVATE_IP>
wi2 ansible_host=<WI2_PUBLIC_IP> private_ip=<WI2_PRIVATE_IP>
wi3 ansible_host=<WI3_PUBLIC_IP> private_ip=<WI3_PRIVATE_IP>
manager ansible_host=<MANAGER_PUBLIC_IP> private_ip=<MANAGER_PRIVATE_IP>
worker  ansible_host=<WORKER_PUBLIC_IP> private_ip=<WORKER_PRIVATE_IP>
dashboard  ansible_host=<DASHBOARD_PUBLIC_IP> private_ip=<DASHBOARD_PRIVATE_IP>

[wi_cluster]
wi1
wi2
wi3

[all:vars]
ansible_user=<USERNAME>
ansible_ssh_common_args='-o StrictHostKeyChecking=no'
ansible_ssh_private_key_file=<PATH_TO_PRIVATE_KEY_FILE>

Managing the Wazuh passwords

The Wazuh Ansible playbooks do not use default passwords. During the first run, the playbook generates a random password for each Wazuh user on the Ansible control node. Each password is stored in its own file in the /etc/ansible/roles/wazuh-ansible/deployment-credentials directory.

To use your own passwords instead of generated ones, set the wazuh_credentials_overrides variable on the first run. The playbook uses a supplied password only for a key that has no file in deployment-credentials yet. For example, store the passwords in a file encrypted with Ansible Vault:

# cd /etc/ansible/roles/wazuh-ansible/
# ansible-vault create credentials-overrides.yml

Add the keys you want to set, then save the file. The playbook generates a password for every key you leave out:

wazuh_credentials_overrides:
  WAZUH_INDEXER_ADMIN_PASSWORD: "<ADMIN_PASSWORD>"
  WAZUH_MANAGER_API_PASSWORD: "<API_PASSWORD>"

Each password must have 12 to 64 characters from A-Z a-z 0-9 . , _ + : @ % ^ = ~ -. It must include at least one uppercase letter, one lowercase letter, one digit, and one of those symbols. Pass the file on the first run, for example:

# ansible-playbook wazuh-aio.yml -e "source=prerelease" -e @credentials-overrides.yml --ask-vault-pass -K

The playbook does not change passwords. After you change a password with the Wazuh passwords tool, write the new value to the file of its key on the Ansible control node. Later runs of the playbook use admin and wazuh users to check the Wazuh indexer and Wazuh manager API, and stop if either password is rejected. If the tool generated the new password, read it from the # >>> wazuh generated block of /etc/wazuh/credentials.env on the host where you ran the tool. The same key also appears earlier in the file with its old value. For example, after you change the admin password, run:

# printf '%s' '<NEW_ADMIN_PASSWORD>' > /etc/ansible/roles/wazuh-ansible/deployment-credentials/WAZUH_INDEXER_ADMIN_PASSWORD

Then remove /etc/wazuh/credentials.env from the host where you ran the tool. The files in deployment-credentials hold the passwords in plain text. Restrict access to them. To read a password, open the corresponding file for the Wazuh user. For example, run the following command to read the password of the wazuh user:

# cat /etc/ansible/roles/wazuh-ansible/deployment-credentials/WAZUH_MANAGER_API_PASSWORD; echo

# ansible <HOSTS> -b -K -m ansible.builtin.file -a "path=/etc/wazuh/credentials.env state=absent"

The playbook also generates the root CA and the certificates of the deployment on the Ansible control node during the first run. It keeps the certificates in /etc/ansible/roles/wazuh-ansible/deployment-config-files/wazuh-certificates. It keeps the root CA and its private key in a directory under /var/lib/wazuh-ansible/, which it prints on every run. Back up both directories.

Each clone of the Wazuh Ansible repository holds one deployment. To deploy another environment, clone the repository into another directory and run the playbook from there. The passwords of that deployment are in the deployment-credentials directory of that clone, so read them there, not in /etc/ansible/roles/wazuh-ansible/.

To change the passwords, see Password management.

Prerequisites

Before deploying Wazuh agents with Ansible, check that the ansible.windows collection is installed on the Ansible control node. The wazuh-agent role uses it for Windows endpoints. The ansible-galaxy install -r requirements.yml command in Deploying Wazuh installs it with the other required collections. Run the following command to confirm:

# ansible-galaxy collection list ansible.windows

Generate an enrollment token

Run the following command on the Wazuh manager to generate an enrollment token. In a Wazuh cluster, run it on the master node, because worker nodes do not create tokens. Replace <WAZUH_MANAGER_ADDRESS> with the IP address or FQDN that the agents use to reach the Wazuh manager.

# /var/wazuh-manager/bin/wazuh-manager-authd --create-enrollment-token --address <WAZUH_MANAGER_ADDRESS>

The command output looks similar to this:

<ENROLLMENT_TOKEN>
id: <TOKEN_ID>
endpoint: <WAZUH_MANAGER_ADDRESS>
expires: <TOKEN_EXPIRY_TIMESTAMP>
pin: <CA_PIN>
credential: yes

Copy the first line, <ENROLLMENT_TOKEN>. The token is valid for 30 days and can be used to enroll several agents until it expires.

Store the token with Ansible Vault on the Ansible control node. Replace <ENROLLMENT_TOKEN> with the token you copied. The commands save it, encrypted, in group_vars/agents/vault.yml next to the playbook, and Ansible loads it for the agents group:

# cd /etc/ansible/roles/wazuh-ansible/
# mkdir -p group_vars/agents
# ansible-vault encrypt_string '<ENROLLMENT_TOKEN>' --name 'vault_wazuh_enrollment_token' >> group_vars/agents/vault.yml

Access the wazuh-ansible directory

Change to the directory where you cloned the Wazuh Ansible repository:

# cd /etc/ansible/roles/wazuh-ansible/
# tree roles -d

The command output looks similar to this:

roles
├── package-urls
│   ├── defaults
│   └── tasks
├── vars
├── wazuh-agent
│   ├── defaults
│   └── tasks
├── wazuh-credentials
│   ├── defaults
│   └── tasks
├── wazuh-dashboard
│   ├── defaults
│   └── tasks
├── wazuh-indexer
│   ├── defaults
│   └── tasks
└── wazuh-manager
    ├── defaults
    └── tasks

You can see the preconfigured playbooks by running the command below:

# ls

The output also lists the group_vars directory, which you created when you stored the enrollment token. If you deployed the Wazuh central components from this clone, it also lists deployment-config-files and deployment-credentials.

The command output looks similar to this:

CHANGELOG.md  LICENSE  README.md  SECURITY.md  VERSION.json  docs  requirements.yml  roles  tools  wazuh-agent.yml  wazuh-aio.yml  wazuh-distributed.yml

The /etc/ansible/roles/wazuh-ansible/wazuh-agent.yml file contains the necessary commands to install a Wazuh agent and register it to the Wazuh manager. Below is an excerpt of the /etc/ansible/roles/wazuh-ansible/wazuh-agent.yml file:

---

- name: Deploy Wazuh agent(s)
  hosts: agents
  strategy: free
  vars:
    wazuh_enrollment_token: "<Your Wazuh Agent Enrollment Token>"
    # Verification posture: full (CA + hostname), certificate (CA only), system
    # (OS trust store) or none. Empty leaves it unset.
    wazuh_ssl_verification: ""
  roles:
    - role: package-urls
  tasks:
    - name: Include wazuh-agent role for Linux/MacOS hosts
      when: ansible_facts.system == "Linux" or ansible_facts.system == "Darwin"
      become: true
      become_user: root
      block:
        - name: Include Wazuh agent role for Linux
          ansible.builtin.include_role:
            name: wazuh-agent

    - name: Include wazuh-agent role for Windows hosts
      when: ansible_facts.os_family == "Windows"
      ansible.builtin.include_role:
        name: wazuh-agent

Where:

• hosts: specifies the Ansible inventory group that contains the endpoints where the Wazuh agent will be installed. The playbook targets the agents group, so the inventory uses the same group name.

• wazuh_enrollment_token: is the enrollment token generated on the Wazuh manager. The role passes it to the agent installer as WAZUH_ENROLLMENT_TOKEN.

• roles: runs the package-urls role, which downloads the list of Wazuh package URLs that the wazuh-agent role uses.

• tasks: includes the wazuh-agent role on Linux, macOS, and Windows hosts. On Linux and macOS hosts, the role runs with root privileges.

Prepare the playbook

Replace the value of wazuh_enrollment_token in the /etc/ansible/roles/wazuh-ansible/wazuh-agent.yml file with the variable of the vaulted token. The block below is an excerpt of the file:

---

- name: Deploy Wazuh agent(s)
  hosts: agents
  strategy: free
  vars:
    wazuh_enrollment_token: "{{ vault_wazuh_enrollment_token }}"
    # Verification posture: full (CA + hostname), certificate (CA only), system
    # (OS trust store) or none. Empty leaves it unset.
    wazuh_ssl_verification: ""
  roles:
    - role: package-urls
  tasks:
    - name: Include wazuh-agent role for Linux/MacOS hosts
      when: ansible_facts.system == "Linux" or ansible_facts.system == "Darwin"
      become: true
      become_user: root
      block:
        - name: Include Wazuh agent role for Linux
          ansible.builtin.include_role:
            name: wazuh-agent

    - name: Include wazuh-agent role for Windows hosts
      when: ansible_facts.os_family == "Windows"
      ansible.builtin.include_role:
        name: wazuh-agent

Add the endpoints where the Wazuh agent will be installed to the agents group of the /etc/ansible/hosts Ansible hosts file.

The contents of the Ansible host file below:

[agents]
agent1 ansible_host=<WAZUH_AGENT1_IP>
agent2 ansible_host=<WAZUH_AGENT2_IP>

[agents:vars]
ansible_user=<USERNAME>
ansible_ssh_common_args='-o StrictHostKeyChecking=no'
ansible_ssh_private_key_file=<PATH_TO_PRIVATE_KEY_FILE>

Where:

• ansible_host specifies the IP address of the endpoint where the Wazuh agent will be installed. Replace <WAZUH_AGENT1_IP> and <WAZUH_AGENT2_IP> with the actual IP addresses or hostnames of the Wazuh agent endpoints.

• ansible_user specifies the remote user account Ansible uses to connect over SSH. Replace <USERNAME> with a valid user account that has the required privileges on the endpoints.

• ansible_ssh_private_key_file specifies the SSH private key used by Ansible to connect to the target hosts. Replace <PATH_TO_PRIVATE_KEY_FILE> with the full path of the private key file on the Ansible control node.

• ansible_ssh_common_args='-o StrictHostKeyChecking=no' makes SSH accept the host key of each endpoint, new or changed, without asking you to confirm it. Remove it if the Ansible control node already trusts the host keys of the endpoints.

To install Windows agents, add the following configuration to the [agents] section in the /etc/ansible/hosts Ansible hosts file:

windows_agent ansible_host=<WINDOWS_AGENT_IP>  ansible_connection=winrm  ansible_port=5986  ansible_winrm_transport=ntlm  ansible_user=<WINDOWS_USERNAME>  ansible_password=<WINDOWS_PASSWORD> ansible_winrm_server_cert_validation=ignore

Where:

• ansible_host specifies the IP address of the endpoint where the Wazuh agent will be installed. Replace <WINDOWS_AGENT_IP> with the IP address or hostname of the Windows endpoint.

• ansible_user specifies the username of an administrator account on the endpoint.

• ansible_password specifies the password of an administrator account on the endpoint.

• ansible_connection=winrm and ansible_port=5986 make Ansible connect to a Windows endpoint over WinRM HTTPS. ansible_winrm_transport=ntlm makes Ansible sign in with NTLM. Without it, Ansible uses Basic authentication, which WinRM on Windows turns off by default. ansible_winrm_server_cert_validation=ignore skips the check of the WinRM certificate. Remove it if a CA that the control node trusts signed the certificate.

# cd /etc/ansible/roles/wazuh-ansible/
# ansible-vault encrypt_string '<WINDOWS_PASSWORD>' --name 'vault_wazuh_agent_windows_password' >> group_vars/agents/vault.yml

Run the playbook

1. Run the command below from the playbook directory on the Ansible control node:

   # ansible-playbook wazuh-agent.yml -e "source=prerelease" --ask-vault-pass -K
   

   Note

   The playbook passes wazuh_enrollment_token and wazuh_ssl_verification to the Wazuh agent installer only when it installs the agent. On an endpoint where the Wazuh agent is already installed, a new run skips the installation and applies neither value. If an agent did not enroll, for example because its token expired, the run fails at the Start and enable Wazuh Agent service task. Remove the Wazuh agent from the endpoint and run the playbook again.

2. Check the status of the Wazuh agent:

   • Wazuh agent status on the endpoint

     Linux	macOS	Windows
     # systemctl status wazuh-agent	# /Library/Ossec/bin/wazuh-control status	> Get-Service -Name WazuhSVC

3. Navigate to Agents management > Summary on the Wazuh dashboard to confirm the agent is enrolled.