Features/IncrementalBackup

Overview

QEMU's Incremental Backup feature is implemented using user-manipulable 'dirty bitmap' primitives. By allowing the user (A human, management interface library such as libvirt, or a backup application utility) to interface directly with these primitives, a rich variety of functionality can be achieved without enforcing inflexible paradigms.

This wiki document is based on the source code documentation for the feature, which can be found here: https://github.com/jnsnow/qemu/blob/master/docs/bitmaps.md

Development & Status

The feature as it currently exists in QEMU (as of 2015-05-11) was written by John Snow, modified from patches authored by Fam Zheng. The core functionality of the feature was merged 2015-04-28 during the QEMU 2.4 development window and should be released as part of QEMU 2.4.

There are several features still pending:

• QMP transactions to be able to atomically combine bitmap operations while the VM is running are currently pending on-list
• The live migration of dirty bitmap objects has seen several revisions on-list by Vladimir Sementsov-Ogievskiy
• The persistence of dirty bitmaps when closing and opening VMs is a work in progress also by Vladimir.

Dirty Bitmaps and Incremental Backup

Dirty bitmaps are objects that track which data needs to be backed up for the next incremental backup. It does this by taking note of which sectors on disk have been modified since the last incremental backup. The granularity at which it tracks data (Every 32KiB? 64KiB? 128KiB? etc) is configurable by the user.

These dirty bitmaps track the modification of data for nodes they are attached to. This would mean that you need at least one bitmap per drive you wish to back up incrementally.

Dirty bitmaps can be created by the user at any time and can be attached to any node in the drive graph, not just the root node.

Dirty Bitmap Names

A dirty bitmap's name is unique to the node, but bitmaps attached to different nodes can share the same name. For example:

• A drive with an id of 'drive0' can have a bitmap attached simply named 'bitmap'.
• A different drive with id 'drive1' can also have a bitmap attached that is named 'bitmap'.

Bitmap Modes

• A Bitmap can be "frozen," which means that it is currently in-use by a backup operation and cannot be deleted, renamed, written to, reset, etc. it is effectively completely immutable.
• A Bitmap can be "disabled", which is another internal mode that simply puts the bitmap in a "read only" state. This mode is used principally during migration. The bitmap cannot be written to or reset in this state.

Basic QMP Usage

Supported Commands

block-dirty-bitmap-add

Create a new, empty bitmap and attach it to a specific node.

block-dirty-bitmap-remove

Delete a bitmap that is not currently in-use by a backup operation.

block-dirty-bitmap-clear

Reset a specific bitmap back to a clean slate, as if it was newly created.

Creation

• To create a new bitmap, enabled, on the drive with id=drive0:

{ "execute": "block-dirty-bitmap-add",
  "arguments": {
    "node": "drive0",
    "name": "bitmap0"
  }
}

• This bitmap will have a default granularity that matches the cluster size of its associated drive, if available, clamped to between [4KiB, 64KiB]. The current default for qcow2 is 64KiB.
• To create a new bitmap that tracks changes in 32KiB segments:

{ "execute": "block-dirty-bitmap-add",
  "arguments": {
    "node": "drive0",
    "name": "bitmap0",
    "granularity": 32768
  }
}

Deletion

• Bitmaps that are frozen cannot be deleted.
• Deleting the bitmap does not impact any other bitmaps attached to the same node, nor does it affect any backups already created from this node.
• Because bitmaps are only unique to the node to which they are attached, you must specify the node/drive name here, too.

{ "execute": "block-dirty-bitmap-remove",
  "arguments": {
    "node": "drive0",
    "name": "bitmap0"
  }
}

Resetting

• Resetting a bitmap will clear all information it holds.
• An incremental backup created from an empty bitmap will copy no data, as if nothing has changed.

{ "execute": "block-dirty-bitmap-clear",
  "arguments": {
    "node": "drive0",
    "name": "bitmap0"
  }
}

Transactions (Not yet implemented)

• Transactional commands are forthcoming in a future version, and are not yet available for use. This section serves as documentation of intent for their design and usage.

Justification

Bitmaps can be safely modified when the VM is paused or halted by using the basic QMP commands. For instance, you might perform the following actions:

1. Boot the VM in a paused state.
2. Create a full drive backup of drive0.
3. Create a new bitmap attached to drive0.
4. Resume execution of the VM.
5. Incremental backups are ready to be created.

At this point, the bitmap and drive backup would be correctly in sync, and incremental backups made from this point forward would be correctly aligned to the full drive backup.

This is not particularly useful if we decide we want to start incremental backups after the VM has been running for a while, for which we will need to perform actions such as the following:

1. Boot the VM and begin execution.
2. Using a single transaction, perform the following operations:
   • Create bitmap0.
   • Create a full drive backup of drive0.
3. Incremental backups are now ready to be created.

Supported Bitmap Transactions

• block-dirty-bitmap-add
• block-dirty-bitmap-clear

The usages are identical to their respective QMP commands, but see below for examples.

