Docs Menu
Docs Home
/
Languages
/
C++
/
C++ Driver

Configuration

On this page

  • Configuring TLS/SSL
  • Configuring Authentication
  • Configuring a connection pool
  • Compressing data to and from MongoDB

In the mongocxx driver, most configuration is done via the connection URI. Some additional connection options are possible via the mongocxx::options::client class.

Configuring TLS/SSL

To enable TLS (SSL), set tls=true in the URI:

mongodb://mongodb.example.com/?tls=true

By default, mongocxx will verify server certificates against the local system CA list. You can override that either by specifying different settings in the connection string, or by creating a mongocxx::options::tls object and passing it to tls_opts on mongocxx::options::client.

For example, to use a custom CA or to disable certificate validation, see the following example:

// 1) Using tls_options
mongocxx::options::client client_options;
mongocxx::options::tls tls_options;
// If the server certificate is not signed by a well-known CA,
// you can set a custom CA file with the `ca_file` option.
tls_options.ca_file("/path/to/custom/cert.pem");
// If you want to disable certificate verification, you
// can set the `allow_invalid_certificates` option.
tls_options.allow_invalid_certificates(true);
client_options.tls_opts(tls_options);
auto client1 = mongocxx::client{uri{"mongodb://host1/?tls=true"}, client_options};
// 2) Using the URI
auto client2 = mongocxx::client{uri{"mongodb://host1/?tls=true&tlsAllowInvalidCertificates=true&tlsCAFile=/path/to/custom/cert.pem"}};

Configuring Authentication

Default Authentication Mechanism

MongoDB 3.0 changed the default authentication mechanism from MONGODB-CR to SCRAM-SHA-1. To create a credential that will authenticate properly regardless of server version, use a connection string with the user and password directly in the URI and with a parameter specifying the database to authenticate from:

#include <mongocxx/client.hpp>
#include <mongocxx/uri.hpp>
auto client = mongocxx::client{uri{"mongodb://user1:pwd1@host1/?authSource=db1"}};

SCRAM-SHA-1

To explicitly create a credential of type SCRAM-SHA-1 use a connection string as above but with a parameter specifying the authentication mechanism as "SCRAM-SHA-1":

#include <mongocxx/client.hpp>
#include <mongocxx/uri.hpp>
auto client = mongocxx::client{
    uri{"mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-1"}
    };

MONGODB-CR

The MONGODB-CR authMechanism is deprecated and will no longer function in MongoDB 4.0. Instead, specify no authMechanism and the driver will use an authentication mechanism compatible with your server.

X.509

The X.509 mechanism authenticates a user whose name is derived from the distinguished subject name of the X.509 certificate presented by the driver during TLS negotiation. This authentication method requires the use of TLS connections with certificate validation and is available in MongoDB 2.6 and newer. To create a credential of this type, use a connection string with a parameter that specifies the authentication mechanism as "MONGODB-X509", that specifies the path to the PEM file containing the client private key and certificate, and that has TLS enabled:

#include <mongocxx/client.hpp>
#include <mongocxx/uri.hpp>
auto client = mongocxx::client{
    uri{"mongodb://host1/?authMechanism=MONGODB-X509&tlsCertificateKeyFile=client.pem&tls=true"}
    };

See the MongoDB server X.509 tutorial for more information about determining the subject name from the certificate.

The PEM file can also be specified using the mongocxx::options::tls class, see the default TLS/SSL configuration example above.

Kerberos (GSSAPI)

MongoDB Enterprise supports proxy authentication through Kerberos service. To create a credential of type Kerberos (GSSAPI) use a connection string with the username and realm in the URI as well as a parameter specifying the authentication mechanism as "GSSAPI":

#include <mongocxx/client.hpp>
#include <mongocxx/uri.hpp>
auto client = mongocxx::client{
    uri{"mongodb://username%40REALM.COM@host1/?authMechanism=GSSAPI"}
    };

Note

The @ symbol in the URI string must be escaped to %40 as shown in the example above.

LDAP

MongoDB Enterprise supports proxy authentication through a Lightweight Directory Access Protocol (LDAP) service. To create a credential of type LDAP use a connection string specifying the user as well as parameters specifying the authentication source as "$external" and the authentication mechanishm as "PLAIN":

#include <mongocxx/client.hpp>
#include <mongocxx/uri.hpp>
auto client = mongocxx::client{
    uri{"mongodb://user1:pwd1@host1/?authSource=$external&authMechanism=PLAIN"}
    };

Configuring a connection pool

To configure a connection pool, first create a mongocxx::pool, passing the URI as an argument. The size of the pool can be configured in the URI. Then, call mongocxx::pool::acquire to receive a client from the pool. The client will automatically be returned to the pool when it goes out of scope.

#include <mongocxx/pool.hpp>
#include <mongocxx/uri.hpp>
auto pool = mongocxx::pool{uri{"mongodb://host1/?minPoolSize=3&maxPoolSize=5"}};
{
    // To get a client from the pool, call `acquire()`.
    auto client = pool.acquire();
    // The client is returned to the pool when it goes out of scope.
}

See connection pool documentation for more details.

Compressing data to and from MongoDB

MongoDB 3.4 added Snappy compression support, while zlib compression was added in 3.6, and zstd compression in 4.2.

You can enable data compression the appropriate URI options. Learn about these options in the MongoDB C driver API documentation.

Back

Advanced Configuration and Installation Options