Wazuh Indexer Technical Documentation

This folder contains the technical documentation for the Wazuh Indexer. The documentation is organized into the following guides:

• Development Guide: Instructions for building, testing, and packaging the Indexer.
• Reference Manual: Detailed information on the Indexer’s architecture, configuration, and usage.

Requirements

To work with this documentation, you need mdBook installed.

• Get the latest cargo (hit enter when prompted for a default install)

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  

• Install mdbook and mdbook-mermaid

  cargo install mdbook
  cargo install mdbook-mermaid
  

Usage

• To build the documentation, run:

  ./build.sh
  

  The output will be generated in the book directory.

• To serve the documentation locally for preview, run:

  ./server.sh
  

  The documentation will be available at http://127.0.0.1:3000.

Development documentation

Under this section, you will find the development documentation of Wazuh Indexer. This documentation contains instructions to compile, run, test and package the source code. Moreover, you will find instructions to set up a development environment in order to get started at developing the Wazuh Indexer.

This documentation assumes basic knowledge of certain tools and technologies, such as Docker, Bash (Linux) or Git.

Set up the development environment

1. Git

Install and configure Git (ssh keys, commits and tags signing, user and email).

1. Set your username.
2. Set your email address.
3. Generate an SSH key.
4. Add the public key to your GitHub account for authentication and signing.
5. Configure Git to sign commits with your SSH key.

2. Repositories

Before you start, you need to properly configure your working repository to have origin and upstream remotes.

• Clone the wazuh-indexer fork

  git clone git@github.com:wazuh-indexer.git
  git remote add upstream git@github.com:opensearch-project/opensearch.git
  

• Clone the wazuh-indexer-reporting fork

  git clone git@github.com:wazuh/wazuh-indexer-reporting.git
  git remote add upstream git@github.com:opensearch-project/reporting.git
  

• Clone the wazuh-indexer-plugins repository

  git clone git@github.com:wazuh/wazuh-indexer-plugins.git
  

3. IntelliJ IDEA

Prepare your IDE:

1. Install IDEA Community Edition as per the official documentation.
2. Set a global SDK to Eclipse Temurin following this guide.

You can find the JDK version to use under the wazuh-indexer/gradle/libs.versions.toml file. IntelliJ IDEA includes some JDKs by default. If you need to change it, or if you want to use a different distribution, follow the instructions on the next section.

4. JDK (Optional)

We use the Eclipse Temurin JDK. To use a different JDK installed on your machine, use sudo update-alternatives --config java to select the JDK of your preference.

Set the JAVA_HOME and PATH environment variables by adding these lines to your Shell RC file (.bashrc, .zsrhrc, …):

export JAVA_HOME=/usr/lib/jvm/temurin-21-jdk-amd64
export PATH=$PATH:/usr/lib/jvm/temurin-21-jdk-amd64/bin

After that, restart your shell or run source ~/.zshrc (or similar) to apply the changes. Finally, check Java is installed correctly by running java --version.

How to generate a package

This guide includes instructions to generate distribution packages locally using Docker.

Wazuh Indexer supports any of these combinations:

• distributions: ['tar', 'deb', 'rpm']
• architectures: ['x64', 'arm64']

Windows is currently not supported.

For more information navigate to the compatibility section.

Before you get started, make sure to clean your environment by running ./gradlew clean on the root level of the wazuh-indexer repository.

Pre-requisites

The process to build packages requires Docker and Docker Compose.

• Install Docker
• Install Docker Compose

Your workstation must meet the minimum hardware requirements (the more resources the better ☺):

• 8 GB of RAM (minimum)
• 4 cores

The tools and source code to generate a package of Wazuh Indexer are hosted in the wazuh-indexer repository, so clone it if you haven't done already.

Building wazuh-indexer packages

The Docker environment under wazuh-indexer/build-scripts/builder automates the build and assemble process for the Wazuh Indexer and its plugins, making it easy to create packages on any system.

Use the builder.sh script to build a package.

./builder.sh -h
Usage: ./builder.sh [args]

Arguments:
-p INDEXER_PLUGINS_BRANCH     [Optional] wazuh-indexer-plugins repo branch, default is 'main'.
-r INDEXER_REPORTING_BRANCH   [Optional] wazuh-indexer-reporting repo branch, default is 'main'.
-R REVISION                   [Optional] Package revision, default is '0'.
-s STAGE                      [Optional] Staging build, default is 'false'.
-d DISTRIBUTION               [Optional] Distribution, default is 'rpm'.
-a ARCHITECTURE               [Optional] Architecture, default is 'x64'.
-D      Destroy the docker environment
-h      Print help

The example below it will generate a wazuh-indexer package for Debian based systems, for the x64 architecture, using 1 as revision number and using the production naming convention.

# Wihtin wazuh-indexer/build-scripts/builder
bash builder.sh -d deb -a x64 -R 1 -s true

The resulting package will be stored at wazuh-indexer/artifacts/dist.

The STAGE option defines the naming of the package. When set to false, the package will be unequivocally named with the commits' SHA of the wazuh-indexer, wazuh-indexer-plugins and wazuh-indexer-reporting repositories, in that order. For example: wazuh-indexer_5.0.0-0_x86_64_aff30960363-846f143-494d125.rpm.

How to generate a container image

This guide includes instructions to generate distribution packages locally using Docker.

Wazuh Indexer supports any of these combinations:

• distributions: ['tar', 'deb', 'rpm']
• architectures: ['x64', 'arm64']

Windows is currently not supported.

For more information navigate to the compatibility section.

Before you get started, make sure to clean your environment by running ./gradlew clean on the root level of the wazuh-indexer repository.

Pre-requisites

The process to build packages requires Docker and Docker Compose.

• Install Docker
• Install Docker Compose

Your workstation must meet the minimum hardware requirements (the more resources the better ☺):

• 8 GB of RAM (minimum)
• 4 cores

