Restore

Enterprise

Bacula Enterprise Only

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

The restore workflow can target HDFS or a local filesystem.

Restore Modes

• Restore to the original HDFS location: use where=/ or leave where empty.

• Restore to a local filesystem: set where to a destination path on the File Daemon host.

• Restore to a live HDFS namespace under a specific subdirectory: set destination_path in the HDFS plugin parameters.

• Replace existing files: controlled by Bacula Replace semantics.

Restore Parameters

The restore operation uses the same connection settings as the backup side. Reuse the HDFS authentication parameters here, including user_principal, keytab, and service_principal when Kerberos is enabled, and point the XML files to local copies on the File Daemon host if you copied them from the HDFS cluster.

HDFS restore parameters

Parameter	Default	Notes
destination_path	empty	Destination path prepended when restoring into a live HDFS namespace.
url	none	HDFS endpoint URL used during restore. Mandatory.
user	none	User used to access the HDFS namespace during restore. Mandatory.
core_site_path	none	Path to the local copy of core-site.xml on the File Daemon host.
hdfs_site_path	none	Path to the local copy of hdfs-site.xml on the File Daemon host.
ssl_client_path	none	Path to the local copy of ssl-client.xml when HTTPS client settings are required.
user_principal	none	Kerberos principal used by the File Daemon when Kerberos is enabled.
keytab	none	Path to the Kerberos keytab file on the File Daemon host.
service_principal	none	Kerberos service principal used to reach the target HDFS services.
debug	none	Controls debug level from 0 to 9

How Restore Works

1. Bacula replays the selected backup files to the plugin.

2. The plugin checks whether each target file already exists.

3. The Replace policy determines whether the file is overwritten, skipped, or compared by modification time.

4. When where is set to a local path, the file is restored on the File Daemon host instead of being written back to HDFS.

5. When restoring to HDFS, destination_path is prepended to each restored file name before upload if it is configured.

Example Restore to HDFS

*restore jobid=889 where=/
 You have selected the following JobId: 889

 Building directory tree for JobId(s) 889 ...
 1 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: /
 $ mark *
 22456 files marked.
 $ done
 Bootstrap records written to /opt/bacula/working/bacula-director-dir.restore.1.bsr

 The Job will require the following (*=>InChanger):
   Volume(s)                 Storage(s)                SD Device(s)
 ===========================================================================

     Vol-0025                  DiskAutochanger           DiskAutochanger

 Volumes marked with "*" are in the Autochanger.

 1 BSR record selected to be restored.

 Defined Clients:
     1: bacula-director-fd
     2: bacula-hdfs-fd
     3: am-d13-fdonly-postgresql-tst-fd
     4: am-r10-fdonly-18-2-4-tst-fd
     5: bacula-proxy-vm-test
     6: glb-centos7-backup-fdplugins-bck-fd
     7: proxmox03-fd
     8: pve-fd
     9: rescue-fd
 Select the Client (1-9): 2
 Using Catalog "BaculaCatalog"
 Run Restore job
 JobName:         Restore
 Bootstrap:       /opt/bacula/working/bacula-director-dir.restore.1.bsr
 Where:           /
 Replace:         Always
 FileSet:         BaculaConfigs
 Backup Client:   bacula-hdfs-fd
 Restore Client:  bacula-hdfs-fd
 Storage:         DiskAutochanger
 When:            2026-06-10 11:06:24
 Catalog:         BaculaCatalog
 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 : hdfs: url=hdfs://mycluster user=ana base_snap_dir=/user/ana core_site_path=/opt/bacula/etc/hdfs/core-site.xml hdfs_site_path=/opt/bacula/etc/hdfs/hdfs-site.xml keep_snapshot=no
 Plugin Restore Options
 Option                         Current Value        Default Value
 destination_path:              *None*               (*none*)
 url:                           *None*               (*none*)
 user:                          *None*               (*none*)
 core_site_path:                *None*               (*none*)
 hdfs_site_path:                *None*               (*none*)
 ssl_client_path:               *None*               (*none*)
 user_principal:                *None*               (*none*)
 keytab:                        *None*               (*none*)
 service_principal:             *None*               (*none*)
 debug:                         *None*               (*none*)
 Use above plugin configuration? (Yes/mod/no): mod
 You have the following choices:
     1: destination_path (HDFS Destination path to store the restored data)
     2: url (HDFS Url)
     3: user (HDFS User owning root path)
     4: core_site_path (HDFS core-site.xml file to connect to destination cluster)
     5: hdfs_site_path (HDFS hdfs-site.xml file to connect to destination cluster)
     6: ssl_client_path (HDFS ssl-site.xml file to connect to destination cluster)
     7: user_principal (HDFS Kerberos Auth user principal)
     8: keytab (HDFS Kerberos Auth keytab)
     9: service_principal (HDFS Kerberos Auth service principal)
     10: debug (Change debug level)
 Select parameter to modify (1-10): 1
 Please enter a value for destination_path: /user/ana/testR
 Plugin Restore Options
 Option                         Current Value        Default Value
 destination_path:              /user/ana/testR      (*none*)
 url:                           *None*               (*none*)
 user:                          *None*               (*none*)
 core_site_path:                *None*               (*none*)
 hdfs_site_path:                *None*               (*none*)
 ssl_client_path:               *None*               (*none*)
 user_principal:                *None*               (*none*)
 keytab:                        *None*               (*none*)
 service_principal:             *None*               (*none*)
 debug:                         *None*               (*none*)
 Use above plugin configuration? (Yes/mod/no): yes
 Run Restore job
 JobName:         Restore
 Bootstrap:       /opt/bacula/working/bacula-director-dir.restore.1.bsr
 Where:           /
 Replace:         Always
 FileSet:         BaculaConfigs
 Backup Client:   bacula-hdfs-fd
 Restore Client:  bacula-hdfs-fd
 Storage:         DiskAutochanger
 When:            2026-06-10 11:06:24
 Catalog:         BaculaCatalog
 Priority:        10
 Plugin Options:  User specified
 OK to run? (Yes/mod/no): yes
 Job queued. JobId=890

This keeps the restore in the HDFS namespace and replays the files back into the target filesystem.

The joblog will report HDFS environment connection information as the backup:

*list joblog jobid=890
 +----------------------------------------------------------------------------------------------------+
 | logtext                                                                                              |
 +----------------------------------------------------------------------------------------------------+
 | bacula-director-dir JobId 890: Start Restore Job Restore.2026-06-10_11.06.42_00               |
 | bacula-director-dir JobId 890: Restoring files from JobId(s) 889                              |
 | bacula-director-dir JobId 890: Connected to Storage "DiskAutochanger" at bacula-director:9103 with TLS |
 | bacula-director-dir JobId 890: Using Device "DiskAutochanger_Dev1" to read.                   |
 | bacula-director-dir JobId 890: Connected to Client "bacula-hdfs-fd" at bacula-hdfs:9102 with TLS |
 | bacula-hdfs-fd JobId 890: Connected to Storage at bacula-director:9103 with TLS     |
 | bacula-director-sd JobId 890: Ready to read from volume "Vol-0025" on File device "DiskAutochanger_Dev1" (/opt/bacula/archive). |
 | bacula-director-sd JobId 890: Forward spacing Volume "Vol-0025" to addr=6888                  |
 | bacula-director-sd JobId 890: End of Volume "Vol-0025" at addr=9083 on device "DiskAutochanger_Dev1" (/opt/bacula/archive). |
 | bacula-director-sd JobId 890: Elapsed time=00:00:01, Transfer rate=279  Bytes/second          |
 | bacula-hdfs-fd JobId 890: hdfs: Jar Version: 1.0.0 | Java version: 1.8.0_412 | Java Pid: 18770 |
 | bacula-hdfs-fd JobId 890: hdfs: Maximum java memory configured: 3.56 GiB                   |
 | bacula-hdfs-fd JobId 890: hdfs: Starting backend restore process                           |
 | bacula-hdfs-fd JobId 890: hdfs: Loaded core-site.xml from: /opt/bacula/etc/hdfs/core-site.xml |
 | bacula-hdfs-fd JobId 890: hdfs: Loaded hdfs-site.xml from: /opt/bacula/etc/hdfs/hdfs-site.xml |
 | bacula-hdfs-fd JobId 890: hdfs: Connected to hdfs://mycluster                              |
 | bacula-hdfs-fd JobId 890: hdfs: HDFS Restore to:/user/ana/testR                            |
 | bacula-hdfs-fd JobId 890: hdfs: No more items to restore. Restore ended                    |
 ...

To restore into a specific HDFS subdirectory, set destination_path in the HDFS plugin parameters before running the restore.

Example Restore to Local Disk

restore jobid=1 where=/bacula-restores all done yes

This writes the restored files under /bacula-restores on the File Daemon host.

See also

Previous articles:

• Backup

Next articles:

• Useful Commands

• List and Query

Go back to: Operations.