Upgrade a Cluster to Use TLS/SSL

The MongoDB server supports listening for both TLS/SSL encrypted andunencrypted connections on the same TCP port. This allows upgrades ofMongoDB clusters to use TLS/SSL encrypted connections.

Note

Starting in version 4.0, MongoDB disables support for TLS 1.0encryption on systems where TLS 1.1+ is available. Formore details, see Disable TLS 1.0.

Procedure (Using tls Settings)

Important

A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, and Certificate Authority is beyond the scope of this document.This page assumes prior knowledge of TLS/SSL as well as access to valid certificates.

To upgrade from a MongoDB cluster using no TLS/SSL encryption to oneusing only TLS/SSL encryption, use the following rolling upgradeprocess.

Note

The procedures in this section use the tls settings/option(Available in MongoDB 4.2). For procedures using their sslaliases, see Procedure (Using ssl Settings).

The tls settings/options provide identical functionalityas the ssl options since MongoDB has always supported TLS 1.0and later.

• For each node of a cluster, start the node with the command-line option—tlsMode or the configuration file option net.tls.mode set to allowTLS.The allowTLS setting allows the node to accept both TLS/SSLand non-TLS/non-SSL incoming connections. Its connections to other serversdo not use TLS/SSL. Include other TLS/SSL options[2] as well as any other options that arerequired for your specific configuration.

Note

Starting in MongoDB 3.6, mongod and mongosbind to localhost by default. If the members of your deployment arerun on different hosts or if you wish remote clients to connect toyour deployment, you must specify —bind_ip ornet.bindIp. For more information, seeLocalhost Binding Compatibility Changes.

For example:

• Command-Line Options
• Configuration File Options

mongod --replSet <name> --tlsMode allowTLS --tlsCertificateKeyFile <TLS/SSL certificate and key file> --sslCAFile <path to root CA PEM file> <additional options>

To specify these options in the configuration file, include the followingsettings in the file:

net:
   tls:
      mode: allowTLS
      PEMKeyFile: <path to TLS/SSL certificate and key PEM file>
      CAFile: <path to root CA PEM file>

Upgrade all nodes of the cluster to these settings.

• Switch all clients to use TLS/SSL. See TLS/SSL Configuration for Clients.

• For each node of a cluster, use the setParametercommand to update the tlsMode to preferTLS.[1] With preferTLS as itsnet.tls.mode, the node accepts both TLS/SSL and non-TLS/non-SSL incomingconnections, and its connections to other servers use TLS/SSL. Forexample:

db.adminCommand( { setParameter: 1, tlsMode: "preferTLS" } )

Upgrade all nodes of the cluster to these settings.

At this point, all connections should be using TLS/SSL.

• For each node of the cluster, use thesetParameter command to update the tlsModeto requireTLS. [1] With requireTLSas its net.tls.mode, the node will reject any non-TLS/non-SSLconnections. For example:

db.adminCommand( { setParameter: 1, tlsMode: "requireTLS" } )

• After the upgrade of all nodes, edit the configuration file with the appropriate TLS/SSLsettings to ensure that upon subsequent restarts, the cluster usesTLS/SSL.

Procedure (Using ssl Settings)

Important

A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, and Certificate Authority is beyond the scope of this document.This page assumes prior knowledge of TLS/SSL as well as access to valid certificates.

To upgrade from a MongoDB cluster using no TLS/SSL encryption to oneusing only TLS/SSL encryption, use the following rolling upgradeprocess.

Note

The procedures in this section use the ssl settings/option. Forprocedures using their tls aliases (Available in MongoDB 4.2),see Procedure (Using tls Settings).

The tls settings/options provide identical functionalityas the ssl options since MongoDB has always supported TLS 1.0and later.

• For each node of a cluster, start the node with the command-line option—sslMode or the configuration file option net.ssl.mode set to allowSSL.The allowSSL setting allows the node to accept both TLS/SSLand non-TLS/non-SSL incoming connections. Its connections to other serversdo not use TLS/SSL. Include other TLS/SSL options[2] as well as any other options that arerequired for your specific configuration.

Note

Starting in MongoDB 3.6, mongod and mongosbind to localhost by default. If the members of your deployment arerun on different hosts or if you wish remote clients to connect toyour deployment, you must specify —bind_ip ornet.bindIp. For more information, seeLocalhost Binding Compatibility Changes.

For example:

• Command-Line Options
• Configuration File Options

mongod --replSet <name> --sslMode allowSSL --sslPEMKeyFile <path to TLS/SSL Certificate and key PEM file> --sslCAFile <path to root CA PEM file> <additional options>

To specify these options in the configuration file, include the followingsettings in the file:

net:
   ssl:
      mode: <allowSSL>
      PEMKeyFile: <path to TLS/SSL certificate and key PEM file>
      CAFile: <path to root CA PEM file>

Upgrade all nodes of the cluster to these settings.

• Switch all clients to use TLS/SSL. See TLS/SSL Configuration for Clients.

• For each node of a cluster, use the setParametercommand to update the sslMode to preferSSL.[1] With preferSSL as itsnet.ssl.mode, the node accepts both TLS/SSL and non-TLS/non-SSL incomingconnections, and its connections to other servers use TLS/SSL. Forexample:

db.adminCommand( { setParameter: 1, sslMode: "preferSSL" } )

Upgrade all nodes of the cluster to these settings.

At this point, all connections should be using TLS/SSL.

• For each node of the cluster, use thesetParameter command to update the sslModeto requireSSL. [1] With requireSSLas its net.ssl.mode, the node will reject any non-TLS/non-SSLconnections. For example:

db.adminCommand( { setParameter: 1, sslMode: "requireSSL" } )

• After the upgrade of all nodes, edit the configuration file with the appropriate TLS/SSLsettings to ensure that upon subsequent restarts, the cluster usesTLS/SSL.