The tools and source code to generate a package of Wazuh Indexer are hosted in the wazuh-indexer repository, so clone it if you haven't done already.

Building wazuh-indexer Docker images

The wazuh-indexer/build-scripts/docker folder contains the code to build Docker images. Below there is an example of the command needed to build the image. Set the build arguments and the image tag accordingly.

The Docker image is built from a wazuh-indexer tarball (tar.gz), which must be present in the same folder as the Dockerfile in wazuh-indexer/build-scripts/docker.

docker build \
   --build-arg="VERSION=<version>" \
   --build-arg="INDEXER_TAR_NAME=wazuh-indexer_<version>-<revision>_linux-x64.tar.gz" \
   --tag=wazuh-indexer:<version>-<revision> \
   --progress=plain \
   --no-cache .

Then, start a container with:

docker run -p 9200:9200 -it --rm wazuh-indexer:<version>-<revision>

The build-and-push-docker-image.sh script automates the process to build and push Wazuh Indexer Docker images to our repository in quay.io. The script takes several parameters. Use the -h option to display them.

To push images, credentials must be set at environment level:

• QUAY_USERNAME
• QUAY_TOKEN

Usage: build-scripts/build-and-push-docker-image.sh [args]

Arguments:
-n NAME         [required] Tarball name.
-r REVISION     [Optional] Revision qualifier, default is 0.
-h help

The script will stop if the credentials are not set, or if any of the required parameters are not provided.

This script is used in the 5_builderpackage_docker.yml GitHub Workflow, which is used to automate the process even more. When possible, prefer this method.

How to build from sources

Every Wazuh Indexer repository includes one or more Gradle projects with predefined tasks to run and build the source code.

In this case, to build (compile and zip) a distribution of Wazuh Indexer, run the ./gradlew build command at the root level of the repository. When completed, the distribution artifacts will be located in the build/distributions directory.

How to run from sources

Every Wazuh Indexer repository includes one or more Gradle projects with predefined tasks to run and build the source code.

In this case, to run a Gradle project from source code, run the ./gradlew run command.

For Wazuh Indexer, additional plugins may be installed by passing the -PinstalledPlugins flag:

./gradlew run -PinstalledPlugins="['plugin1', 'plugin2']"

The ./gradlew run command will build and start the project, writing its log above Gradle's status message. A lot of stuff is logged on startup, specifically these lines tell you that OpenSearch is ready.

[2020-05-29T14:50:35,167][INFO ][o.e.h.AbstractHttpServerTransport] [runTask-0] publish_address {127.0.0.1:9200}, bound_addresses {[::1]:9200}, {127.0.0.1:9200}
[2020-05-29T14:50:35,169][INFO ][o.e.n.Node               ] [runTask-0] started

It's typically easier to wait until the console stops scrolling, and then run curl in another window to check if OpenSearch instance is running.

curl localhost:9200

{
  "name" : "runTask-0",
  "cluster_name" : "runTask",
  "cluster_uuid" : "oX_S6cxGSgOr_mNnUxO6yQ",
  "version" : {
    "number" : "1.0.0-SNAPSHOT",
    "build_type" : "tar",
    "build_hash" : "0ba0e7cc26060f964fcbf6ee45bae53b3a9941d0",
    "build_date" : "2021-04-16T19:45:44.248303Z",
    "build_snapshot" : true,
    "lucene_version" : "8.7.0",
    "minimum_wire_compatibility_version" : "6.8.0",
    "minimum_index_compatibility_version" : "6.0.0-beta1"
  }
}

Use -Dtests.opensearch. to pass additional settings to the running instance. For example, to enable OpenSearch to listen on an external IP address, pass -Dtests.opensearch.http.host. Make sure your firewall or security policy allows external connections for this to work.

./gradlew run -Dtests.opensearch.http.host=0.0.0.0

How to run the tests

This section explains how to run the Wazuh Indexer tests.

Full set of tests

To execute all kind of tests, use the command ./gradlew check. This command does not only run tests, but also tasks to check the quality of the code, such as documentation and linter checks.

Unit tests

To run unit tests, use the ./gradlew test command.

Integration tests

To run integration tests, use the ./gradlew integTest and the ./gradlew yamlresttest commands.

Package testing

For package testing, we conduct smoke tests on the packages using the GitHub Actions Workflows. These tests consist on installing the packages on a supported operating system. DEB packages are installed in the “Ubuntu 24.04” runner executing the workflow, while RPM packages are installed in a Red Hat 9 Docker container, as there is no RPM compatible runner available in GitHub Actions.

As a last note, there is also a Vagrantfile and testing scripts in the repository to perform some tests on a real wazuh-indexer service running on a virtual machine. Refer to its README.md for more information about how to run these tests.

Wazuh Indexer Setup Plugin — Development Guide

This document describes how to extend the Wazuh Indexer setup plugin to create new index templates and index management policies (ISM) for OpenSearch.

📦 Creating a New Index

1. Add a New Index Template

Create a new JSON file in the directory: /plugins/setup/src/main/resources

Follow the existing structure and naming convention. Example:

{
  "index_patterns": ["<pattern>"],
  "mappings": {
    "date_detection": false,
    "dynamic": "strict",
    "properties": {
      <custom mappings and fields>
    }
  },
  "order": 1,
  "settings": {
    "index": {
      "number_of_shards": 1,
      "number_of_replicas": 1
    }
  }
}

2. Register the Index in the Code

Edit the constructor of the SetupPlugin class located at: /plugins/setup/src/main/java/com/wazuh/setup/SetupPlugin.java

Add the template and index entry to the indices map. There are two kind of indices:

• Stream index. Stream indices contain time-based events of any kind (alerts, statistics, logs...).
• Stateful index. Stateful indices represent the most recent information of a subject (active vulnerabilities, installed packages, open ports, ...). These indices are different of Stream indices as they do not contain timestamps. The information is not based on time, as they always represent the most recent state.

