Installing the Wazuh indexer step-by-step

Installing package dependencies

1. Run the following command to install the following packages if missing:

   APTYumDNF

   # apt-get install -y iproute2 openssl passwd
   

Adding the Wazuh repository

Creating the passwords

On the first Wazuh indexer node only, create the five deployment passwords before installing the package. The Wazuh indexer uses three of these passwords instead of generating its own. In the next stage, all five passwords are packaged into wazuh-certificates.tar for use on the other nodes. The assisted method uses wazuh-install-files.tar instead.

1. Create the five passwords in credentials.env, in your working directory. A password must be 12 to 64 characters long and use only A-Z a-z 0-9 . , _ + : @ % ^ = ~ -. It must contain at least one uppercase letter, one lowercase letter, one digit, and one symbol. You can choose them yourself, or run the following command to generate them with this function:

   wazuh_generate_password() {
       local password
       while :; do
           password=$(LC_ALL=C tr -dc 'A-Za-z0-9.,_+:@%^=~-' < /dev/urandom | head -c 32)
           [[ $password =~ [A-Z] && $password =~ [a-z] && $password =~ [0-9] && $password =~ [.,_+:@%^=~-] ]] && break
       done
       printf '%s\n' "$password"
   }
   

   # install -m 0600 /dev/null credentials.env
   # cat > credentials.env <<EOF
   WAZUH_INDEXER_ADMIN_PASSWORD="$(wazuh_generate_password)"
   WAZUH_INDEXER_KIBANASERVER_PASSWORD="$(wazuh_generate_password)"
   WAZUH_INDEXER_MANAGER_PASSWORD="$(wazuh_generate_password)"
   WAZUH_MANAGER_API_PASSWORD="$(wazuh_generate_password)"
   WAZUH_MANAGER_WUI_PASSWORD="$(wazuh_generate_password)"
   EOF
   

2. WAZUH_MANAGER_API_PASSWORD is the password of the wazuh user of the Wazuh manager API, the one you use in API requests. WAZUH_MANAGER_WUI_PASSWORD is the password of wazuh-internal-client, the user that the Wazuh dashboard uses.

3. Copy the Wazuh indexer passwords from credentials.env to /etc/wazuh-indexer/local.env on this node. The following commands create the directory and file with the required permissions, then copy only the Wazuh indexer credentials:

   # install -d -m 0750 /etc/wazuh-indexer
   # install -m 0600 /dev/null /etc/wazuh-indexer/local.env
   # grep '^WAZUH_INDEXER_' credentials.env > /etc/wazuh-indexer/local.env
   

Installing the Wazuh indexer

1. On the first Wazuh indexer node, install the Wazuh indexer package:

   APTYumDNF

   # apt-get -y install wazuh-indexer=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-indexer_5.0.0-rc2_amd64.deb, so dpkg -l and rpm -q show 5.0.0-1.

Checking the passwords

On the first Wazuh indexer node, the package uses the three passwords created in Creating the passwords instead of generating new ones. The package publishes the passwords of its three users in /etc/wazuh-indexer/export/credentials.env, readable by root only. Run the following command to verify that each variable contains the value you created. The output shows three lines, one per variable.

# grep '^WAZUH_INDEXER_' /etc/wazuh-indexer/export/credentials.env | sort -u

The other Wazuh indexer nodes get the same three passwords from wazuh-certificates.tar in Deploying certificates, before their package is installed. So they never generate their own. Keep the file until all components are installed and running, then remove it as described in Securing your Wazuh installation.

Passwords are generated once. Reinstalling, restarting, or upgrading the Wazuh indexer does not change them, and neither does removing this file. To change a password after installation, see the password management documentation.

Generating the SSL certificates

