Installing the Wazuh manager step-by-step

Adding the Wazuh repository

Deploying certificates and passwords

Do this before installing the package. The package then uses these files and passwords instead of generating its own.

# install -d -m 0750 /etc/wazuh-manager
# install -m 0600 /dev/null /etc/wazuh-manager/local.env
# grep -E '^(WAZUH_MANAGER_API_PASSWORD|WAZUH_MANAGER_WUI_PASSWORD)=' credentials.env > /etc/wazuh-manager/local.env

1. Replace <MANAGER_NODE_NAME> with your Wazuh manager node certificate name, the same used in config.yml when creating the certificates. In our case, the node name is manager. Then extract the archive, and place the root CA and the passwords:

   # NODE_NAME=<MANAGER_NODE_NAME>
   # umask 022
   # mkdir wazuh-certificates
   # tar -xf wazuh-certificates.tar -C wazuh-certificates
   # install -d -m 0750 /etc/wazuh-manager
   # install -d -m 0700 /etc/wazuh-manager/ca
   # install -m 0644 wazuh-certificates/root-ca.pem /etc/wazuh-manager/ca/root-ca.pem
   # install -m 0600 /dev/null /etc/wazuh-manager/local.env
   # grep -E '^(WAZUH_INDEXER_MANAGER_PASSWORD|WAZUH_MANAGER_API_PASSWORD|WAZUH_MANAGER_WUI_PASSWORD)=' wazuh-certificates/credentials.env > /etc/wazuh-manager/local.env
   

   Keep the wazuh-certificates directory, as it is required after the installation. Before installing the package, place the root CA in the deployment so the package uses your deployment's CA instead of generating its own.

   For a Wazuh manager cluster, follow these steps on every node. Every node gets the same root CA, so the Wazuh agents trust every node, and no node needs the root CA private key.

2. Recommended action: If no other Wazuh components will be installed on this node, remove the wazuh-certificates.tar file.

   # rm -f ./wazuh-certificates.tar
   

Installing the Wazuh manager

1. Install the Wazuh manager package:

   APTYumDNF

   # apt-get -y install wazuh-manager=5.0.0-1
   

   Release candidate packages carry the version of the final release, 5.0.0-1. Only their file names show the RC stage, for example wazuh-manager_5.0.0-rc2_amd64.deb, so dpkg -l and rpm -q show 5.0.0-1.

2. On a host without the Wazuh indexer, the installation prints MISSING lines for remoted.pem, apid.pem, indexer-ca.pem, and indexer-connector.pem, a WARNING about the dashboard client pair, and Credential resolution is incomplete. This is expected, and you don't need to stage the root CA private key. Place this node's certificates and the Wazuh indexer root CA. They are in the directory where you extracted wazuh-certificates.tar. Skip this step on the first Wazuh indexer node:

   # install -m 0640 -o root -g wazuh-manager wazuh-certificates/$NODE_NAME-remoted.pem /etc/wazuh-manager/certs/remoted.pem
   # install -m 0640 -o root -g wazuh-manager wazuh-certificates/$NODE_NAME-remoted-key.pem /etc/wazuh-manager/certs/remoted-key.pem
   # install -m 0640 -o root -g wazuh-manager wazuh-certificates/$NODE_NAME-apid.pem /etc/wazuh-manager/certs/apid.pem
   # install -m 0640 -o root -g wazuh-manager wazuh-certificates/$NODE_NAME-apid-key.pem /etc/wazuh-manager/certs/apid-key.pem
   # install -m 0640 -o root -g wazuh-manager wazuh-certificates/root-ca.pem /etc/wazuh-manager/certs/indexer-ca.pem
   # install -m 0640 -o root -g wazuh-manager wazuh-certificates/$NODE_NAME.pem /etc/wazuh-manager/certs/indexer-connector.pem
   # install -m 0640 -o root -g wazuh-manager wazuh-certificates/$NODE_NAME-key.pem /etc/wazuh-manager/certs/indexer-connector-key.pem
   

3. Remove the extracted files. They hold private keys:

   # rm -rf wazuh-certificates
   

   Note

   Firewalls can block communication between Wazuh components on different hosts. Refer to the Required ports section and make sure the necessary ports are open.

Checking the agent listener certificate

The agent listener certificate, /etc/wazuh-manager/certs/remoted.pem, lists the addresses that Wazuh agents use to reach this node. You can create enrollment tokens only for these addresses. Follow these steps to check the certificate and, if needed, add an address.

