Wazuh central components

This section guides you through the upgrade process of the Wazuh indexer, the Wazuh server, and the Wazuh dashboard.

  • All-in-one deployments: Execute all commands and configuration actions on the same node since all components run on a single system.

  • Multi-node cluster deployments: Run commands and apply configurations on the respective node where the component being upgraded is located.

Preparing the upgrade

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

  1. Ensure you have added the Wazuh repository to every Wazuh indexer, server, and dashboard node before proceeding to perform the upgrade actions.

    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/4.x/yum/\nprotect=1' | tee /etc/yum.repos.d/wazuh.repo
      
  2. Stop the Filebeat and Wazuh dashboard services if installed in the node.

    # systemctl stop filebeat
    # systemctl stop wazuh-dashboard
    

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://<WAZUH_INDEXER_IP_ADDRESS>:9200/_cluster/settings" \
    -u <USERNAME>:<PASSWORD> -k -H "Content-Type: application/json" -d '
    {
       "persistent": {
          "cluster.routing.allocation.enable": "primaries"
       }
    }'
    
    {
      "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
    
    {
       "_shards" : {
          "total" : 19,
          "successful" : 19,
          "failed" : 0
       }
    }
    
  3. Run the following command on the Wazuh manager node(s) if running a single-node Wazuh indexer cluster.

    # systemctl stop wazuh-manager
    

Upgrading the Wazuh indexer nodes

Perform the following steps on each Wazuh indexer node to upgrade them. Upgrade nodes with the cluster_manager role last to maintain cluster connectivity among online nodes.

Note

You can check the role of Wazuh indexer nodes in the cluster using the following command:

# curl -k -u <USERNAME>:<PASSWORD> https://<WAZUH_INDEXER_IP_ADDRESS>:9200/_cat/nodes?v
  1. Stop the Wazuh indexer service.

    # systemctl stop wazuh-indexer
    
  2. Upgrade the Wazuh indexer to the latest version.

    # yum upgrade wazuh-indexer
    
  3. Restart the Wazuh indexer service.

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

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"
       }
    }
    '
    
    {
      "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
    
    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
    
  4. Run the following command on the Wazuh manager node(s) to start the Wazuh manager service if you stopped it earlier.

    # systemctl start wazuh-manager
    

Note

Note that the upgrade process doesn't update plugins installed manually. Outdated plugins might cause the upgrade to fail.

  1. Run the following command on each Wazuh indexer node to list installed plugins and identify those that require an update:

    # /usr/share/wazuh-indexer/bin/opensearch-plugin list
    

    In the output, plugins that require an update will be labeled as "outdated".

  2. Remove the outdated plugins and reinstall the latest version replacing <PLUGIN_NAME> with the name of the plugin:

    # /usr/share/wazuh-indexer/bin/opensearch-plugin remove <PLUGIN_NAME>
    # /usr/share/wazuh-indexer/bin/opensearch-plugin install <PLUGIN_NAME>
    

Upgrading the Wazuh server

When upgrading a multi-node Wazuh manager cluster, run the upgrade in every node. Start with the master node to reduce server downtime. To successfully upgrade the Wazuh server, follow these steps in order:

  1. Upgrade the Wazuh manager.

  2. Configure the vulnerability detection. (if required based on the version you are upgrading from).

  3. Configure Filebeat.

Note

Upgrading from Wazuh 4.2.x or lower creates the wazuh operating system user and group to replace ossec. To avoid upgrade conflicts, make sure that the wazuh user and group are not present in your operating system.

Upgrading the Wazuh manager

Upgrade the Wazuh manager to the latest version:

# yum upgrade wazuh-manager

Warning

If the /var/ossec/etc/ossec.conf configuration file was modified, it will not be replaced by the upgrade. You will therefore have to add the settings of the new capabilities manually. More information can be found in the User manual.

Configuring vulnerability detection

If upgrading from version 4.8.x or later, skip the vulnerability detection configuration and proceed to Configuring Filebeat. No action is needed as the vulnerability detection block is already configured.

When upgrading from Wazuh version 4.7.x or earlier, follow these steps to configure the vulnerability detection block.

  1. Update the configuration file

    Edit the /var/ossec/etc/ossec.conf file to include the new <vulnerability-detection> block. Remove the old <vulnerability-detector> block if it exists.

    The updated configuration enables the Wazuh Vulnerability Detection module to index vulnerabilities and alerts, with the vulnerability feed refreshing every 60 minutes. Add the following block to the configuration file:

    <vulnerability-detection>
       <enabled>yes</enabled>
       <index-status>yes</index-status>
       <feed-update-interval>60m</feed-update-interval>
    </vulnerability-detection>
    
  2. Configure the indexer block

    1. Ensure the <indexer> block contains the details of your Wazuh indexer host. During the upgrade, a default <indexer> configuration is added under <ossec_conf> if none exists in /var/ossec/etc/ossec.conf. By default, the configuration includes one host with the IP address 0.0.0.0:

      <indexer>
         <enabled>yes</enabled>
         <hosts>
            <host>https://0.0.0.0:9200</host>
         </hosts>
         <ssl>
            <certificate_authorities>
               <ca>/etc/filebeat/certs/root-ca.pem</ca>
            </certificate_authorities>
            <certificate>/etc/filebeat/certs/filebeat.pem</certificate>
            <key>/etc/filebeat/certs/filebeat-key.pem</key>
         </ssl>
      </indexer>
      

      Replace 0.0.0.0 with the IP address or hostname of your Wazuh indexer node. You can find this value in the Filebeat configuration file at /etc/filebeat/filebeat.yml. Ensure that the <certificate> and <key> names match the files located in /etc/filebeat/certs/.

    2. If using a Wazuh indexer cluster, add a <host> entry in the Wazuh manager /var/ossec/etc/ossec.conf file for each node in the cluster. For example, for a two-node configuration:

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

      The Wazuh server will prioritize reporting to the first indexer node in the list and switch to the next available node if it becomes unavailable.

  3. Store Wazuh indexer credentials

    Save the Wazuh indexer username and password into the Wazuh manager keystore using the Wazuh-keystore tool:

    # echo '<INDEXER_USERNAME>' | /var/ossec/bin/wazuh-keystore -f indexer -k username
    # echo '<INDEXER_PASSWORD>' | /var/ossec/bin/wazuh-keystore -f indexer -k password
    

    If you have forgotten your Wazuh indexer password, refer to the password management guide to reset it.

Configuring Filebeat

When upgrading Wazuh, you must also update the Wazuh Filebeat module and the alerts template to ensure compatibility with the latest Wazuh indexer version. Follow these steps to configure Filebeat properly:

  1. Download the Wazuh module for Filebeat:

    # curl -s https://packages.wazuh.com/4.x/filebeat/wazuh-filebeat-0.4.tar.gz | sudo tar -xvz -C /usr/share/filebeat/module
    
  2. Download the alerts template:

    # curl -so /etc/filebeat/wazuh-template.json https://raw.githubusercontent.com/wazuh/wazuh/v4.10.1/extensions/elasticsearch/7.x/wazuh-template.json
    # chmod go+r /etc/filebeat/wazuh-template.json
    
  3. Restart Filebeat:

    # systemctl daemon-reload
    # systemctl enable filebeat
    # systemctl start filebeat
    
  4. Upload the new Wazuh template and pipelines for Filebeat:

    # filebeat setup --pipelines
    # filebeat setup --index-management -E output.logstash.enabled=false
    
  5. If you are upgrading from Wazuh versions v4.8.x or v4.9.x, manually update the wazuh-states-vulnerabilities-* mappings using the following command. Replace <WAZUH_INDEXER_IP_ADDRESS>, <USERNAME>, and <PASSWORD> with the values applicable to your deployment.

    Skip this step if upgrading from other versions.

    curl -X PUT "https://<WAZUH_INDEXER_IP_ADDRESS>:9200/wazuh-states-vulnerabilities-*/_mapping" \
    -u <USERNAME>:<PASSWORD> -k -H "Content-Type: application/json" -d '
    {
       "properties": {
          "vulnerability": {
             "properties": {
                "under_evaluation": {
                   "type": "boolean"
                },
                "scanner": {
                   "properties": {
                      "source": {
                         "type": "keyword",
                         "ignore_above": 1024
                      }
                   }
                }
             }
          }
       }
    }
    '
    

Upgrading the Wazuh dashboard

Backup the /etc/wazuh-dashboard/opensearch_dashboards.yml file to save your settings. For example, create a copy of the file using the following command:

# cp /etc/wazuh-dashboard/opensearch_dashboards.yml /etc/wazuh-dashboard/opensearch_dashboards.yml.old
  1. Upgrade the Wazuh dashboard.

    # yum upgrade wazuh-dashboard
    
  2. Manually reapply any configuration changes to the /etc/wazuh-dashboard/opensearch_dashboards.yml file. Ensure that the values of server.ssl.key and server.ssl.certificate match the files located in /etc/wazuh-dashboard/certs/.

  3. Ensure the value of uiSettings.overrides.defaultRoute in the /etc/wazuh-dashboard/opensearch_dashboards.yml file is set to /app/wz-home as shown below:

    uiSettings.overrides.defaultRoute: /app/wz-home
    
  4. Restart the Wazuh dashboard:

    # systemctl daemon-reload
    # systemctl enable wazuh-dashboard
    # systemctl start wazuh-dashboard
    

You can now access the Wazuh dashboard via: https://<DASHBOARD_IP_ADDRESS>/app/wz-home.

Note

Note that the upgrade process doesn't update plugins installed manually. Outdated plugins might cause the upgrade to fail.

  1. Run the following command on the Wazuh dashboard server to list installed plugins and identify those that require an update:

    # sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin list
    

    In the output, plugins that require an update will be labeled as "outdated".

  2. Remove the outdated plugins and reinstall the latest version replacing <PLUGIN_NAME> with the name of the plugin:

    # sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin remove <PLUGIN_NAME>
    # sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin install <PLUGIN_NAME>
    

Next steps

The Wazuh server, indexer, and dashboard are now successfully upgraded. You can verify the versions by running the following commands on the node(s) where the central components are installed:

# yum list installed wazuh-indexer
# yum list installed wazuh-manager
# yum list installed wazuh-dashboard

Next, upgrade the Wazuh agents by following the instructions in Upgrading the Wazuh agent.