Single Item Restore

Important

Remember to read the Best Practices chapter common for all of our hypervisor plugins.

This article presents how to use the Hyper-V VSS Single File Restore feature with Bacula Enterprise and the Hyper-V Plugin.

Features Summary

The Bacula Enterprise Hyper-V VSS Single File Restore provides the following main features:

  • Console interface

  • Compatible with Hyper-V Server 2019

  • Support for Linux filesystems (ext3, ext4, btrfs, lvm, xfs)

  • Support for Windows filesystems (FAT, NTFS)

Hyper-V SIR is available starting with Bacula Enterprise 12.8

This document will present solutions for Bacula Enterprise 12.8 and later, which are not applicable to prior versions. The Hyper-V VSS Single File Restore has been tested and is supported on RHEL 7.x, RHEL 8.x, Ubuntu Focal and Debian Stretch. SELinux is currently not supported.

Installation

Packages for the Hyper-V VSS Single File Restore plugin are available for supported platforms. Please contact Bacula Systems to get them.

Download the plugin package to your Storage Daemon server and then install using the package manager like so:

rpm -ivh bacula-enterprise-single-item-restore*.rpm

The package manager will ensure that your Bacula Enterprise version is compatible with the Hyper-V VSS Single File Restore plugin and will install dependencies. On Redhat, it will be necessary to install the perl-JSON package from rpmforge and the libguestfs-winsupport package.

Note

On Redhat 7.x, it is necessary to install a custom version of the libguestfs packages from our repository to support NTFS devices. Those should not be updated with a newer version from official repositories. The YUM package manager has plugins to prevent package updates, try yum-plugin-versionlock or yum-plugin-priorities.

Additionally, the ntfs-3g package from the EPEL repository is needed for NTFS support. To install the EPEL respository, please follow the official instructions on the EPEL website to install the “epel-release” package here:

https://fedoraproject.org/wiki/EPEL

Note

On Redhat 8.X and 9.x, you must have the the AppStream repository enabled to install the perl-File-Copy. The perl-File-Copy module is a dependency required by the bacula-enterprise-single-item-restore package.

Since Bacula Enterprise 16.0.13.

# cat /etc/yum.repos.d/dag.repo
[dag] name = Red Hat Enterprise - RPMFORGE
baseurl = https://www.baculasystems.com/dl/DAG/rhel6-64
enabled = 1
protect = 0
gpgcheck = 0

# cat /etc/yum.repos.d/baculasystems.repo
[single_file_restore_hyper-v]
name = Red Hat Enterprise - RPMFORGE
baseurl = https://www.baculasystems.com/dl/<xxx>/rhel6-64
enabled = 1
protect = 0
gpgcheck = 0

Note

This following repository is required on RHEL7:

[Bacula-Enterprise-DAG-Guestfish]
name = Bacula Enterprise - DAG for Guestfish
baseurl = https://www.baculasystems.com/dl/DAG/rhel7-64/guestfish/
enabled = 1
protect = 0
gpgcheck = 0
yum install bacula-enterprise-single-item-restore perl-JSON

If BWeb Management Suite is used, you need to run:

service bweb restart

Notes about the “bacula” Account on Redhat

All commands in this document use the “bacula” unix account to run.

On Redhat, the Unix “bacula” account is locked by default. It means that it’s not possible by default to execute a command such as “su - bacula”.

It is possible to unlock the “bacula” account, or to use “sudo -u bacula” to execute commands. For example:

bacula@storage# /opt/bacula/bin/bconsole

Can be run from the root account using the following command:

root@storage# sudo -u bacula /opt/bacula/bin/bconsole

It is also possible to start a shell session using

root@storage# sudo -u bacula /bin/bash

Or unlock the “bacula” unix account and use “su -” with a command such as:

root@storage# chsh -s /bin/bash bacula root@storage# su - bacula
bacula@storage# whoami bacula

Fuse FileSystem

If a restore session is not properly cleaned up, some directories might still be mounted with the Bacula Fuse FileSystem.

baculafs on /opt/bacula/working/cat-ro type fuse.baculafs
(ro,user=bacula) backend0 on /opt/bacula/working/test-vm-0 type
fuse.backend0 (ro,user=bacula) /dev/fuse on
/opt/bacula/working/test-vm type fuse (rw,nosuid,nodev,user=bacula)

It is possible to unmount directories with the fusermount -u command.

bacula@storage# fusermount -z -u /opt/bacula/working/26
bacula@storage# fusermount -z -u /opt/bacula/working/test-vm-0
bacula@storage# fusermount -z -u /opt/bacula/working/test-vm

Samba SMB Shares

The Bacula Enterprise Hyper-V VSS Single File Restore plugin can automatically set up Samba SMB shares from the console program or the BWeb Management Suite.

To enable Samba SMB network shares, installing and configuring the “samba” package is mandatory. To configure the /etc/samba/smb.conf file correctly, you need to run install-single-item-restore.sh script.

root@storage# /opt/bacula/scripts/install-single-item-restore.sh install
Do you want to initialise Samba smb.conf [yes/No]: yes
Choose a Workgroup [BACULA]:

root@storage# cat /etc/samba/smb.conf
[global]
workgroup = BACULA
include = /etc/samba/conf.d/all

At this point, it is possible to modify /etc/samba/smb.conf to add your own configuration directives.

Network share descriptions will be stored in the directory /etc/samba/conf.d. It is possible to create and customize the template used by Bacula to generate configuration files.

root@storage# cat /etc/samba/conf.d/custom.tpl
[__share__]
path = __path__
follow symlinks = yes
wide links = yes
writable = yes

Configuration

On the Storage Daemon host server, the bconsole program should be configured properly to let the “bacula” user connect to the Director with /opt/bacula/etc/bconsole.conf.

bacula@storage# /opt/bacula/bin/bconsole
Connecting to Director mydir-dir:9101
1000 OK: 10002 mydir-dir Version: 12.8.0
Enter a period to cancel a command.
* version
mydir-dir Version: 12.8.0 x86_64-redhat-linux-gnu
* quit

The package contains a script to test the connection with the Director and to test if the system can mount the Bacula Virtual File System properly.

bacula@storage# /opt/bacula/scripts/install-single-item-restore.sh check
I: Try to restart the script with sudo...
I: Found catalog MyCatalog
I: bacula-fused started on /tmp/bee-bfuse.XXXXX
I: MyCatalog found
I: 10 Client(s) found
I: /tmp/bee-bfuse.XXXXX unmounted
I: bacula-fused (rw) started on /tmp/bee-bfuse.XXXXX
I: MyCatalog found
I: 10 Client(s) found
I: /tmp/bee-bfuse.XXXXX unmounted
OK: All tests are good.

The Bacula Virtual File System is not designed to be used by end users to browse or restore files directly. If you try to access and browse the mount point, you may not see any files or files may have strange permissions, ownerships and sizes and will inaccessible even to the root user.

Restore Scenario With Text Console Interface

The Hyper-V VSS Single File Restore plugin provides a simple console program that provides access to files inside VMs.

bacula@storage# /opt/bacula/bin/mount-vm
Automatically Selected Catalog: MyCatalog

Client list:
1: 127.0.0.1-fd
2: win2008-fd
3: rhel7-fd Select a Client: 1
Selected Client: 127.0.0.1-fd

Job list:
1: HYPERV08.2021-02-15_19.12.51_34
2: HYPERV08.2021-02-16_12.12.29_39
3: HYPERV08.2021-02-16_12.37.54_03
4: HYPERV08.2021-02-16_14.23.47_03
5: HYPERV08.2021-02-16_15.45.32_03
6: HYPERV08.2021-02-16_17.00.47_52
Select a Job: 6
Selected HYPERV08.2021-02-16_17.00.47_52

Virtual Machine:
1: squeeze2
2: win2008
3: rhel7
4: sir-test-vm
Select a Virtual Machine: 4
Selected sir-test-vm

Actions list:
1: Mount guest filesystem locally
2: Export guest filesystem through SMB
3: Cleanup
Select a Actions: 1
Selected Mount guest filesystem locally