1. Edit /usr/share/wazuh-indexer/tools/config.yml and replace the node names and IP values with the corresponding names and IP addresses. You need to do this for all Wazuh manager, Wazuh indexer, and Wazuh dashboard nodes. Add as many node fields as needed. If there is more than one Wazuh manager node, each one must have a node_type:

   nodes:
     # Wazuh indexer nodes
     indexer:
       - name: indexer
         ip: "<indexer-node-ip>"
       #- name: indexer-2
       #  ip: "<indexer-node-ip>"
       #- name: indexer-3
       #  ip: "<indexer-node-ip>"
   
     # Wazuh manager nodes
     # If there is more than one Wazuh manager
     # node, each one must have a node_type
     manager:
       - name: manager
         ip: "<wazuh-manager-ip>"
       #  node_type: master
       #- name: manager-2
       #  ip: "<wazuh-manager-ip>"
       #  node_type: worker
       #- name: manager-3
       #  ip: "<wazuh-manager-ip>"
       #  node_type: worker
   
     # Wazuh dashboard nodes
     dashboard:
       - name: dashboard
         ip: "<dashboard-node-ip>"
   
     # ip and dns both accept a list, for a node reachable at more than one address.
     # Every item reaches the certificate of the node; the first one is the address
     # the components are configured with.
     #- name: manager-2
     #  ip:
     #    - "<wazuh-manager-ip>"
     #    - "<wazuh-manager-second-ip>"
     #  dns:
     #    - "<wazuh-manager-name>"
   
     # Optional. Only for a proxy that TERMINATES the agents' TLS session: it issues the
     # certificate that proxy serves, from the same root-ca the agents pin. A layer 4
     # passthrough load balancer terminates nothing and needs --agent-san with its
     # address instead, so that address reaches the listener certificate of every
     # manager node.
     #load_balancer:
     #  - name: lb
     #    dns:
     #      - "<load-balancer-name>"
     #    ip:
     #      - "<load-balancer-ip>"
   

   For a Wazuh manager cluster, uncomment node_type in every manager entry. Set master on one node and worker on all others. For a single Wazuh manager, leave node_type commented. When two components share a host, give both entries that host's IP address.

   Each node needs an ip, a dns, or both, and each accepts a list. The node's certificate includes its name and every ip and dns value. For a Wazuh manager node, this applies to its agent listener and Wazuh manager API certificates. If a node has only a dns name, use that name wherever these sections ask for its address, for example network.host.

   The shipped file also has commented examples for a node with several addresses and for a TLS-terminating load balancer. For more about certificates, see Certificates deployment.

   Run the tool to create the certificates. WAZUH_CA_DIR makes it sign them with the root CA that the package created in /etc/wazuh-indexer/ca. Without it, the tool creates a second root CA, which the Wazuh manager and Wazuh dashboard don't trust. The tool writes the certificates to wazuh-certificates/, beside it:

   # WAZUH_CA_DIR=/etc/wazuh-indexer/ca bash /usr/share/wazuh-indexer/tools/wazuh-certs-tool.sh -A
   

   To add another address that agents use to reach a Wazuh manager, add -as <ALTERNATE_ADDRESS> to the command. Examples are a public IP, a NAT address, a load balancer, or the address of each Wazuh manager worker node that agents will use. Each -as takes one address. To add several, repeat it, for example -as 203.0.113.10 -as wazuh.example.com. Pass every address in the same run, because the certificate holds only the -as values of that run.

   Note

   The root CA private key, root-ca.key, stays in /etc/wazuh-indexer/ca on this node and is not in wazuh-certificates.tar. Back up /etc/wazuh-indexer/ca: you need it to add nodes or renew certificates.

Adding the passwords

1. Add the five passwords from Creating the passwords to the certificates. Each Wazuh manager node reads its Wazuh indexer password and two Wazuh manager API passwords from /etc/wazuh-manager/local.env. You write that file in Deploying certificates and passwords. The Wazuh dashboard receives WAZUH_MANAGER_WUI_PASSWORD in the same archive:

   # install -m 0600 credentials.env /usr/share/wazuh-indexer/tools/wazuh-certificates/credentials.env
   

Packing and copying the archive

1. Compress all the necessary files and make the archive readable by root only:

   # tar -cvf ./wazuh-certificates.tar -C /usr/share/wazuh-indexer/tools/wazuh-certificates/ .
   # chmod 600 ./wazuh-certificates.tar
   # rm -rf /usr/share/wazuh-indexer/tools/wazuh-certificates
   

