Upgrade Graylog on Red Hat

This guide describes the recommended way to upgrade Graylog on RHEL 8 and 9.

Warning: This guide does not cover security settings! The server administrator must make sure the Graylog server is not publicly exposed and is following security best practices. See Secure Your Graylog Environment for more information.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

You must be a Graylog administrator to perform a system upgrade.
Review the release notes for your target Graylog version to identify breaking changes and required configuration updates.
Back up data for all services before upgrading to enable rollback if needed. See Backup and Restore Best Practices for details.
Ensure all system components are compatible with your target Graylog version.
If you are upgrading MongoDB (or self-managed OpenSearch, if used as your search backend) do so before upgrading Graylog.

Warning: This guide assumes a sequential upgrade through each Graylog version. If you are upgrading across multiple versions, review the incremental upgrade process.

Software Verification

To verify your current version of Graylog or any of its dependencies before upgrading, use the following commands:

Graylog

Copy

sudo yum list installed | grep graylog

Data Node

Copy

sudo yum list installed | grep graylog-datanode

MongoDB

Copy

sudo yum list installed | grep mongod

Upgrade with Self-Managed OpenSearch

This guide describes the upgrade process for Graylog environments using Graylog Data Node as a search backend. If you have deployed Graylog with self-managed OpenSearch, then you will only need to follow the process described in subsequent sections to upgrade the Graylog service.

If you wish to upgrade OpenSearch to a Graylog-supported version, you must do so before you upgrade Graylog. See the OpenSearch documentation for more information on upgrading OpenSearch.

To verify your current version of OpenSearch before upgrading, run the following command:

Copy

sudo yum list installed | grep opensearch

Upgrade Graylog

To ensure data consistency, all Graylog Server instances must be stopped before upgrading. Graylog releases may include database migrations, and running different Graylog versions within the same environment can lead to errors or inconsistent MongoDB data. For this reason, rolling upgrades of the Graylog service are not recommended.

Warning: During the upgrade window, Graylog cannot receive or process logs. Plan the upgrade to account for this interruption, including how log data is handled while Graylog is unavailable, to avoid unintended data loss.

To upgrade the Graylog service, follow the steps below.

Hint: This guide assumes you are upgrading to the latest version of Graylog, version 7.0.

Stop the Graylog service:
Copy
```
sudo systemctl stop graylog-server.service
```
Hint: In a multi-node cluster, stop Graylog on all nodes before upgrading packages. This ensures that database migrations run only after all nodes are offline.
Monitor the status of the Graylog service to verify it has stopped:
Copy
```
ps -aefww | grep graylog
```

Once the service has stopped, update the local package cache:

Copy

sudo rpm -Uvh https://packages.graylog2.org/repo/packages/graylog-7.0-repository_latest.rpm
sudo yum clean all
sudo yum update

To display all available versions of Graylog:

Graylog Open ▼

Copy

sudo yum list graylog-server --showduplicates

Graylog Enterprise ▼

Copy

sudo yum list graylog-enterprise --showduplicates

Graylog Security ▼

Copy

sudo yum list graylog-enterprise --showduplicates

If you have a lock on the Graylog package using yum-versionlock, you may then be prompted to remove it before allowing the upgrade to execute:
Copy
```
sudo yum versionlock delete graylog-server
```

Upgrade the Graylog 7.0 package(s):

Graylog Open ▼

Copy

sudo yum upgrade graylog-server

Graylog Enterprise ▼

Copy

sudo yum upgrade graylog-enterprise

Graylog Security ▼

Copy

sudo yum upgrade graylog-enterprise

To verify that the updated Graylog packages have been installed:
Copy
```
sudo yum list installed | grep graylog
```
If the release notes for your target version indicate configuration changes are necessary, then make these changes in the server.conf file. To open the file:
Copy
```
sudo nano /etc/graylog/server/server.conf
```

Start the Graylog service:

Copy

sudo systemctl start graylog-server.service

