Rolling Update of x.509 Cluster Certificates that Contain New DN

Members of a replica set or a sharded cluster can use x.509certificates for membership authentication toidentify each other as memers of the same deployment.

To identify each others as members of the same deployment, theOrganization attributes (O’s), the Organizational Unit attributes(OU’s), and the Domain Components (DC’s) from thecertificates must match.

In some situations, you may need to update the member certificates tonew certificates with the new Distinguished Name (DN), such as ifan organization changes its name. Starting in version 4.2, MongoDBprovides a new tlsX509ClusterAuthDNOverride parameter toset an alternative DN to use in matching. Using this parameter, youcan perform a rolling update of the certificates to new certificateswith different DN.

The following tutorial describes the process to update thecertificates for a replica set without downtime.

Consider a replica set where each member’s certificates(clusterFile andcertificateKeyFile) with DN value that contains"OU=10gen Server,O=10gen" (additional attributes are not consideredas part of the comparison):

  1. net.tls.mode: requireTLS
  2. net.tls.certificateKeyFile: "./mycerts/10gen-server1.pem"
  3. net.tls.CAFile: "./mycerts/ca.pem"
  4.  
  5. security.clusterAuthMode: x509
  6. net.tls.clusterFile:  "./mycerts/10gen-cluster1.pem"
  7. net.tls.clusterCAFile: "./mycerts/ca.pem"

The following procedure updates the members’ certificates(clusterFile andcertificateKeyFile) to new certificates that have aDN value with "OU=MongoDB Server,O=MongoDB".

Note

The following procedure assumes that the new x.509 certificates meetmembership certificate all other requirements. For details, seeMember Certificate Requirements

Procedure

0. Optional. Set Override Parameter on Running Members

The procedure requires that all members of the deployment berestarted. As the settings will not take into consideration untilyou restart all members, your instances may log messages until theprocedure completes.

To avoid these messages, you can set the override parameter onrunning members.

Connect a mongo shell directly to each member of thedeployment and set the tlsX509ClusterAuthDNOverrideparameter to the new certificate DN:

  1. db.adminCommand( { setParameter: 1, tlsX509ClusterAuthDNOverride: "OU=MongoDB Server,O=MongoDB" } )

1. Modify the Configuration of ALL Members

Modify each member’s configuration:

For example:

  1. net.tls.mode: requireTLS
  2. net.tls.certificateKeyFile: "./mycerts/mongodb-server1.pem"
  3. net.tls.CAFile: "./mycerts/ca.pem"
  4.  
  5. security.clusterAuthMode: x509
  6.  
  7. net.tls.clusterFile:  "./mycerts/mongodb-cluster1.pem"
  8. net.tls.clusterCAFile: "./mycerts/ca.pem"
  9.  
  10. setParameter:
  11.    tlsX509ClusterAuthDNOverride: "OU=MongoDB Server,O=MongoDB"

The settings will not take into consideration until you restart eachmember (see next step).

2. Restart Each Member

Once you have modified the configuration for all the members,restart each secondaries and then the primary.

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

  1. use admin
  2. db.shutdownServer()
  • Restart the member.

Ensure the member has reached SECONDARY state beforerestarting the next secondary.

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

  1. rs.stepDown()
  1. use admin
  2. db.shutdownServer()
  • Restart the member.

3. Remove the tlsX509ClusterAuthDNOverride Setting

Once all the members have been restarted with the new certificate,you can remove the tlsX509ClusterAuthDNOverride parameter fromthe configuration.

For example:

  1. net.tls.mode: requireTLS
  2. net.tls.certificateKeyFile: "./mycerts/mongodb-server1.pem"
  3. net.tls.CAFile: "./mycerts/ca.pem"
  4.  
  5. security.clusterAuthMode: x509
  6.  
  7. net.tls.clusterFile:  "./mycerts/mongodb-cluster1.pem"
  8. net.tls.clusterCAFile: "./mycerts/ca.pem"

The settings will not take into consideration until you restart eachmember.