Debian - Process for Upgrading MongoDB 4.2 Standalone to MongoDB 6.0 Standalone

MongoDB upgrade requires that you must upgrade to each version of MongoDB along the way.

This document will follow the MongoDB upgrade path from 4.2 → 4.4 → 5.0 → 6.0, with the document structured as follows:

Prerequisites
Upgrade Preparation
Upgrade from MongoDB 4.2 to MongoDB 4.4
Upgrade from MongoDB 4.4 to MongoDB 5.0
Upgrade from MongoDB 5.0 to MongoDB 6.0
Services Restart
Clean-up

Notes

NOTE: All Linux commands in this document are run at root level: you need access to root via su or sudo -i

Set these two environment variables with your MongoDB admin username and password so that these script examples can be used:

export YOUR_USERNAME=opUserRW
export YOUR_PASSWORD=t0pS3cr3tpw

showMongoFcv() {
    if which mongosh; then  local MONGOSH=mongosh;   else   local MONGOSH=mongo; fi;
    $MONGOSH -u $YOUR_USERNAME -p $YOUR_PASSWORD --authenticationDatabase=admin --quiet --eval "db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )"
}

setMongoFcv() {
    if which mongosh; then  local MONGOSH=mongosh;   else   local MONGOSH=mongo; fi;
    $MONGOSH -u $YOUR_USERNAME -p $YOUR_PASSWORD --authenticationDatabase=admin --quiet --eval "db.adminCommand( { setFeatureCompatibilityVersion: \"$1\" } )"
}

Table of Contents

Prerequisites for Upgrading MongoDB 4.2 to MongoDB 6.0

This document outlines the process to bring MongoDB up to version 6.0. There are a series of prerequisites that determine the type of update required. This document outlines the process for MongoDB Standalone.

There are 4 prerequisites to confirm:

Operating System
MongoDB Version
MongoDB Storage Engine
NMIS and Modules for Mongo 6.0

Supported Operating Systems

MongoDB 6.0 is officially supported on the following Debian platforms:

MongoDB 6.0 supported on Debian 11 (“Bullseye”), Debian 10 ("Buster")
MongoDB 5.0 supported on Debian 11 (“Bullseye”), Debian 10 ("Buster"), Debian 9("Stretch")
MongoDB 4.4 supported on Debian 10 ("Buster"), Debian 9("Stretch")

We have tested the upgrade process from MongoDB 4.2 to MongoDB 6.0 on:

Debian 11

To determine the version of Linux running on your system use the following command in a terminal session:

lsb_release -rc

An example output of this command

Release: 11
Codename: bullseye

MongoDB 4.2 Installed and Running

Verify by running (with your mongodb <username> and <password>)

This command does not do anything however, the output will show us the running shell and server that is running.

mongo -u $YOUR_USERNAME -p $YOUR_PASSWORD --authenticationDatabase=admin --eval 'quit()' | grep MongoDB

Result will look like below, we are looking for the two version numbers to be 4.2.x

If the versions do not match there may be an issue with your running installation and you should not proceed until this is resolved.

MongoDB shell version v4.2.25 MongoDB server version: 4.2.25

MongoDB Storage Engine

Verify storage engine by running

mongo -u $YOUR_USERNAME -p $YOUR_PASSWORD --authenticationDatabase=admin --quiet --eval 'db.serverStatus().storageEngine'

The "name" line should have "wiredTiger" in order to proceed.

{
        "name" : "wiredTiger",
        "supportsCommittedReads" : true,
        "readOnly" : false,
        "persistent" : true
}

If this mongo cli command does not work you can try the following to determine the storage engine in use

grep -i "active storage engine" /var/log/mongodb/mongod.log*

Example correct log output - notice the log entry declares the storage engine to be using "wiredTiger"

2024-06-19T06:45:27.632+0000 I STORAGE [initandlisten] Detected data files in /var/lib/mongodb created by the 'wiredTiger' storage engine, so setting the active storage engine to 'wiredTiger'.

If the system is not using wiredTiger the data migration process should follow a different process. Refer to the following link.

https://www.mongodb.com/docs/v4.2/tutorial/change-standalone-wiredtiger/

Upgrade NMIS and Modules for MongoDB 6.0

NMIS and Modules must be updated to versions that support MongoDB 6.0 before upgrading to MongoDB 6.0. These releases are backwards compatible with MongoDB v4.2 which means that you can upgrade to NMIS and Modules that support MongoDB 6.0, restart NMIS and Modules, and continue to use them with MongoDB 4.2, then upgrade your MongoDB from 4.2 to 6.0 later.

Minimum releases that support MongoDB 6.0 are:

