Connections: TLS, x509, LDAP, Kerberos, Atlas and AWS¶

A connection is a MongoDB connection string plus optional TLS material. MongoRescue uses it in two ways:

The Database Tools (mongodump, mongorestore) move the data. They get the connection string through a private --config file, never on the command line.
The Go driver runs everything else: the connection test, database and collection discovery, manifests, the restore preflight, restore tests, post-restore commands and the PITR oplog reader.

A connection only works if both sides can authenticate. This page lists, per method, what to enter, which privileges the user needs, and whether the method is tested.

What is tested¶

Method	Status	How
Username and password (SCRAM)	Tested in CI	The whole integration suite (`scripts/test-integration-docker.sh`), MongoDB 5.0 to 8.0, standalone and replica set
TLS with a custom CA	Tested in CI	`TestTLSWithCustomCA`: a MongoDB with `--tlsMode requireTLS` and a CA generated by the test; backup and restore with the real tools, the connection test with and without the CA
x509 client certificate	Tested in CI	`TestX509ClientCertificate`: an `$external` user named after the client certificate, `MONGODB-X509`, an encrypted PKCS#8 key; backup, restore, connection test and discovery
MongoDB Atlas (`mongodb+srv://`)	Not tested in CI	Atlas cannot run in CI. Use the manual checklist
LDAP (`PLAIN`)	Not tested	LDAP needs MongoDB Enterprise or Atlas. MongoDB Community, which CI runs, has no LDAP
Kerberos (`GSSAPI`)	Not tested, not supported by the release builds	See Kerberos
AWS IAM (`MONGODB-AWS`)	Not tested	Supported by the driver and the Database Tools; needs Atlas or a MongoDB with AWS authentication

"Not tested" means the URI is passed through unchanged and probably works. It does not mean the method is supported. Run the checklist against your server before you rely on it.

TLS settings¶

The connection form has a TLS / client certificate section. The API takes the same fields on POST /api/v1/connections, PUT /api/v1/connections/{id} and POST /api/v1/connections/test:

Field	Meaning
`tls_ca_pem`	PEM certificates of the CA that signed the server certificate. Empty: the system roots
`tls_client_cert_pem`	PEM client certificate for x509 authentication, intermediates after it
`tls_client_key_pem`	Its private key, PKCS#1, SEC 1 or PKCS#8. Sealed at rest, returned as `******`
`tls_client_key_password`	Password of an encrypted PKCS#8 key. Sealed at rest, returned as `******`
`tls_allow_invalid_hostnames`	Skip the check that the server certificate names the host. The chain is still verified. The dashboard shows a warning
`tls_insecure`	Accept any server certificate. Only taken with `"tls_insecure_confirm": true` the first time it is turned on. The dashboard asks for confirmation and marks the connection TLS not verified

Rules:

An omitted field keeps the stored value, and "" removes it. Send ****** back for the key or password to keep it, like the URI's password.
The material is checked on save. The CA must parse, the certificate and key must match, and an encrypted key must open with its password. Errors name the field and never quote its value.
Legacy encrypted PEM keys are refused (Proc-Type: 4,ENCRYPTED). Convert them: openssl pkcs8 -topk8 -v2 aes256 -in old.key -out new.key.
Encrypted keys must use PBES2 with bounded key derivation: PBKDF2 with at most 1,000,000 iterations, or scrypt with N at most 2^20, r at most 32, p at most 16, r·p at most 64 and at most 256 MiB of memory (128·N·r). Other keys are refused on save before anything is derived. A key is derived once and kept in memory, parsed, until its connection changes or is deleted or secret.key is rotated.
TLS goes in the fields or in the URI, not both. A URI with tlsCAFile, tlsCertificateKeyFile, tlsCertificateKeyFilePassword, tlsInsecure, tlsAllowInvalidCertificates, tlsAllowInvalidHostnames or their ssl* forms is refused when TLS fields are set, and so is tls=false. Setting any TLS field adds tls=true to the stored connection string, so a client that is built from the connection string alone still uses TLS, verified against the system roots, and never falls back to plain text.
Changing the TLS material clears the last connection test.
The material belongs to the hosts it was saved for. Testing a connection string with other hosts (POST /api/v1/connections/test with connection_id) uses none of the stored material: no CA, no client key, no loosened checks. Moving a connection that has tls_insecure to other hosts needs tls_insecure_confirm again.
Loosened checks stay visible. Turning tls_insecure or tls_allow_invalid_hostnames on or off is recorded in the audit log of the request (tls_insecure_from/tls_insecure_to, tls_allow_invalid_hostnames_from/tls_allow_invalid_hostnames_to) and logged as a warning. While any connection has either on, GET /api/v1/settings reports the connection_tls_loosened warning with those connections (connections), and the dashboard shows it as a banner next to the badges in the connections table.

