Upgrade a Cluster to Use TLS/SSL
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.
Note
MongoDB disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more 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 one using only TLS/SSL encryption, use the following rolling upgrade process.
Note
The procedures in this section use the tls
settings/option
(Available in MongoDB 4.2). For procedures using their ssl
aliases, see Procedure (Using ssl
Settings).
The tls
settings/options provide identical functionality
as the ssl
options since MongoDB has always supported TLS 1.0
and later.
For each node of a cluster, start the node with the command-line option
--tlsMode
or the configuration file optionnet.tls.mode
set toallowTLS
. TheallowTLS
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 [2] as well as any other options that are required for your specific configuration.Note
mongod
andmongos
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
ornet.bindIp
.For example:
mongod --replSet <name> --tlsMode allowTLS --tlsCertificateKeyFile <TLS/SSL certificate and key file> --tlsCAFile <path to root CA PEM file> <additional options> To specify these options in the configuration file, include the following settings 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
setParameter
command to update thetlsMode
topreferTLS
. [1] WithpreferTLS
as itsnet.tls.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, 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 the
setParameter
command to update thetlsMode
torequireTLS
. [1] WithrequireTLS
as itsnet.tls.mode
, the node will reject any non-TLS/non-SSL connections. For example:db.adminCommand( { setParameter: 1, tlsMode: "requireTLS" } ) 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.
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 one using only TLS/SSL encryption, use the following rolling upgrade process.
Note
The procedures in this section use the ssl
settings/option. For
procedures using their tls
aliases (Available in MongoDB 4.2),
see Procedure (Using tls
Settings).
The tls
settings/options provide identical functionality
as the ssl
options since MongoDB has always supported TLS 1.0
and later.
For each node of a cluster, start the node with the command-line option
--sslMode
or the configuration file optionnet.ssl.mode
set toallowSSL
. TheallowSSL
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 [2] as well as any other options that are required for your specific configuration.Note
mongod
andmongos
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
ornet.bindIp
.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> To specify these options in the configuration file, include the following settings 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
setParameter
command to update thesslMode
topreferSSL
. [1] WithpreferSSL
as itsnet.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.
For each node of the cluster, use the
setParameter
command to update thesslMode
torequireSSL
. [1] WithrequireSSL
as itsnet.ssl.mode
, the node will reject any non-TLS/non-SSL connections. For example:db.adminCommand( { 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, 3, 4) As an alternative to using the
setParameter command, you can also
restart the nodes with the appropriate TLS/SSL options and values. |
[2] | (1, 2) Starting in MongoDB 4.0, you can use system SSL certificate stores
for Windows and macOS. To use the system SSL certificate store, use:
|