Navigation
This version of the documentation is archived and no longer supported.

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:

  1. 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>
    
  2. Switch all clients to use TLS/SSL. See TLS/SSL Configuration for Clients.

  3. 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.adminCommand( { setParameter: 1, sslMode: "preferSSL" } )
    

    Upgrade all nodes of the cluster to these settings.

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

  4. 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.adminCommand( { setParameter: 1, sslMode: "requireSSL" } )
    
  5. 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.