Moving A Cluster to MongoDB Enterprise with SSL

Porsche_356_CarreraWHY SSL

MongoDB’s SSL support allows MongoDB clients to talk to the database using encrypted connections for security. Now if you are trying to run  from a regular distribution of MongoDB, it probably will not work, because the fre version of MongoDB does not contain support for SSL. To use SSL, you must either build MongoDB yourself or buy MongoDB Enterprise.

What this blog post is about, how to move a cluster running MongoDB to MongoDB Enterprise with SSL, and a little background into what is going on with the MongoDB servers in the process.

More of an outline for getting started with SSL and assume that you have already installed a build of MongoDB that includes SSL support and that your client driver supports SSL.

There are two parts relevant to moving your cluster to SSL. The server side as the servers communicate with each other and the client side that send queries to the servers. In MongoDB 2.6, there is a new net.ssl.mode parameter that can ease the transition.


The net.ssl.mode parameter is new in version 2.6. There are four modes that ssl can operate using. The major difference is how the servers communicate between servers. One of the reason you may consider this is because of client drivers.

disabled No SSL encrypted connections
allowSSL Between servers do not use SSL. Otherwise accept both SSL and non-SSL.
preferSSL Between servers use SSL. Otherwise accept both SSL and non-SSL.
requireSSL Only SSL encrypted connections


MongoDB Servers

Servers can operate in three modes. The first is SSL encryption mode where everything is encrypted. The second is that clients have a cert from a certificate authority , which rules out self signed certificates. Finally, the server validates with a valid certificate or NO certificate. The last mode only fails if the client passes and invalid certificate.

To upgrade a cluster, you go through the three SSL modes. First you start the server nodes with all the nodes using allowSSL. Then using this command update the entire cluster to preferSSL

db.getSiblingDB('admin').runCommand( { setParameter: 1, sslMode: "preferSSL" } )

And finally , the last move to requireSSL, which blocks any non SSL nodes.

db.getSiblingDB('admin').runCommand( { setParameter: 1, sslMode: "requireSSL" } )

After this, update /etc/mongodb.conf to requireSSL so the settings will stay the same after a reboot

MongoDB SSL Clients

Now that the servers are running in SSL, lets look the MongoDB client.  All the mongo tools, (mongo, mongodump, mongoexport,mongofiles,mongoimport,mongooplog, mongorestore, mongostat, mongotop ) need to have SSL configured, in the same way as the shell. Since you will be upgrading your cluster, you need your shell configured first.

As an example with mongo ( that is just as valid with the other mongo utilities ), you would pass -ssl along with a .pem file.

mongo --ssl --sslPEMKeyFile /etc/ssl/client.pem

If the server only cared about encryption, then passing -ssl would be fine

mongo --ssl

Not all client drivers support SSL connections. This is a pain, and another reason why you should use the official driver. I was using a C# driver that did not support SSL and when the requirement came along to use SSL , then a lot of re-factorings had to happen switching to the official driver which did support SSL.

A Note on FIPS

The United States government defines many (several hundred) “Federal Information Processing Standard” (FIPS) documents. One of the FIPS regulations, FIPS 140, governs the use of encryption and cryptographic services. FIPS Mode”, which is really “FIPS 140 Mode”. Both MongoDB Enterprise and MongoDB compiled with –ssl can operate in FIPS 140 Mode.