Upgrade a Cluster to Use TLS/SSL¶

Changed in version 3.0: Most MongoDB distributions now include support for TLS/SSL. See Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients for more information about TLS/SSL and MongoDB.

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.

Changed in version 2.6.

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

To upgrade from a MongoDB cluster using no TLS/SSL encryption to one using only TLS/SSL encryption, use the following rolling upgrade process:

For each node of a cluster, start the node with the option --sslMode set to allowSSL. The --sslMode allowSSL setting allows the node to accept both TLS/SSL and non-TLS/non-SSL incoming connections. Its connections to other servers do not use TLS/SSL. Include other TLS/SSL options as well as any other options that are required for your specific configuration. For example:
```
mongod --replSet <name> --sslMode allowSSL --sslPEMKeyFile <path to TLS/SSL Certificate and key PEM file> --sslCAFile <path to root CA PEM file>
```
Upgrade all nodes of the cluster to these settings.

You may also specify these options in the configuration file. If using a YAML format configuration file, specify the following settings in the file:
```
net:
   ssl:
      mode: <disabled|allowSSL|preferSSL|requireSSL>
      PEMKeyFile: <path to TLS/SSL certificate and key PEM file>
      CAFile: <path to root CA PEM file>
```
Or, if using the older configuration file format:
```
sslMode = <disabled|allowSSL|preferSSL|requireSSL>
sslPEMKeyFile = <path to TLS/SSL certificate and key PEM file>
sslCAFile = <path to root CA PEM file>
```
Switch all clients to use TLS/SSL. See TLS/SSL Configuration for Clients.
For each node of a cluster, use the setParameter command to update the sslMode to preferSSL. [1] With preferSSL as its net.ssl.mode, the node accepts both TLS/SSL and non-TLS/non-SSL incoming connections, and its connections to other servers use TLS/SSL. For example:
```
db.getSiblingDB('admin').runCommand( { 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 the setParameter command to update the sslMode to requireSSL. [1] With requireSSL as its net.ssl.mode, the node will reject any non-TLS/non-SSL connections. For example:
```
db.getSiblingDB('admin').runCommand( { setParameter: 1, sslMode: "requireSSL" } )
```
After the upgrade of all nodes, edit the configuration file with the appropriate TLS/SSL settings to ensure that upon subsequent restarts, the cluster uses TLS/SSL.

[1]	(1, 2) As an alternative to using the `setParameter` command, you can also restart the nodes with the appropriate TLS/SSL options and values.

← TLS/SSL Configuration for Clients Configure MongoDB for FIPS →

Was this page helpful?

Yes No

Thank you for your feedback!

We're sorry! You can Report a Problem to help us improve this page.