Hint: In a multi-node cluster, start the leader node first after upgrading. Once the leader is running, you may start all follower nodes.

Upgrade Data Node

Simplify your Data Node upgrade! Try our interactive Data Node rolling upgrade walkthrough, guiding you through every step for a seamless, zero-downtime upgrade.

Graylog Data Node must be on the same version as your Graylog service. For example, if you have upgraded Graylog to 7.0, then you must also upgrade Data Node to the 7.0 release.

Warning: Rolling upgrades are only applicable to Data Node clusters of three or more nodes. If you have fewer than three Data Nodes, you must perform a restart upgrade, where you shut down all Data Nodes and stop the service during the upgrade process.

To complete a rolling upgrade of three or more Data Node servers, follow the steps below.

Hint: This guide assumes you are upgrading to the latest version of Graylog Data Node, version 7.0.

To begin the Data Node upgrade process, you must first log in to the Graylog interface and navigate to System > Cluster Configuration > Data Node Upgrade. Note that after upgrading Graylog, you will receive a warning on this page that there is a version mismatch between Graylog and your Data Nodes.
Select Rolling Upgrade.
Graylog will indicate the Data Node (by its hostname) that should be upgraded first, so for the first node listed, click Start Upgrade Process. This disables shard replication temporarily for the upgrade to proceed safely.

Hint: Unlike upgrading the Graylog service, upgrading the Data Node service requires that you start on a follower node first and finish with the leader node. The Graylog interface will indicate the correct upgrade order.
Now, navigate to the physical Data Node host on which you are performing the upgrade and stop the Data Node service:
Copy
```
sudo systemctl stop graylog-datanode
```
Monitor the status of the Data Node service to verify it has stopped:
Copy
```
ps -aefww | grep graylog-datanode
```

Once the service has stopped, update the local package cache:

Copy

sudo rpm -Uvh https://packages.graylog2.org/repo/packages/graylog-7.0-repository_latest.rpm
sudo yum clean all
sudo yum update

To display all available versions of Data Node:

Copy

sudo yum list graylog-datanode --showduplicates

If you have a lock on the Graylog Data Node package using yum-versionlock, you may then be prompted to remove it before allowing the upgrade to execute:
Copy
```
sudo yum versionlock delete graylog-datanode
```
Upgrade the latest Graylog 7.0 repository:
Copy
```
sudo yum upgrade graylog-datanode
```
To verify that the updated Data Node packages have been installed:
Copy
```
sudo yum list installed | grep graylog-datanode
```
If the release notes for your target version indicate configuration changes are necessary for Data Node, then make these changes in the datanode.conf file. To open the file:
Copy
```
sudo nano /etc/graylog/datanode/datanode.conf
```
Start the Data Node service:
Copy
```
sudo systemctl start graylog-datanode
```
Return to the Graylog interface and select Confirm Upgrade for the node indicated. This re-enables shard replication and signals Graylog that the node upgrade is complete.
Repeat all the previous steps for the remaining nodes, upgrading them one at a time in the order indicated by Graylog.

Incremental Upgrade

When upgrading across multiple Graylog versions (for example, from 5.x to 7.x), it is essential to perform the upgrade incrementally through every minor version and not just between major releases. Each Graylog version may include important database migrations, configuration updates, or compatibility changes that must be applied in order.

The recommended process is to upgrade one version at a time, following the full sequence of available releases until you reach the target version. Skipping versions may result in failed migrations or inconsistent system behavior.

Incremental Upgrade Path Example

For example, if you are upgrading from Graylog 5.2 to Graylog 7.0, you should follow this path:

Graylog 5.2 → 6.0 → 6.1 → 6.2 → 6.3 → 7.0

This ensures that all intermediate schema changes, configuration updates, and feature migrations are properly applied at each step.

Hint: In a multi-node cluster, all nodes must be upgraded to the same version before proceeding to the next step in the sequence. Using the example above, upgrade all nodes to 6.0 before continuing to 6.1, then to 6.2, 6.3, and finally 7.0.