Install Wazuh Agent

We can install the Wazuh agent on endpoints using the roles and playbooks available in the Wazuh Ansible repository. The Ansible server must have access to the endpoints where the agents are to be installed.

Note

  • SSH key-pairing should already be configured between the ansible deployment server and the endpoints.

  • Add the endpoints where the agent will be deployed in the Ansible hosts file under the [wazuh-agents] hosts group.

  • This playbook does not support deploying Wazuh agents to macOS endpoints.

1 - Accessing the wazuh-ansible directory

We access the contents of the directory on the Ansible server where we have cloned the repository to. We can see the roles we have by running the command below in the cloned directory:

# cd /etc/ansible/roles/wazuh-ansible/
# tree roles -d
roles
├── ansible-galaxy
│   └── meta
└── wazuh
    ├── ansible-filebeat-oss
    │   ├── defaults
    │   ├── handlers
    │   ├── meta
    │   ├── tasks
    │   └── templates
    ├── ansible-wazuh-agent
    │   ├── defaults
    │   ├── handlers
    │   ├── meta
    │   ├── tasks
    │   └── templates
    ├── ansible-wazuh-manager
    │   ├── defaults
    │   ├── files
    │   │   └── custom_ruleset
    │   │       ├── decoders
    │   │       └── rules
    │   ├── handlers
    │   ├── meta
    │   ├── tasks
    │   ├── templates
    │   └── vars
    ├── wazuh-dashboard
    │   ├── defaults
    │   ├── handlers
    │   ├── tasks
    │   ├── templates
    │   └── vars
    └── wazuh-indexer
        ├── defaults
        ├── handlers
        ├── meta
        ├── tasks
        └── templates

And we can see the preconfigured playbooks we have by running the command below:

# tree playbooks/
playbooks
├── ansible.cfg
├── wazuh-agent.yml
├── wazuh-dashboard.yml
├── wazuh-indexer.yml
├── wazuh-manager-oss.yml
├── wazuh-production-ready.yml
└── wazuh-single.yml

For the agent deployment, we are going to use the role of wazuh-agent, which contains the necessary commands to install an agent and register it in our Wazuh environment. Below is the content of the YAML file /etc/ansible/roles/wazuh-ansible/playbooks/wazuh-agent.yml we are going to run for a complete installation of the Wazuh agent.

---
- hosts: <your wazuh agents hosts>
  become: yes
  become_user: root
  roles:
    - ../roles/wazuh/ansible-wazuh-agent
  vars:
    wazuh_managers:
      - address: <your manager IP>
        port: 1514
        protocol: tcp
        api_port: 55000
        api_proto: 'https'
        api_user: wazuh
        max_retries: 5
        retry_interval: 5

Let’s take a closer look at the content.

  • The first line hosts: indicates the machines where the commands in the playbook will be executed.

  • The roles: section indicates the roles that will be executed on the hosts specified. In this case, we are going to install the role of wazuh-agent.

  • The variables list wazuh_managers: indicates details for the connection with the Wazuh manager. This list overwrites the default configuration.

There are several variables we can use to customize the installation or configuration. If we want to change the default configuration:

  • We can change the /etc/ansible/roles/wazuh-ansible/roles/wazuh/ansible-wazuh-agent/defaults/main.yml file directly.

  • Alternatively, we can create another YAML file with the content we want to change in the configuration. If we want to do this, we can find more information about the Wazuh agent role.

More details on default configuration variables can be found in the variables references section.

2 - Preparing to run the playbook

We can create a similar YAML file or modify the one we already have to adapt it to our configuration. We will use the host group of the endpoints where we are going to install the Wazuh agent in the hosts section. In this case, it is wazuh-agents. Make sure to replace these values with your agents actual data. Add and remove lines accordingly. The hosts file will look like this:

[wazuh-agents]
agent_1 ansible_host=192.168.33.31 ansible_ssh_user=<username>

We will also add the IP address of the Wazuh server to the wazuh_managers: section.

Our resulting file is:

---
- hosts: wazuh-agents
  become: yes
  become_user: root
  roles:
    - ../roles/wazuh/ansible-wazuh-agent
  vars:
    wazuh_managers:
      - address: 192.168.33.31
        port: 1514
        protocol: tcp
        api_port: 55000
        api_proto: 'https'
        api_user: wazuh
        max_retries: 5
        retry_interval: 5

3 - Running the playbook

Now, we are ready to run the playbook and start the installation. However, some of the operations to be performed on the remote systems will need sudo permissions. We can solve this in several ways, either by opting to enter the password when Ansible requests it or using the become option (to avoid entering passwords one by one).

  1. Let’s run the playbook.

    Switch to the playbooks folder on the Ansible server and proceed to run the command below:

    # ansible-playbook wazuh-agent.yml -b -K
    
  2. Once the deployment completes, we can check the status of the Wazuh agent on the endpoints.

    # systemctl status wazuh-agent
    

    We can also view agent information from the Wazuh server.

    # /var/ossec/bin/agent_control -l