How the material is used:

The driver builds its TLS configuration in memory (TLS 1.2 or later). No file is written.
The tools get the material as files in a private directory (0700) in the temporary directory: ca.pem and client.pem (certificate followed by the key), each 0600. They are named by --ssl, --sslCAFile and --sslPEMKeyFile, and the loosened checks by --sslAllowInvalidHostnames and --sslAllowInvalidCertificates. The key password goes into the --config file with the URI as sslPEMKeyPassword, because the tools' configuration file accepts only uri, password and sslPEMKeyPassword. The directory is removed when the tool exits, also after a failure or a panic. Directories left by a crash are removed at the next start.
Neither is logged. PEM contents and passwords never appear in logs, errors, run logs or API responses.
The client key and its password are sealed with secret.key, bound to their connection, and re-sealed by a key rotation. The CA and the client certificate are public and stored in plain form.

Temporary credentials on disk¶

While mongodump or mongorestore runs, the connection string (with its password) and, for TLS connections, the CA, the client certificate with its key and the key's password are in files the tool reads. They are in a private directory (0700, files 0600, readable by MongoRescue's user only) that is removed as soon as the tool exits, also after a failure. Directories left by a crash or SIGKILL are removed at the next start.

The directory is the system temporary directory (TMPDIR), or MONGORESCUE_TMP_DIR / -tmp-dir when set; <data dir>/tmp is used only when the system one is not writable. Keep it off persistent and backed-up disks:

Kubernetes: the Helm chart mounts a memory-backed emptyDir (credentialsTmp.medium: Memory) at /run/mongorescue-tmp and sets MONGORESCUE_TMP_DIR to it, so these files never reach a node's disk. See kubernetes.md.
Docker: /tmp is in the container's writable layer. To keep the files in RAM, add a tmpfs, for example --tmpfs /run/mongorescue-tmp:mode=0700,uid=10001 with -e MONGORESCUE_TMP_DIR=/run/mongorescue-tmp.
Linux and macOS: a tmpfs /tmp (the default on many distributions) keeps them in RAM. Otherwise point MONGORESCUE_TMP_DIR at one.
Windows: 0700/0600 modes do not apply. The files inherit the ACL of their directory: the default %TEMP% (C:\Users\<user>\AppData\Local\Temp) is readable only by that user, administrators and SYSTEM. If you set MONGORESCUE_TMP_DIR, choose a directory whose inherited ACL grants no one else access.
Swap and backups: exclude the directory from file-level backups and antivirus uploads, and use encrypted swap if memory-backed directories can be swapped out.

TLS with a custom CA¶

For a server whose certificate is signed by a private CA:

mongodb://<username>:<password>@db1.internal:27017,db2.internal:27017/?replicaSet=rs0&tls=true&authSource=admin

Paste the CA certificate, or a bundle with the intermediates, into CA certificate (PEM), or load it from a file. A server that requires client certificates for every connection (net.tls.allowConnectionsWithoutCertificates: false, the default when the server has a CA file) also needs the client certificate and key below, even with password authentication.

Check the certificate's host names before you turn on Allow invalid hostnames. The certificate must name every host in the URI, or the replica set members' names as the server reports them. Fix the certificate or connect by the names it lists.

x509 client certificates¶

Issue a client certificate whose subject differs from the server certificates in at least one of O, OU or DC. MongoDB treats a certificate with the same values as a cluster member.
Read the subject in RFC 2253 order:

openssl x509 -in client.crt -noout -subject -nameopt RFC2253
# subject=CN=backup,OU=Clients,O=Example

Create the user in $external, with the roles from Privileges:

db.getSiblingDB("$external").createUser({
  user: "CN=backup,OU=Clients,O=Example",
  roles: [{ role: "backup", db: "admin" }, { role: "restore", db: "admin" }]
})

Create the connection with no user name or password in the URI:

mongodb://db1.internal:27017/?tls=true&authMechanism=MONGODB-X509