I: Files are available under /opt/bacula/working/mount-vm-6434/disks/sir-test-vm
I: Press enter to finish and cleanup the session

In this step, the virtual machine filesystem is mounted locally (in the example above, files are available under /opt/bacula/working/mount-vm-6434/disks/sir-test-vm. It is possible to browse directories and copy files (with cp, scp, ftp) as with a standard filesystem from another terminal session with the Unix “root” and “bacula” accounts. If you need to use another Unix account to operate on files, use the “-o allow_other” option when starting the mount-vm script.

bacula@storage# ls /opt/bacula/working/mount-vm-6434/disks/sir-test-vm
bin   dev  home        lib         media  opt   root  selinux  sys  usr  vmlinuz
boot  etc  initrd.img  lost+found  mnt    proc  sbin  srv      tmp  var

To clean up the session, just press “Enter” in the terminal session where the mount-vm script was started.

It is possible to limit the Job list with the following command line options:

  • -s=<days> Limit the job list to the last days

  • -l=<number> Limit the job list to the last number entries

  • -f=<filter> Specify an advanced filter based on the Job name, the FileSet name or the JobId

# Limit the job output to the last 100 jobs
bacula@storage# /opt/bacula/bin/mount-vm -l 100

# Limit the job output to the last 30 days
bacula@storage# /opt/bacula/bin/mount-vm -s 30

# Limit the job output to jobs that start with "MyHyper-V"
bacula@storage# /opt/bacula/bin/mount-vm -f ’jobname=MyHyper-V*’

# BAD USAGE for the filter option, it will search for a job named "MyHyper-V"
bacula@storage# /opt/bacula/bin/mount-vm -f ’jobname=MyHyper-V’

# Limit the job output to jobs that start with "MyHyper-V"
# and that use the FileSet Test1
bacula@storage# /opt/bacula/bin/mount-vm -f ’jobname=MyHyper-V\* fileset=Test1’

# Limit the job to the jobid XX
bacula@storage# /opt/bacula/bin/mount-vm -f jobid=XX

On some cases, the device detection doesn’t work properly. It is possible to use the -m option to mount recognized disks in a simple way. The option is automatically set when only one disk is selected during the restore.

bacula@storage# /opt/bacula/bin/mount-vm -m

Notes

Cache Directory

To speed up future Hyper-V Single File restore sessions, some files that are generated during a restore session are kept in a cache directory.

bacula@storage# ls /opt/bacula/working/mount-cache
sir-test-vm-0.bmp  sir-test-vm-2.bmp    MyCatalog-2.idx  MyCatalog-5.idx  MyCatalog-8.idx
sir-test-vm-1.bmp  sir-test-vm.profile  MyCatalog-4.idx  MyCatalog-6.idx  MyCatalog-9.idx

It is possible to remove files in the cache after some time; they will be re-generated if needed.

Support

The install-single-item-restore.sh script can collect traces automatically when a mount-vm session is running.

root@storage# /opt/bacula/scripts/install-single-item-restore.sh support

Limitations

  • The Hyper-V VSS Single File Restore feature uses the Bacula BVFS interface to list files and directories. The Bacula BVFS interface is known to have some performance issues with the MySQL catalog backend due to internal MySQL limitations with indexes on TEXT colums. For Hyper-V Single Item Restore there should not be too much impact on performance (the backup structure is usually quite small) but we advise to use the PostgreSQL backend for the best experience.

  • The Hyper-V VSS Single File Restore performance may vary depending on various factors. For instance, Bacula will have to read more data if the Volume was created with a large number of concurrent jobs.

  • The Storage Daemon where the Hyper-V VSS Single File Restore is installed should be have a CPU with the VT-x/EPT extensions. If these extensions are not available, you may experience delays (from 20 seconds up to 10 minutes in our lab).

  • Redhat 7 does not support mounting NTFS disks with the libguestfs provided with their system. To mount Microsoft NTFS disks on Redhat 7, it is required to install a patched version of the libguestfs packages. Please see notes in the “Installation” section of this document for more information.

  • The Hyper-V VSS Single File Restore is compatible with file based devices (cloud, dedup, aligned, file, etc..). Tape devices are not supported.