Navigation

Upgrade a Cluster to Use TLS/SSL

Note

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

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.

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 <--sslMode> 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.

    Note

    Starting in MongoDB 3.6, mongod and mongos bind to localhost by default. If the members of your deployment are run on different hosts or if you wish remote clients to connect to your deployment, you must specify --bind_ip or net.bindIp. For more information, see Localhost Binding Compatibility Changes.

    For example:

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

    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, include 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>
    

    Note

    If you are using --sslCertificateSelector or certificateSelector, the --sslPEMKeyFile option is invalid. See instructions on how to configure TLS/SSL with certificateSelector.

New in version 4.0.

  1. For Windows and Mac instances running with system certificate stores, configure the appropriate selectors. You can use system certificates for communication between

    MacOS and Windows both offer system certificate stores that can be accessed across applications via OS specific APIs. Starting in MongoDB version 4.0, certificates can be retrieved from these stores by searching for them via certain well-defined selectors that are available in all certificates.

    On the command line you can pass the --sslCertificateSelector followed by the certificate selector you would like to use and the value of that selector.

    The following selectors are available.

    property name value type value description
    subject ASCII string subject name or common name on certificate
    thumbprint hex string certificate thumbprint

    Note

    The term thumbprint refers to what is also frequently referred to as a fingerprint. It is a short sequence of bytes used to identify a longer public key.

    Use the selectors by passing <parameter>=<value> on the command line. For example, for a certificate with the common name or subject my.dev.server, you would use:

    mongod --sslMode requireSSL --sslCertificateSelector subject=my.dev.server
    

    To enable encryption internally, between members of a cluster use --sslClusterCertificateSelector. Note that you will likely want to use a different certificate for internal communication.

    mongod --sslMode requireSSL --sslCertificateSelector subject=my.dev.server --sslClusterCertificateSelector subject=my.shard.server
    

    Alternatively, use the certificateSelector and/or clusterCertificateSelector to configure the certificate storage selector with a config file.

    net:
       ssl:
          clusterCertificateSelector: <parameter>=<value>
          certificateSelector: <parameter>=<value>
    

Tip

If you are using --sslCertificateSelector or certificateSelector, the --sslPEMKeyFile is invalid. OCSP (Online Certificate Status Protocol) is used to validate the revocation status of certificates.

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

  2. 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.

  3. 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" } )
    
  4. 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.