Navigation

TLS/SSL Configuration for Clients

On this page

Clients must have support for TLS/SSL to connect to a mongod or a mongos instance that require TLS/SSL connections.

Note
  • The Linux 64-bit legacy x64 binaries of MongoDB do not include support for TLS/SSL.
  • 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.

Note

Starting in version 4.2, MongoDB provides tls options that corresponds to the ssl options. The tls options provide identical functionality as the ssl options since MongoDB has always supported TLS 1.0 and later.

The procedures in this section use the tls options. For procedures using their ssl aliases, see mongosh Configuration (Using ssl Options).

mongosh provides various TLS/SSL settings, including:

TLS Option (New in 4.2)
Notes
Enables TLS/SSL connection.

Specifies the .pem file that contains mongosh's certificate and key to present to the mongod or mongos instance. This option is mutually exclusive with --tlsCertificateSelector

Changed in version 4.4: mongod / mongos logs a warning on connection if the presented x.509 certificate expires within 30 days of the mongod/mongos host system time. See x.509 Certificates Nearing Expiry Trigger Warnings for more information.

If mongosh's certificate key file is encrypted.
Specifies the Certificate Authority (CA) .pem file for verification of the certificate presented by the mongod or the mongos instance.

If running on Windows or macOS, use a certificate from the system certificate store. (New in version 4.0)

This option is mutually exclusive with --tlsCertificateKeyFile.

Changed in version 4.4: mongod / mongos logs a warning on connection if the presented x.509 certificate expires within 30 days of the mongod/mongos host system time. See x.509 Certificates Nearing Expiry Trigger Warnings for more information.

For a complete list of mongosh's tls options, see TLS Options.

For TLS/SSL connections, mongosh validates the certificate presented by the mongod or mongos instance:

Note

The procedure uses the tls options (available starting in MongoDB 4.2). For procedures using their ssl aliases, see mongosh Configuration (Using ssl Options).

To connect to a mongod or mongos instance that requires encrypted communication, start mongosh with:

For example, consider a mongod instance running on hostname.example.com with the following options:

mongod --tlsMode requireTLS --tlsCertificateKeyFile <pem>

To connect to the instance, start mongosh with the following options:

mongosh --tls --host hostname.example.com --tlsCAFile /etc/ssl/caToValidateServerCertificates.pem

mongosh verifies the certificate presented by the mongod instance against the specified hostname and the CA file.

Note

The procedure uses the tls options (available starting in MongoDB 4.2). For procedures using their ssl aliases, see mongosh Configuration (Using ssl Options).

To connect to a mongod or mongos that requires CA-signed client certificates, start mongosh with:

For example, consider a mongod instance running on hostname.example.com with the following options:

mongod --tlsMode requireTLS --tlsCertificateKeyFile /etc/ssl/mongodb.pem --tlsCAFile /etc/ssl/caToValidateClientCertificates.pem

To connect to the instance, start mongosh with the following options:

mongosh --tls --host hostname.example.com --tlsCertificateKeyFile /etc/ssl/client.pem --tlsCAFile /etc/ssl/caToValidateServerCertificates.pem
On Windows and macOS,

You can also use the --tlsCertificateSelector option to specify the client certificate from the system certificate store instead of using --tlsCertificateKeyFile. If the CA file is also in the system certificate store, you can omit the --tlsCAFile option as well. For example, to use a certificate with the CN (Common Name) of myclient.example.net and the CA file from the system certificate store on macOS, start mongosh with the following options:

mongosh --tls --host hostname.example.com --tlsCertificateSelector subject="myclient.example.net"

Although still available, mongosh --ssl, --sslCAFile, --sslPEMKeyFile, and --sslCertificateSelector options are deprecated as of MongoDB 4.2.

Warning

Although available, avoid using the --tlsAllowInvalidCertificates option if possible. If the use of --tlsAllowInvalidCertificates is necessary, only use the option on systems where intrusion is not possible.