/**
* Main class of the Indexer Setup plugin. This plugin is responsible for the creation of the index
* templates and indices required by Wazuh to work properly.
*/
public class SetupPlugin extends Plugin implements ClusterPlugin {

  // ...

  // Stream indices
  this.indices.add(new StreamIndex("my-stream-index-000001", "my-index-template-1", "my-alias"));
  // State indices
  this.indices.add(new StateIndex("my-state-index", "my-index-template-2"));

  //...
}

✅ Verifying Template and Index Creation After building the plugin and deploying the Wazuh Indexer with it, you can verify the index templates and indices using the following commands:

curl -X GET <indexer-IP>:9200/_index_template/
curl -X GET <indexer-IP>:9200/_cat/indices?v

Alternatively, use the Developer Tools console from the Wazuh Dashboard, or your browser.

🔁 Creating a New ISM (Index State Management) Policy

1. Add Rollover Alias to the Index Template

Edit the existing index template JSON file and add the following setting:

"plugins.index_state_management.rollover_alias": "<index-name>"

2. Define the ISM Policy

Refer to the OpenSearch ISM Policies documentation for more details.

Here is an example ISM policy:

{
  "policy": {
    "policy_id": "<index-name>-rollover-policy",
    "description": "<policy-description>",
    "last_updated_time": <unix-timestamp-in-milliseconds>,
    "schema_version": 21,
    "error_notification": null,
    "default_state": "rollover",
    "states": [
      {
        "name": "rollover",
        "actions": [
          {
            "rollover": {
              "min_doc_count": 200000000,
              "min_index_age": "7d",
              "min_primary_shard_size": "25gb"
            }
          }
        ],
        "transitions": []
      }
    ],
    "ism_template": [
      {
        "index_patterns": [
          "wazuh-<pattern1>-*"
          // Optional additional patterns
          // "wazuh-<pattern2>-*"
        ],
        "priority": <priority-int>,
        "last_updated_time": <unix-timestamp-in-milliseconds>
      }
    ]
  }
}

3. Register the ISM Policy in the Plugin Code

Edit the IndexStateManagement class located at: /plugins/setup/src/main/java/com/wazuh/setup/index/IndexStateManagement.java

Register the new policy constant and add it in the constructor:

// ISM policy name constant (filename without .json extension)
static final String MY_POLICY = "my-policy-filename";

...

/**
 * Constructor
 *
 * @param index    Index name
 * @param template Index template name
 */
public IndexStateManagement(String index, String template) {
    super(index, template);
    this.policies = new ArrayList<>();

    // Register the ISM policy to be created
    this.policies.add(MY_POLICY);
}

📌 Additional Notes

Always follow existing naming conventions to maintain consistency.

Use epoch timestamps (in milliseconds) for last_updated_time fields.

ISM policies and templates must be properly deployed before the indices are created.

Defining default users and roles for Wazuh Indexer

The Wazuh Indexer packages include a set of default users and roles specially crafted for Wazuh's use cases. This guide provides instructions to extend or modify these users and roles so they end up being included in the Wazuh Indexer package by default.

Note that the access control and permissions management are handled by the OpenSearch's security plugin. As a result, we provide configuration files for it. The data is applied during the cluster's initialization, as a result of running the indexer-security-init.sh script.

Considerations and conventions

As these configuration files are included in the Wazuh Indexer package, they are hosted in the wazuh-indexer repository. Be aware of that when reading this guide.

Any security related resource (roles, action groups, users, ...) created by us must be reserved (reserved: true). This ensures they cannot be modified by the users, in order to guarantee the correct operation of Wazuh Central Components. Also, they should be visible (hidden: false) unless explicitly defined otherwise.

1. Adding a new user

Add the new user to the internal_users.wazuh.yml file located at: wazuh-indexer/distribution/src/config/security/.

new-user:
  # Generate the hash using the tool at `plugins/opensearch-security/tools/hash.sh -p <new-password>`
  hash: "<HASHED-PASSWORD>"
  reserved: true
  hidden: false
  backend_roles: []
  description: "New user description"

OpenSearch's reference:

• internal_users.yml

2. Adding a new role

Add the new role to the roles.wazuh.yml file located at: wazuh-indexer/distribution/src/config/security/.

• Under index_permissions.index_patterns, list the index patterns the role will have effect on.
• Under index_permissions.allowed_actions, list the allowed action groups or indiviual permissions granted to this role.

The default action groups for cluster_permissions and index_permissions are listed in the Default action groups documentation

role-read:
   reserved: true
   hidden: false
   cluster_permissions: []
   index_permissions:
     - index_patterns:
         - "wazuh-*"
       dls: ""
       fls: []
       masked_fields: []
       allowed_actions:
         - "read"
   tenant_permissions: []
   static: true

role-write:
   reserved: true
   hidden: false
   cluster_permissions: []
   index_permissions:
     - index_patterns:
         - "wazuh-*"
       dls: ""
       fls: []
       masked_fields: []
       allowed_actions:
         - "index"
   tenant_permissions: []
   static: true

OpenSearch's reference:

• roles.yml
• action_groups.yml
• Default action groups

3. Adding a new role mapping

Add the new role mapping to roles_mapping.wazuh.yml file located at: wazuh-indexer/distribution/src/config/security/. Note that the mapping name must match the role name.

• Under users, list the users the role will be mapped to.

role-read:
   reserved: true
   hidden: false
   backend_roles: [ ]
   hosts: [ ]
   users:
     - "new-user"
   and_backend_roles: [ ]

role-write:
   reserved: true
   hidden: false
   backend_roles: [ ]
   hosts: [ ]
   users:
     - "new-user"
   and_backend_roles: [ ]

OpenSearch's reference:

• roles_mapping.yml

Testing the configuration

The validation of the new configuration needs to be tested on a running deployment of Wazuh Indexer containing the security plugin.

You can follow any of these paths:

