Rotate Keys for Replica Sets

Replica set members can use keyfiles toauthenticate each other as memers of the same deployment.

Starting in version 4.2, a keyfile cancontain multiple keys and membership authentication is established ifat least one key is common across members. This allows for rollingupgrade of the keys without downtime.

The following tutorial steps through the process to update the key fora replica set without downtime. [1]

Warning

The example keys in this tutorial are for illustrative purposesonly. Do NOT use for your deployment. Instead, generate akeyfile using any method you choose (for example, openssl rand -base64756, etc.).

Consider a replica set where each member’s keyfile contains thefollowing key:

The following procedure updates the replica set members to use a newkey:

Procedure

1. Modify the Keyfile to Include Old and New Keys

Modify each member’s keyfile to include both the old and new keys. Youcan specify multiple keys either as strings enclosed in quotes or as asequence of keys.

Warning

The example keys in this tutorial are for illustrative purposesonly. Do NOT use for your deployment. Instead, generate akeyfile using any method you choose (e.g. openssl rand -base64756, etc.).

• Multiple Key Strings
• Multiple Key Sequence

You can specify multiple key strings where each keystring is enclosed in quotes.

You can specify multiple key strings as a sequence of keystrings (optionally enclosed in quotes).

2. Restart Each Member

Once all the keyfiles contain both the old and new keys, restart eachmember one at a time.

For each secondary member, connect a mongo shell to themember and:

• Use the db.shutdownServer() method to shut down the member:

use admin
db.shutdownServer()

• Restart the member.

For the primary, connect a mongo shell to the member and

• Use rs.stepDown() to step down the member:

rs.stepDown()

• Use the db.shutdownServer() method to shut down the member:

use admin
db.shutdownServer()

• Restart the member.

Since the keyfiles contains both the old and new keys, all members cannow accept either keys for membership authentication.

3. Update Keyfile Content to the New Key Only

Warning

The example keys in this tutorial are for illustrative purposesonly. Do NOT use for your deployment. Instead, generate akeyfile using any method you choose (e.g. openssl rand -base64756, etc.).

Modify each member’s keyfile to include only the new password.

4. Restart Each Member

Once all the keyfiles contain the new key only, restart each member oneat a time.

For each secondary member, connect a mongo shell to themember and:

• Use the db.shutdownServer() method to shut down the member:

use admin
db.shutdownServer()

• Restart the member.

For the primary, connect a mongo shell to the member and

• Use rs.stepDown() to step down the member:

rs.stepDown()

• Use the db.shutdownServer() method to shut down the member:

use admin
db.shutdownServer()

• Restart the member.

All members now accept only the new key for membership authentication.