WarningRunning Graylog 5.2 requires MongoDB 5.0 or 6.0. Prior versions of Graylog allowed running MongoDB 3.6 and above, but those versions are out of date and often no longer receive bug fixes or security updates.

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.

HintThe standalone 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.2.

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.
WarningMongoDB 5.0 requires use of the AVX instruction set. For further details, see the MongoDB documentation.

Upgrade to 4.0.28

For more detailed information, be sure to read Upgrade a Standalone to 4.0, MongoDB manual.

  1. Make sure you are running MongoDB 3.6.23, upgrade to the latest 3.6 bug fix release if necessary.

  2. If your Graylog cluster is running, stop message processing on all nodes, via the System → Nodes page. Choose “More Actions” and “Pause message processing.”

  3. Stop the MongoDB service.

  4. Install MongoDB 4.0.28 binaries, replacing the existing 3.6.23 installation.

  5. Start MongoDB 4.0.28.

  6. 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

  7. Enable message processing on all nodes similar to step 2.

  8. 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.

  1. Make sure you are running MongoDB 4.0.28, upgrade to the latest 4.0 bug fix release if necessary.
  2. In the MongoDB shell with an administrator account, run db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
    1. ensure that the result includes "featureCompatibilityVersion" : { "version" : "4.0" }
    2. if it doesn’t, run the command db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } )
  3. If your Graylog cluster is running, stop message processing on all nodes, via the System → Nodes page. Choose “More Actions” and “Pause message processing”.
  4. Stop the MongoDB service.
  5. Install MongoDB 4.2.22 binaries, replacing the existing 4.0.28 installation.
  6. Start MongoDB 4.2.22.
  7. 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
  8. Enable message processing on all nodes similar to step 2.
  9. 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.

  1. Make sure you are running MongoDB 4.2.22, upgrade to the latest 4.2 bug fix release if necessary.
  2. In the MongoDB shell with an administrator account, run db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
    1. Ensure that the result includes "featureCompatibilityVersion" : { "version" : "4.2" }
    2. If it doesn’t, run the command db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } )
  3. If your Graylog cluster is running, stop message processing on all nodes, via the System → Nodes page. Choose “More Actions” and “Pause message processing”.
  4. Stop the MongoDB service.
  5. Install MongoDB 4.4.17 binaries, replacing the existing 4.2.22 installation.
  6. Start MongoDB 4.4.17.
  7. 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
  8. Enable message processing on all nodes similar to step 2.
  9. 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.

  1. Make sure you are running MongoDB 4.4.17; upgrade to the latest 4.4 bug fix release if necessary.
  2. In the MongoDB shell with an administrator account, run db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
    1. Ensure that the result includes "featureCompatibilityVersion" : { "version" : "4.4" }
    2. If it doesn’t, run the command db.adminCommand( { setFeatureCompatibilityVersion: "4.4" } )
  3. If your Graylog cluster is running, stop message processing on all nodes, via the System → Nodes page. Choose “More Actions” and “Pause message processing”.
  4. Stop the MongoDB service.
  5. Install MongoDB 5.0.12 binaries, replacing the existing 4.4.17 installation.
  6. Start MongoDB 5.0.12.
  7. 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
  8. Enable message processing on all nodes similar to step 2.
  9. 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.

  1. Make sure you are running MongoDB 5.0.12; upgrade to the latest 5.0 bug fix release if necessary.
  2. In the MongoDB shell with an administrator account, run db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
    1. Ensure that the result includes "featureCompatibilityVersion" : { "version" : "5.0" }
    2. If it doesn’t, run the command db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )
  3. If your Graylog cluster is running, stop message processing on all nodes, via the System → Nodes page. Choose “More Actions” and “Pause message processing”.
  4. Stop the MongoDB service.
  5. Install MongoDB 6.0.2 binaries, replacing the existing 5.0.12 installation.
  6. Start MongoDB 6.0.2.
  7. 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
  8. Enable message processing on all nodes similar to step 2.
  9. 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

  1. An existing MongoDB replica set that you want to upgrade.
  2. A running Graylog 4.3 cluster.
  3. Access to the servers where MongoDB is installed and the necessary privileges to install and start/stop software.
  4. MongoDB administrator credentials for the cluster.
  5. Administrator access to Graylog.
  6. 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.

  1. Make sure you are running MongoDB 3.6.23; upgrade to the latest 3.6 bug fix release if necessary.
  2. Connect to the replica set using the MongoDB shell and run rs.status().
    1. Note the addresses for the members marked SECONDARY.
    2. Note the address for the member marked PRIMARY.
  3. For each of the SECONDARY members, one after another, perform the following steps:
    1. Stop the MongoDB service.
    2. Install MongoDB 4.0.28 binaries, replacing the existing 3.6.23 installation.
    3. Start MongoDB 4.0.28.
    4. Keep checking rs.status() that the SECONDARY member has rejoined the replica set before moving on to the next.
  4. After all SECONDARY members have been updated in this manner, connect the MongoDB shell to the PRIMARY (the MongoDB shell prompt will include PRIMARY):
    1. Run rs.stepDown().
    2. Once another member has been promoted to PRIMARY, stop the old PRIMARY and update the binaries as above.
    3. Restart the MongoDB server.
    4. Ensure that the restarted member has rejoined the replica set as SECONDARY using rs.status().
  5. 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.

  1. Make sure you are running MongoDB 4.0.28; upgrade to the latest 4.0 bug fix release if necessary.
  2. Connect to the replica set using the MongoDB shell and run rs.status().
    1. Note the addresses for the members marked SECONDARY.
    2. Note the address for the member marked PRIMARY.
  3. For each of the SECONDARY members, one after another, perform the following steps:
    1. Stop the MongoDB service.
    2. Install MongoDB 4.2.22 binaries, replacing the existing 4.0.28 installation.
    3. Start MongoDB 4.2.22.
    4. Keep checking rs.status() that the SECONDARY member has rejoined the replica set before moving on to the next.
  4. After all SECONDARY members have been updated in this manner, connect the MongoDB shell to the PRIMARY (the MongoDB shell prompt will include PRIMARY):
    1. Run rs.stepDown().
    2. Once another member has been promoted to PRIMARY, stop the old PRIMARY and update the binaries as above.
    3. Restart the MongoDB server.
    4. Ensure that the restarted member has rejoined the replica set as SECONDARY using rs.status().
  5. 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.

  1. Make sure you are running MongoDB 4.2.22; upgrade to the latest 4.2 bug fix release if necessary.
  2. Connect to the replica set using the MongoDB shell and run rs.status().
    1. Note the addresses for the members marked SECONDARY.
    2. Note the address for the member marked PRIMARY.
  3. For each of the SECONDARY members, one after another, perform the following steps:
    1. Stop the MongoDB service.
    2. Install MongoDB 4.4.17 binaries, replacing the existing 4.2.22 installation.
    3. Start MongoDB 4.4.17.
    4. Keep checking rs.status() that the SECONDARY member has rejoined the replica set before moving on to the next.
  4. After all SECONDARY members have been updated in this manner, connect the MongoDB shell to the PRIMARY (the MongoDB shell prompt will include PRIMARY):
    1. Run rs.stepDown().
    2. Once another member has been promoted to PRIMARY, stop the old PRIMARY and update the binaries as above.
    3. Restart the MongoDB server.
    4. Ensure that the restarted member has rejoined the replica set as SECONDARY using rs.status().
  5. 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.

  1. Make sure you are running MongoDB 4.4.17; upgrade to the latest 4.4 bug fix release if necessary.
  2. Connect to the replica set using the MongoDB shell and run rs.status().
    1. Note the addresses for the members marked SECONDARY.
    2. Note the address for the member marked PRIMARY.
  3. For each of the SECONDARY members, one after another, perform the following steps:
    1. Stop the MongoDB service.
    2. Install MongoDB 5.0.12 binaries, replacing the existing 4.4.17 installation.
    3. Start MongoDB 5.0.12.
    4. Keep checking rs.status() that the SECONDARY member has rejoined the replica set before moving on to the next.
  4. After all SECONDARY members have been updated in this manner, connect the MongoDB shell to the PRIMARY (the MongoDB shell prompt will include PRIMARY):
    1. Run rs.stepDown().
    2. Once another member has been promoted to PRIMARY, stop the old PRIMARY and update the binaries as above.
    3. Restart the MongoDB server.
    4. Ensure that the restarted member has rejoined the replica set as SECONDARY using rs.status().
  5. 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

  1. Make sure you are running MongoDB 5.0.12; upgrade to the latest 4.4 bug fix release if necessary.
  2. Connect to the replica set using the MongoDB shell and run rs.status().
    1. Note the addresses for the members marked SECONDARY.
    2. Note the address for the member marked PRIMARY.
  3. For each of the SECONDARY members, one after another, perform the following steps:
    1. Stop the MongoDB service.
    2. Install MongoDB 6.0.2 binaries, replacing the existing 5.0.12 installation.
    3. Start MongoDB 6.0.2.
    4. Keep checking rs.status() that the SECONDARY member has rejoined the replica set before moving on to the next.
  4. After all SECONDARY members have been updated in this manner, connect the MongoDB shell to the PRIMARY (the MongoDB shell prompt will include PRIMARY):
    1. Run rs.stepDown().
    2. Once another member has been promoted to PRIMARY, stop the old PRIMARY and update the binaries as above.
    3. Restart the MongoDB server.
    4. Ensure that the restarted member has rejoined the replica set as SECONDARY using rs.status().
  5. Run the following command in the MongoDB shell as an administrator on the PRIMARY member: db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } )