Connection Parameters

Enterprise

Bacula Enterprise Only

This solution is only available for Bacula Enterprise. For subscription inquiries, please reach out to sales@baculasystems.com.

The plugin supports two connection styles:

• URI mode, using uri

• Structured mode, using host plus optional authentication, replica-set, and TLS parameters.

Use URI mode for simple configurations. Use structured mode when passwords, TLS files, or BWeb-generated forms should be kept as separate parameters.

Parameter Reference

Connection parameters

Option	Required	Default	Values	Example	Description
uri	Yes*		MongoDB connection string	mongodb://mongo1.example.com:27017/admin	Complete MongoDB URI. Do not combine with structured connection options such as host, username, replica_set, or TLS file parameters.
host	Yes*		host[:port]	mongo1.example.com:27017	MongoDB host or seed host. Repeat for replica-set seeds.
username	No		String	backup	MongoDB username. Required when password-based authentication is used.
password	No		String	secret	MongoDB password. Prefer password_file or password_env in production.
password_file	No		Path	/opt/bacula/etc/mongodb.pass	File containing the MongoDB password.
password_env	No		Environment variable name	MONGODB_BACKUP_PASSWORD	Environment variable containing the MongoDB password.
authentication_database	No	admin	Database name	admin	Authentication database. Use $external for MONGODB-X509.
authentication_mechanism	No	Driver default	SCRAM-SHA-1, SCRAM-SHA-256, MONGODB-X509	SCRAM-SHA-256	Authentication mechanism passed to the MongoDB driver and tools.
replica_set	No		Replica-set name	rs0	Expected replica-set name.
direct_connection	No	no	yes or no	yes	Force direct connection to one MongoDB node. Useful in controlled test environments.
tls	No	no	yes or no	yes	Enable TLS.
tls_ca_file	No		Path	/opt/bacula/etc/mongodb-ca.pem	PEM file containing trusted CA certificates.
tls_certificate_key_file	No		Path	/opt/bacula/etc/bacula-mongodb-client.pem	PEM file containing client certificate chain and unencrypted private key.
tls_allow_invalid_hostnames	No	no	yes or no	no	Allow TLS hostname mismatch. Use only in controlled labs or temporary migrations.

A connection definition is required for Bacula backup, restore, LIST, and QUERY operations. Use either uri or structured connection parameters. When structured parameters are used, at least one host value is required.

Use only one password source: password, password_file, or password_env.

Connection Rules by Scenario

Use the following combinations as the baseline for each deployment type:

• Standalone mongod (no replica set): use URI mode (uri=...) or structured mode with one host. Do not set replica_set. Keep direct_connection=no unless you explicitly need direct node binding.

• Replica set (recommended): use URI with multiple seeds or structured mode with multiple host entries plus replica_set=<name>. Keep direct_connection=no so MongoDB driver discovery can route operations to the writable primary.

• Replica set (forced single node): use direct_connection=yes only for controlled scenarios (for example diagnostics). For backup/restore operations, this node must be writable primary, otherwise operations can fail by design.

• Sharded cluster through mongos: connect to mongos routers (URI or structured host values that point to mongos), do not set replica_set, and keep direct_connection=no.

• TLS-enabled deployments: add tls=yes plus trust material (typically tls_ca_file). Add tls_certificate_key_file when client certificates are required.

• Authentication source selection: keep authentication_database=admin for most users; use $external only for external mechanisms such as X.509.

Practical safety rules:

• Pick one mode only: either uri or structured parameters.

• Keep credentials out of plain filesets when possible by using password_file or password_env.

• For replica sets, provide at least two seed hosts when available, so node changes do not break connectivity.

X.509 Rules

When authentication_mechanism=MONGODB-X509 is used:

• tls=yes is required.

• tls_certificate_key_file is required.

• authentication_database must be $external.

• Do not set password, password_file, or password_env.

• The username must match the client certificate subject exactly as MongoDB expects it.

Example subject:

X.509 username option

username="O=Bacula,OU=Backup,CN=bacula-mongodb-client"

See also

Next articles:

• Backup Parameters

• Restore Parameters

• Common Parameters

• Tuning Parameters

• Fileset Examples

Go back to: Plugin Configuration.