2. Copy wazuh-certificates.tar to the working directory of each remaining Wazuh indexer, manager, and dashboard node. Transfer it as root, or stage it as your login user with permissions set to 0600 and remove it after use. For example, to copy it with scp, run the following commands on this node. Replace <USER> with a login user on this node, <REMOTE_USER> with one on the other node, and <NODE_IP> with the other node's IP address. <USER> must be able to sign in to the other node over SSH as <REMOTE_USER>. The first connection asks you to confirm the host key.

   # install -m 0600 -o <USER> ./wazuh-certificates.tar /home/<USER>/
   # sudo -u <USER> scp /home/<USER>/wazuh-certificates.tar <REMOTE_USER>@<NODE_IP>:
   # rm -f /home/<USER>/wazuh-certificates.tar
   

   If the nodes cannot sign in to each other, replace the scp line with the following command. Run it on a workstation that can sign in to both nodes, before you run the rm line. Replace <FIRST_NODE_IP> with this node's IP address.

   $ scp -3 <USER>@<FIRST_NODE_IP>:/home/<USER>/wazuh-certificates.tar <REMOTE_USER>@<NODE_IP>:
   

   Then run the following command on the other node, from its working directory:

   # install -m 0600 /home/<REMOTE_USER>/wazuh-certificates.tar ./ && rm -f /home/<REMOTE_USER>/wazuh-certificates.tar
   

Deploying certificates

1. Run the following commands in the directory that holds wazuh-certificates.tar. Replace <INDEXER_NODE_NAME> with this node's name in config.yml. For example, indexer on the first node and indexer-2 on the second node:

   # NODE_NAME=<INDEXER_NODE_NAME>
   # umask 022
   # mkdir wazuh-certificates
   # tar -xf wazuh-certificates.tar -C wazuh-certificates
   

2. On every Wazuh indexer node except the first, place the passwords and the root CA certificate of the deployment. The first node already has both, and its /etc/wazuh-indexer/ca also holds the root CA private key, which must stay there:

   # install -d -m 0750 /etc/wazuh-indexer /etc/wazuh-indexer/ca
   # install -m 0644 wazuh-certificates/root-ca.pem /etc/wazuh-indexer/ca/root-ca.pem
   # install -m 0600 /dev/null /etc/wazuh-indexer/local.env
   # grep '^WAZUH_INDEXER_' wazuh-certificates/credentials.env > /etc/wazuh-indexer/local.env
   

3. Place this node's certificates using the filenames expected by the package. On the first node, they replace the certificates that the package created:

   # install -d -m 0750 /etc/wazuh-indexer
   # install -d -m 0750 /etc/wazuh-indexer/certs
   # install -m 0400 wazuh-certificates/$NODE_NAME.pem /etc/wazuh-indexer/certs/indexer.pem
   # install -m 0400 wazuh-certificates/$NODE_NAME-key.pem /etc/wazuh-indexer/certs/indexer-key.pem
   # install -m 0400 wazuh-certificates/admin.pem /etc/wazuh-indexer/certs/admin.pem
   # install -m 0400 wazuh-certificates/admin-key.pem /etc/wazuh-indexer/certs/admin-key.pem
   # rm -rf wazuh-certificates
   

   On the first node, give the certificates the owners and modes the package uses. The directory must stay owned by root, or the Wazuh indexer refuses to start with UNSAFE /etc/wazuh-indexer/certs. On the other nodes, the package does this when you install it in step 4.

   # chown root:wazuh-indexer /etc/wazuh-indexer/certs && chmod 0750 /etc/wazuh-indexer/certs
   # chown root:wazuh-indexer /etc/wazuh-indexer/certs/indexer.pem /etc/wazuh-indexer/certs/indexer-key.pem
   # chmod 0640 /etc/wazuh-indexer/certs/indexer.pem /etc/wazuh-indexer/certs/indexer-key.pem
   # chown root:root /etc/wazuh-indexer/certs/admin.pem /etc/wazuh-indexer/certs/admin-key.pem
   # chmod 0600 /etc/wazuh-indexer/certs/admin.pem /etc/wazuh-indexer/certs/admin-key.pem
   

   The certificates tool issues each certificate with the node name from config.yml as CN. Run the following command to display the certificate subject in the format that plugins.security.nodes_dn expects:

   # openssl x509 -noout -subject -nameopt RFC2253 -in /etc/wazuh-indexer/certs/indexer.pem
   

4. On every Wazuh indexer node except the first, install the Wazuh indexer package now. The package uses the passwords and certificates you placed and generates nothing. It gives the certificates to the wazuh-indexer group and keeps the admin certificate pair owned by root.

   APTYumDNF

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

5. Recommended action: If no other Wazuh components will be installed on this node, run the following command to remove the wazuh-certificates.tar file.

   # rm -f ./wazuh-certificates.tar
   

Configuring the Wazuh indexer