1. Check the agent listener certificate:

   # openssl verify -CAfile /etc/wazuh-manager/certs/root-ca.pem /etc/wazuh-manager/certs/remoted.pem
   # openssl x509 -in /etc/wazuh-manager/certs/remoted.pem -noout -ext subjectAltName
   

   The first command prints /etc/wazuh-manager/certs/remoted.pem: OK. The second lists the addresses that agents can use to reach this node.

2. To add an address later, such as a load balancer or a NAT name, issue the certificates again on the first Wazuh indexer node. Pass every address that agents use, not only the new one:

   # rm -rf /usr/share/wazuh-indexer/tools/wazuh-certificates
   # WAZUH_CA_DIR=/etc/wazuh-indexer/ca bash /usr/share/wazuh-indexer/tools/wazuh-certs-tool.sh -wm -as <ALTERNATE_ADDRESS> -as <OTHER_ALTERNATE_ADDRESS>
   

   The tool writes new certificates for every Wazuh manager node to /usr/share/wazuh-indexer/tools/wazuh-certificates.

3. Copy <NODE_NAME>-remoted.pem and <NODE_NAME>-remoted-key.pem to each Wazuh manager node. Then install them and restart the Wazuh manager:

   # install -m 0640 -o root -g wazuh-manager <NODE_NAME>-remoted.pem /etc/wazuh-manager/certs/remoted.pem
   # install -m 0640 -o root -g wazuh-manager <NODE_NAME>-remoted-key.pem /etc/wazuh-manager/certs/remoted-key.pem
   # systemctl restart wazuh-manager
   

4. Check that the certificate lists the new address:

   # openssl x509 -in /etc/wazuh-manager/certs/remoted.pem -noout -ext subjectAltName
   

5. Remove the wazuh-certificates directory and the copied files. They hold private keys.

Configuring the Wazuh indexer connection

1. Edit /etc/wazuh-manager/wazuh-manager.conf file to configure the indexer connection. Do it on the master node and on every worker node, as the cluster does not synchronize this block. By default, the indexer settings configure one host. It's set to 127.0.0.1:

   <indexer>
      <hosts>
        <host>https://127.0.0.1:9200</host>
      </hosts>
      <ssl>
        <certificate_authorities>
          <ca>/etc/wazuh-manager/certs/indexer-ca.pem</ca>
        </certificate_authorities>
        <certificate>/etc/wazuh-manager/certs/indexer-connector.pem</certificate>
        <key>/etc/wazuh-manager/certs/indexer-connector-key.pem</key>
      </ssl>
    </indexer>
   

   • Replace 127.0.0.1 with the address of your Wazuh indexer node. It's the node's ip value in config.yml and its network.host value in /etc/wazuh-indexer/opensearch.yml on that node. Edit only the <host> value: the <ssl> block already points to the certificate files in /etc/wazuh-manager/certs. If the Wazuh indexer runs on this host and you left network.host at the package default, keep 127.0.0.1.

   If you are running a Wazuh indexer cluster infrastructure, add a <host> entry for each one of your Wazuh indexer nodes. For example, in a two-node configuration:

   <hosts>
     <host>https://10.0.0.1:9200</host>
     <host>https://10.0.0.2:9200</host>
   </hosts>
   

   The Wazuh manager prioritizes reporting to the first Wazuh indexer node in the list. It switches to the next node if it is unavailable.

Starting the Wazuh manager

1. Enable and start the Wazuh manager service. The package neither enables nor starts it. The first start usually takes a few seconds, and systemd reports a failure after three minutes:

   # systemctl daemon-reload
   # systemctl enable --now wazuh-manager
   

2. Run the following command to verify the Wazuh manager status. Check that the output shows Active: active (running):

   # systemctl status wazuh-manager
   

   If the Wazuh manager doesn't start, run /var/wazuh-manager/bin/wazuh-manager-resolve-credentials --check. It names each missing or invalid password and certificate, and prints check: no problem found when there is none. To read the refusals in the log, run:

   # grep -E 'MISSING|INVALID|UNSAFE' /var/wazuh-manager/logs/wazuh-manager.log | tail
   

   For example, MISSING WAZUH_INDEXER_MANAGER_PASSWORD means that the password isn't in /etc/wazuh-manager/local.env. UNSAFE /etc/wazuh-manager/certs/indexer-ca.pem: group is root, not wazuh-manager means that the file has the wrong group.