A. Generating a new Wazuh Indexer package

1. Apply your changes to the configuration files in wazuh-indexer/distribution/src/config/security/.
2. Generate a new package (see Build Packages).
3. Follow the official installation and configuration steps.
4. Check the new changes are applied (you can use the UI or the API).

B. Applying the new configuration to an existing Wazuh Indexer deployment (using the UI or API)

1. Use the Wazuh Indexer API or the Wazuh Dashboard to create a new security resource. Follow the steps in Defining users and roles.

C. Applying the new configuration to an existing Wazuh Indexer deployment (using configuration files)

1. Add the new configuration to the affected file within /etc/wazuh-indexer/opensearch-security/.
2. Run the /usr/share/wazuh-indexer/bin/indexer-security-init.sh script to load the new configuration.

Description

The Wazuh indexer is a highly scalable, full-text search and analytics engine. This Wazuh central component indexes and stores alerts generated by the Wazuh server and provides near real-time data search and analytics capabilities. The Wazuh indexer can be configured as a single-node or multi-node cluster, providing scalability and high availability.

The Wazuh indexer stores data as JSON documents. Each document correlates a set of keys, field names or properties, with their corresponding values which can be strings, numbers, booleans, dates, arrays of values, geolocations, or other types of data.

An index is a collection of documents that are related to each other. The documents stored in the Wazuh indexer are distributed across different containers known as shards. By distributing the documents across multiple shards, and distributing those shards across multiple nodes, the Wazuh indexer can ensure redundancy. This protects your system against hardware failures and increases query capacity as nodes are added to a cluster.

The Wazuh indexer stores the data collected by the Wazuh agents in separate indices. Each index contains documents with specific inventory information. In the Indices table section, you can find a description of the information in each index.

Architecture

Compatibility

Supported operating systems

We aim to support as many operating systems as OpenSearch does. Wazuh indexer should work on many Linux distributions, but we only test a handful. The following table lists the operating system versions that we currently support.

For 5.0.0 and above, we support the operating system versions and architectures included in the table below.

OpenSearch

Currently, Wazuh indexer is using version 3.0.0 of OpenSearch.

Requirements

Hardware recommendations

The Wazuh indexer can be installed as a single-node or as a multi-node cluster.

Hardware recommendations for each node

Disk space requirements

The amount of data depends on the generated alerts per second (APS). This table details the estimated disk space needed per agent to store 90 days of alerts on a Wazuh indexer server, depending on the type of monitored endpoints.

For example, for an environment with 80 workstations, 10 servers, and 10 network devices, the storage needed on the Wazuh indexer server for 90 days of alerts is 230 GB.

Packages

Please refer to this section for information pertaining to compatibility.

Installation

Installing the Wazuh indexer step by step

Install and configure the Wazuh indexer as a single-node or multi-node cluster, following step-by-step instructions. The installation process is divided into three stages.

1. Certificates creation

2. Nodes installation

3. Cluster initialization

Note You need root user privileges to run all the commands described below.

1. Certificates creation

Generating the SSL certificates

1. Download the wazuh-certs-tool.sh script and the config.yml configuration file. This creates the certificates that encrypt communications between the Wazuh central components.

   curl -sO https://packages-dev.wazuh.com/5.0/wazuh-certs-tool.sh
   curl -sO https://packages-dev.wazuh.com/5.0/config.yml
   

2. Edit ./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 server, Wazuh indexer, and Wazuh dashboard nodes. Add as many node fields as needed.

   nodes:
     # Wazuh indexer nodes
     indexer:
       - name: node-1
         ip: "<indexer-node-ip>"
       #- name: node-2
       #  ip: "<indexer-node-ip>"
       #- name: node-3
       #  ip: "<indexer-node-ip>"
   
     # Wazuh server nodes
     # If there is more than one Wazuh server
     # node, each one must have a node_type
     server:
       - name: wazuh-1
         ip: "<wazuh-manager-ip>"
       #  node_type: master
       #- name: wazuh-2
       #  ip: "<wazuh-manager-ip>"
       #  node_type: worker
       #- name: wazuh-3
       #  ip: "<wazuh-manager-ip>"
       #  node_type: worker
   
     # Wazuh dashboard nodes
     dashboard:
       - name: dashboard
         ip: "<dashboard-node-ip>"
   

   To learn more about how to create and configure the certificates, see the Certificates deployment section.

3. Run ./wazuh-certs-tool.sh to create the certificates. For a multi-node cluster, these certificates need to be later deployed to all Wazuh instances in your cluster.

   ./wazuh-certs-tool.sh -A
   

4. Compress all the necessary files.

   tar -cvf ./wazuh-certificates.tar -C ./wazuh-certificates/ .
   rm -rf ./wazuh-certificates
   

5. Copy the wazuh-certificates.tar file to all the nodes, including the Wazuh indexer, Wazuh server, and Wazuh dashboard nodes. This can be done by using the scp utility.

2. Nodes installation

Installing package dependencies

Install the following packages if missing:

Yum

yum install coreutils

APT

apt-get install debconf adduser procps

Adding the Wazuh repository

Yum

1. Import the GPG key.

   rpm --import https://packages.wazuh.com/key/GPG-KEY-WAZUH
   

2. Add the repository.

   echo -e '[wazuh]\ngpgcheck=1\ngpgkey=https://packages.wazuh.com/key/GPG-KEY-WAZUH\nenabled=1\nname=EL-$releasever - Wazuh\nbaseurl=https://packages.wazuh.com/5.x/yum/\nprotect=1' | tee /etc/yum.repos.d/wazuh.repo
   

APT

1. Install the following packages if missing.

   apt-get install gnupg apt-transport-https
   

2. Install the GPG key.

   curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | gpg --no-default-keyring --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg --import && chmod 644 /usr/share/keyrings/wazuh.gpg
   