Example: New Incremental Backup

As outlined in the justification, perhaps we want to create a new incremental backup chain attached to a drive.

{ "execute": "transaction",
  "arguments": {
    "actions": [
      {"type": "block-dirty-bitmap-add",
       "data": {"node": "drive0", "name": "bitmap0"} },
      {"type": "drive-backup",
       "data": {"device": "drive0", "target": "/path/to/full_backup.img",
                "sync": "full", "format": "qcow2"} }
    ]
  }
}

Example: New Incremental Backup Anchor Point

Maybe we just want to create a new full backup with an existing bitmap and want to reset the bitmap to track the new chain.

{ "execute": "transaction",
  "arguments": {
    "actions": [
      {"type": "block-dirty-bitmap-clear",
       "data": {"node": "drive0", "name": "bitmap0"} },
      {"type": "drive-backup",
       "data": {"device": "drive0", "target": "/path/to/new_full_backup.img",
                "sync": "full", "format": "qcow2"} }
    ]
  }
}

Incremental Backups

The star of the show.

Nota Bene! Only incremental backups of entire drives are supported for now. So despite the fact that you can attach a bitmap to any arbitrary node, they are only currently useful when attached to the root node. This is because drive-backup only supports drives/devices instead of arbitrary nodes.

Example: First Incremental Backup

1. Create a full backup and sync it to the dirty bitmap, as in the transactional examples above; or with the VM offline, manually create a full copy and then create a new bitmap before the VM begins execution.

   • Let's assume the full backup is named 'full_backup.img'.
   • Let's assume the bitmap you created is 'bitmap0' attached to 'drive0'.

2. Create a destination image for the incremental backup that utilizes the full backup as a backing image.

   • Let's assume it is named 'incremental.0.img'.

   # qemu-img create -f qcow2 incremental.0.img -b full_backup.img -F qcow2

3. Issue the incremental backup command:

   { "execute": "drive-backup",
     "arguments": {
       "device": "drive0",
       "bitmap": "bitmap0",
       "target": "incremental.0.img",
       "format": "qcow2",
       "sync": "dirty-bitmap",
       "mode": "existing"
     }
   }

Example: Second Incremental Backup

1. Create a new destination image for the incremental backup that points to the previous one, e.g.: 'incremental.1.img'

   # qemu-img create -f qcow2 incremental.1.img -b incremental.0.img -F qcow2

2. Issue a new incremental backup command. The only difference here is that we have changed the target image below.

   { "execute": "drive-backup",
     "arguments": {
       "device": "drive0",
       "bitmap": "bitmap0",
       "target": "incremental.1.img",
       "format": "qcow2",
       "sync": "dirty-bitmap",
       "mode": "existing"
     }
   }

Errors

• In the event of an error that occurs after a backup job is successfully launched, either by a direct QMP command or a QMP transaction, the user will receive a BLOCK_JOB_COMPLETE event with a failure message, accompanied by a BLOCK_JOB_ERROR event.
• In the case of an event being cancelled, the user will receive a BLOCK_JOB_CANCELLED event instead of a pair of COMPLETE and ERROR events.
• In either case, the incremental backup data contained within the bitmap is safely rolled back, and the data within the bitmap is not lost. The image file created for the failed attempt can be safely deleted.
• Once the underlying problem is fixed (e.g. more storage space is freed up), you can simply retry the incremental backup command with the same bitmap.

Example

1. Create a target image:

   # qemu-img create -f qcow2 incremental.0.img -b full_backup.img -F qcow2

2. Attempt to create an incremental backup via QMP:

   { "execute": "drive-backup",
     "arguments": {
       "device": "drive0",
       "bitmap": "bitmap0",
       "target": "incremental.0.img",
       "format": "qcow2",
       "sync": "dirty-bitmap",
       "mode": "existing"
     }
   }

3. Receive an event notifying us of failure:

   { "timestamp": { "seconds": 1424709442, "microseconds": 844524 },
     "data": { "speed": 0, "offset": 0, "len": 67108864,
               "error": "No space left on device",
               "device": "drive1", "type": "backup" },
     "event": "BLOCK_JOB_COMPLETED" }

4. Delete the failed incremental, and re-create the image.

   # rm incremental.0.img
   # qemu-img create -f qcow2 incremental.0.img -b full_backup.img -F qcow2

5. Retry the command after fixing the underlying problem, such as freeing up space on the backup volume:

   { "execute": "drive-backup",
     "arguments": {
       "device": "drive0",
       "bitmap": "bitmap0",
       "target": "incremental.0.img",
       "format": "qcow2",
       "sync": "dirty-bitmap",
       "mode": "existing"
     }
   }

6. Receive confirmation that the job completed successfully:

   { "timestamp": { "seconds": 1424709668, "microseconds": 526525 },
     "data": { "device": "drive1", "type": "backup",
               "speed": 0, "len": 67108864, "offset": 67108864},
     "event": "BLOCK_JOB_COMPLETED" }