NMIS 9.5.0
opAddress 2.4.0
opCharts 4.8.0
opConfig 4.6.0
opEvents 4.4.0
opHA 4.1.0
opReports 4.6.0
opFlow 4.1.0

You can determine the versions you are running by browsing to:

https://<yourserveraddress>/omk/

You should follow the standard upgrade process for each of these packages, which is handled by the FirstWave Installer.

Preparation

The preparation phase includes 3 sections

System Snapshot/Backup
Upgrade Linux to latest stable release packages
Shutdown all OMK Daemons

This is to be done in this specific sequence.

System Snapshot/Backup

For System Snapshots and Backups you will need to refer to the documentation for your environment.

If the information on your system, or stability of the system is critical to your business it is important to retain a working backup. It is important that you have confirmed that your backups can be restored.

Options:

Full system backups, including Operating System and Data - Contact your IT department, Vendor Support, or Integrator
Virtual Machine Snapshots - Refer to the solution guides for the environment
Database Dump - MongoDB documentation: https://www.mongodb.com/docs/database-tools/mongodump/

Upgrade Linux Packages

After completing the snapshot/backup follow Debian's instructions for upgrading and checking the sanity of the apt package system.

An example of the update/upgrade cycle is as follows:

apt-get update && apt-get upgrade -y

This command will execute all outstanding upgrades. Check for any errors and address as required.

Once this step is completed you may optionally reboot the system. This can clear out any memory leaks and instabilities in the system that occur due to long uptimes.

Shutdown All FirstWave Daemons

Prior to commencing into the MongoDB upgrade cycles it is required to shutdown all FirstWave processes.

The following commands are used to complete this task

/usr/local/omk/bin/checkomkdaemons.sh stop
systemctl stop nmis9d

# confirm that the daemons have stopped /usr/local/omk/bin/checkomkdaemons.sh status systemctl status nmis9d

Example Command and Output

user@servername:~/installers# systemctl status nmis9d
● nmis9d.service - FirstWave NMIS9 Daemon
Loaded: loaded (/etc/systemd/system/nmis9d.service; enabled; vendor preset: enabled)
Active: inactive (dead) since Thu 2024-06-27 17:32:05 AEST; 26s ago
Process: 252049 ExecStartPre=/bin/sh -c sleep 3 (code=exited, status=0/SUCCESS)
Process: 252058 ExecStart=/usr/local/nmis9/bin/nmisd (code=exited, status=0/SUCCESS)
Main PID: 252105 (code=exited, status=0/SUCCESS)
CPU: 1h 23.745s

Jun 27 17:32:04 m6poller1 systemd[1]: Stopping FirstWave NMIS9 Daemon...
Jun 27 17:32:05 m6poller1 systemd[1]: nmis9d.service: Succeeded.
Jun 27 17:32:05 m6poller1 systemd[1]: Stopped FirstWave NMIS9 Daemon.
Jun 27 17:32:05 m6poller1 systemd[1]: nmis9d.service: Consumed 1h 23.745s CPU time.

Upgrade from MongoDB 4.2 to MongoDB 4.4

Prepare the Database for Upgrade

Check the database compatibility mode is set to "4.2"

showMongoFcv

The result should be as follows ensuring that the value 4.2 is set

{ "featureCompatibilityVersion" : "4.2", "ok" : 1 }

If MongoDB is on version 4.2 and the featureCompatibilityVersion is not "4.2" then set this with the following command

setMongoFcv 4.2

As before, the check the featureCompatibilityVersion again confirming the correct value

Example Command and Output

showMongoFcv

{ "featureCompatibilityVersion" : "4.2", "ok" : 1 }

Debian - Install MongoDB 4.4 Repo and Upgrade

Details available here:

https://www.mongodb.com/docs/v4.4/release-notes/4.4-upgrade-standalone/ and https://www.mongodb.com/docs/v4.4/tutorial/install-mongodb-on-debian/

Commands summarised here:

systemctl stop mongod

wget -qO - https://www.mongodb.org/static/pgp/server-4.4.asc | sudo apt-key add

echo "deb [ trusted=yes ] http://repo.mongodb.org/apt/debian buster/mongodb-org/4.4 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list

curl -fsSL https://www.mongodb.org/static/pgp/server-4.4.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-4.4.gpg --dearmor

echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-4.4.gpg ] http://repo.mongodb.org/apt/debian buster/mongodb-org/4.4 main" | \ sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list

sudo apt-get update

sudo apt-get upgrade mongodb-org -y --allow-unauthenticated

mongod --version

systemctl stop mongod
systemctl start mongod
systemctl daemon-reload
systemctl is-active mongod

Complete the upgrade with the following commands and retest. If you skip the stop/start sequence above the following command will fail.