If mongosh runs with the --tlsAllowInvalidCertificates option, mongosh will not attempt to validate the server certificates. This creates a vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. If you only need to disable the validation of the hostname in the TLS/SSL certificates, see --tlsAllowInvalidHostnames.

mongosh provides various TLS/SSL settings, including:

SSL Option (Deprecated in 4.2)
Notes
--ssl
Enables TLS/SSL connection.
--sslPEMKeyFile
Specifies the .pem file that contains mongosh's certificate and key to present to the mongod or mongos instance.
--sslPEMKeyPassword
If mongosh's certificate key file is encrypted.
--sslCAFile
Specifies the Certificate Authority (CA) .pem file for verification of the certificate presented by the mongod or the mongos instance.
--sslCertificateSelector
If running on Windows or macOS, use a certificate from the system certificate store. (New in version 4.0)

For a complete list of ssl options, see SSL Options.

For TLS/SSL connections, mongosh validates the certificate presented by the mongod or mongos instance:

Note

The procedure uses the ssl options. For procedures using the tls aliases (available starting in MongoDB 4.2), see mongosh Configuration (Using tls Options).

To connect to a mongod or mongos instance that requires encrypted communication, start mongosh with:

For example, consider a mongod instance running on hostname.example.com with the following options:

mongod --sslMode requireSSL --sslPEMKeyFile <pem>

To connect to the instance, start mongosh with the following options:

mongosh --ssl --host hostname.example.com --sslCAFile /etc/ssl/caToValidateServerCertificates.pem

mongosh verifies the certificate presented by the mongod instance against the specified hostname and the CA file.

Note

The procedure uses the ssl options. For procedures using the tls aliases (available starting in MongoDB 4.2), see mongosh Configuration (Using tls Options).

To connect to a mongod or mongos that requires CA-signed client certificates, start mongosh with:

For example, consider a mongod instance running on hostname.example.com with the following options:

mongod --sslMode requireSSL --sslPEMKeyFile /etc/ssl/mongodb.pem --sslCAFile /etc/ssl/ca.pem

To connect to the instance, start mongosh with the following options:

mongosh --ssl --host hostname.example.com --sslPEMKeyFile /etc/ssl/client.pem --sslCAFile /etc/ssl/ca.pem
On Windows and macOS,

You can also use the --sslCertificateSelector option to specify the client certificate from the system certificate store instead of using --sslPEMKeyFile. If the CA file is also in the system certificate store, you can omit the --sslCAFile option as well. For example, to use a certificate with the CN (Common Name) of myclient.example.net and the CA file from the system certificate store on macOS, start mongosh with the following options:

mongosh --ssl --host hostname.example.com --sslCertificateSelector subject=myclient.example.net
Warning

Although available, avoid using the --sslAllowInvalidCertificates option if possible. If the use of --sslAllowInvalidCertificates is necessary, only use the option on systems where intrusion is not possible.

If mongosh (and other MongoDB Tools) runs with the --sslAllowInvalidCertificates option, mongosh (and other MongoDB Tools) will not attempt to validate the server certificates. This creates a vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. If you only need to disable the validation of the hostname in the TLS/SSL certificates, see --sslAllowInvalidHostnames.

MongoDB Atlas uses TLS/SSL to encrypt the connections to your databases.

The MongoDB Cloud Manager and Ops Manager Monitoring agents use encrypted communication to gather its statistics. Because the agents already encrypt communications to the MongoDB Cloud Manager/Ops Manager servers, this is just a matter of enabling TLS/SSL support in MongoDB Cloud Manager/Ops Manager on a per host basis.

For more information, see:

The MongoDB Drivers support encrypted communication. See:

Various MongoDB utility programs support encrypted communication. These tools include:

To use encrypted communication with these tools, use the same ssl options as mongosh. See mongosh Configuration (Using ssl Options).

Tip
See also:
Give Feedback

On this page