In order to ensure that those fixes are available for a number of years, Graylog now requires one of the two most recent MongoDB releases to run.
This guide details the necessary steps to bring the MongoDB deployment to a supported version.
In general, MongoDB upgrades must be done from one minor release to the next, going to the latest bug fix version in that release.
For example, you can update from MongoDB v3.6.23 to v4.0.28. You cannot skip minor releases, it’s important to follow the progression, because some versions require running migrations and sometimes commands to enable new features.
Standalone MongoDB
In general, Graylog recommends running MongoDB as a cluster to allow for high availability of the system.
Running a single MongoDB database for a production Graylog cluster is not recommended.
Prerequisites
- A running MongoDB standalone server.
- A running Graylog 5.0+ cluster.
- Access to the servers where MongoDB is installed and the necessary privileges to install and start/stop software.
- MongoDB administrator credentials for the cluster.
- Administrator access to Graylog.
- Access to the Graylog server log files.
Upgrade to 4.0.28
For more detailed information, be sure to read Upgrade a Standalone to 4.0, MongoDB manual.
-
Make sure you are running MongoDB 3.6.23, upgrade to the latest 3.6 bug fix release if necessary.
-
If your Graylog cluster is running, stop message processing on all nodes, via the System → Nodes page. Choose “More Actions” and “Pause message processing.”
-
Stop the MongoDB service.
-
Install MongoDB 4.0.28 binaries, replacing the existing 3.6.23 installation.
-
Start MongoDB 4.0.28.
-
Look for lines similar to the following in the Graylog server log:
2022-10-18 11:57:06,205 INFO : org.mongodb.driver.connection - Opened connection [connectionId{localValue:39, serverValue:2}] to localhost:27017
-
Enable message processing on all nodes similar to step 2.
-
Run the following command in the MongoDB shell as an administrator:
db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } )
Upgrade to 4.2.22
For more detailed information, be sure to read Upgrade a Standalone to 4.2, MongoDB manual.
- Make sure you are running MongoDB 4.0.28, upgrade to the latest 4.0 bug fix release if necessary.
- In the MongoDB shell with an administrator account, run
db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
- ensure that the result includes
"featureCompatibilityVersion" : { "version" : "4.0" }
- if it doesn’t, run the command
db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } )
- ensure that the result includes
- If your Graylog cluster is running, stop message processing on all nodes, via the System → Nodes page. Choose “More Actions” and “Pause message processing”.
- Stop the MongoDB service.
- Install MongoDB 4.2.22 binaries, replacing the existing 4.0.28 installation.
- Start MongoDB 4.2.22.
- Look for lines similar to the following in the Graylog server log:
2022-10-18 11:57:06,205 INFO : org.mongodb.driver.connection - Opened connection [connectionId{localValue:39, serverValue:2}] to localhost:27017
- Enable message processing on all nodes similar to step 2.
- Run the following command in the MongoDB shell as an administrator:
db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } )
Upgrade to 4.4.17
For more detailed information, be sure to read Upgrade a Standalone to 4.4, MongoDB manual.
- Make sure you are running MongoDB 4.2.22, upgrade to the latest 4.2 bug fix release if necessary.
- In the MongoDB shell with an administrator account, run
db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
- Ensure that the result includes
"featureCompatibilityVersion" : { "version" : "4.2" }
- If it doesn’t, run the
command db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } )
- Ensure that the result includes
- If your Graylog cluster is running, stop message processing on all nodes, via the System → Nodes page. Choose “More Actions” and “Pause message processing”.
- Stop the MongoDB service.
- Install MongoDB 4.4.17 binaries, replacing the existing 4.2.22 installation.
- Start MongoDB 4.4.17.
- Look for lines similar to the following in the Graylog server log:
2022-10-18 11:57:06,205 INFO : org.mongodb.driver.connection - Opened connection [connectionId{localValue:39, serverValue:2}] to localhost:27017
- Enable message processing on all nodes similar to step 2.
- Run the following command in the MongoDB shell as an administrator:
db.adminCommand( { setFeatureCompatibilityVersion: "4.4" } )
Upgrade to 5.0.12
For more detailed information, be sure to read Upgrade a Standalone to 5.0, MongoDB manual.
- Make sure you are running MongoDB 4.4.17; upgrade to the latest 4.4 bug fix release if necessary.
- In the MongoDB shell with an administrator account, run
db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
- Ensure that the result includes
"featureCompatibilityVersion" : { "version" : "4.4" }
- If it doesn’t, run the command
db.adminCommand( { setFeatureCompatibilityVersion: "4.4" } )
- Ensure that the result includes
- If your Graylog cluster is running, stop message processing on all nodes, via the System → Nodes page. Choose “More Actions” and “Pause message processing”.
- Stop the MongoDB service.
- Install MongoDB 5.0.12 binaries, replacing the existing 4.4.17 installation.
- Start MongoDB 5.0.12.
- Look for lines similar to the following in the Graylog server log:
2022-10-18 11:57:06,205 INFO : org.mongodb.driver.connection - Opened connection [connectionId{localValue:39, serverValue:2}] to localhost:27017
- Enable message processing on all nodes similar to step 2.
- Run the following command in the MongoDB shell as an administrator:
db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )
Upgrade to 6.0.2
For more detailed information, be sure to read Upgrade a Standalone to 5.0, MongoDB manual.
- Make sure you are running MongoDB 5.0.12; upgrade to the latest 5.0 bug fix release if necessary.
- In the MongoDB shell with an administrator account, run
db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
- Ensure that the result includes
"featureCompatibilityVersion" : { "version" : "5.0" }
- If it doesn’t, run the command
db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )
- Ensure that the result includes
- If your Graylog cluster is running, stop message processing on all nodes, via the System → Nodes page. Choose “More Actions” and “Pause message processing”.
- Stop the MongoDB service.
- Install MongoDB 6.0.2 binaries, replacing the existing 5.0.12 installation.
- Start MongoDB 6.0.2.
- Look for lines similar to the following in the Graylog server log:
2022-10-18 11:57:06,205 INFO : org.mongodb.driver.connection - Opened connection [connectionId{localValue:39, serverValue:2}] to localhost:27017
- Enable message processing on all nodes similar to step 2.
- Run the following command in the MongoDB shell as an administrator:
db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } )
Replica Sets
MongoDB replica sets use a primary write server that replicates to secondary servers to achieve high availability in case of the loss of one or more servers. The recommended minimum amount of MongoDB servers is 3 (1 primary, 2 secondaries), which is what this guide assumes.
There are additional possible topologies. We recommend that you familiarize yourself with the concepts by reading the replication section in the MongoDB documentation.
Using replica sets allows rolling MongoDB updates without stopping message processing in Graylog.
In each step you only need to ensure that you work on one MongoDB instance at a time, waiting with restarts until each instance has successfully rejoined the replica set.
Prerequisites
- An existing MongoDB replica set that you want to upgrade.
- A running Graylog 4.3 cluster.
- Access to the servers where MongoDB is installed and the necessary privileges to install and start/stop software.
- MongoDB administrator credentials for the cluster.
- Administrator access to Graylog.
- Access to the Graylog server log files.
The replica set MongoDB upgrades all follow the same pattern. Simply pick your current version and follow the instructions to the latest version before updating from Graylog 4.3 to 5.0.
When updating across multiple versions of MongoDB, make sure to verify the Primary and Secondary addresses at each step because they change during rolling upgrades.
Do not assume the roles from a previous step are still valid!
Upgrade to 4.0.28
For more detailed information, be sure to read Upgrade a Standalone to 4.0, MongoDB manual.
- Make sure you are running MongoDB 3.6.23; upgrade to the latest 3.6 bug fix release if necessary.
- Connect to the replica set using the MongoDB shell and run
rs.status()
.- Note the addresses for the members marked
SECONDARY
. - Note the address for the member marked
PRIMARY
.
- Note the addresses for the members marked
- For each of the
SECONDARY
members, one after another, perform the following steps:- Stop the MongoDB service.
- Install MongoDB 4.0.28 binaries, replacing the existing 3.6.23 installation.
- Start MongoDB 4.0.28.
- Keep checking
rs.status()
that theSECONDARY
member has rejoined the replica set before moving on to the next.
- After all
SECONDARY
members have been updated in this manner, connect the MongoDB shell to thePRIMARY
(the MongoDB shell prompt will includePRIMARY
):- Run
.rs.stepDown
() - Once another member has been promoted to
PRIMARY
, stop the oldPRIMARY
and update the binaries as above. - Restart the MongoDB server.
- Ensure that the restarted member has rejoined the replica set as
SECONDARY
usingrs.status()
.
- Run
- Run the following command in the MongoDB shell as an administrator on the
PRIMARY
member:db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } )
Upgrade to 4.2.22
For more detailed information, be sure to read Upgrade a Standalone to 4.2, MongoDB manual.
- Make sure you are running MongoDB 4.0.28; upgrade to the latest 4.0 bug fix release if necessary.
- Connect to the replica set using the MongoDB shell and run
rs.status()
.- Note the addresses for the members marked
SECONDARY
. - Note the address for the member marked
PRIMARY
.
- Note the addresses for the members marked
- For each of the
SECONDARY
members, one after another, perform the following steps:- Stop the MongoDB service.
- Install MongoDB 4.2.22 binaries, replacing the existing 4.0.28 installation.
- Start MongoDB 4.2.22.
- Keep checking
rs.status()
that theSECONDARY
member has rejoined the replica set before moving on to the next.
- After all
SECONDARY
members have been updated in this manner, connect the MongoDB shell to thePRIMARY
(the MongoDB shell prompt will includePRIMARY
):- Run
rs.stepDown()
. - Once another member has been promoted to
PRIMARY
, stop the oldPRIMARY
and update the binaries as above. - Restart the MongoDB server.
- Ensure that the restarted member has rejoined the replica set as
SECONDARY
usingrs.status()
.
- Run
- Run the following command in the MongoDB shell as an administrator on the
PRIMARY
member:db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } )
Upgrade to 4.4.17
For more detailed information, be sure to read Upgrade a Standalone to 4.4, MongoDB manual.
- Make sure you are running MongoDB 4.2.22; upgrade to the latest 4.2 bug fix release if necessary.
- Connect to the replica set using the MongoDB shell and run
rs.status()
.- Note the addresses for the members marked
SECONDARY
. - Note the address for the member marked
PRIMARY
.
- Note the addresses for the members marked
- For each of the
SECONDARY
members, one after another, perform the following steps:- Stop the MongoDB service.
- Install MongoDB 4.4.17 binaries, replacing the existing 4.2.22 installation.
- Start MongoDB 4.4.17.
- Keep checking
rs.status()
that theSECONDARY
member has rejoined the replica set before moving on to the next.
- After all
SECONDARY
members have been updated in this manner, connect the MongoDB shell to thePRIMARY
(the MongoDB shell prompt will includePRIMARY
):- Run
rs.stepDown()
. - Once another member has been promoted to
PRIMARY
, stop the oldPRIMARY
and update the binaries as above. - Restart the MongoDB server.
- Ensure that the restarted member has rejoined the replica set as
SECONDARY
usingrs.status()
.
- Run
- Run the following command in the MongoDB shell as an administrator on the
PRIMARY
member:db.adminCommand( { setFeatureCompatibilityVersion: "4.4" } )
Upgrade to 5.0.12
For more detailed information, be sure to read Upgrade a Standalone to 5.0, MongoDB manual.
- Make sure you are running MongoDB 4.4.17; upgrade to the latest 4.4 bug fix release if necessary.
- Connect to the replica set using the MongoDB shell and run
rs.status()
.- Note the addresses for the members marked
SECONDARY
. - Note the address for the member marked
PRIMARY
.
- Note the addresses for the members marked
- For each of the
SECONDARY
members, one after another, perform the following steps:- Stop the MongoDB service.
- Install MongoDB 5.0.12 binaries, replacing the existing 4.4.17 installation.
- Start MongoDB 5.0.12.
- Keep checking
rs.status()
that theSECONDARY
member has rejoined the replica set before moving on to the next.
- After all
SECONDARY
members have been updated in this manner, connect the MongoDB shell to thePRIMARY
(the MongoDB shell prompt will includePRIMARY
):- Run
rs.stepDown()
. - Once another member has been promoted to
PRIMARY
, stop the oldPRIMARY
and update the binaries as above. - Restart the MongoDB server.
- Ensure that the restarted member has rejoined the replica set as
SECONDARY
usingrs.status()
.
- Run
- Run the following command in the MongoDB shell as an administrator on the
PRIMARY
member:db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )
Upgrade to 6.0.2
For more detailed information, be sure to read Upgrade a Standalone to 6.0, MongoDB manual
- Make sure you are running MongoDB 5.0.12; upgrade to the latest 4.4 bug fix release if necessary.
- Connect to the replica set using the MongoDB shell and run
rs.status()
.- Note the addresses for the members marked
SECONDARY
. - Note the address for the member marked
PRIMARY
.
- Note the addresses for the members marked
- For each of the
SECONDARY
members, one after another, perform the following steps:- Stop the MongoDB service.
- Install MongoDB 6.0.2 binaries, replacing the existing 5.0.12 installation.
- Start MongoDB 6.0.2.
- Keep checking
rs.status()
that theSECONDARY
member has rejoined the replica set before moving on to the next.
- After all
SECONDARY
members have been updated in this manner, connect the MongoDB shell to thePRIMARY
(the MongoDB shell prompt will includePRIMARY
):- Run
rs.stepDown()
. - Once another member has been promoted to
PRIMARY
, stop the oldPRIMARY
and update the binaries as above. - Restart the MongoDB server.
- Ensure that the restarted member has rejoined the replica set as
SECONDARY
usingrs.status()
.
- Run
- Run the following command in the MongoDB shell as an administrator on the
PRIMARY
member:db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } )