Best Practices

Bacula Enterprise Only

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

OpenStack Instances and Snapshot Consistency

OpenStack Nova commonly uses the libvirt/QEMU driver to manage instances. For instances created from images that enable QEMU Guest Agent support, Nova can communicate with the guest operating system during snapshot operations and request filesystem freeze/thaw actions before and after the snapshot.

This mechanism can improve snapshot consistency, but it requires all of the following conditions:

The instance must run on a libvirt/QEMU or KVM-based compute backend.
The image used to create the instance must have the hw_qemu_guest_agent=yes property.
The QEMU Guest Agent package must be installed and running inside the guest operating system.
The guest must expose the QEMU Guest Agent virtio device to the operating system.
Any application-level consistency requirements, such as database flush or pause operations, must be handled by freeze/thaw hook scripts inside the guest.

Note

Enabling hw_qemu_guest_agent=yes on an image does not by itself install or start the QEMU Guest Agent inside the guest operating system. For already running instances, do not assume that changing the image metadata is sufficient. Always verify the guest-agent device and service inside the instance.

Verifying the Image Property

In Horizon, open the image details and check that the custom properties include:

hw_qemu_guest_agent = yes

From the command line, use:

openstack image show -f value -c properties <image-name-or-uuid>

The output should include:

'hw_qemu_guest_agent': 'yes'

If required, the property can be added or updated with:

openstack image set --property hw_qemu_guest_agent=yes <image-name-or-uuid>

In Horizon, update the image metadata and set hw_qemu_guest_agent to yes under the libvirt driver image options.

Verifying the Guest Agent Inside the Instance

Inside the guest operating system, verify that the QEMU Guest Agent is installed and running.

On systems using systemd:

systemctl status qemu-guest-agent

Also verify that the guest-agent virtio device exists:

ls -l /dev/virtio-ports/org.qemu.guest_agent.0

If this device is missing, the instance is not currently connected to the QEMU Guest Agent channel, and freeze/thaw actions will not be available for snapshot consistency.

Filesystem and Application Consistency

When QEMU Guest Agent freeze/thaw support is available, Nova can request the guest to freeze filesystems before a snapshot and thaw them after the snapshot completes. This helps provide filesystem-consistent snapshots.

Application-consistent snapshots require additional actions. For example, databases or other write-heavy applications may need to flush buffers, pause writes, or enter a backup-safe mode before the filesystem is frozen. These actions should be implemented with QEMU Guest Agent freeze/thaw hook scripts.

Hook Script Location

The hook location can vary by distribution and QEMU Guest Agent configuration. Common locations include:

/etc/qemu/fsfreeze-hook.d/
/etc/qemu-ga/fsfreeze-hook.d/

Check the guest operating system documentation or the QEMU Guest Agent service configuration to confirm the active hook path.

The hook script must be executable. For example:

chmod 0755 /etc/qemu-ga/fsfreeze-hook.d/test_hook.sh

Example Test Hook

The following hook can be used to verify that freeze and thaw events are executed:

#!/bin/bash

case "$1" in
  freeze)
    echo "$(date): freeze" >> /tmp/qga-freeze-test.log
    ;;
  thaw)
    echo "$(date): thaw" >> /tmp/qga-freeze-test.log
    ;;
  *)
    echo "$(date): unknown action: $1" >> /tmp/qga-freeze-test.log
    exit 1
    ;;
esac

After running a snapshot, verify that both events were recorded:

cat /tmp/qga-freeze-test.log

Expected output should contain both a freeze and a thaw entry.

You can also check the QEMU Guest Agent freeze/thaw hook log if it is enabled on the guest:

tail /var/log/qga-fsfreeze-hook.log

Example output:

Mon Jan 01 12:00:00 PM EST 2025: Executing /etc/qemu-ga/fsfreeze-hook.d/test_hook.sh freeze
Mon Jan 01 12:00:01 PM EST 2025: /etc/qemu-ga/fsfreeze-hook.sh finished successfully
Mon Jan 01 12:00:02 PM EST 2025: Executing /etc/qemu-ga/fsfreeze-hook.d/test_hook.sh thaw
Mon Jan 01 12:00:03 PM EST 2025: /etc/qemu-ga/fsfreeze-hook.sh finished successfully

Summary

Enable hw_qemu_guest_agent=yes on images before creating instances that require consistent snapshots.
Install and enable QEMU Guest Agent as part of the image build process.
Verify the guest-agent service and virtio device before relying on freeze/thaw operations.
Use application-specific freeze/thaw hooks for databases and other applications that require more than filesystem consistency.
Test freeze/thaw hooks before using them in production backup jobs.
Monitor QEMU Guest Agent logs for hook failures or timeout-related issues.

Backup of the .bmp, .sha Files and the /opt/bacula/etc/openstack.conf File

The Bacula Enterprise OpenStack Plugin stores important configuration and working files on the Bacula proxy server. These files should be protected as part of the backup strategy for the proxy server.

The following files are especially important:

/opt/bacula/etc/openstack.conf
the .bmp files created by the OpenStack Plugin
the .sha files created by the OpenStack Plugin

The /opt/bacula/etc/openstack.conf file contains the OpenStack Plugin configuration used by the Bacula File Daemon on the proxy server. Depending on the deployment, this file may include OpenStack authentication parameters, endpoint information, project information, and other plugin required to connect to the OpenStack APIs.

This file should be backed up regularly. If the proxy server is lost or rebuilt, restoring this file helps recover the OpenStack Plugin configuration quickly and avoids having to manually recreate the connection settings.

The .bmp and .sha files are working files used by the plugin to support Incremental and Differential backups. They contain block map and checksum information from previous backups. The plugin uses this information to determine which blocks have changed between backup jobs.

These files are usually small, but they are important for backup efficiency. If the .bmp and .sha files are lost or deleted, the plugin may need to rebuild the block map and checksum information. As a result, the next Incremental or Differential backup may read and store more data than expected.

For this reason, it is strongly recommended to back up the .bmp and .sha files together with the proxy server configuration.

The backup of the Bacula proxy server should include at least:

/opt/bacula/etc/openstack.conf
the directory where the OpenStack Plugin stores its .bmp and .sha files
the Bacula File Daemon configuration used by the proxy server (/opt/bacula/etc/bacula-fd.conf)

The .bmp and .sha files do not need to be kept after a new Full backup has run, because a new Full backup creates a new baseline for future Incremental and Differential backups. However, they should not be manually removed while they are still required by the current Full plus Incremental or Differential backup cycle.

As a best practice, protect the Bacula proxy server with a regular Bacula backup job. This job should be independent from the OpenStack Plugin jobs and should ensure that the proxy server configuration and plugin working files can be restored if the proxy server is lost, damaged, or replaced.

Restoring these files after rebuilding the proxy server helps preserve OpenStack Plugin configuration and allows Incremental and Differential backup operations to continue efficiently, provided that the restored files match the current backup cycle.

Fileset example for the backup of the .bmp, .sha files, and the /opt/bacula/etc/bacula-fd.conf and the /opt/bacula/etc/openstack.conf files:

Fileset {
        Name = "proxy-vm-conf-bmp-sha-files-fileset"
        Include {
                Options {
                        OneFs = "No"
                        IgnoreCase = "Yes"
                        Signature = "Md5"
         wildfile = "*.bmp"
         wildfile = "*.sha"
      }
      Options {
         Exclude = yes
         RegexFile = ".*"
      }
                File = "/opt/bacula/working"
      File = "/opt/bacula/etc/bacula-fd.conf
                File = "/opt/bacula/etc/openstack.conf" # this is the OpenStack RC file you use for authentication in the proxy server
        }
   Include {
                Options {
                        OneFs = "No"
                        IgnoreCase = "Yes"
                        Signature = "Md5"
      }
      File = "/opt/bacula/etc/bacula-fd.conf
                File = "/opt/bacula/etc/openstack.conf" # this is the OpenStack RC file you use for authentication in the proxy server
        }
}