Then set the CA, the client certificate, the key and, for an encrypted key, its password.

LDAP (PLAIN)¶

Requires MongoDB Enterprise or Atlas with LDAP configured. Not tested.

mongodb://<ldap_user>:<password>@db1.internal:27017/?authMechanism=PLAIN&authSource=%24external&tls=true

PLAIN sends the password as it is, so always use TLS. Set the CA field if the server certificate has a private CA. The user's roles come from the LDAP groups mapped on the server (security.ldap.authz.queryTemplate). Map a group to the roles in Privileges.

Kerberos (GSSAPI)¶

Not tested, and not supported by the release builds. The Go driver supports Kerberos only when it is built with cgo and the gssapi build tag. MongoRescue's binaries and image are built with CGO_ENABLED=0. With authMechanism=GSSAPI, the connection test, discovery, manifests, preflight and restore tests fail with GSSAPI support not enabled during build. The Database Tools may still authenticate if they were built with Kerberos support, but a backup also needs the driver.

If you build MongoRescue yourself with CGO_ENABLED=1 go build -tags gssapi ./cmd/mongorescue, the host needs the Kerberos libraries, a krb5.conf and a ticket or keytab for the principal, available to the MongoRescue process and to the tools it starts (KRB5_CONFIG, KRB5_CLIENT_KTNAME). The URI percent-encodes the @ of the principal:

mongodb://backup%40EXAMPLE.COM@db1.internal:27017/?authMechanism=GSSAPI&authSource=%24external&authMechanismProperties=SERVICE_NAME:mongodb

MongoDB Atlas¶

Use the SRV connection string from Connect → Drivers:

mongodb+srv://<db_username>:<db_password>@cluster0.abcde.mongodb.net/?retryWrites=true&w=majority&appName=mongorescue

mongodb+srv:// turns on TLS. Atlas certificates are signed by public CAs, so leave the TLS fields empty. The Docker image includes the system CA bundle (ca-certificates).
DNS must resolve the SRV and TXT records of the cluster from where MongoRescue runs.
Add the MongoRescue host's outbound address to the project's IP access list, or use private endpoints or peering.
Give the database user the roles from Privileges, through Atlas's built-in or custom database roles.
Atlas's own snapshots and point-in-time restore are independent of MongoRescue.

Atlas manual test checklist¶

Run this before you rely on MongoRescue for an Atlas cluster, and again after you change the cluster tier, the MongoDB version or the network setup:

Create the connection with the SRV string. Test connection reports the server version and, for a backup read preference, the member it reads from.
Run a backup of a small database. It completes, and the archive is verified after the upload.
Restore it into a safe clone (<db>_rescue_<timestamp>). The preflight passes, and the clone has the same document counts. Drop the clone.
With a secondary read preference, check in the run log that the dump read from a secondary.
Run a restore test of the job. It reports ok.
If you use PITR, the oplog window appears and a base backup completes. Atlas restricts some commands on shared and flex tiers; check there first.
Check that the run logs, the connection list and the API responses show the password as ******.

AWS IAM (MONGODB-AWS)¶

For Atlas or a MongoDB with AWS IAM authentication. Not tested. The driver and the Database Tools read the AWS credentials from the environment (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN) or from the EC2, ECS or EKS role of the host. Keep the URI free of credentials:

mongodb+srv://cluster0.abcde.mongodb.net/?authMechanism=MONGODB-AWS&authSource=%24external

Keys in the URI (mongodb+srv://AKIA...:SECRET@...) also work. They are sealed and redacted like a password.

Privileges¶

The same for every authentication method. Give the roles to the user in admin, or in $external for x509, LDAP, Kerberos and AWS:

Task	Minimum
Back up one database	`read` on it (`backup` for users and roles, `include_users_and_roles`)
Back up all databases, or with `--oplog`	`backup`
Restore into a safe clone	`readWrite` on the new database (`restore` covers all; bypassing validators needs `restore`)
Restore in place with users and roles	`restore`
Restore tests	`readWriteAnyDatabase`, or `restore` plus `dbAdminAnyDatabase` (see verification.md)
PITR oplog reads	`read` on `local` (see pitr.md)
Point-in-time restores	`restore`, `readWriteAnyDatabase` and `dbAdminAnyDatabase`, or `anyAction`

The restore preflight checks the target user's privileges before anything is written and names the missing ones.