1. Edit /etc/wazuh-indexer/opensearch.yml and replace the following values:

   The package ships a working single-node configuration: one node named node-1, listening on all interfaces. On a single node, these values are optional. Set network.host to listen on one address only, and if you rename the node, change cluster.initial_cluster_manager_nodes to match. A multi-node cluster needs every value, on every node.

   1. network.host: Sets the address of this node for both HTTP and transport traffic. The node will bind to this address and will also use it as its publish address. Accepts an IP address or a hostname.

      Use the same node address set in config.yml to create the SSL certificates.

   2. node.name: Name of the Wazuh indexer node as defined in the config.yml file. For example, indexer. The package sets node-1 on every node, so change it on every node to that node's name in config.yml. List the same names in cluster.initial_cluster_manager_nodes.

   3. cluster.initial_cluster_manager_nodes: List of the names of the master-eligible nodes. Use names defined in the config.yml file, for example, indexer. For a multi-node cluster, uncomment the node-2 and node-3 lines, change the names, or add more lines, according to your config.yml definitions. For high availability, use at least three master-eligible nodes. With two, the cluster can stop when one of them stops.

      cluster.initial_cluster_manager_nodes:
      - "indexer"
      #- "node-2"
      #- "node-3"
      

   4. discovery.seed_hosts: List of the addresses of the master-eligible nodes. Each element can be either an IP address or a hostname. You may leave this setting commented if you are configuring the Wazuh indexer as a single-node. For multi-node configurations, uncomment this setting and set the addresses of each master-eligible node.

      discovery.seed_hosts:
      #  - "<WAZUH_INDEXER_1_ADDRESS>"
      #  - "<WAZUH_INDEXER_2_ADDRESS>"
      #  - "<WAZUH_INDEXER_3_ADDRESS>"
      

   5. plugins.security.nodes_dn: the Distinguished Names (DNs) of the certificates of all Wazuh indexer nodes. The package writes this node's DN, so a single node needs no change. In a multi-node cluster, each node knows only its own DN. On every node, list one line per Wazuh indexer node in config.yml. On the first node, also replace the line with the host name that the package wrote. Each entry is C=US,L=California,O=Wazuh,OU=Wazuh,CN= followed by the node's name in config.yml. Keep the fields in this order, because the Security plugin compares each entry as an exact string. The openssl command in Deploying certificates prints this node's subject in that form, so you can check it:

      plugins.security.nodes_dn:
      - "C=US,L=California,O=Wazuh,OU=Wazuh,CN=<NODE_1_NAME>"
      - "C=US,L=California,O=Wazuh,OU=Wazuh,CN=<NODE_2_NAME>"
      

      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.

2. Set the heap size in /etc/wazuh-indexer/jvm.options before you start the service. The package default is 1 GB. With 1 GB, the Wazuh dashboard can fail its first start with circuit_breaking_exception. Use half of the system RAM when the Wazuh indexer runs alone on the host. Use a quarter when the Wazuh manager or Wazuh dashboard also runs there. For example, use -Xms4g and -Xmx4g on a dedicated node with 8 GB of RAM or a shared host with 16 GB. On an all-in-one host with 8 GB, use -Xms2g and -Xmx2g. For a size that is not a whole number of gigabytes, use megabytes, for example -Xms1536m and -Xmx1536m:

   -Xms4g
   -Xmx4g
   

   Where the total heap space:

   • -Xms4g sets the initial size to 4 GB of RAM.

   • -Xmx4g sets the maximum size to 4 GB of RAM.

   Note

   To prevent performance degradation due to JVM heap resizing at runtime, the minimum (Xms) and maximum (Xmx) size values must be the same.

Starting the service

1. Enable and start the Wazuh indexer service. The package neither enables nor starts it, and it has already reloaded systemd:

   SystemdSysV Init

   # systemctl enable --now wazuh-indexer
   

Repeat this stage of the installation process for every Wazuh indexer node in your multi-node cluster. Then proceed with initializing your single-node or multi-node cluster in the next stage.

Before each start, the Wazuh indexer checks its passwords, certificates, owners, and modes. If one is wrong, it does not start, and it writes one line per problem, starting with MISSING, INVALID, or UNSAFE, to its journal. To read them:

# journalctl -u wazuh-indexer --no-pager | grep -E 'MISSING|INVALID|UNSAFE|resolve-credentials'

To run the same checks without starting the service:

# /usr/share/wazuh-indexer/bin/resolve-credentials.sh --check