Restore
EnterpriseBacula Enterprise Only
This solution is only available for Bacula Enterprise. For subscription inquiries, please reach out to sales@baculasystems.com.
Restore Procedure
The MongoDB Plugin restores Bacula MongoDB artifacts into a running MongoDB target. The target may be the original deployment, a replacement deployment, or a dedicated isolated disaster-recovery environment.
The Bacula restore workflow is:
Start a Bacula restore session.
Select the required MongoDB files under
/@mongodb.Use
Where=/so plugin restore handling receives the original virtual paths.Set plugin restore options such as
conflict_strategy,map_db,replay_to, orisolated_dr.Run
dry_run=yesfirst for important production recoveries.Run the restore job.
Validate application data, indexes, users, roles, and application behavior after restore.
Local Path File-based Restore
Use Where=/local/fd/path to perform a file-based restore over the File Daemon
host in the selected path, instead of running the restore over a running MongoDB
target.
Restore Example Session
*restore jobid=1,2 where=/
You have selected the following JobIds: 1,2
Building directory tree for JobId(s) 1,2 ...
8 nodes inserted into the tree.
You are now entering file selection mode where you add (mark) and
remove (unmark) files to be restored. No files are initially added, unless
you used the "all" keyword on the command line.
Enter "done" to leave this mode.
cwd is: /
$ cd @mongodb
cwd is: /@mongodb/
$ dir
---------- 0 root root 0 1970-01-01 01:00:00 /@mongodb/.bacula-incremental-state/
-rw-r----- 1 nobody nogroup 1546 2026-05-12 13:24:09 /@mongodb/chain-index.json
---------- 0 root root 0 1970-01-01 01:00:00 /@mongodb/dump/
-rw-r----- 1 nobody nogroup 3792 2026-05-12 13:24:09 /@mongodb/manifest.json
---------- 0 root root 0 1970-01-01 01:00:00 /@mongodb/oplog/
$ mark *
8 files marked.
$ done
Bootstrap records written to /tmp/regress/working/127.0.0.1-dir.restore.4.bsr
The Job will require the following (*=>InChanger):
Volume(s) Storage(s) SD Device(s)
===========================================================================
TEST-2026-05-12:0 File FileStorage
Volumes marked with "*" are in the Autochanger.
8 BSR records selected to be restored.
Automatically selected Client: 127.0.0.1-fd
Using Catalog "MyCatalog"
Run Restore job
JobName: RestoreFiles
Bootstrap: /tmp/regress/working/127.0.0.1-dir.restore.4.bsr
Where: /
Replace: Always
FileSet: Full Set
Backup Client: 127.0.0.1-fd
Restore Client: 127.0.0.1-fd
Storage: File
When: 2026-05-12 13:42:29
Catalog: MyCatalog
Priority: 10
Plugin Options: *None*
OK to run? (Yes/mod/no): mod
Parameters to modify:
1: Level
2: Storage
3: Job
4: FileSet
5: Restore Client
6: When
7: Priority
8: Bootstrap
9: Where
10: File Relocation
11: Replace
12: JobId
13: Plugin Options
Select parameter to modify (1-13): 13
Automatically selected : mongodb: uri="mongodb://127.0.0.1:27043/admin?replicaSet=rs0&directConnection=true" database="appdb" skip_security=yes debug=0
Plugin Restore Options
Option Current Value Default Value
uri: *None* (*none*)
host: *None* (*none*)
username: *None* (*none*)
password: *None* (*none*)
password_env: *None* (*none*)
password_file: *None* (*none*)
authentication_database: *None* (*none*)
authentication_mechanism: *None* (*none*)
replica_set: *None* (*none*)
direct_connection: *None* (*none*)
tls: *None* (*none*)
tls_ca_file: *None* (*none*)
tls_certificate_key_file: *None* (*none*)
tls_allow_invalid_hostnames: *None* (*none*)
conflict_strategy: *None* (*none*)
map_db: *None* (*none*)
collection: *None* (*none*)
replay_to: *None* (*none*)
isolated_dr: *None* (*none*)
recover_admin: *None* (*none*)
skip_security: *None* (*none*)
report_format: *None* (*none*)
dry_run: *None* (*none*)
stream_telemetry: *None* (*none*)
debug: *None* (*none*)
Use above plugin configuration? (Yes/mod/no): mod
You have the following choices:
1: uri (MongoDB connection string with administrative credentials for the restore target)
2: host (MongoDB host[:port] for a structured restore connection. For multiple hosts, use a comma-separated list)
3: username (MongoDB username for structured restore connections)
4: password (MongoDB password for structured restore connections)
5: password_env (Environment variable containing the MongoDB password)
6: password_file (File containing the MongoDB password)
7: authentication_database (MongoDB authentication database)
8: authentication_mechanism (MongoDB authentication mechanism)
9: replica_set (Replica set name expected by the target connection)
10: direct_connection (Force a direct connection to a single MongoDB node)
11: tls (Enable TLS for restore connections and MongoDB tools)
12: tls_ca_file (PEM file containing trusted CA certificates for MongoDB TLS)
13: tls_certificate_key_file (PEM file containing the client certificate chain and private key)
14: tls_allow_invalid_hostnames (Allow TLS when the certificate hostname does not match)
15: conflict_strategy (Restore conflict strategy: fail, drop, or skip)
16: map_db (Database remapping in source=target form. For multiple mappings, use a comma-separated list)
17: collection (Collection name to restore. For multiple collections, use a comma-separated list)
18: replay_to (Replay limit for oplog-based restore in seconds[:ordinal] form)
19: isolated_dr (Enable isolated disaster-recovery restore rules)
20: recover_admin (Replay the dumped admin database during isolated DR when supported)
21: skip_security (Skip users and roles during restore)
22: report_format (Dry-run report format: text or json)
23: dry_run (Run restore preflight without changing the target)
24: stream_telemetry (Enable verbose stream telemetry logs (bytes, throughput, duration))
25: debug (Change debug level)
Select parameter to modify (1-25): 1
Please enter a value for uri: mongodb://127.0.0.1:27044/admin?replicaSet=rs0&directConnection=true
Plugin Restore Options
Option Current Value Default Value
uri: mongodb://127.0.0.1:27044/admin?replicaSet=rs0&directConnection=true (*none*)
host: *None* (*none*)
username: *None* (*none*)
password: *None* (*none*)
password_env: *None* (*none*)
password_file: *None* (*none*)
authentication_database: *None* (*none*)
authentication_mechanism: *None* (*none*)
replica_set: *None* (*none*)
direct_connection: *None* (*none*)
tls: *None* (*none*)
tls_ca_file: *None* (*none*)
tls_certificate_key_file: *None* (*none*)
tls_allow_invalid_hostnames: *None* (*none*)
conflict_strategy: *None* (*none*)
map_db: *None* (*none*)
collection: *None* (*none*)
replay_to: *None* (*none*)
isolated_dr: *None* (*none*)
recover_admin: *None* (*none*)
skip_security: *None* (*none*)
report_format: *None* (*none*)
dry_run: *None* (*none*)
stream_telemetry: *None* (*none*)
debug: *None* (*none*)
Use above plugin configuration? (Yes/mod/no): yes
Run Restore job
JobName: RestoreFiles
Bootstrap: /tmp/regress/working/127.0.0.1-dir.restore.4.bsr
Where: /
Replace: Always
FileSet: Full Set
Backup Client: 127.0.0.1-fd
Restore Client: 127.0.0.1-fd
Storage: File
When: 2026-05-12 13:42:29
Catalog: MyCatalog
Priority: 10
Plugin Options: User specified
OK to run? (Yes/mod/no): yes
Job queued. JobId=7
| 127.0.0.1-dir JobId 7: Start Restore Job RestoreFiles.2026-05-12_13.43.24_26 |
| 127.0.0.1-dir JobId 7: Restoring files from JobId(s) 1,2 |
| 127.0.0.1-dir JobId 7: Connected to Storage "File" at 127.0.0.1:8103 with TLS |
| 127.0.0.1-dir JobId 7: Using Device "FileStorage" to read. |
| 127.0.0.1-dir JobId 7: Connected to Client "127.0.0.1-fd" at 127.0.0.1:8102 with TLS |
| 127.0.0.1-fd JobId 7: Connected to Storage at 127.0.0.1:8103 with TLS |
| 127.0.0.1-sd JobId 7: Ready to read from volume "TEST-2026-05-12:0" on File device "FileStorage" (/tmp/regress/tmp). |
| 127.0.0.1-sd JobId 7: Forward spacing Volume "TEST-2026-05-12:0" to addr=249 |
| 127.0.0.1-sd JobId 7: Elapsed time=00:00:01, Transfer rate=11.23 K Bytes/second |
| 127.0.0.1-fd JobId 7: mongodb: Jar Version: 0.1.0 | Java version: 21.0.10 | Java Pid: 316898 |
| 127.0.0.1-fd JobId 7: mongodb: MongoDB Bacula restore target connection: hosts=127.0.0.1:27044, replicaSet=rs0, directConnection=true, tls=false |
| 127.0.0.1-fd JobId 7: mongodb: Using Bacula restore stream plan to stream archive dump/appdb.archive without staging dump payload (security: false, collection scoped: false). |
| 127.0.0.1-fd JobId 7: mongodb: Restoring database appdb into appdb |
| 127.0.0.1-fd JobId 7: mongodb: Direct streaming restore for dump/appdb.archive into appdb |
| 127.0.0.1-fd JobId 7: mongodb: Staged Bacula restore control metadata file .bacula-incremental-state/1778585042-job-1/manifest.json under /tmp/regress/working/mongodb/RestoreFiles.2026-05-12_13.43.24_26/mongodb-bacula-restore-7-16970689073729387253. |
| 127.0.0.1-fd JobId 7: mongodb: Staged Bacula restore control metadata file chain-index.json under /tmp/regress/working/mongodb/RestoreFiles.2026-05-12_13.43.24_26/mongodb-bacula-restore-7-16970689073729387253. |
| 127.0.0.1-fd JobId 7: mongodb: Staged Bacula restore oplog recovery payload file oplog/local/oplog.rs.bson under /tmp/regress/working/mongodb/RestoreFiles.2026-05-12_13.43.24_26/mongodb-bacula-restore-7-16970689073729387253. |
| 127.0.0.1-fd JobId 7: mongodb: Staged Bacula restore oplog recovery payload file oplog/local/oplog.rs.metadata.json under /tmp/regress/working/mongodb/RestoreFiles.2026-05-12_13.43.24_26/mongodb-bacula-restore-7-16970689073729387253. |
| 127.0.0.1-fd JobId 7: mongodb: Staged Bacula restore oplog recovery payload file oplog/local/prelude.json under /tmp/regress/working/mongodb/RestoreFiles.2026-05-12_13.43.24_26/mongodb-bacula-restore-7-16970689073729387253. |
| 127.0.0.1-fd JobId 7: mongodb: Staged Bacula restore control metadata file .bacula-incremental-state/1778585049-job-2/manifest.json under /tmp/regress/working/mongodb/RestoreFiles.2026-05-12_13.43.24_26/mongodb-bacula-restore-7-16970689073729387253. |
| 127.0.0.1-fd JobId 7: mongodb: Auto-selected replay boundary from included recovery chain metadata: 1778585044:3 |
| 127.0.0.1-fd JobId 7: mongodb: Replaying oplog segment 1778585036:5 -> 1778585044:3 from streamed restore metadata at /tmp/regress/working/mongodb/RestoreFiles.2026-05-12_13.43.24_26/mongodb-bacula-restore-7-16970689073729387253/.stream-replay-artifacts/1778585049-job-2 |
| 127.0.0.1-fd JobId 7: mongodb: MongoDB Bacula restore finished in direct archive stream mode. |
| 127.0.0.1-dir JobId 7: Bacula 127.0.0.1-dir 18.2.4 (10Mar26):
Build OS: x86_64-pc-linux-gnu ubuntu 24.04
JobId: 7
Job: RestoreFiles.2026-05-12_13.43.24_26
Restore Client: "127.0.0.1-fd" 18.2.4 (10Mar26) x86_64-pc-linux-gnu,ubuntu,24.04
Where: /
Replace: Always
Start time: 12-may-2026 13:43:26
End time: 12-may-2026 13:43:29
Elapsed time: 3 secs
Files Expected: 8
Files Restored: 8
Bytes Restored: 15,921 (15.92 KB)
Rate: 5.3 KB/s
FD Errors: 0
FD termination status: OK
SD termination status: OK
Termination: Restore OK |
| 127.0.0.1-dir JobId 7: Begin pruning Jobs older than 6 months . |
| 127.0.0.1-dir JobId 7: No Jobs found to prune. |
| 127.0.0.1-dir JobId 7: Begin pruning Files. |
| 127.0.0.1-dir JobId 7: No Files found to prune. |
| 127.0.0.1-dir JobId 7: End auto prune. |
+----------------------------------------------------------------------------------------------------+
At the plugin options prompt, set values such as conflict_strategy=drop or
dry_run=yes when required. See MongoDBRestoreParameters for the full
restore option reference.
For the complete restore-specific configuration and examples, see Restore Parameters.
What Happens During Restore
Before changing the target, the plugin builds a restore plan from the selected Bacula files and the restore options. The plan includes these steps:
Receive restore packets from the Bacula File Daemon for files under
/@mongodb.Stage small control files such as
manifest.json,chain-index.json,cluster-metadata.json, andcontrol/stream-plan/*.jsonin the configured working path.Use the stream-plan record, or a compatible manifest when it arrives first, to identify each
dump/*.archivepayload before the archive bytes are consumed.Validate sharded direct-stream restores against a
mongostarget and stop if the target balancer is active.Validate replica-set chain continuity when Full plus Incremental or Differential artifacts are selected.
Apply the selected restore mode with
mongorestoreand driver operations.Restore users and custom roles when the artifact contains security metadata and the restore options allow it.
Remove empty temporary restore directories created during planning.
For current Bacula backups, large database archives are streamed from Bacula
directly into mongorestore --archive during compatible live restores. They
are not written as complete temporary dump files in the File Daemon working
path. Restore planning still stages metadata because the plugin must inspect it
locally before applying changes. Replica-set chain restores also stage oplog
payload files under oplog/ so they can be replayed in validated order after
the streamed Full archive has been restored.
Full Application Restore
A Full application restore loads the selected databases and collections from a
Full artifact. The plugin uses mongorestore archive input to recreate
collection data, collection options, and indexes recorded by MongoDB Database
Tools.
The safest production default is conflict_strategy=fail against an empty or
prepared target. This prevents accidental overwrite when a restore is pointed at
the wrong MongoDB deployment. Use conflict_strategy=drop only when the
operator intentionally wants the plugin to drop existing target collections
before restore. Use conflict_strategy=skip for controlled partial restores
where existing collections must remain untouched.
Replica-Set Chain Restore
A replica-set chain restore uses a Full artifact plus the selected Incremental or Differential artifact set. The plugin validates the chain before modifying the target:
The Full artifact must belong to the same source identity as the chain artifacts.
Chain digests and boundaries must be continuous.
Oplog files must be present and pass checksum validation.
replay_tomust fall inside the selected chain when it is configured.
The plugin restores the Full artifact first. It then replays oplog entries in
order until the end of the selected chain or until replay_to is reached.
This is the restore mode used for replica-set point-in-time recovery within the
oplog ranges protected by Bacula.
Database Rename Restore
Use map_db=source=target to restore one dumped database under a different
name. This is useful for test restores, application validation, and selected
migration workflows.
Database rename restores are application-data restores. Security metadata is not renamed automatically. Review users, roles, and application connection strings after the restore.
Selective Collection Restore
Use collection to restrict restore to one or more collection names. This is
useful for accidental collection deletion or controlled data extraction.
Selective collection restore does not guarantee application consistency by itself. Applications often require related collections, indexes, reference data, or user-defined metadata to be restored together.
Isolated Disaster Recovery
Use isolated_dr=yes for a dedicated recovery target that is separate from
production. This option allows restore behavior that is appropriate for a clean
DR environment but risky on an active production deployment.
Set recover_admin=yes only when administrative users and roles from the
backup must be recovered. This is normally limited to isolated standalone or
replica-set recovery targets.
Dry-Run Restore
Set dry_run=yes to validate the restore plan without modifying the target.
The plugin checks metadata, checksums, version compatibility, chain continuity,
conflicts, and isolated-DR guardrails. Use report_format=json when the plan
is consumed by BWeb, automation, or support tooling.
Restore Staging and Cleanup
Operators may see log messages about staged restore metadata resources. These messages refer to small control files required for planning and validation, such as manifests, chain indexes, checksum inventories, and sharded metadata.
Temporary directories created for restore planning are removed when they are no
longer needed. Empty Bacula restore working directories, such as
RestoreFiles.<timestamp>, are cleaned up at the end of the operation.
In current Bacula restore flows, data and metadata are handled differently by design:
Control metadata is staged locally for validation and planning.
Full dump archives may be streamed directly to
mongorestorewhen the restore mode is compatible with streaming.Oplog payloads are staged when chain replay is required.
Use-case Behavior
The following summarizes where the plugin streams versus stages payloads:
Full restore (single Full artifact, standard scope):
dump/*.archiveis streamed directly intomongorestore --archive.Database users and roles can be restored from the same archive when the artifact contains security metadata and
skip_securityis not enabled.Control metadata, for example
manifest.jsonand stream-plan records, is staged.
Full + Incremental or Differential replay (full-plus-oplog):
The base Full
dump/*.archivecan be streamed directly.Oplog payload files under
oplog/are staged for ordered replay.Control metadata is staged.
Standalone or sharded Incremental/Differential fallback jobs:
These jobs are full-style logical artifacts. Their
dump/*.archivepayloads can be streamed directly during normal live restore.
Collection-scoped restore (collection=...):
Compatible with archive streaming in supported Full and Full+oplog modes.
Namespace filters are applied during restore.
Sharded restore workflows through mongos:
The plugin stages sharded planning metadata and validates the target balancer state before applying data through
mongorestore.
dry_run=yes:
Metadata validation only; no live data apply.
Special restore modes such as explicit replay_to, map_db,
isolated_dr=yes, or recover_admin=yes may require the conservative
local artifact path for additional validation and safety checks.
Compatibility and Guardrails
Compatible with direct archive streaming:
Simple Full restore scenarios that do not require remapping or DR-only behaviors.
Simple Full restore with or without application user/role replay, when the archive format and selected scope support streaming.
Full plus oplog replay when the replay boundary is selected from staged chain metadata and oplog files.
Not compatible with direct archive streaming (fallback to staged flow):
Explicit
replay_to,map_db,isolated_dr,recover_admin,dry_run, and sharded restore orchestration paths.Older artifacts or selected file sets that do not provide enough metadata before the dump archive arrives.
Operational Notes
Seeing staged-file log lines during a streamed restore is expected. A restore can stream dump archives and still stage metadata and oplog resources.
Security replay for simple Full restores can use the same streamed archive; DR-specific admin recovery remains guarded by isolated-DR restore rules.
Go back to: MongoDB Plugin: Operations.