3. Check that the Wazuh manager reaches the Wazuh indexer:

   # grep -E 'indexer is reachable|No configured indexer host' /var/wazuh-manager/logs/wazuh-manager.log | tail -1
   

   The output is a line that ends in INFO: The indexer is reachable; inventory documents can be delivered. If the command prints nothing, wait a minute and run it again. If it still prints nothing, or it prints No configured indexer host is currently reachable, check the <indexer> block. Also check that this host can reach port 9200/TCP of the Wazuh indexer.

Your Wazuh manager node is now successfully installed. Repeat this stage of the installation process for every Wazuh manager node in your Wazuh cluster, then proceed with configuring the Wazuh cluster. If you want a Wazuh manager single-node cluster, everything is set, and you can proceed directly with Installing the Wazuh dashboard step-by-step.

Configuring the Wazuh manager master node

1. On the master node, create the cluster key and keep the output. You use the same value on the master node and on every worker node:

   # openssl rand -hex 16
   

   Then edit the following settings in the /etc/wazuh-manager/wazuh-manager.conf file and configure the necessary parameters:

   <cluster>
     <name>wazuh</name>
     <node_name>master-node</node_name>
     <node_type>master</node_type>
     <key><CLUSTER_KEY></key>
     <port>1516</port>
     <bind_addr>0.0.0.0</bind_addr>
     <nodes>
         <node><WAZUH_MASTER_ADDRESS></node>
     </nodes>
     <hidden>no</hidden>
   </cluster>
   

   Configuration parameters:

   name	Indicates the name of the cluster. All nodes must use the same cluster name.
   node_name	Indicates the name of the current node. Each node of the cluster must have a unique name.
   node_type	Specifies the role of the node. It has to be set to master.
   key	Key that encrypts communication between cluster nodes. Replace <CLUSTER_KEY> with a 32-character key that is the same on every node. Create it once, on the master node, with openssl rand -hex 16.
   port	It indicates the destination port for cluster communication.
   bind_addr	It is the network IP to which the node is bound to listen for incoming requests (0.0.0.0 to listen on all interfaces.).
   nodes	It is the address of the master node and can be either an IP or a DNS. This parameter must be specified in all nodes, including the master itself. Replace <WAZUH_MASTER_ADDRESS> with the IP address or DNS name of the master node.
   hidden	Has no effect in Wazuh 5.0. Keep the default, no.

2. Restart the Wazuh manager:

   # systemctl restart wazuh-manager
   

Configuring the Wazuh manager worker nodes

1. The Wazuh manager cluster lets you scale horizontally by distributing the load across multiple nodes. On each worker node, edit the <cluster> block in /etc/wazuh-manager/wazuh-manager.conf as follows. Use a unique node_name, for example worker-node1 and worker-node2, set node_type to worker, and use the same <CLUSTER_KEY> as the master node:

   <cluster>
       <name>wazuh</name>
       <node_name>worker-node1</node_name>
       <node_type>worker</node_type>
       <key><CLUSTER_KEY></key>
       <port>1516</port>
       <bind_addr>0.0.0.0</bind_addr>
       <nodes>
           <node><WAZUH_MASTER_ADDRESS></node>
       </nodes>
       <hidden>no</hidden>
   </cluster>
   

   Configuration parameters:

   name	Indicates the name of the cluster. All nodes must use the same cluster name.
   node_name	Indicates the name of the current node. Each node of the cluster must have a unique name.
   node_type	Specifies the role of the node. It has to be set as worker.
   key	The <CLUSTER_KEY> value you created on the master node (the package wrote a different random key on this node). It must be the same on every node.
   nodes	Specifies the address of the master node. Replace <WAZUH_MASTER_ADDRESS> with the IP address or DNS name of the master node, the same value you set on the master node.

2. Restart the Wazuh manager:

   # systemctl restart wazuh-manager
   

Repeat these configuration steps for every Wazuh manager worker node in your cluster.

Testing the Wazuh manager cluster

On any Wazuh manager node, run the following command to verify that the Wazuh cluster is enabled and all the nodes are connected:

# /var/wazuh-manager/bin/cluster_control -l

An example output of the command looks as follows:

NAME         TYPE    VERSION  ADDRESS
master-node  master  5.0.0    10.0.0.3
worker-node1 worker  5.0.0    10.0.0.4
worker-node2 worker  5.0.0    10.0.0.5

Note that the IP addresses 10.0.0.3, 10.0.0.4, and 10.0.0.5 are used as examples.

The Wazuh manager API listens only on the master node, so port 55000 on a worker node doesn't answer.