3. Add the repository.

   echo "deb [signed-by=/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/5.x/apt/ stable main" | tee -a /etc/apt/sources.list.d/wazuh.list
   

4. Update the packages information.

   apt-get update
   

Installing the Wazuh indexer package

Yum

yum -y install wazuh-indexer

APT

apt-get -y install wazuh-indexer

Configuring the Wazuh indexer

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

a. network.host: Sets the address of this node for both HTTP and transport traffic. The node will bind to this address and 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.

b. node.name: Name of the Wazuh indexer node as defined in the config.yml file. For example, node-1.

c. cluster.initial_cluster_manager_nodes: List of the names of the master-eligible nodes. These names are defined in the config.yml file. Uncomment the node-2 and config.yml and node-3lines, change the names, or add more lines, according to your onfig.yml`definitions.

cluster.initial_cluster_manager_nodes:
- "node-1"
- "node-2"
- "node-3"

d. 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 IP addresses of each master-eligible node.

discovery.seed_hosts:
- "10.0.0.1"
- "10.0.0.2"
- "10.0.0.3"

e. plugins.security.nodes_dn: List of the Distinguished Names of the certificates of all the Wazuh indexer cluster nodes. Uncomment the lines for node-2 and node-3 and change the common names (CN) and values according to your settings and your config.yml definitions.

plugins.security.nodes_dn:
- "CN=node-1,OU=Wazuh,O=Wazuh,L=California,C=US"
- "CN=node-2,OU=Wazuh,O=Wazuh,L=California,C=US"
- "CN=node-3,OU=Wazuh,O=Wazuh,L=California,C=US"

Deploying certificates

Note: Make sure that a copy of the nazuh-certificates.tar file, created during the initial configuration step, is placed in your working directory.

Run the following commands, replacing <INDEXER_NODE_NAME> with the name of the Wazuh indexer node you are configuring as defined in config.yml. For example, node-1. This deploys the SSL certificates to encrypt communications between the Wazuh central components.

NODE_NAME=<INDEXER_NODE_NAME>

mkdir /etc/wazuh-indexer/certs
tar -xf ./wazuh-certificates.tar -C /etc/wazuh-indexer/certs/ ./$NODE_NAME.pem ./$NODE_NAME-key.pem ./admin.pem ./admin-key.pem ./root-ca.pem
mv -n /etc/wazuh-indexer/certs/$NODE_NAME.pem /etc/wazuh-indexer/certs/indexer.pem
mv -n /etc/wazuh-indexer/certs/$NODE_NAME-key.pem /etc/wazuh-indexer/certs/indexer-key.pem
chmod 500 /etc/wazuh-indexer/certs
chmod 400 /etc/wazuh-indexer/certs/*
chown -R wazuh-indexer:wazuh-indexer /etc/wazuh-indexer/certs

Starting the service

Enable and start the Wazuh indexer service.

Systemd

systemctl daemon-reload
systemctl enable wazuh-indexer
systemctl start wazuh-indexer

SysV init

Choose one option according to the operating system used.

a. RPM-based operating system:

chkconfig --add wazuh-indexer
service wazuh-indexer start

b. Debian-based operating system:

update-rc.d wazuh-indexer defaults 95 10
service wazuh-indexer start

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

3. Cluster initialization

Run the Wazuh indexer indexer-security-init.sh script on any Wazuh indexer node to load the new certificates information and start the single-node or multi-node cluster.

/usr/share/wazuh-indexer/bin/indexer-security-init.sh

Note: You only have to initialize the cluster once, there is no need to run this command on every node.

Testing the cluster installation

1. Replace <WAZUH_INDEXER_IP_ADDRESS> and run the following commands to confirm that the installation is successful.

   curl -k -u admin:admin https://<WAZUH_INDEXER_IP_ADRESS>:9200
   

   Output

   {
     "name" : "node-1",
     "cluster_name" : "wazuh-cluster",
     "cluster_uuid" : "095jEW-oRJSFKLz5wmo5PA",
     "version" : {
       "number" : "7.10.2",
       "build_type" : "rpm",
       "build_hash" : "db90a415ff2fd428b4f7b3f800a51dc229287cb4",
       "build_date" : "2023-06-03T06:24:25.112415503Z",
       "build_snapshot" : false,
       "lucene_version" : "9.6.0",
       "minimum_wire_compatibility_version" : "7.10.0",
       "minimum_index_compatibility_version" : "7.0.0"
     },
     "tagline" : "The OpenSearch Project: https://opensearch.org/"
   }
   

2. Replace <WAZUH_INDEXER_IP_ADDRESS> and run the following command to check if the single-node or multi-node cluster is working correctly.

   curl -k -u admin:admin https://<WAZUH_INDEXER_IP_ADDRESS>:9200/_cat/nodes?v
   

Configuration Files

Initialization plugin settings

Timeout for the OpenSearch client

• Key: plugins.setup.timeout
• Type: Integer
• Default: 30
• Minimum: 5
• Maximum: 120
• Description: Timeout in seconds for index and search operations.

Backoff (delay) for the retry mechanism

• Key: plugins.setup.backoff
• Type: Integer
• Default: 15
• Minimum: 5
• Maximum: 60
• Description: Delay in seconds for the retry mechanism involving initialization tasks.

Example

Below, there is an example of custom values for these settings within the opensearch.yml file:

plugins.setup.timeout: 60
plugins.setup.backoff: 30

Security - Access Control

Wazuh Indexer uses the OpenSearch Security plugin to manage access control and security features.

The configuration files for the security plugin are located under the /etc/wazuh-indexer/opensearch-security/ directory by default.

Among these files, Wazuh Indexer uses these particularly to add its own security resources:

• internal_users.yml: Defines the internal users for the Wazuh Indexer. Each user has a hashed password, reserved status, backend roles, and a description.

• roles.yml: Defines the roles and their permissions within the Wazuh Indexer. Each role specifies the cluster permissions, index permissions, and tenant permissions.

• roles_mapping.yml: Maps users and backend roles to the defined roles. This file specifies which users or backend roles have access to each role.

The Access Control section contains information about the security resources added to the Wazuh Indexer by default.

Wazuh Indexer Initialization plugin

The wazuh-indexer-setup plugin is a module composing the Wazuh Indexer responsible for the initialization of the indices required by Wazuh to store all the data gathered and generated by other Central Components, such as the agents and the server (engine).

The Wazuh Indexer Setup Plugin in responsible for:

• Create the index templates, to define the mappings and settings of the indices.
• Create the initial indices. We distinguish between stateful and stateless indices. Stateful indices are unique, and its data is update over time (agents' inventory), stateless indices are rotated and static (alerts).
• For stateless indices, it creates the indices aliases and lifecycle policies for rollover.

Indices

The following table lists the indices created by this plugin.

Install

The wazuh-indexer-setup plugin is part of the official Wazuh Indexer packages and is installed by default. However, to manually install the plugin, follow the next steps.

Note: You need to use the wazuh-indexer or root user to run these commands.

/usr/share/wazuh-indexer/bin/opensearch-plugin install file://[absolute-path-to-the-plugin-zip]

Once installed, restart the Wazuh Indexer service.

Uninstall

Note You need to use the wazuh-indexer or root user to run these commands.

To list the installed plugins, run: /usr/share/wazuh-indexer/bin/opensearch-plugin list

To remove a plugin, use its name as a parameter with the remove command: /usr/share/wazuh-indexer/bin/opensearch-plugin remove <plugin-name>

/usr/share/wazuh-indexer/bin/opensearch-plugin remove wazuh-indexer-setup

Architecture

Design

The plugin implements the ClusterPlugin interface in order to be able to hook into the node’s lifecycle overriding the onNodeStarted() method.

The SetupPlugin class holds the list of indices to create. The logic for the creation of the index templates and the indices is encapsulated in the Index abstract class. Each subclass can override this logic if necessary. The SetupPlugin::onNodeStarted() method invokes the Index::initialize() method, effectively creating every index in the list.

By design, the plugin will overwrite any existing index template under the same name.

Retry mechanism

The plugin features a retry mechanism to handle transient faults. In case of a temporal failure (timeouts or similar) during the initialization of the indices, the task is retried after a given amount of time (backoff). If two consecutive faults occur during the initialization of the same index, the initialization process is halted, and the node is shut down. Proper logging is in place to notify administrators before the shutdown occurs.

The backoff time is configurable. Head to Configuration Files for more information.

Class diagram

---
title: Wazuh Indexer setup plugin
---
classDiagram
    %% Classes
    class IndexInitializer
    <<interface>> IndexInitializer
    class Index
    <<abstract>> Index
    class IndexStateManagement
    class WazuhIndex
    <<abstract>> WazuhIndex
    class StateIndex
    class StreamIndex

    %% Relations
    IndexInitializer <|-- Index : implements
    Index <|-- IndexStateManagement
    Index <|-- WazuhIndex
    WazuhIndex <|-- StateIndex
    WazuhIndex <|-- StreamIndex

    %% Schemas
    class IndexInitializer {
        +createIndex(String index) void
        +createTemplate(String template) void
    }
    class Index {
        Client client
        ClusterService clusterService
        IndexUtils utils
        String index
        String template
        +Index(String index, String template)
        +setClient(Client client) IndexInitializer
        +setClusterService(ClusterService clusterService) IndexInitializer
        +setIndexUtils(IndexUtils utils) IndexInitializer
        +indexExists(String indexName) bool
        +initialize() void
        +createIndex(String index) void
        +createTemplate(String template) void
        %% initialize() podría reemplazarse por createIndex() y createTemplate()
    }
    class IndexStateManagement {
        -List~String~ policies
        +initialize() void
        -createPolicies() void
        -indexPolicy(String policy) void
    }
    class WazuhIndex {
    }
    class StreamIndex {
        -String alias
        +StreamIndex(String index, String template, String alias)
        +createIndex(String index)
    }
    class StateIndex {
    }

Sequence diagram

Note Calls to Client are asynchronous.

sequenceDiagram
    actor Node
    participant SetupPlugin
    participant Index
    participant Client
    Node->>SetupPlugin: plugin.onNodeStarted()
    activate SetupPlugin
    Note over Node,SetupPlugin: Invoked on Node::start()

    activate Index
    loop i..n indices
        SetupPlugin->>Index: i.initialize()


        Index-)Client: createTemplate(i)
        Client--)Index: response

        Index-)Client: indexExists(i)
        Client--)Index: response
        alt index i does not exist
            Index-)Client: createIndex(i)
            Client--)Index: response
        end
    end

    deactivate Index
    deactivate SetupPlugin

Wazuh Common Schema

Refer to the docs for complete definitions of the indices. The indices inherit the settings and mappings defined in the index templates.

JavaDoc

The plugin is documented using JavaDoc. You can compile the documentation using the Gradle task for that purpose. The generated JavaDoc is in the build/docs folder.

./gradlew javadoc

Upgrade

This section guides you through the upgrade process of the Wazuh indexer.

Preparing the upgrade

In case Wazuh is installed in a multi-node cluster configuration, repeat the following steps for every node.

Ensure you have added the Wazuh repository to every Wazuh indexer node before proceeding to perform the upgrade actions.

Yum

1. Import the GPG key.

   rpm --import https://packages.wazuh.com/key/GPG-KEY-WAZUH
   

2. Add the repository.

   echo -e '[wazuh]\ngpgcheck=1\ngpgkey=https://packages.wazuh.com/key/GPG-KEY-WAZUH\nenabled=1\nname=EL-$releasever - Wazuh\nbaseurl=https://packages.wazuh.com/5.x/yum/\nprotect=1' | tee /etc/yum.repos.d/wazuh.repo
   

APT

1. Install the following packages if missing.

   apt-get install gnupg apt-transport-https
   

2. Install the GPG key.

   curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | gpg --no-default-keyring --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg --import && chmod 644 /usr/share/keyrings/wazuh.gpg
   

3. Add the repository.

   echo "deb [signed-by=/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/5.x/apt/ stable main" | tee -a /etc/apt/sources.list.d/wazuh.list
   

4. Update the packages information.

   apt-get update
   

Upgrading the Wazuh indexer

The Wazuh indexer cluster remains operational throughout the upgrade. The rolling upgrade process allows nodes to be updated one at a time, ensuring continuous service availability and minimizing disruptions. The steps detailed in the following sections apply to both single-node and multi-node Wazuh indexer clusters.

Preparing the Wazuh indexer cluster for upgrade

Perform the following steps on any of the Wazuh indexer nodes replacing <WAZUH_INDEXER_IP_ADDRESS>, <USERNAME>, and <PASSWORD>.

1. Disable shard replication to prevent shard replicas from being created while Wazuh indexer nodes are being taken offline for the upgrade.

   curl -X PUT "https://:9200/_cluster/settings" \
   -u : -k -H "Content-Type: application/json" -d '
   {
   "persistent": {
       "cluster.routing.allocation.enable": "primaries"
   }
   }'
   

   Output

   {
       "acknowledged" : true,
       "persistent" : {
         "cluster" : {
           "routing" : {
             "allocation" : {
               "enable" : "primaries"
             }
           }
         }
       },
       "transient" : {}
       }
   

2. Perform a flush operation on the cluster to commit transaction log entries to the index.

   curl -X POST "https://<WAZUH_INDEXER_IP_ADDRESS>:9200/_flush" -u <USERNAME>:<PASSWORD> -k
   

   Output

   {
   "_shards" : {
       "total" : 19,
       "successful" : 19,
       "failed" : 0
      }
   }
   

Upgrading the Wazuh indexer nodes

1. Stop the Wazuh indexer service.

   Systemd

   systemctl stop wazuh-indexer
   

   SysV init

   service wazuh-indexer stop
   

2. Upgrade the Wazuh indexer to the latest version.

   Yum

   yum upgrade wazuh-indexer
   

   APT

   apt-get install wazuh-indexer
   

3. Restart the Wazuh indexer service.

   Systemd

   systemctl daemon-reload
   systemctl enable wazuh-indexer
   systemctl start wazuh-indexer
   

   SysV init

   Choose one option according to the operating system used.

   a. RPM-based operating system:

   chkconfig --add wazuh-indexer
   service wazuh-indexer start
   

   b. Debian-based operating system:

   update-rc.d wazuh-indexer defaults 95 10
   service wazuh-indexer start
   

Repeat steps 1 to 3 above on all Wazuh indexer nodes before proceeding to the post-upgrade actions.

Post-upgrade actions

Perform the following steps on any of the Wazuh indexer nodes replacing <WAZUH_INDEXER_IP_ADDRESS>, <USERNAME>, and <PASSWORD>.

1. Check that the newly upgraded Wazuh indexer nodes are in the cluster.

   curl -k -u <USERNAME>:<PASSWORD> https://<WAZUH_INDEXER_IP_ADDRESS>:9200/_cat/nodes?v
   

2. Re-enable shard allocation.

   # curl -X PUT "https://<WAZUH_INDEXER_IP_ADDRESS>:9200/_cluster/settings" \
   -u <USERNAME>:<PASSWORD> -k -H "Content-Type: application/json" -d '
   {
       "persistent": {
           "cluster.routing.allocation.enable": "all"
       }
   }
   '
   

   Output

   {
       "acknowledged" : true,
       "persistent" : {
           "cluster" : {
           "routing" : {
               "allocation" : {
               "enable" : "all"
               }
           }
           }
       },
       "transient" : {}
   }
   

3. Check the status of the Wazuh indexer cluster again to see if the shard allocation has finished.

   curl -k -u <USERNAME>:<PASSWORD> https://<WAZUH_INDEXER_IP_ADDRESS>:9200/_cat/nodes?v
   

   Output

   ip         heap.percent ram.percent cpu load_1m load_5m load_15m node.role node.roles                                        cluster_manager name
   172.18.0.3           34          86  32    6.67    5.30     2.53 dimr      cluster_manager,data,ingest,remote_cluster_client -               wazuh2.indexer
   172.18.0.4           21          86  32    6.67    5.30     2.53 dimr      cluster_manager,data,ingest,remote_cluster_client *               wazuh1.indexer
   172.18.0.2           16          86  32    6.67    5.30     2.53 dimr      cluster_manager,data,ingest,remote_cluster_client -               wazuh3.indexer
   

Uninstall

Note You need root user privileges to run all the commands described below.

Yum

yum remove wazuh-indexer -y
rm -rf /var/lib/wazuh-indexer/
rm -rf /usr/share/wazuh-indexer/
rm -rf /etc/wazuh-indexer/

APT

apt-get remove --purge wazuh-indexer -y

Backup and restore

In this section you can find instructions on how to create and restore a backup of your Wazuh Indexer key files, preserving file permissions, ownership, and path. Later, you can move this folder contents back to the corresponding location to restore your certificates and configurations. Backing up these files is useful in cases such as moving your Wazuh installation to another system.

Note: This backup only restores the configuration files, not the data. To backup data stored in the indexer, use snapshots.

Creating a backup

To create a backup of the Wazuh indexer, follow these steps. Repeat them on every cluster node you want to back up.

Note: You need root user privileges to run all the commands described below.

Preparing the backup

1. Create the destination folder to store the files. For version control, add the date and time of the backup to the name of the folder.

   bkp_folder=~/wazuh_files_backup/$(date +%F_%H:%M)
   mkdir -p $bkp_folder && echo $bkp_folder
   

2. Save the host information.

   cat /etc/*release* > $bkp_folder/host-info.txt
   echo -e "\n$(hostname): $(hostname -I)" >> $bkp_folder/host-info.txt
   

Backing up the Wazuh indexer

Back up the Wazuh indexer certificates and configuration

rsync -aREz \
/etc/wazuh-indexer/certs/ \
/etc/wazuh-indexer/jvm.options \
/etc/wazuh-indexer/jvm.options.d \
/etc/wazuh-indexer/log4j2.properties \
/etc/wazuh-indexer/opensearch.yml \
/etc/wazuh-indexer/opensearch.keystore \
/etc/wazuh-indexer/opensearch-observability/ \
/etc/wazuh-indexer/opensearch-reports-scheduler/ \
/etc/wazuh-indexer/opensearch-security/ \
/usr/lib/sysctl.d/wazuh-indexer.conf $bkp_folder

Compress the files and transfer them to the new server:

```bash
tar -cvzf wazuh_central_components.tar.gz ~/wazuh_files_backup/
```

Restoring Wazuh indexer from backup

This guide explains how to restore a backup of your configuration files.

Note: This guide is designed specifically for restoration from a backup of the same version.

Note: For a multi-node setup, there should be a backup file for each node within the cluster. You need root user privileges to execute the commands below.

Preparing the data restoration

1. In the new node, move the compressed backup file to the root / directory:

   mv wazuh_central_components.tar.gz /
   cd /
   

2. Decompress the backup files and change the current working directory to the directory based on the date and time of the backup files:

   tar -xzvf wazuh_central_components.tar.gz
   cd ~/wazuh_files_backup/<DATE_TIME>
   

Restoring Wazuh indexer files

Perform the following steps to restore the Wazuh indexer files on the new server.

1. Stop the Wazuh indexer to prevent any modifications to the Wazuh indexer files during the restoration process:

   systemctl stop wazuh-indexer
   

2. Restore the Wazuh indexer configuration files and change the file permissions and ownerships accordingly:

   sudo cp etc/wazuh-indexer/jvm.options /etc/wazuh-indexer/jvm.options
   chown wazuh-indexer:wazuh-indexer /etc/wazuh-indexer/jvm.options
   sudo cp -r etc/wazuh-indexer/jvm.options.d/* /etc/wazuh-indexer/jvm.options.d/
   chown wazuh-indexer:wazuh-indexer /etc/wazuh-indexer/jvm.options.d
   sudo cp etc/wazuh-indexer/log4j2.properties /etc/wazuh-indexer/log4j2.properties
   chown wazuh-indexer:wazuh-indexer /etc/wazuh-indexer/log4j2.properties
   sudo cp etc/wazuh-indexer/opensearch.keystore /etc/wazuh-indexer/opensearch.keystore
   chown wazuh-indexer:wazuh-indexer /etc/wazuh-indexer/opensearch.keystore
   sudo cp -r etc/wazuh-indexer/opensearch-observability/* /etc/wazuh-indexer/opensearch-observability/
   chown -R wazuh-indexer:wazuh-indexer /etc/wazuh-indexer/opensearch-observability/
   sudo cp -r etc/wazuh-indexer/opensearch-reports-scheduler/* /etc/wazuh-indexer/opensearch-reports-scheduler/
   chown -R wazuh-indexer:wazuh-indexer /etc/wazuh-indexer/opensearch-reports-scheduler/
   sudo cp usr/lib/sysctl.d/wazuh-indexer.conf /usr/lib/sysctl.d/wazuh-indexer.conf
   

3. Start the Wazuh indexer service:

   systemctl start wazuh-indexer
   

Access Control

Wazuh Indexer uses the OpenSearch Security plugin to manage access control and security features. This allows you to define users, roles, and permissions for accessing indices and performing actions within the Wazuh Indexer.

You can find a more detailed overview of the OpenSearch Security plugin in the OpenSearch documentation.

Wazuh default Internal Users

Wazuh defines internal users and roles for the different Wazuh components to handle index management.

These default users and roles definitions are stored in the internal_users.yml, roles.yml, and roles_mapping.yml files on the /etc/wazuh-indexer/opensearch-security/ directory.

Find more info about the configurations files in the Configuration Files section.

Users

Roles

Defining Users and Roles

You can create and manage users and roles through the Wazuh Dashboard UI.

Creating a New User, Role, and Role Mapping via the Wazuh Dashboard

Prerequisites

• You must be logged in as a user with administrative privileges (e.g., admin).

Follow these steps:

1. Create a Role

1. In the Wazuh Dashboard, go to Index Management -> Security -> Roles.
2. Click Create role.
3. Enter a Role name (e.g., custom-read-write).
4. Under Cluster permissions, select permissions if needed.
5. Under Index permissions:
   • Index: e.g., wazuh-*
   • Index permissions: choose appropriate actions such as:
     • read (to allow read access)
     • index (to allow write access)
   • Optionally, configure Document-level security (DLS) or Field-level security (FLS).
6. Click Create to save the role.

2. Create a User

1. In the Wazuh Dashboard, go to Index Management -> Security -> Internal users.
2. Click Create internal user.
3. Fill in the following:
   • Username (e.g., new-user)
   • Password (enter and confirm)
   • Description (optional)
4. Click Create to create the user.

3. Verify Role Mapping

When you assign a role to a user during creation, the mapping is created automatically. To review or edit:

1. In Security, go to Roles.
2. Find and click your role (custom-read-write).
3. Go to Mapped users
4. Click Map users.
5. Fill in the following:
   • Users (e.g., new-user).
   • Backend roles (optional).
6. Click Map to save the mapping.

4. Test Access

After creating the user and role:

1. Log out from the Dashboard.
2. Log in with the new user's credentials.
3. Navigate to Index Management -> Dev Tools.
4. Run a query to test access, such as:

   GET /wazuh-*/_search
   

Additional Resources

• OpenSearch Security Plugin - User Management
• OpenSearch Security Plugin - Roles