setMongoFcv 4.4
showMongoFcv
systemctl stop mongod
systemctl start mongod

Upgrade from MongoDB 4.4 to MongoDB 5.0

Prepare the Database for Upgrade

Check the database compatibility mode is set to "4.4"

showMongoFcv

The result should be as follows ensuring that the value 4.4 is set

{ "featureCompatibilityVersion" : "4.4", "ok" : 1 }

If MongoDB is on version 4.4 and the featureCompatibilityVersion is not "4.4" then set this with the following command

mongo w;

As before, the check the featureCompatibilityVersion again confirming the correct value

Example Command and Output

showMongoFcv

{ "featureCompatibilityVersion" : "4.4", "ok" : 1 }

Debian - Install MongoDB 5.0 Repo and Upgrade

Details available here:

https://www.mongodb.com/docs/manual/release-notes/5.0-upgrade-standalone/ and https://www.mongodb.com/docs/v5.0/tutorial/install-mongodb-on-debian/

Commands summarised here:

systemctl stop mongod

wget -qO - https://www.mongodb.org/static/pgp/server-5.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-5.0.gpg --dearmor

echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-5.0.gpg] http://repo.mongodb.org/apt/debian bullseye/mongodb-org/5.0 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-5.0.list

sudo apt-get update

sudo apt-get upgrade -y mongodb-org------------------------------------

If you get an error

Errors were encountered while processing:
/var/cache/apt/archives/mongodb-org-database-tools-extra_5.0.27_amd64.deb

Fix it by using:

sudo dpkg -i --force-overwrite /var/cache/apt/archives/mongodb-org-database-tools-extra_5.0.27_amd64.deb

then

sudo apt-get upgrade -y mongodb-org

and answer N to keep your currently installed version of /etc/mongod.conf

-------------------------------------

systemctl stop mongod ; systemctl start mongod ; systemctl daemon-reload ; systemctl is-active mongod ; systemctl status mongod

Complete the upgrade with the following commands and retest. If you skip the stop/start sequence above the following command will fail.

setMongoFcv5.0
showMongoFcv
systemctl stop mongod ; systemctl start mongod ; systemctl status mongod

As before, check the featureCompatibilityVersion output from above is "5.0"

Example Command and Output

showMongoFcv

{ "featureCompatibilityVersion" : "5.0", "ok" : 1 }

Upgrade from MongoDB 5.0 to MongoDB 6.0

Prepare the Database for Upgrade

Check the database compatibility mode is set to "5.0"

showMongoFcv

The result should be as follows ensuring that the value 5.0 is set

{ "featureCompatibilityVersion" : "5.0", "ok" : 1 }

If MongoDB is on version 5.0 and the featureCompatibilityVersion is not "5.0" then set this with the following command

setMongoFcv 5.0

As before, the check the featureCompatibilityVersion again confirming the correct value

Example Command and Output

showMongoFcv

{ "featureCompatibilityVersion" : "5.0", "ok" : 1 }

Debian - Install MongoDB 6.0 Repo and Upgrade

Details available here:

https://www.mongodb.com/docs/manual/release-notes/6.0-upgrade-standalone/ and https://www.mongodb.com/docs/v6.0/tutorial/install-mongodb-on-debian/

Commands summarised here:

systemctl stop mongod

wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-6.0.gpg --dearmor

echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-6.0.gpg] http://repo.mongodb.org/apt/debian bullseye/mongodb-org/6.0 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list

sudo apt-get update

sudo apt-get upgrade -y mongodb-org and answer N to keep your currently installed version of /etc/mongod.conf

systemctl stop mongod ; systemctl start mongod ; systemctl daemon-reload ; systemctl is-active mongod ; systemctl status mongod

Complete the upgrade with the following commands and retest. If you skip the stop/start sequence above the following command will fail.

Note that you must now use the mongosh command instead of mongo

setMongoFcv 6.0
showMongoFcv
systemctl stop mongod
systemctl start mongod

As before, check the featureCompatibilityVersion output from above is "6.0"

Example Command and Output

showMongoFcv

{ "featureCompatibilityVersion" : "6.0", "ok" : 1 }

This completes the in-situ upgrade of MongoDB 4.2 to 6.0 Standalone

Restart All FirstWave Daemons

Now the MongoDB upgrade is complete, you can start all the NMIS and FirstWave daemons.

The following commands are used to complete this task

systemctl start nmis9d/usr/local/omk/bin/checkomkdaemons.sh start

# confirm that the daemons have started /usr/local/omk/bin/checkomkdaemons.sh status ; systemctl status nmis9d

You can now browse to your FirstWave instance with:

https://<yourserver>/omk

You will get a screen similar to the following which will give you a status on all installed modules: