| 1 | The following changes since commit ca4e667dbf431d4a2a5a619cde79d30dd2ac3eb2: | 1 | The following changes since commit 871af84dd599fab68c8ed414d9ecbdb2bcfc5801: |
|---|---|---|---|
| 2 | 2 | ||
| 3 | Merge remote-tracking branch 'remotes/kraxel/tags/usb-20170717-pull-request' into staging (2017-07-17 17:54:17 +0100) | 3 | Merge tag 'for-upstream' of https://gitlab.com/bonzini/qemu into staging (2025-01-29 09:51:03 -0500) |
| 4 | 4 | ||
| 5 | are available in the git repository at: | 5 | are available in the Git repository at: |
| 6 | 6 | ||
| 7 | git://github.com/codyprime/qemu-kvm-jtc.git tags/block-pull-request | 7 | https://gitlab.com/stefanha/qemu.git tags/block-pull-request |
| 8 | 8 | ||
| 9 | for you to fetch changes up to 8508eee740c78d1465e25dad7c3e06137485dfbc: | 9 | for you to fetch changes up to 58607752d173438994d28dea7e2c2587726663e6: |
| 10 | 10 | ||
| 11 | live-block-ops.txt: Rename, rewrite, and improve it (2017-07-18 00:11:01 -0400) | 11 | parallels: fix ext_off assertion failure due to overflow (2025-01-30 15:22:28 -0500) |
| 12 | 12 | ||
| 13 | ---------------------------------------------------------------- | 13 | ---------------------------------------------------------------- |
| 14 | Block patches (documentation) | 14 | Pull request |
| 15 | |||
| 15 | ---------------------------------------------------------------- | 16 | ---------------------------------------------------------------- |
| 16 | 17 | ||
| 17 | Kashyap Chamarthy (2): | 18 | Denis Rastyogin (1): |
| 18 | bitmaps.md: Convert to rST; move it into 'interop' dir | 19 | parallels: fix ext_off assertion failure due to overflow |
| 19 | live-block-ops.txt: Rename, rewrite, and improve it | ||
| 20 | 20 | ||
| 21 | docs/devel/bitmaps.md | 505 --------------- | 21 | block/parallels.c | 4 ++++ |
| 22 | docs/interop/bitmaps.rst | 555 ++++++++++++++++ | 22 | 1 file changed, 4 insertions(+) |
| 23 | docs/interop/live-block-operations.rst | 1088 ++++++++++++++++++++++++++++++++ | ||
| 24 | docs/live-block-ops.txt | 72 --- | ||
| 25 | 4 files changed, 1643 insertions(+), 577 deletions(-) | ||
| 26 | delete mode 100644 docs/devel/bitmaps.md | ||
| 27 | create mode 100644 docs/interop/bitmaps.rst | ||
| 28 | create mode 100644 docs/interop/live-block-operations.rst | ||
| 29 | delete mode 100644 docs/live-block-ops.txt | ||
| 30 | 23 | ||
| 31 | -- | 24 | -- |
| 32 | 2.9.4 | 25 | 2.48.1 |
| 33 | |||
| 34 | diff view generated by jsdifflib |
Deleted patch | |||
|---|---|---|---|
| 1 | From: Kashyap Chamarthy <kchamart@redhat.com> | ||
| 2 | 1 | ||
| 3 | This is part of the on-going effort to convert QEMU upstream | ||
| 4 | documentation syntax to reStructuredText (rST). | ||
| 5 | |||
| 6 | The conversion to rST was done using: | ||
| 7 | |||
| 8 | $ pandoc -f markdown -t rst bitmaps.md -o bitmaps.rst | ||
| 9 | |||
| 10 | Then, make a couple of small syntactical adjustments. While at it, | ||
| 11 | reword a statement to avoid ambiguity. Addressing the feedback from | ||
| 12 | this thread: | ||
| 13 | |||
| 14 | https://lists.nongnu.org/archive/html/qemu-devel/2017-06/msg05428.html | ||
| 15 | |||
| 16 | Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com> | ||
| 17 | Reviewed-by: John Snow <jsnow@redhat.com> | ||
| 18 | Reviewed-by: Eric Blake <eblake@redhat.com> | ||
| 19 | Message-id: 20170717105205.32639-2-kchamart@redhat.com | ||
| 20 | Signed-off-by: Jeff Cody <jcody@redhat.com> | ||
| 21 | --- | ||
| 22 | docs/devel/bitmaps.md | 505 ------------------------------------------ | ||
| 23 | docs/interop/bitmaps.rst | 555 +++++++++++++++++++++++++++++++++++++++++++++++ | ||
| 24 | 2 files changed, 555 insertions(+), 505 deletions(-) | ||
| 25 | delete mode 100644 docs/devel/bitmaps.md | ||
| 26 | create mode 100644 docs/interop/bitmaps.rst | ||
| 27 | |||
| 28 | diff --git a/docs/devel/bitmaps.md b/docs/devel/bitmaps.md | ||
| 29 | deleted file mode 100644 | ||
| 30 | index XXXXXXX..XXXXXXX | ||
| 31 | --- a/docs/devel/bitmaps.md | ||
| 32 | +++ /dev/null | ||
| 33 | @@ -XXX,XX +XXX,XX @@ | ||
| 34 | -<!-- | ||
| 35 | -Copyright 2015 John Snow <jsnow@redhat.com> and Red Hat, Inc. | ||
| 36 | -All rights reserved. | ||
| 37 | - | ||
| 38 | -This file is licensed via The FreeBSD Documentation License, the full text of | ||
| 39 | -which is included at the end of this document. | ||
| 40 | ---> | ||
| 41 | - | ||
| 42 | -# Dirty Bitmaps and Incremental Backup | ||
| 43 | - | ||
| 44 | -* Dirty Bitmaps are objects that track which data needs to be backed up for the | ||
| 45 | - next incremental backup. | ||
| 46 | - | ||
| 47 | -* Dirty bitmaps can be created at any time and attached to any node | ||
| 48 | - (not just complete drives.) | ||
| 49 | - | ||
| 50 | -## Dirty Bitmap Names | ||
| 51 | - | ||
| 52 | -* A dirty bitmap's name is unique to the node, but bitmaps attached to different | ||
| 53 | - nodes can share the same name. | ||
| 54 | - | ||
| 55 | -* Dirty bitmaps created for internal use by QEMU may be anonymous and have no | ||
| 56 | - name, but any user-created bitmaps may not be. There can be any number of | ||
| 57 | - anonymous bitmaps per node. | ||
| 58 | - | ||
| 59 | -* The name of a user-created bitmap must not be empty (""). | ||
| 60 | - | ||
| 61 | -## Bitmap Modes | ||
| 62 | - | ||
| 63 | -* A Bitmap can be "frozen," which means that it is currently in-use by a backup | ||
| 64 | - operation and cannot be deleted, renamed, written to, reset, | ||
| 65 | - etc. | ||
| 66 | - | ||
| 67 | -* The normal operating mode for a bitmap is "active." | ||
| 68 | - | ||
| 69 | -## Basic QMP Usage | ||
| 70 | - | ||
| 71 | -### Supported Commands ### | ||
| 72 | - | ||
| 73 | -* block-dirty-bitmap-add | ||
| 74 | -* block-dirty-bitmap-remove | ||
| 75 | -* block-dirty-bitmap-clear | ||
| 76 | - | ||
| 77 | -### Creation | ||
| 78 | - | ||
| 79 | -* To create a new bitmap, enabled, on the drive with id=drive0: | ||
| 80 | - | ||
| 81 | -```json | ||
| 82 | -{ "execute": "block-dirty-bitmap-add", | ||
| 83 | - "arguments": { | ||
| 84 | - "node": "drive0", | ||
| 85 | - "name": "bitmap0" | ||
| 86 | - } | ||
| 87 | -} | ||
| 88 | -``` | ||
| 89 | - | ||
| 90 | -* This bitmap will have a default granularity that matches the cluster size of | ||
| 91 | - its associated drive, if available, clamped to between [4KiB, 64KiB]. | ||
| 92 | - The current default for qcow2 is 64KiB. | ||
| 93 | - | ||
| 94 | -* To create a new bitmap that tracks changes in 32KiB segments: | ||
| 95 | - | ||
| 96 | -```json | ||
| 97 | -{ "execute": "block-dirty-bitmap-add", | ||
| 98 | - "arguments": { | ||
| 99 | - "node": "drive0", | ||
| 100 | - "name": "bitmap0", | ||
| 101 | - "granularity": 32768 | ||
| 102 | - } | ||
| 103 | -} | ||
| 104 | -``` | ||
| 105 | - | ||
| 106 | -### Deletion | ||
| 107 | - | ||
| 108 | -* Bitmaps that are frozen cannot be deleted. | ||
| 109 | - | ||
| 110 | -* Deleting the bitmap does not impact any other bitmaps attached to the same | ||
| 111 | - node, nor does it affect any backups already created from this node. | ||
| 112 | - | ||
| 113 | -* Because bitmaps are only unique to the node to which they are attached, | ||
| 114 | - you must specify the node/drive name here, too. | ||
| 115 | - | ||
| 116 | -```json | ||
| 117 | -{ "execute": "block-dirty-bitmap-remove", | ||
| 118 | - "arguments": { | ||
| 119 | - "node": "drive0", | ||
| 120 | - "name": "bitmap0" | ||
| 121 | - } | ||
| 122 | -} | ||
| 123 | -``` | ||
| 124 | - | ||
| 125 | -### Resetting | ||
| 126 | - | ||
| 127 | -* Resetting a bitmap will clear all information it holds. | ||
| 128 | - | ||
| 129 | -* An incremental backup created from an empty bitmap will copy no data, | ||
| 130 | - as if nothing has changed. | ||
| 131 | - | ||
| 132 | -```json | ||
| 133 | -{ "execute": "block-dirty-bitmap-clear", | ||
| 134 | - "arguments": { | ||
| 135 | - "node": "drive0", | ||
| 136 | - "name": "bitmap0" | ||
| 137 | - } | ||
| 138 | -} | ||
| 139 | -``` | ||
| 140 | - | ||
| 141 | -## Transactions | ||
| 142 | - | ||
| 143 | -### Justification | ||
| 144 | - | ||
| 145 | -Bitmaps can be safely modified when the VM is paused or halted by using | ||
| 146 | -the basic QMP commands. For instance, you might perform the following actions: | ||
| 147 | - | ||
| 148 | -1. Boot the VM in a paused state. | ||
| 149 | -2. Create a full drive backup of drive0. | ||
| 150 | -3. Create a new bitmap attached to drive0. | ||
| 151 | -4. Resume execution of the VM. | ||
| 152 | -5. Incremental backups are ready to be created. | ||
| 153 | - | ||
| 154 | -At this point, the bitmap and drive backup would be correctly in sync, | ||
| 155 | -and incremental backups made from this point forward would be correctly aligned | ||
| 156 | -to the full drive backup. | ||
| 157 | - | ||
| 158 | -This is not particularly useful if we decide we want to start incremental | ||
| 159 | -backups after the VM has been running for a while, for which we will need to | ||
| 160 | -perform actions such as the following: | ||
| 161 | - | ||
| 162 | -1. Boot the VM and begin execution. | ||
| 163 | -2. Using a single transaction, perform the following operations: | ||
| 164 | - * Create bitmap0. | ||
| 165 | - * Create a full drive backup of drive0. | ||
| 166 | -3. Incremental backups are now ready to be created. | ||
| 167 | - | ||
| 168 | -### Supported Bitmap Transactions | ||
| 169 | - | ||
| 170 | -* block-dirty-bitmap-add | ||
| 171 | -* block-dirty-bitmap-clear | ||
| 172 | - | ||
| 173 | -The usages are identical to their respective QMP commands, but see below | ||
| 174 | -for examples. | ||
| 175 | - | ||
| 176 | -### Example: New Incremental Backup | ||
| 177 | - | ||
| 178 | -As outlined in the justification, perhaps we want to create a new incremental | ||
| 179 | -backup chain attached to a drive. | ||
| 180 | - | ||
| 181 | -```json | ||
| 182 | -{ "execute": "transaction", | ||
| 183 | - "arguments": { | ||
| 184 | - "actions": [ | ||
| 185 | - {"type": "block-dirty-bitmap-add", | ||
| 186 | - "data": {"node": "drive0", "name": "bitmap0"} }, | ||
| 187 | - {"type": "drive-backup", | ||
| 188 | - "data": {"device": "drive0", "target": "/path/to/full_backup.img", | ||
| 189 | - "sync": "full", "format": "qcow2"} } | ||
| 190 | - ] | ||
| 191 | - } | ||
| 192 | -} | ||
| 193 | -``` | ||
| 194 | - | ||
| 195 | -### Example: New Incremental Backup Anchor Point | ||
| 196 | - | ||
| 197 | -Maybe we just want to create a new full backup with an existing bitmap and | ||
| 198 | -want to reset the bitmap to track the new chain. | ||
| 199 | - | ||
| 200 | -```json | ||
| 201 | -{ "execute": "transaction", | ||
| 202 | - "arguments": { | ||
| 203 | - "actions": [ | ||
| 204 | - {"type": "block-dirty-bitmap-clear", | ||
| 205 | - "data": {"node": "drive0", "name": "bitmap0"} }, | ||
| 206 | - {"type": "drive-backup", | ||
| 207 | - "data": {"device": "drive0", "target": "/path/to/new_full_backup.img", | ||
| 208 | - "sync": "full", "format": "qcow2"} } | ||
| 209 | - ] | ||
| 210 | - } | ||
| 211 | -} | ||
| 212 | -``` | ||
| 213 | - | ||
| 214 | -## Incremental Backups | ||
| 215 | - | ||
| 216 | -The star of the show. | ||
| 217 | - | ||
| 218 | -**Nota Bene!** Only incremental backups of entire drives are supported for now. | ||
| 219 | -So despite the fact that you can attach a bitmap to any arbitrary node, they are | ||
| 220 | -only currently useful when attached to the root node. This is because | ||
| 221 | -drive-backup only supports drives/devices instead of arbitrary nodes. | ||
| 222 | - | ||
| 223 | -### Example: First Incremental Backup | ||
| 224 | - | ||
| 225 | -1. Create a full backup and sync it to the dirty bitmap, as in the transactional | ||
| 226 | -examples above; or with the VM offline, manually create a full copy and then | ||
| 227 | -create a new bitmap before the VM begins execution. | ||
| 228 | - | ||
| 229 | - * Let's assume the full backup is named 'full_backup.img'. | ||
| 230 | - * Let's assume the bitmap you created is 'bitmap0' attached to 'drive0'. | ||
| 231 | - | ||
| 232 | -2. Create a destination image for the incremental backup that utilizes the | ||
| 233 | -full backup as a backing image. | ||
| 234 | - | ||
| 235 | - * Let's assume it is named 'incremental.0.img'. | ||
| 236 | - | ||
| 237 | - ```sh | ||
| 238 | - # qemu-img create -f qcow2 incremental.0.img -b full_backup.img -F qcow2 | ||
| 239 | - ``` | ||
| 240 | - | ||
| 241 | -3. Issue the incremental backup command: | ||
| 242 | - | ||
| 243 | - ```json | ||
| 244 | - { "execute": "drive-backup", | ||
| 245 | - "arguments": { | ||
| 246 | - "device": "drive0", | ||
| 247 | - "bitmap": "bitmap0", | ||
| 248 | - "target": "incremental.0.img", | ||
| 249 | - "format": "qcow2", | ||
| 250 | - "sync": "incremental", | ||
| 251 | - "mode": "existing" | ||
| 252 | - } | ||
| 253 | - } | ||
| 254 | - ``` | ||
| 255 | - | ||
| 256 | -### Example: Second Incremental Backup | ||
| 257 | - | ||
| 258 | -1. Create a new destination image for the incremental backup that points to the | ||
| 259 | - previous one, e.g.: 'incremental.1.img' | ||
| 260 | - | ||
| 261 | - ```sh | ||
| 262 | - # qemu-img create -f qcow2 incremental.1.img -b incremental.0.img -F qcow2 | ||
| 263 | - ``` | ||
| 264 | - | ||
| 265 | -2. Issue a new incremental backup command. The only difference here is that we | ||
| 266 | - have changed the target image below. | ||
| 267 | - | ||
| 268 | - ```json | ||
| 269 | - { "execute": "drive-backup", | ||
| 270 | - "arguments": { | ||
| 271 | - "device": "drive0", | ||
| 272 | - "bitmap": "bitmap0", | ||
| 273 | - "target": "incremental.1.img", | ||
| 274 | - "format": "qcow2", | ||
| 275 | - "sync": "incremental", | ||
| 276 | - "mode": "existing" | ||
| 277 | - } | ||
| 278 | - } | ||
| 279 | - ``` | ||
| 280 | - | ||
| 281 | -## Errors | ||
| 282 | - | ||
| 283 | -* In the event of an error that occurs after a backup job is successfully | ||
| 284 | - launched, either by a direct QMP command or a QMP transaction, the user | ||
| 285 | - will receive a BLOCK_JOB_COMPLETE event with a failure message, accompanied | ||
| 286 | - by a BLOCK_JOB_ERROR event. | ||
| 287 | - | ||
| 288 | -* In the case of an event being cancelled, the user will receive a | ||
| 289 | - BLOCK_JOB_CANCELLED event instead of a pair of COMPLETE and ERROR events. | ||
| 290 | - | ||
| 291 | -* In either case, the incremental backup data contained within the bitmap is | ||
| 292 | - safely rolled back, and the data within the bitmap is not lost. The image | ||
| 293 | - file created for the failed attempt can be safely deleted. | ||
| 294 | - | ||
| 295 | -* Once the underlying problem is fixed (e.g. more storage space is freed up), | ||
| 296 | - you can simply retry the incremental backup command with the same bitmap. | ||
| 297 | - | ||
| 298 | -### Example | ||
| 299 | - | ||
| 300 | -1. Create a target image: | ||
| 301 | - | ||
| 302 | - ```sh | ||
| 303 | - # qemu-img create -f qcow2 incremental.0.img -b full_backup.img -F qcow2 | ||
| 304 | - ``` | ||
| 305 | - | ||
| 306 | -2. Attempt to create an incremental backup via QMP: | ||
| 307 | - | ||
| 308 | - ```json | ||
| 309 | - { "execute": "drive-backup", | ||
| 310 | - "arguments": { | ||
| 311 | - "device": "drive0", | ||
| 312 | - "bitmap": "bitmap0", | ||
| 313 | - "target": "incremental.0.img", | ||
| 314 | - "format": "qcow2", | ||
| 315 | - "sync": "incremental", | ||
| 316 | - "mode": "existing" | ||
| 317 | - } | ||
| 318 | - } | ||
| 319 | - ``` | ||
| 320 | - | ||
| 321 | -3. Receive an event notifying us of failure: | ||
| 322 | - | ||
| 323 | - ```json | ||
| 324 | - { "timestamp": { "seconds": 1424709442, "microseconds": 844524 }, | ||
| 325 | - "data": { "speed": 0, "offset": 0, "len": 67108864, | ||
| 326 | - "error": "No space left on device", | ||
| 327 | - "device": "drive1", "type": "backup" }, | ||
| 328 | - "event": "BLOCK_JOB_COMPLETED" } | ||
| 329 | - ``` | ||
| 330 | - | ||
| 331 | -4. Delete the failed incremental, and re-create the image. | ||
| 332 | - | ||
| 333 | - ```sh | ||
| 334 | - # rm incremental.0.img | ||
| 335 | - # qemu-img create -f qcow2 incremental.0.img -b full_backup.img -F qcow2 | ||
| 336 | - ``` | ||
| 337 | - | ||
| 338 | -5. Retry the command after fixing the underlying problem, | ||
| 339 | - such as freeing up space on the backup volume: | ||
| 340 | - | ||
| 341 | - ```json | ||
| 342 | - { "execute": "drive-backup", | ||
| 343 | - "arguments": { | ||
| 344 | - "device": "drive0", | ||
| 345 | - "bitmap": "bitmap0", | ||
| 346 | - "target": "incremental.0.img", | ||
| 347 | - "format": "qcow2", | ||
| 348 | - "sync": "incremental", | ||
| 349 | - "mode": "existing" | ||
| 350 | - } | ||
| 351 | - } | ||
| 352 | - ``` | ||
| 353 | - | ||
| 354 | -6. Receive confirmation that the job completed successfully: | ||
| 355 | - | ||
| 356 | - ```json | ||
| 357 | - { "timestamp": { "seconds": 1424709668, "microseconds": 526525 }, | ||
| 358 | - "data": { "device": "drive1", "type": "backup", | ||
| 359 | - "speed": 0, "len": 67108864, "offset": 67108864}, | ||
| 360 | - "event": "BLOCK_JOB_COMPLETED" } | ||
| 361 | - ``` | ||
| 362 | - | ||
| 363 | -### Partial Transactional Failures | ||
| 364 | - | ||
| 365 | -* Sometimes, a transaction will succeed in launching and return success, | ||
| 366 | - but then later the backup jobs themselves may fail. It is possible that | ||
| 367 | - a management application may have to deal with a partial backup failure | ||
| 368 | - after a successful transaction. | ||
| 369 | - | ||
| 370 | -* If multiple backup jobs are specified in a single transaction, when one of | ||
| 371 | - them fails, it will not interact with the other backup jobs in any way. | ||
| 372 | - | ||
| 373 | -* The job(s) that succeeded will clear the dirty bitmap associated with the | ||
| 374 | - operation, but the job(s) that failed will not. It is not "safe" to delete | ||
| 375 | - any incremental backups that were created successfully in this scenario, | ||
| 376 | - even though others failed. | ||
| 377 | - | ||
| 378 | -#### Example | ||
| 379 | - | ||
| 380 | -* QMP example highlighting two backup jobs: | ||
| 381 | - | ||
| 382 | - ```json | ||
| 383 | - { "execute": "transaction", | ||
| 384 | - "arguments": { | ||
| 385 | - "actions": [ | ||
| 386 | - { "type": "drive-backup", | ||
| 387 | - "data": { "device": "drive0", "bitmap": "bitmap0", | ||
| 388 | - "format": "qcow2", "mode": "existing", | ||
| 389 | - "sync": "incremental", "target": "d0-incr-1.qcow2" } }, | ||
| 390 | - { "type": "drive-backup", | ||
| 391 | - "data": { "device": "drive1", "bitmap": "bitmap1", | ||
| 392 | - "format": "qcow2", "mode": "existing", | ||
| 393 | - "sync": "incremental", "target": "d1-incr-1.qcow2" } }, | ||
| 394 | - ] | ||
| 395 | - } | ||
| 396 | - } | ||
| 397 | - ``` | ||
| 398 | - | ||
| 399 | -* QMP example response, highlighting one success and one failure: | ||
| 400 | - * Acknowledgement that the Transaction was accepted and jobs were launched: | ||
| 401 | - ```json | ||
| 402 | - { "return": {} } | ||
| 403 | - ``` | ||
| 404 | - | ||
| 405 | - * Later, QEMU sends notice that the first job was completed: | ||
| 406 | - ```json | ||
| 407 | - { "timestamp": { "seconds": 1447192343, "microseconds": 615698 }, | ||
| 408 | - "data": { "device": "drive0", "type": "backup", | ||
| 409 | - "speed": 0, "len": 67108864, "offset": 67108864 }, | ||
| 410 | - "event": "BLOCK_JOB_COMPLETED" | ||
| 411 | - } | ||
| 412 | - ``` | ||
| 413 | - | ||
| 414 | - * Later yet, QEMU sends notice that the second job has failed: | ||
| 415 | - ```json | ||
| 416 | - { "timestamp": { "seconds": 1447192399, "microseconds": 683015 }, | ||
| 417 | - "data": { "device": "drive1", "action": "report", | ||
| 418 | - "operation": "read" }, | ||
| 419 | - "event": "BLOCK_JOB_ERROR" } | ||
| 420 | - ``` | ||
| 421 | - | ||
| 422 | - ```json | ||
| 423 | - { "timestamp": { "seconds": 1447192399, "microseconds": 685853 }, | ||
| 424 | - "data": { "speed": 0, "offset": 0, "len": 67108864, | ||
| 425 | - "error": "Input/output error", | ||
| 426 | - "device": "drive1", "type": "backup" }, | ||
| 427 | - "event": "BLOCK_JOB_COMPLETED" } | ||
| 428 | - | ||
| 429 | -* In the above example, "d0-incr-1.qcow2" is valid and must be kept, | ||
| 430 | - but "d1-incr-1.qcow2" is invalid and should be deleted. If a VM-wide | ||
| 431 | - incremental backup of all drives at a point-in-time is to be made, | ||
| 432 | - new backups for both drives will need to be made, taking into account | ||
| 433 | - that a new incremental backup for drive0 needs to be based on top of | ||
| 434 | - "d0-incr-1.qcow2." | ||
| 435 | - | ||
| 436 | -### Grouped Completion Mode | ||
| 437 | - | ||
| 438 | -* While jobs launched by transactions normally complete or fail on their own, | ||
| 439 | - it is possible to instruct them to complete or fail together as a group. | ||
| 440 | - | ||
| 441 | -* QMP transactions take an optional properties structure that can affect | ||
| 442 | - the semantics of the transaction. | ||
| 443 | - | ||
| 444 | -* The "completion-mode" transaction property can be either "individual" | ||
| 445 | - which is the default, legacy behavior described above, or "grouped," | ||
| 446 | - a new behavior detailed below. | ||
| 447 | - | ||
| 448 | -* Delayed Completion: In grouped completion mode, no jobs will report | ||
| 449 | - success until all jobs are ready to report success. | ||
| 450 | - | ||
| 451 | -* Grouped failure: If any job fails in grouped completion mode, all remaining | ||
| 452 | - jobs will be cancelled. Any incremental backups will restore their dirty | ||
| 453 | - bitmap objects as if no backup command was ever issued. | ||
| 454 | - | ||
| 455 | - * Regardless of if QEMU reports a particular incremental backup job as | ||
| 456 | - CANCELLED or as an ERROR, the in-memory bitmap will be restored. | ||
| 457 | - | ||
| 458 | -#### Example | ||
| 459 | - | ||
| 460 | -* Here's the same example scenario from above with the new property: | ||
| 461 | - | ||
| 462 | - ```json | ||
| 463 | - { "execute": "transaction", | ||
| 464 | - "arguments": { | ||
| 465 | - "actions": [ | ||
| 466 | - { "type": "drive-backup", | ||
| 467 | - "data": { "device": "drive0", "bitmap": "bitmap0", | ||
| 468 | - "format": "qcow2", "mode": "existing", | ||
| 469 | - "sync": "incremental", "target": "d0-incr-1.qcow2" } }, | ||
| 470 | - { "type": "drive-backup", | ||
| 471 | - "data": { "device": "drive1", "bitmap": "bitmap1", | ||
| 472 | - "format": "qcow2", "mode": "existing", | ||
| 473 | - "sync": "incremental", "target": "d1-incr-1.qcow2" } }, | ||
| 474 | - ], | ||
| 475 | - "properties": { | ||
| 476 | - "completion-mode": "grouped" | ||
| 477 | - } | ||
| 478 | - } | ||
| 479 | - } | ||
| 480 | - ``` | ||
| 481 | - | ||
| 482 | -* QMP example response, highlighting a failure for drive2: | ||
| 483 | - * Acknowledgement that the Transaction was accepted and jobs were launched: | ||
| 484 | - ```json | ||
| 485 | - { "return": {} } | ||
| 486 | - ``` | ||
| 487 | - | ||
| 488 | - * Later, QEMU sends notice that the second job has errored out, | ||
| 489 | - but that the first job was also cancelled: | ||
| 490 | - ```json | ||
| 491 | - { "timestamp": { "seconds": 1447193702, "microseconds": 632377 }, | ||
| 492 | - "data": { "device": "drive1", "action": "report", | ||
| 493 | - "operation": "read" }, | ||
| 494 | - "event": "BLOCK_JOB_ERROR" } | ||
| 495 | - ``` | ||
| 496 | - | ||
| 497 | - ```json | ||
| 498 | - { "timestamp": { "seconds": 1447193702, "microseconds": 640074 }, | ||
| 499 | - "data": { "speed": 0, "offset": 0, "len": 67108864, | ||
| 500 | - "error": "Input/output error", | ||
| 501 | - "device": "drive1", "type": "backup" }, | ||
| 502 | - "event": "BLOCK_JOB_COMPLETED" } | ||
| 503 | - ``` | ||
| 504 | - | ||
| 505 | - ```json | ||
| 506 | - { "timestamp": { "seconds": 1447193702, "microseconds": 640163 }, | ||
| 507 | - "data": { "device": "drive0", "type": "backup", "speed": 0, | ||
| 508 | - "len": 67108864, "offset": 16777216 }, | ||
| 509 | - "event": "BLOCK_JOB_CANCELLED" } | ||
| 510 | - ``` | ||
| 511 | - | ||
| 512 | -<!-- | ||
| 513 | -The FreeBSD Documentation License | ||
| 514 | - | ||
| 515 | -Redistribution and use in source (Markdown) and 'compiled' forms (SGML, HTML, | ||
| 516 | -PDF, PostScript, RTF and so forth) with or without modification, are permitted | ||
| 517 | -provided that the following conditions are met: | ||
| 518 | - | ||
| 519 | -Redistributions of source code (Markdown) must retain the above copyright | ||
| 520 | -notice, this list of conditions and the following disclaimer of this file | ||
| 521 | -unmodified. | ||
| 522 | - | ||
| 523 | -Redistributions in compiled form (transformed to other DTDs, converted to PDF, | ||
| 524 | -PostScript, RTF and other formats) must reproduce the above copyright notice, | ||
| 525 | -this list of conditions and the following disclaimer in the documentation and/or | ||
| 526 | -other materials provided with the distribution. | ||
| 527 | - | ||
| 528 | -THIS DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" | ||
| 529 | -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||
| 530 | -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE | ||
| 531 | -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE | ||
| 532 | -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | ||
| 533 | -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR | ||
| 534 | -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER | ||
| 535 | -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, | ||
| 536 | -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF | ||
| 537 | -THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||
| 538 | ---> | ||
| 539 | diff --git a/docs/interop/bitmaps.rst b/docs/interop/bitmaps.rst | ||
| 540 | new file mode 100644 | ||
| 541 | index XXXXXXX..XXXXXXX | ||
| 542 | --- /dev/null | ||
| 543 | +++ b/docs/interop/bitmaps.rst | ||
| 544 | @@ -XXX,XX +XXX,XX @@ | ||
| 545 | +.. | ||
| 546 | + Copyright 2015 John Snow <jsnow@redhat.com> and Red Hat, Inc. | ||
| 547 | + All rights reserved. | ||
| 548 | + | ||
| 549 | + This file is licensed via The FreeBSD Documentation License, the full | ||
| 550 | + text of which is included at the end of this document. | ||
| 551 | + | ||
| 552 | +==================================== | ||
| 553 | +Dirty Bitmaps and Incremental Backup | ||
| 554 | +==================================== | ||
| 555 | + | ||
| 556 | +- Dirty Bitmaps are objects that track which data needs to be backed up | ||
| 557 | + for the next incremental backup. | ||
| 558 | + | ||
| 559 | +- Dirty bitmaps can be created at any time and attached to any node | ||
| 560 | + (not just complete drives). | ||
| 561 | + | ||
| 562 | +.. contents:: | ||
| 563 | + | ||
| 564 | +Dirty Bitmap Names | ||
| 565 | +------------------ | ||
| 566 | + | ||
| 567 | +- A dirty bitmap's name is unique to the node, but bitmaps attached to | ||
| 568 | + different nodes can share the same name. | ||
| 569 | + | ||
| 570 | +- Dirty bitmaps created for internal use by QEMU may be anonymous and | ||
| 571 | + have no name, but any user-created bitmaps must have a name. There | ||
| 572 | + can be any number of anonymous bitmaps per node. | ||
| 573 | + | ||
| 574 | +- The name of a user-created bitmap must not be empty (""). | ||
| 575 | + | ||
| 576 | +Bitmap Modes | ||
| 577 | +------------ | ||
| 578 | + | ||
| 579 | +- A bitmap can be "frozen," which means that it is currently in-use by | ||
| 580 | + a backup operation and cannot be deleted, renamed, written to, reset, | ||
| 581 | + etc. | ||
| 582 | + | ||
| 583 | +- The normal operating mode for a bitmap is "active." | ||
| 584 | + | ||
| 585 | +Basic QMP Usage | ||
| 586 | +--------------- | ||
| 587 | + | ||
| 588 | +Supported Commands | ||
| 589 | +~~~~~~~~~~~~~~~~~~ | ||
| 590 | + | ||
| 591 | +- ``block-dirty-bitmap-add`` | ||
| 592 | +- ``block-dirty-bitmap-remove`` | ||
| 593 | +- ``block-dirty-bitmap-clear`` | ||
| 594 | + | ||
| 595 | +Creation | ||
| 596 | +~~~~~~~~ | ||
| 597 | + | ||
| 598 | +- To create a new bitmap, enabled, on the drive with id=drive0: | ||
| 599 | + | ||
| 600 | +.. code:: json | ||
| 601 | + | ||
| 602 | + { "execute": "block-dirty-bitmap-add", | ||
| 603 | + "arguments": { | ||
| 604 | + "node": "drive0", | ||
| 605 | + "name": "bitmap0" | ||
| 606 | + } | ||
| 607 | + } | ||
| 608 | + | ||
| 609 | +- This bitmap will have a default granularity that matches the cluster | ||
| 610 | + size of its associated drive, if available, clamped to between [4KiB, | ||
| 611 | + 64KiB]. The current default for qcow2 is 64KiB. | ||
| 612 | + | ||
| 613 | +- To create a new bitmap that tracks changes in 32KiB segments: | ||
| 614 | + | ||
| 615 | +.. code:: json | ||
| 616 | + | ||
| 617 | + { "execute": "block-dirty-bitmap-add", | ||
| 618 | + "arguments": { | ||
| 619 | + "node": "drive0", | ||
| 620 | + "name": "bitmap0", | ||
| 621 | + "granularity": 32768 | ||
| 622 | + } | ||
| 623 | + } | ||
| 624 | + | ||
| 625 | +Deletion | ||
| 626 | +~~~~~~~~ | ||
| 627 | + | ||
| 628 | +- Bitmaps that are frozen cannot be deleted. | ||
| 629 | + | ||
| 630 | +- Deleting the bitmap does not impact any other bitmaps attached to the | ||
| 631 | + same node, nor does it affect any backups already created from this | ||
| 632 | + node. | ||
| 633 | + | ||
| 634 | +- Because bitmaps are only unique to the node to which they are | ||
| 635 | + attached, you must specify the node/drive name here, too. | ||
| 636 | + | ||
| 637 | +.. code:: json | ||
| 638 | + | ||
| 639 | + { "execute": "block-dirty-bitmap-remove", | ||
| 640 | + "arguments": { | ||
| 641 | + "node": "drive0", | ||
| 642 | + "name": "bitmap0" | ||
| 643 | + } | ||
| 644 | + } | ||
| 645 | + | ||
| 646 | +Resetting | ||
| 647 | +~~~~~~~~~ | ||
| 648 | + | ||
| 649 | +- Resetting a bitmap will clear all information it holds. | ||
| 650 | + | ||
| 651 | +- An incremental backup created from an empty bitmap will copy no data, | ||
| 652 | + as if nothing has changed. | ||
| 653 | + | ||
| 654 | +.. code:: json | ||
| 655 | + | ||
| 656 | + { "execute": "block-dirty-bitmap-clear", | ||
| 657 | + "arguments": { | ||
| 658 | + "node": "drive0", | ||
| 659 | + "name": "bitmap0" | ||
| 660 | + } | ||
| 661 | + } | ||
| 662 | + | ||
| 663 | +Transactions | ||
| 664 | +------------ | ||
| 665 | + | ||
| 666 | +Justification | ||
| 667 | +~~~~~~~~~~~~~ | ||
| 668 | + | ||
| 669 | +Bitmaps can be safely modified when the VM is paused or halted by using | ||
| 670 | +the basic QMP commands. For instance, you might perform the following | ||
| 671 | +actions: | ||
| 672 | + | ||
| 673 | +1. Boot the VM in a paused state. | ||
| 674 | +2. Create a full drive backup of drive0. | ||
| 675 | +3. Create a new bitmap attached to drive0. | ||
| 676 | +4. Resume execution of the VM. | ||
| 677 | +5. Incremental backups are ready to be created. | ||
| 678 | + | ||
| 679 | +At this point, the bitmap and drive backup would be correctly in sync, | ||
| 680 | +and incremental backups made from this point forward would be correctly | ||
| 681 | +aligned to the full drive backup. | ||
| 682 | + | ||
| 683 | +This is not particularly useful if we decide we want to start | ||
| 684 | +incremental backups after the VM has been running for a while, for which | ||
| 685 | +we will need to perform actions such as the following: | ||
| 686 | + | ||
| 687 | +1. Boot the VM and begin execution. | ||
| 688 | +2. Using a single transaction, perform the following operations: | ||
| 689 | + | ||
| 690 | + - Create ``bitmap0``. | ||
| 691 | + - Create a full drive backup of ``drive0``. | ||
| 692 | + | ||
| 693 | +3. Incremental backups are now ready to be created. | ||
| 694 | + | ||
| 695 | +Supported Bitmap Transactions | ||
| 696 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 697 | + | ||
| 698 | +- ``block-dirty-bitmap-add`` | ||
| 699 | +- ``block-dirty-bitmap-clear`` | ||
| 700 | + | ||
| 701 | +The usages are identical to their respective QMP commands, but see below | ||
| 702 | +for examples. | ||
| 703 | + | ||
| 704 | +Example: New Incremental Backup | ||
| 705 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 706 | + | ||
| 707 | +As outlined in the justification, perhaps we want to create a new | ||
| 708 | +incremental backup chain attached to a drive. | ||
| 709 | + | ||
| 710 | +.. code:: json | ||
| 711 | + | ||
| 712 | + { "execute": "transaction", | ||
| 713 | + "arguments": { | ||
| 714 | + "actions": [ | ||
| 715 | + {"type": "block-dirty-bitmap-add", | ||
| 716 | + "data": {"node": "drive0", "name": "bitmap0"} }, | ||
| 717 | + {"type": "drive-backup", | ||
| 718 | + "data": {"device": "drive0", "target": "/path/to/full_backup.img", | ||
| 719 | + "sync": "full", "format": "qcow2"} } | ||
| 720 | + ] | ||
| 721 | + } | ||
| 722 | + } | ||
| 723 | + | ||
| 724 | +Example: New Incremental Backup Anchor Point | ||
| 725 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 726 | + | ||
| 727 | +Maybe we just want to create a new full backup with an existing bitmap | ||
| 728 | +and want to reset the bitmap to track the new chain. | ||
| 729 | + | ||
| 730 | +.. code:: json | ||
| 731 | + | ||
| 732 | + { "execute": "transaction", | ||
| 733 | + "arguments": { | ||
| 734 | + "actions": [ | ||
| 735 | + {"type": "block-dirty-bitmap-clear", | ||
| 736 | + "data": {"node": "drive0", "name": "bitmap0"} }, | ||
| 737 | + {"type": "drive-backup", | ||
| 738 | + "data": {"device": "drive0", "target": "/path/to/new_full_backup.img", | ||
| 739 | + "sync": "full", "format": "qcow2"} } | ||
| 740 | + ] | ||
| 741 | + } | ||
| 742 | + } | ||
| 743 | + | ||
| 744 | +Incremental Backups | ||
| 745 | +------------------- | ||
| 746 | + | ||
| 747 | +The star of the show. | ||
| 748 | + | ||
| 749 | +**Nota Bene!** Only incremental backups of entire drives are supported | ||
| 750 | +for now. So despite the fact that you can attach a bitmap to any | ||
| 751 | +arbitrary node, they are only currently useful when attached to the root | ||
| 752 | +node. This is because drive-backup only supports drives/devices instead | ||
| 753 | +of arbitrary nodes. | ||
| 754 | + | ||
| 755 | +Example: First Incremental Backup | ||
| 756 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 757 | + | ||
| 758 | +1. Create a full backup and sync it to the dirty bitmap, as in the | ||
| 759 | + transactional examples above; or with the VM offline, manually create | ||
| 760 | + a full copy and then create a new bitmap before the VM begins | ||
| 761 | + execution. | ||
| 762 | + | ||
| 763 | + - Let's assume the full backup is named ``full_backup.img``. | ||
| 764 | + - Let's assume the bitmap you created is ``bitmap0`` attached to | ||
| 765 | + ``drive0``. | ||
| 766 | + | ||
| 767 | +2. Create a destination image for the incremental backup that utilizes | ||
| 768 | + the full backup as a backing image. | ||
| 769 | + | ||
| 770 | + - Let's assume the new incremental image is named | ||
| 771 | + ``incremental.0.img``. | ||
| 772 | + | ||
| 773 | + .. code:: bash | ||
| 774 | + | ||
| 775 | + $ qemu-img create -f qcow2 incremental.0.img -b full_backup.img -F qcow2 | ||
| 776 | + | ||
| 777 | +3. Issue the incremental backup command: | ||
| 778 | + | ||
| 779 | + .. code:: json | ||
| 780 | + | ||
| 781 | + { "execute": "drive-backup", | ||
| 782 | + "arguments": { | ||
| 783 | + "device": "drive0", | ||
| 784 | + "bitmap": "bitmap0", | ||
| 785 | + "target": "incremental.0.img", | ||
| 786 | + "format": "qcow2", | ||
| 787 | + "sync": "incremental", | ||
| 788 | + "mode": "existing" | ||
| 789 | + } | ||
| 790 | + } | ||
| 791 | + | ||
| 792 | +Example: Second Incremental Backup | ||
| 793 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 794 | + | ||
| 795 | +1. Create a new destination image for the incremental backup that points | ||
| 796 | + to the previous one, e.g.: ``incremental.1.img`` | ||
| 797 | + | ||
| 798 | + .. code:: bash | ||
| 799 | + | ||
| 800 | + $ qemu-img create -f qcow2 incremental.1.img -b incremental.0.img -F qcow2 | ||
| 801 | + | ||
| 802 | +2. Issue a new incremental backup command. The only difference here is | ||
| 803 | + that we have changed the target image below. | ||
| 804 | + | ||
| 805 | + .. code:: json | ||
| 806 | + | ||
| 807 | + { "execute": "drive-backup", | ||
| 808 | + "arguments": { | ||
| 809 | + "device": "drive0", | ||
| 810 | + "bitmap": "bitmap0", | ||
| 811 | + "target": "incremental.1.img", | ||
| 812 | + "format": "qcow2", | ||
| 813 | + "sync": "incremental", | ||
| 814 | + "mode": "existing" | ||
| 815 | + } | ||
| 816 | + } | ||
| 817 | + | ||
| 818 | +Errors | ||
| 819 | +------ | ||
| 820 | + | ||
| 821 | +- In the event of an error that occurs after a backup job is | ||
| 822 | + successfully launched, either by a direct QMP command or a QMP | ||
| 823 | + transaction, the user will receive a ``BLOCK_JOB_COMPLETE`` event with | ||
| 824 | + a failure message, accompanied by a ``BLOCK_JOB_ERROR`` event. | ||
| 825 | + | ||
| 826 | +- In the case of an event being cancelled, the user will receive a | ||
| 827 | + ``BLOCK_JOB_CANCELLED`` event instead of a pair of COMPLETE and ERROR | ||
| 828 | + events. | ||
| 829 | + | ||
| 830 | +- In either case, the incremental backup data contained within the | ||
| 831 | + bitmap is safely rolled back, and the data within the bitmap is not | ||
| 832 | + lost. The image file created for the failed attempt can be safely | ||
| 833 | + deleted. | ||
| 834 | + | ||
| 835 | +- Once the underlying problem is fixed (e.g. more storage space is | ||
| 836 | + freed up), you can simply retry the incremental backup command with | ||
| 837 | + the same bitmap. | ||
| 838 | + | ||
| 839 | +Example | ||
| 840 | +~~~~~~~ | ||
| 841 | + | ||
| 842 | +1. Create a target image: | ||
| 843 | + | ||
| 844 | + .. code:: bash | ||
| 845 | + | ||
| 846 | + $ qemu-img create -f qcow2 incremental.0.img -b full_backup.img -F qcow2 | ||
| 847 | + | ||
| 848 | +2. Attempt to create an incremental backup via QMP: | ||
| 849 | + | ||
| 850 | + .. code:: json | ||
| 851 | + | ||
| 852 | + { "execute": "drive-backup", | ||
| 853 | + "arguments": { | ||
| 854 | + "device": "drive0", | ||
| 855 | + "bitmap": "bitmap0", | ||
| 856 | + "target": "incremental.0.img", | ||
| 857 | + "format": "qcow2", | ||
| 858 | + "sync": "incremental", | ||
| 859 | + "mode": "existing" | ||
| 860 | + } | ||
| 861 | + } | ||
| 862 | + | ||
| 863 | +3. Receive an event notifying us of failure: | ||
| 864 | + | ||
| 865 | + .. code:: json | ||
| 866 | + | ||
| 867 | + { "timestamp": { "seconds": 1424709442, "microseconds": 844524 }, | ||
| 868 | + "data": { "speed": 0, "offset": 0, "len": 67108864, | ||
| 869 | + "error": "No space left on device", | ||
| 870 | + "device": "drive1", "type": "backup" }, | ||
| 871 | + "event": "BLOCK_JOB_COMPLETED" } | ||
| 872 | + | ||
| 873 | +4. Delete the failed incremental, and re-create the image. | ||
| 874 | + | ||
| 875 | + .. code:: bash | ||
| 876 | + | ||
| 877 | + $ rm incremental.0.img | ||
| 878 | + $ qemu-img create -f qcow2 incremental.0.img -b full_backup.img -F qcow2 | ||
| 879 | + | ||
| 880 | +5. Retry the command after fixing the underlying problem, such as | ||
| 881 | + freeing up space on the backup volume: | ||
| 882 | + | ||
| 883 | + .. code:: json | ||
| 884 | + | ||
| 885 | + { "execute": "drive-backup", | ||
| 886 | + "arguments": { | ||
| 887 | + "device": "drive0", | ||
| 888 | + "bitmap": "bitmap0", | ||
| 889 | + "target": "incremental.0.img", | ||
| 890 | + "format": "qcow2", | ||
| 891 | + "sync": "incremental", | ||
| 892 | + "mode": "existing" | ||
| 893 | + } | ||
| 894 | + } | ||
| 895 | + | ||
| 896 | +6. Receive confirmation that the job completed successfully: | ||
| 897 | + | ||
| 898 | + .. code:: json | ||
| 899 | + | ||
| 900 | + { "timestamp": { "seconds": 1424709668, "microseconds": 526525 }, | ||
| 901 | + "data": { "device": "drive1", "type": "backup", | ||
| 902 | + "speed": 0, "len": 67108864, "offset": 67108864}, | ||
| 903 | + "event": "BLOCK_JOB_COMPLETED" } | ||
| 904 | + | ||
| 905 | +Partial Transactional Failures | ||
| 906 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 907 | + | ||
| 908 | +- Sometimes, a transaction will succeed in launching and return | ||
| 909 | + success, but then later the backup jobs themselves may fail. It is | ||
| 910 | + possible that a management application may have to deal with a | ||
| 911 | + partial backup failure after a successful transaction. | ||
| 912 | + | ||
| 913 | +- If multiple backup jobs are specified in a single transaction, when | ||
| 914 | + one of them fails, it will not interact with the other backup jobs in | ||
| 915 | + any way. | ||
| 916 | + | ||
| 917 | +- The job(s) that succeeded will clear the dirty bitmap associated with | ||
| 918 | + the operation, but the job(s) that failed will not. It is not "safe" | ||
| 919 | + to delete any incremental backups that were created successfully in | ||
| 920 | + this scenario, even though others failed. | ||
| 921 | + | ||
| 922 | +Example | ||
| 923 | +^^^^^^^ | ||
| 924 | + | ||
| 925 | +- QMP example highlighting two backup jobs: | ||
| 926 | + | ||
| 927 | + .. code:: json | ||
| 928 | + | ||
| 929 | + { "execute": "transaction", | ||
| 930 | + "arguments": { | ||
| 931 | + "actions": [ | ||
| 932 | + { "type": "drive-backup", | ||
| 933 | + "data": { "device": "drive0", "bitmap": "bitmap0", | ||
| 934 | + "format": "qcow2", "mode": "existing", | ||
| 935 | + "sync": "incremental", "target": "d0-incr-1.qcow2" } }, | ||
| 936 | + { "type": "drive-backup", | ||
| 937 | + "data": { "device": "drive1", "bitmap": "bitmap1", | ||
| 938 | + "format": "qcow2", "mode": "existing", | ||
| 939 | + "sync": "incremental", "target": "d1-incr-1.qcow2" } }, | ||
| 940 | + ] | ||
| 941 | + } | ||
| 942 | + } | ||
| 943 | + | ||
| 944 | +- QMP example response, highlighting one success and one failure: | ||
| 945 | + | ||
| 946 | + - Acknowledgement that the Transaction was accepted and jobs were | ||
| 947 | + launched: | ||
| 948 | + | ||
| 949 | + .. code:: json | ||
| 950 | + | ||
| 951 | + { "return": {} } | ||
| 952 | + | ||
| 953 | + - Later, QEMU sends notice that the first job was completed: | ||
| 954 | + | ||
| 955 | + .. code:: json | ||
| 956 | + | ||
| 957 | + { "timestamp": { "seconds": 1447192343, "microseconds": 615698 }, | ||
| 958 | + "data": { "device": "drive0", "type": "backup", | ||
| 959 | + "speed": 0, "len": 67108864, "offset": 67108864 }, | ||
| 960 | + "event": "BLOCK_JOB_COMPLETED" | ||
| 961 | + } | ||
| 962 | + | ||
| 963 | + - Later yet, QEMU sends notice that the second job has failed: | ||
| 964 | + | ||
| 965 | + .. code:: json | ||
| 966 | + | ||
| 967 | + { "timestamp": { "seconds": 1447192399, "microseconds": 683015 }, | ||
| 968 | + "data": { "device": "drive1", "action": "report", | ||
| 969 | + "operation": "read" }, | ||
| 970 | + "event": "BLOCK_JOB_ERROR" } | ||
| 971 | + | ||
| 972 | + .. code:: json | ||
| 973 | + | ||
| 974 | + { "timestamp": { "seconds": 1447192399, "microseconds": | ||
| 975 | + 685853 }, "data": { "speed": 0, "offset": 0, "len": 67108864, | ||
| 976 | + "error": "Input/output error", "device": "drive1", "type": | ||
| 977 | + "backup" }, "event": "BLOCK_JOB_COMPLETED" } | ||
| 978 | + | ||
| 979 | +- In the above example, ``d0-incr-1.qcow2`` is valid and must be kept, | ||
| 980 | + but ``d1-incr-1.qcow2`` is invalid and should be deleted. If a VM-wide | ||
| 981 | + incremental backup of all drives at a point-in-time is to be made, | ||
| 982 | + new backups for both drives will need to be made, taking into account | ||
| 983 | + that a new incremental backup for drive0 needs to be based on top of | ||
| 984 | + ``d0-incr-1.qcow2``. | ||
| 985 | + | ||
| 986 | +Grouped Completion Mode | ||
| 987 | +~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 988 | + | ||
| 989 | +- While jobs launched by transactions normally complete or fail on | ||
| 990 | + their own, it is possible to instruct them to complete or fail | ||
| 991 | + together as a group. | ||
| 992 | + | ||
| 993 | +- QMP transactions take an optional properties structure that can | ||
| 994 | + affect the semantics of the transaction. | ||
| 995 | + | ||
| 996 | +- The "completion-mode" transaction property can be either "individual" | ||
| 997 | + which is the default, legacy behavior described above, or "grouped," | ||
| 998 | + a new behavior detailed below. | ||
| 999 | + | ||
| 1000 | +- Delayed Completion: In grouped completion mode, no jobs will report | ||
| 1001 | + success until all jobs are ready to report success. | ||
| 1002 | + | ||
| 1003 | +- Grouped failure: If any job fails in grouped completion mode, all | ||
| 1004 | + remaining jobs will be cancelled. Any incremental backups will | ||
| 1005 | + restore their dirty bitmap objects as if no backup command was ever | ||
| 1006 | + issued. | ||
| 1007 | + | ||
| 1008 | + - Regardless of if QEMU reports a particular incremental backup job | ||
| 1009 | + as CANCELLED or as an ERROR, the in-memory bitmap will be | ||
| 1010 | + restored. | ||
| 1011 | + | ||
| 1012 | +Example | ||
| 1013 | +^^^^^^^ | ||
| 1014 | + | ||
| 1015 | +- Here's the same example scenario from above with the new property: | ||
| 1016 | + | ||
| 1017 | + .. code:: json | ||
| 1018 | + | ||
| 1019 | + { "execute": "transaction", | ||
| 1020 | + "arguments": { | ||
| 1021 | + "actions": [ | ||
| 1022 | + { "type": "drive-backup", | ||
| 1023 | + "data": { "device": "drive0", "bitmap": "bitmap0", | ||
| 1024 | + "format": "qcow2", "mode": "existing", | ||
| 1025 | + "sync": "incremental", "target": "d0-incr-1.qcow2" } }, | ||
| 1026 | + { "type": "drive-backup", | ||
| 1027 | + "data": { "device": "drive1", "bitmap": "bitmap1", | ||
| 1028 | + "format": "qcow2", "mode": "existing", | ||
| 1029 | + "sync": "incremental", "target": "d1-incr-1.qcow2" } }, | ||
| 1030 | + ], | ||
| 1031 | + "properties": { | ||
| 1032 | + "completion-mode": "grouped" | ||
| 1033 | + } | ||
| 1034 | + } | ||
| 1035 | + } | ||
| 1036 | + | ||
| 1037 | +- QMP example response, highlighting a failure for ``drive2``: | ||
| 1038 | + | ||
| 1039 | + - Acknowledgement that the Transaction was accepted and jobs were | ||
| 1040 | + launched: | ||
| 1041 | + | ||
| 1042 | + .. code:: json | ||
| 1043 | + | ||
| 1044 | + { "return": {} } | ||
| 1045 | + | ||
| 1046 | + - Later, QEMU sends notice that the second job has errored out, but | ||
| 1047 | + that the first job was also cancelled: | ||
| 1048 | + | ||
| 1049 | + .. code:: json | ||
| 1050 | + | ||
| 1051 | + { "timestamp": { "seconds": 1447193702, "microseconds": 632377 }, | ||
| 1052 | + "data": { "device": "drive1", "action": "report", | ||
| 1053 | + "operation": "read" }, | ||
| 1054 | + "event": "BLOCK_JOB_ERROR" } | ||
| 1055 | + | ||
| 1056 | + .. code:: json | ||
| 1057 | + | ||
| 1058 | + { "timestamp": { "seconds": 1447193702, "microseconds": 640074 }, | ||
| 1059 | + "data": { "speed": 0, "offset": 0, "len": 67108864, | ||
| 1060 | + "error": "Input/output error", | ||
| 1061 | + "device": "drive1", "type": "backup" }, | ||
| 1062 | + "event": "BLOCK_JOB_COMPLETED" } | ||
| 1063 | + | ||
| 1064 | + .. code:: json | ||
| 1065 | + | ||
| 1066 | + { "timestamp": { "seconds": 1447193702, "microseconds": 640163 }, | ||
| 1067 | + "data": { "device": "drive0", "type": "backup", "speed": 0, | ||
| 1068 | + "len": 67108864, "offset": 16777216 }, | ||
| 1069 | + "event": "BLOCK_JOB_CANCELLED" } | ||
| 1070 | + | ||
| 1071 | +.. raw:: html | ||
| 1072 | + | ||
| 1073 | + <!-- | ||
| 1074 | + The FreeBSD Documentation License | ||
| 1075 | + | ||
| 1076 | + Redistribution and use in source (Markdown) and 'compiled' forms (SGML, HTML, | ||
| 1077 | + PDF, PostScript, RTF and so forth) with or without modification, are permitted | ||
| 1078 | + provided that the following conditions are met: | ||
| 1079 | + | ||
| 1080 | + Redistributions of source code (Markdown) must retain the above copyright | ||
| 1081 | + notice, this list of conditions and the following disclaimer of this file | ||
| 1082 | + unmodified. | ||
| 1083 | + | ||
| 1084 | + Redistributions in compiled form (transformed to other DTDs, converted to PDF, | ||
| 1085 | + PostScript, RTF and other formats) must reproduce the above copyright notice, | ||
| 1086 | + this list of conditions and the following disclaimer in the documentation and/or | ||
| 1087 | + other materials provided with the distribution. | ||
| 1088 | + | ||
| 1089 | + THIS DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" | ||
| 1090 | + AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||
| 1091 | + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE | ||
| 1092 | + DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE | ||
| 1093 | + FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | ||
| 1094 | + DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR | ||
| 1095 | + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER | ||
| 1096 | + CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, | ||
| 1097 | + OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF | ||
| 1098 | + THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||
| 1099 | + --> | ||
| 1100 | -- | ||
| 1101 | 2.9.4 | ||
| 1102 | |||
| 1103 | diff view generated by jsdifflib |
| 1 | From: Kashyap Chamarthy <kchamart@redhat.com> | 1 | From: Denis Rastyogin <gerben@altlinux.org> |
|---|---|---|---|
| 2 | 2 | ||
| 3 | This patch documents (including their QMP invocations) all the four | 3 | This error was discovered by fuzzing qemu-img. |
| 4 | major kinds of live block operations: | ||
| 5 | 4 | ||
| 6 | - `block-stream` | 5 | When ph.ext_off has a sufficiently large value, the operation |
| 7 | - `block-commit` | 6 | le64_to_cpu(ph.ext_off) << BDRV_SECTOR_BITS in |
| 8 | - `drive-mirror` (& `blockdev-mirror`) | 7 | parallels_read_format_extension() can cause an overflow in int64_t. |
| 9 | - `drive-backup` (& `blockdev-backup`) | 8 | This overflow triggers the assert(ext_off > 0) |
| 9 | check in block/parallels-ext.c: parallels_read_format_extension(), | ||
| 10 | leading to a crash. | ||
| 10 | 11 | ||
| 11 | Things considered while writing this document: | 12 | This commit adds a check to prevent overflow when shifting ph.ext_off |
| 13 | by BDRV_SECTOR_BITS, ensuring that the value remains within a valid range. | ||
| 12 | 14 | ||
| 13 | - Use reStructuredText as markup language (with the goal of generating | 15 | Reported-by: Leonid Reviakin <L.reviakin@fobos-nt.ru> |
| 14 | the HTML output using the Sphinx Documentation Generator). It is | 16 | Signed-off-by: Denis Rastyogin <gerben@altlinux.org> |
| 15 | gentler on the eye, and can be trivially converted to different | 17 | Reviewed-by: Denis V. Lunev <den@openvz.org> |
| 16 | formats. (Another reason: upstream QEMU is considering to switch to | 18 | Message-ID: <20241212104212.513947-2-gerben@altlinux.org> |
| 17 | Sphinx, which uses reStructuredText as its markup language.) | 19 | Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> |
| 20 | --- | ||
| 21 | block/parallels.c | 4 ++++ | ||
| 22 | 1 file changed, 4 insertions(+) | ||
| 18 | 23 | ||
| 19 | - Raw QMP JSON output vs. 'qmp-shell'. I debated with myself whether | 24 | diff --git a/block/parallels.c b/block/parallels.c |
| 20 | to only show raw QMP JSON output (as that is the canonical | 25 | index XXXXXXX..XXXXXXX 100644 |
| 21 | representation), or use 'qmp-shell', which takes key-value pairs. I | 26 | --- a/block/parallels.c |
| 22 | settled on the approach of: for the first occurrence of a command, | 27 | +++ b/block/parallels.c |
| 23 | use raw JSON; for subsequent occurrences, use 'qmp-shell', with an | 28 | @@ -XXX,XX +XXX,XX @@ static int parallels_open(BlockDriverState *bs, QDict *options, int flags, |
| 24 | occasional exception. | 29 | error_setg(errp, "Catalog too large"); |
| 25 | 30 | return -EFBIG; | |
| 26 | - Usage of `-blockdev` command-line. | 31 | } |
| 27 | 32 | + if (le64_to_cpu(ph.ext_off) >= (INT64_MAX >> BDRV_SECTOR_BITS)) { | |
| 28 | - Usage of 'node-name' vs. file path to refer to disks. While we have | 33 | + error_setg(errp, "Invalid image: Too big offset"); |
| 29 | `blockdev-{mirror, backup}` as 'node-name'-alternatives for | 34 | + return -EFBIG; |
| 30 | `drive-{mirror, backup}`, the `block-commit` command still operates | ||
| 31 | on file names for parameters 'base' and 'top'. So I added a caveat | ||
| 32 | at the beginning to that effect. | ||
| 33 | |||
| 34 | Refer this related thread that I started (where I learnt | ||
| 35 | `block-stream` was recently reworked to accept 'node-name' for 'top' | ||
| 36 | and 'base' parameters): | ||
| 37 | https://lists.nongnu.org/archive/html/qemu-devel/2017-05/msg06466.html | ||
| 38 | "[RFC] Making 'block-stream', and 'block-commit' accept node-name" | ||
| 39 | |||
| 40 | All commands showed in this document were tested while documenting. | ||
| 41 | |||
| 42 | Thanks: Eric Blake for the section: "A note on points-in-time vs file | ||
| 43 | names". This useful bit was originally articulated by Eric in his | ||
| 44 | KVMForum 2015 presentation, so I included that specific bit in this | ||
| 45 | document. | ||
| 46 | |||
| 47 | Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com> | ||
| 48 | Reviewed-by: Eric Blake <eblake@redhat.com> | ||
| 49 | Message-id: 20170717105205.32639-3-kchamart@redhat.com | ||
| 50 | Signed-off-by: Jeff Cody <jcody@redhat.com> | ||
| 51 | --- | ||
| 52 | docs/interop/live-block-operations.rst | 1088 ++++++++++++++++++++++++++++++++ | ||
| 53 | docs/live-block-ops.txt | 72 --- | ||
| 54 | 2 files changed, 1088 insertions(+), 72 deletions(-) | ||
| 55 | create mode 100644 docs/interop/live-block-operations.rst | ||
| 56 | delete mode 100644 docs/live-block-ops.txt | ||
| 57 | |||
| 58 | diff --git a/docs/interop/live-block-operations.rst b/docs/interop/live-block-operations.rst | ||
| 59 | new file mode 100644 | ||
| 60 | index XXXXXXX..XXXXXXX | ||
| 61 | --- /dev/null | ||
| 62 | +++ b/docs/interop/live-block-operations.rst | ||
| 63 | @@ -XXX,XX +XXX,XX @@ | ||
| 64 | +.. | ||
| 65 | + Copyright (C) 2017 Red Hat Inc. | ||
| 66 | + | ||
| 67 | + This work is licensed under the terms of the GNU GPL, version 2 or | ||
| 68 | + later. See the COPYING file in the top-level directory. | ||
| 69 | + | ||
| 70 | +============================ | ||
| 71 | +Live Block Device Operations | ||
| 72 | +============================ | ||
| 73 | + | ||
| 74 | +QEMU Block Layer currently (as of QEMU 2.9) supports four major kinds of | ||
| 75 | +live block device jobs -- stream, commit, mirror, and backup. These can | ||
| 76 | +be used to manipulate disk image chains to accomplish certain tasks, | ||
| 77 | +namely: live copy data from backing files into overlays; shorten long | ||
| 78 | +disk image chains by merging data from overlays into backing files; live | ||
| 79 | +synchronize data from a disk image chain (including current active disk) | ||
| 80 | +to another target image; and point-in-time (and incremental) backups of | ||
| 81 | +a block device. Below is a description of the said block (QMP) | ||
| 82 | +primitives, and some (non-exhaustive list of) examples to illustrate | ||
| 83 | +their use. | ||
| 84 | + | ||
| 85 | +.. note:: | ||
| 86 | + The file ``qapi/block-core.json`` in the QEMU source tree has the | ||
| 87 | + canonical QEMU API (QAPI) schema documentation for the QMP | ||
| 88 | + primitives discussed here. | ||
| 89 | + | ||
| 90 | +.. todo (kashyapc):: Remove the ".. contents::" directive when Sphinx is | ||
| 91 | + integrated. | ||
| 92 | + | ||
| 93 | +.. contents:: | ||
| 94 | + | ||
| 95 | +Disk image backing chain notation | ||
| 96 | +--------------------------------- | ||
| 97 | + | ||
| 98 | +A simple disk image chain. (This can be created live using QMP | ||
| 99 | +``blockdev-snapshot-sync``, or offline via ``qemu-img``):: | ||
| 100 | + | ||
| 101 | + (Live QEMU) | ||
| 102 | + | | ||
| 103 | + . | ||
| 104 | + V | ||
| 105 | + | ||
| 106 | + [A] <----- [B] | ||
| 107 | + | ||
| 108 | + (backing file) (overlay) | ||
| 109 | + | ||
| 110 | +The arrow can be read as: Image [A] is the backing file of disk image | ||
| 111 | +[B]. And live QEMU is currently writing to image [B], consequently, it | ||
| 112 | +is also referred to as the "active layer". | ||
| 113 | + | ||
| 114 | +There are two kinds of terminology that are common when referring to | ||
| 115 | +files in a disk image backing chain: | ||
| 116 | + | ||
| 117 | +(1) Directional: 'base' and 'top'. Given the simple disk image chain | ||
| 118 | + above, image [A] can be referred to as 'base', and image [B] as | ||
| 119 | + 'top'. (This terminology can be seen in in QAPI schema file, | ||
| 120 | + block-core.json.) | ||
| 121 | + | ||
| 122 | +(2) Relational: 'backing file' and 'overlay'. Again, taking the same | ||
| 123 | + simple disk image chain from the above, disk image [A] is referred | ||
| 124 | + to as the backing file, and image [B] as overlay. | ||
| 125 | + | ||
| 126 | + Throughout this document, we will use the relational terminology. | ||
| 127 | + | ||
| 128 | +.. important:: | ||
| 129 | + The overlay files can generally be any format that supports a | ||
| 130 | + backing file, although QCOW2 is the preferred format and the one | ||
| 131 | + used in this document. | ||
| 132 | + | ||
| 133 | + | ||
| 134 | +Brief overview of live block QMP primitives | ||
| 135 | +------------------------------------------- | ||
| 136 | + | ||
| 137 | +The following are the four different kinds of live block operations that | ||
| 138 | +QEMU block layer supports. | ||
| 139 | + | ||
| 140 | +(1) ``block-stream``: Live copy of data from backing files into overlay | ||
| 141 | + files. | ||
| 142 | + | ||
| 143 | + .. note:: Once the 'stream' operation has finished, three things to | ||
| 144 | + note: | ||
| 145 | + | ||
| 146 | + (a) QEMU rewrites the backing chain to remove | ||
| 147 | + reference to the now-streamed and redundant backing | ||
| 148 | + file; | ||
| 149 | + | ||
| 150 | + (b) the streamed file *itself* won't be removed by QEMU, | ||
| 151 | + and must be explicitly discarded by the user; | ||
| 152 | + | ||
| 153 | + (c) the streamed file remains valid -- i.e. further | ||
| 154 | + overlays can be created based on it. Refer the | ||
| 155 | + ``block-stream`` section further below for more | ||
| 156 | + details. | ||
| 157 | + | ||
| 158 | +(2) ``block-commit``: Live merge of data from overlay files into backing | ||
| 159 | + files (with the optional goal of removing the overlay file from the | ||
| 160 | + chain). Since QEMU 2.0, this includes "active ``block-commit``" | ||
| 161 | + (i.e. merge the current active layer into the base image). | ||
| 162 | + | ||
| 163 | + .. note:: Once the 'commit' operation has finished, there are three | ||
| 164 | + things to note here as well: | ||
| 165 | + | ||
| 166 | + (a) QEMU rewrites the backing chain to remove reference | ||
| 167 | + to now-redundant overlay images that have been | ||
| 168 | + committed into a backing file; | ||
| 169 | + | ||
| 170 | + (b) the committed file *itself* won't be removed by QEMU | ||
| 171 | + -- it ought to be manually removed; | ||
| 172 | + | ||
| 173 | + (c) however, unlike in the case of ``block-stream``, the | ||
| 174 | + intermediate images will be rendered invalid -- i.e. | ||
| 175 | + no more further overlays can be created based on | ||
| 176 | + them. Refer the ``block-commit`` section further | ||
| 177 | + below for more details. | ||
| 178 | + | ||
| 179 | +(3) ``drive-mirror`` (and ``blockdev-mirror``): Synchronize a running | ||
| 180 | + disk to another image. | ||
| 181 | + | ||
| 182 | +(4) ``drive-backup`` (and ``blockdev-backup``): Point-in-time (live) copy | ||
| 183 | + of a block device to a destination. | ||
| 184 | + | ||
| 185 | + | ||
| 186 | +.. _`Interacting with a QEMU instance`: | ||
| 187 | + | ||
| 188 | +Interacting with a QEMU instance | ||
| 189 | +-------------------------------- | ||
| 190 | + | ||
| 191 | +To show some example invocations of command-line, we will use the | ||
| 192 | +following invocation of QEMU, with a QMP server running over UNIX | ||
| 193 | +socket:: | ||
| 194 | + | ||
| 195 | + $ ./x86_64-softmmu/qemu-system-x86_64 -display none -nodefconfig \ | ||
| 196 | + -M q35 -nodefaults -m 512 \ | ||
| 197 | + -blockdev node-name=node-A,driver=qcow2,file.driver=file,file.node-name=file,file.filename=./a.qcow2 \ | ||
| 198 | + -device virtio-blk,drive=node-A,id=virtio0 \ | ||
| 199 | + -monitor stdio -qmp unix:/tmp/qmp-sock,server,nowait | ||
| 200 | + | ||
| 201 | +The ``-blockdev`` command-line option, used above, is available from | ||
| 202 | +QEMU 2.9 onwards. In the above invocation, notice the ``node-name`` | ||
| 203 | +parameter that is used to refer to the disk image a.qcow2 ('node-A') -- | ||
| 204 | +this is a cleaner way to refer to a disk image (as opposed to referring | ||
| 205 | +to it by spelling out file paths). So, we will continue to designate a | ||
| 206 | +``node-name`` to each further disk image created (either via | ||
| 207 | +``blockdev-snapshot-sync``, or ``blockdev-add``) as part of the disk | ||
| 208 | +image chain, and continue to refer to the disks using their | ||
| 209 | +``node-name`` (where possible, because ``block-commit`` does not yet, as | ||
| 210 | +of QEMU 2.9, accept ``node-name`` parameter) when performing various | ||
| 211 | +block operations. | ||
| 212 | + | ||
| 213 | +To interact with the QEMU instance launched above, we will use the | ||
| 214 | +``qmp-shell`` utility (located at: ``qemu/scripts/qmp``, as part of the | ||
| 215 | +QEMU source directory), which takes key-value pairs for QMP commands. | ||
| 216 | +Invoke it as below (which will also print out the complete raw JSON | ||
| 217 | +syntax for reference -- examples in the following sections):: | ||
| 218 | + | ||
| 219 | + $ ./qmp-shell -v -p /tmp/qmp-sock | ||
| 220 | + (QEMU) | ||
| 221 | + | ||
| 222 | +.. note:: | ||
| 223 | + In the event we have to repeat a certain QMP command, we will: for | ||
| 224 | + the first occurrence of it, show the ``qmp-shell`` invocation, *and* | ||
| 225 | + the corresponding raw JSON QMP syntax; but for subsequent | ||
| 226 | + invocations, present just the ``qmp-shell`` syntax, and omit the | ||
| 227 | + equivalent JSON output. | ||
| 228 | + | ||
| 229 | + | ||
| 230 | +Example disk image chain | ||
| 231 | +------------------------ | ||
| 232 | + | ||
| 233 | +We will use the below disk image chain (and occasionally spelling it | ||
| 234 | +out where appropriate) when discussing various primitives:: | ||
| 235 | + | ||
| 236 | + [A] <-- [B] <-- [C] <-- [D] | ||
| 237 | + | ||
| 238 | +Where [A] is the original base image; [B] and [C] are intermediate | ||
| 239 | +overlay images; image [D] is the active layer -- i.e. live QEMU is | ||
| 240 | +writing to it. (The rule of thumb is: live QEMU will always be pointing | ||
| 241 | +to the rightmost image in a disk image chain.) | ||
| 242 | + | ||
| 243 | +The above image chain can be created by invoking | ||
| 244 | +``blockdev-snapshot-sync`` commands as following (which shows the | ||
| 245 | +creation of overlay image [B]) using the ``qmp-shell`` (our invocation | ||
| 246 | +also prints the raw JSON invocation of it):: | ||
| 247 | + | ||
| 248 | + (QEMU) blockdev-snapshot-sync node-name=node-A snapshot-file=b.qcow2 snapshot-node-name=node-B format=qcow2 | ||
| 249 | + { | ||
| 250 | + "execute": "blockdev-snapshot-sync", | ||
| 251 | + "arguments": { | ||
| 252 | + "node-name": "node-A", | ||
| 253 | + "snapshot-file": "b.qcow2", | ||
| 254 | + "format": "qcow2", | ||
| 255 | + "snapshot-node-name": "node-B" | ||
| 256 | + } | ||
| 257 | + } | 35 | + } |
| 258 | + | 36 | |
| 259 | +Here, "node-A" is the name QEMU internally uses to refer to the base | 37 | size = bat_entry_off(s->bat_size); |
| 260 | +image [A] -- it is the backing file, based on which the overlay image, | 38 | s->header_size = ROUND_UP(size, bdrv_opt_mem_align(bs->file->bs)); |
| 261 | +[B], is created. | ||
| 262 | + | ||
| 263 | +To create the rest of the overlay images, [C], and [D] (omitting the raw | ||
| 264 | +JSON output for brevity):: | ||
| 265 | + | ||
| 266 | + (QEMU) blockdev-snapshot-sync node-name=node-B snapshot-file=c.qcow2 snapshot-node-name=node-C format=qcow2 | ||
| 267 | + (QEMU) blockdev-snapshot-sync node-name=node-C snapshot-file=d.qcow2 snapshot-node-name=node-D format=qcow2 | ||
| 268 | + | ||
| 269 | + | ||
| 270 | +A note on points-in-time vs file names | ||
| 271 | +-------------------------------------- | ||
| 272 | + | ||
| 273 | +In our disk image chain:: | ||
| 274 | + | ||
| 275 | + [A] <-- [B] <-- [C] <-- [D] | ||
| 276 | + | ||
| 277 | +We have *three* points in time and an active layer: | ||
| 278 | + | ||
| 279 | +- Point 1: Guest state when [B] was created is contained in file [A] | ||
| 280 | +- Point 2: Guest state when [C] was created is contained in [A] + [B] | ||
| 281 | +- Point 3: Guest state when [D] was created is contained in | ||
| 282 | + [A] + [B] + [C] | ||
| 283 | +- Active layer: Current guest state is contained in [A] + [B] + [C] + | ||
| 284 | + [D] | ||
| 285 | + | ||
| 286 | +Therefore, be aware with naming choices: | ||
| 287 | + | ||
| 288 | +- Naming a file after the time it is created is misleading -- the | ||
| 289 | + guest data for that point in time is *not* contained in that file | ||
| 290 | + (as explained earlier) | ||
| 291 | +- Rather, think of files as a *delta* from the backing file | ||
| 292 | + | ||
| 293 | + | ||
| 294 | +Live block streaming --- ``block-stream`` | ||
| 295 | +----------------------------------------- | ||
| 296 | + | ||
| 297 | +The ``block-stream`` command allows you to do live copy data from backing | ||
| 298 | +files into overlay images. | ||
| 299 | + | ||
| 300 | +Given our original example disk image chain from earlier:: | ||
| 301 | + | ||
| 302 | + [A] <-- [B] <-- [C] <-- [D] | ||
| 303 | + | ||
| 304 | +The disk image chain can be shortened in one of the following different | ||
| 305 | +ways (not an exhaustive list). | ||
| 306 | + | ||
| 307 | +.. _`Case-1`: | ||
| 308 | + | ||
| 309 | +(1) Merge everything into the active layer: I.e. copy all contents from | ||
| 310 | + the base image, [A], and overlay images, [B] and [C], into [D], | ||
| 311 | + *while* the guest is running. The resulting chain will be a | ||
| 312 | + standalone image, [D] -- with contents from [A], [B] and [C] merged | ||
| 313 | + into it (where live QEMU writes go to):: | ||
| 314 | + | ||
| 315 | + [D] | ||
| 316 | + | ||
| 317 | +.. _`Case-2`: | ||
| 318 | + | ||
| 319 | +(2) Taking the same example disk image chain mentioned earlier, merge | ||
| 320 | + only images [B] and [C] into [D], the active layer. The result will | ||
| 321 | + be contents of images [B] and [C] will be copied into [D], and the | ||
| 322 | + backing file pointer of image [D] will be adjusted to point to image | ||
| 323 | + [A]. The resulting chain will be:: | ||
| 324 | + | ||
| 325 | + [A] <-- [D] | ||
| 326 | + | ||
| 327 | +.. _`Case-3`: | ||
| 328 | + | ||
| 329 | +(3) Intermediate streaming (available since QEMU 2.8): Starting afresh | ||
| 330 | + with the original example disk image chain, with a total of four | ||
| 331 | + images, it is possible to copy contents from image [B] into image | ||
| 332 | + [C]. Once the copy is finished, image [B] can now be (optionally) | ||
| 333 | + discarded; and the backing file pointer of image [C] will be | ||
| 334 | + adjusted to point to [A]. I.e. after performing "intermediate | ||
| 335 | + streaming" of [B] into [C], the resulting image chain will be (where | ||
| 336 | + live QEMU is writing to [D]):: | ||
| 337 | + | ||
| 338 | + [A] <-- [C] <-- [D] | ||
| 339 | + | ||
| 340 | + | ||
| 341 | +QMP invocation for ``block-stream`` | ||
| 342 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 343 | + | ||
| 344 | +For `Case-1`_, to merge contents of all the backing files into the | ||
| 345 | +active layer, where 'node-D' is the current active image (by default | ||
| 346 | +``block-stream`` will flatten the entire chain); ``qmp-shell`` (and its | ||
| 347 | +corresponding JSON output):: | ||
| 348 | + | ||
| 349 | + (QEMU) block-stream device=node-D job-id=job0 | ||
| 350 | + { | ||
| 351 | + "execute": "block-stream", | ||
| 352 | + "arguments": { | ||
| 353 | + "device": "node-D", | ||
| 354 | + "job-id": "job0" | ||
| 355 | + } | ||
| 356 | + } | ||
| 357 | + | ||
| 358 | +For `Case-2`_, merge contents of the images [B] and [C] into [D], where | ||
| 359 | +image [D] ends up referring to image [A] as its backing file:: | ||
| 360 | + | ||
| 361 | + (QEMU) block-stream device=node-D base-node=node-A job-id=job0 | ||
| 362 | + | ||
| 363 | +And for `Case-3`_, of "intermediate" streaming", merge contents of | ||
| 364 | +images [B] into [C], where [C] ends up referring to [A] as its backing | ||
| 365 | +image:: | ||
| 366 | + | ||
| 367 | + (QEMU) block-stream device=node-C base-node=node-A job-id=job0 | ||
| 368 | + | ||
| 369 | +Progress of a ``block-stream`` operation can be monitored via the QMP | ||
| 370 | +command:: | ||
| 371 | + | ||
| 372 | + (QEMU) query-block-jobs | ||
| 373 | + { | ||
| 374 | + "execute": "query-block-jobs", | ||
| 375 | + "arguments": {} | ||
| 376 | + } | ||
| 377 | + | ||
| 378 | + | ||
| 379 | +Once the ``block-stream`` operation has completed, QEMU will emit an | ||
| 380 | +event, ``BLOCK_JOB_COMPLETED``. The intermediate overlays remain valid, | ||
| 381 | +and can now be (optionally) discarded, or retained to create further | ||
| 382 | +overlays based on them. Finally, the ``block-stream`` jobs can be | ||
| 383 | +restarted at anytime. | ||
| 384 | + | ||
| 385 | + | ||
| 386 | +Live block commit --- ``block-commit`` | ||
| 387 | +-------------------------------------- | ||
| 388 | + | ||
| 389 | +The ``block-commit`` command lets you merge live data from overlay | ||
| 390 | +images into backing file(s). Since QEMU 2.0, this includes "live active | ||
| 391 | +commit" (i.e. it is possible to merge the "active layer", the right-most | ||
| 392 | +image in a disk image chain where live QEMU will be writing to, into the | ||
| 393 | +base image). This is analogous to ``block-stream``, but in the opposite | ||
| 394 | +direction. | ||
| 395 | + | ||
| 396 | +Again, starting afresh with our example disk image chain, where live | ||
| 397 | +QEMU is writing to the right-most image in the chain, [D]:: | ||
| 398 | + | ||
| 399 | + [A] <-- [B] <-- [C] <-- [D] | ||
| 400 | + | ||
| 401 | +The disk image chain can be shortened in one of the following ways: | ||
| 402 | + | ||
| 403 | +.. _`block-commit_Case-1`: | ||
| 404 | + | ||
| 405 | +(1) Commit content from only image [B] into image [A]. The resulting | ||
| 406 | + chain is the following, where image [C] is adjusted to point at [A] | ||
| 407 | + as its new backing file:: | ||
| 408 | + | ||
| 409 | + [A] <-- [C] <-- [D] | ||
| 410 | + | ||
| 411 | +(2) Commit content from images [B] and [C] into image [A]. The | ||
| 412 | + resulting chain, where image [D] is adjusted to point to image [A] | ||
| 413 | + as its new backing file:: | ||
| 414 | + | ||
| 415 | + [A] <-- [D] | ||
| 416 | + | ||
| 417 | +.. _`block-commit_Case-3`: | ||
| 418 | + | ||
| 419 | +(3) Commit content from images [B], [C], and the active layer [D] into | ||
| 420 | + image [A]. The resulting chain (in this case, a consolidated single | ||
| 421 | + image):: | ||
| 422 | + | ||
| 423 | + [A] | ||
| 424 | + | ||
| 425 | +(4) Commit content from image only image [C] into image [B]. The | ||
| 426 | + resulting chain:: | ||
| 427 | + | ||
| 428 | + [A] <-- [B] <-- [D] | ||
| 429 | + | ||
| 430 | +(5) Commit content from image [C] and the active layer [D] into image | ||
| 431 | + [B]. The resulting chain:: | ||
| 432 | + | ||
| 433 | + [A] <-- [B] | ||
| 434 | + | ||
| 435 | + | ||
| 436 | +QMP invocation for ``block-commit`` | ||
| 437 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 438 | + | ||
| 439 | +For :ref:`Case-1 <block-commit_Case-1>`, to merge contents only from | ||
| 440 | +image [B] into image [A], the invocation is as follows:: | ||
| 441 | + | ||
| 442 | + (QEMU) block-commit device=node-D base=a.qcow2 top=b.qcow2 job-id=job0 | ||
| 443 | + { | ||
| 444 | + "execute": "block-commit", | ||
| 445 | + "arguments": { | ||
| 446 | + "device": "node-D", | ||
| 447 | + "job-id": "job0", | ||
| 448 | + "top": "b.qcow2", | ||
| 449 | + "base": "a.qcow2" | ||
| 450 | + } | ||
| 451 | + } | ||
| 452 | + | ||
| 453 | +Once the above ``block-commit`` operation has completed, a | ||
| 454 | +``BLOCK_JOB_COMPLETED`` event will be issued, and no further action is | ||
| 455 | +required. As the end result, the backing file of image [C] is adjusted | ||
| 456 | +to point to image [A], and the original 4-image chain will end up being | ||
| 457 | +transformed to:: | ||
| 458 | + | ||
| 459 | + [A] <-- [C] <-- [D] | ||
| 460 | + | ||
| 461 | +.. note:: | ||
| 462 | + The intermediate image [B] is invalid (as in: no more further | ||
| 463 | + overlays based on it can be created). | ||
| 464 | + | ||
| 465 | + Reasoning: An intermediate image after a 'stream' operation still | ||
| 466 | + represents that old point-in-time, and may be valid in that context. | ||
| 467 | + However, an intermediate image after a 'commit' operation no longer | ||
| 468 | + represents any point-in-time, and is invalid in any context. | ||
| 469 | + | ||
| 470 | + | ||
| 471 | +However, :ref:`Case-3 <block-commit_Case-3>` (also called: "active | ||
| 472 | +``block-commit``") is a *two-phase* operation: In the first phase, the | ||
| 473 | +content from the active overlay, along with the intermediate overlays, | ||
| 474 | +is copied into the backing file (also called the base image). In the | ||
| 475 | +second phase, adjust the said backing file as the current active image | ||
| 476 | +-- possible via issuing the command ``block-job-complete``. Optionally, | ||
| 477 | +the ``block-commit`` operation can be cancelled by issuing the command | ||
| 478 | +``block-job-cancel``, but be careful when doing this. | ||
| 479 | + | ||
| 480 | +Once the ``block-commit`` operation has completed, the event | ||
| 481 | +``BLOCK_JOB_READY`` will be emitted, signalling that the synchronization | ||
| 482 | +has finished. Now the job can be gracefully completed by issuing the | ||
| 483 | +command ``block-job-complete`` -- until such a command is issued, the | ||
| 484 | +'commit' operation remains active. | ||
| 485 | + | ||
| 486 | +The following is the flow for :ref:`Case-3 <block-commit_Case-3>` to | ||
| 487 | +convert a disk image chain such as this:: | ||
| 488 | + | ||
| 489 | + [A] <-- [B] <-- [C] <-- [D] | ||
| 490 | + | ||
| 491 | +Into:: | ||
| 492 | + | ||
| 493 | + [A] | ||
| 494 | + | ||
| 495 | +Where content from all the subsequent overlays, [B], and [C], including | ||
| 496 | +the active layer, [D], is committed back to [A] -- which is where live | ||
| 497 | +QEMU is performing all its current writes). | ||
| 498 | + | ||
| 499 | +Start the "active ``block-commit``" operation:: | ||
| 500 | + | ||
| 501 | + (QEMU) block-commit device=node-D base=a.qcow2 top=d.qcow2 job-id=job0 | ||
| 502 | + { | ||
| 503 | + "execute": "block-commit", | ||
| 504 | + "arguments": { | ||
| 505 | + "device": "node-D", | ||
| 506 | + "job-id": "job0", | ||
| 507 | + "top": "d.qcow2", | ||
| 508 | + "base": "a.qcow2" | ||
| 509 | + } | ||
| 510 | + } | ||
| 511 | + | ||
| 512 | + | ||
| 513 | +Once the synchronization has completed, the event ``BLOCK_JOB_READY`` will | ||
| 514 | +be emitted. | ||
| 515 | + | ||
| 516 | +Then, optionally query for the status of the active block operations. | ||
| 517 | +We can see the 'commit' job is now ready to be completed, as indicated | ||
| 518 | +by the line *"ready": true*:: | ||
| 519 | + | ||
| 520 | + (QEMU) query-block-jobs | ||
| 521 | + { | ||
| 522 | + "execute": "query-block-jobs", | ||
| 523 | + "arguments": {} | ||
| 524 | + } | ||
| 525 | + { | ||
| 526 | + "return": [ | ||
| 527 | + { | ||
| 528 | + "busy": false, | ||
| 529 | + "type": "commit", | ||
| 530 | + "len": 1376256, | ||
| 531 | + "paused": false, | ||
| 532 | + "ready": true, | ||
| 533 | + "io-status": "ok", | ||
| 534 | + "offset": 1376256, | ||
| 535 | + "device": "job0", | ||
| 536 | + "speed": 0 | ||
| 537 | + } | ||
| 538 | + ] | ||
| 539 | + } | ||
| 540 | + | ||
| 541 | +Gracefully complete the 'commit' block device job:: | ||
| 542 | + | ||
| 543 | + (QEMU) block-job-complete device=job0 | ||
| 544 | + { | ||
| 545 | + "execute": "block-job-complete", | ||
| 546 | + "arguments": { | ||
| 547 | + "device": "job0" | ||
| 548 | + } | ||
| 549 | + } | ||
| 550 | + { | ||
| 551 | + "return": {} | ||
| 552 | + } | ||
| 553 | + | ||
| 554 | +Finally, once the above job is completed, an event | ||
| 555 | +``BLOCK_JOB_COMPLETED`` will be emitted. | ||
| 556 | + | ||
| 557 | +.. note:: | ||
| 558 | + The invocation for rest of the cases (2, 4, and 5), discussed in the | ||
| 559 | + previous section, is omitted for brevity. | ||
| 560 | + | ||
| 561 | + | ||
| 562 | +Live disk synchronization --- ``drive-mirror`` and ``blockdev-mirror`` | ||
| 563 | +---------------------------------------------------------------------- | ||
| 564 | + | ||
| 565 | +Synchronize a running disk image chain (all or part of it) to a target | ||
| 566 | +image. | ||
| 567 | + | ||
| 568 | +Again, given our familiar disk image chain:: | ||
| 569 | + | ||
| 570 | + [A] <-- [B] <-- [C] <-- [D] | ||
| 571 | + | ||
| 572 | +The ``drive-mirror`` (and its newer equivalent ``blockdev-mirror``) allows | ||
| 573 | +you to copy data from the entire chain into a single target image (which | ||
| 574 | +can be located on a different host). | ||
| 575 | + | ||
| 576 | +Once a 'mirror' job has started, there are two possible actions while a | ||
| 577 | +``drive-mirror`` job is active: | ||
| 578 | + | ||
| 579 | +(1) Issuing the command ``block-job-cancel`` after it emits the event | ||
| 580 | + ``BLOCK_JOB_CANCELLED``: will (after completing synchronization of | ||
| 581 | + the content from the disk image chain to the target image, [E]) | ||
| 582 | + create a point-in-time (which is at the time of *triggering* the | ||
| 583 | + cancel command) copy, contained in image [E], of the the entire disk | ||
| 584 | + image chain (or only the top-most image, depending on the ``sync`` | ||
| 585 | + mode). | ||
| 586 | + | ||
| 587 | +(2) Issuing the command ``block-job-complete`` after it emits the event | ||
| 588 | + ``BLOCK_JOB_COMPLETED``: will, after completing synchronization of | ||
| 589 | + the content, adjust the guest device (i.e. live QEMU) to point to | ||
| 590 | + the target image, and, causing all the new writes from this point on | ||
| 591 | + to happen there. One use case for this is live storage migration. | ||
| 592 | + | ||
| 593 | +About synchronization modes: The synchronization mode determines | ||
| 594 | +*which* part of the disk image chain will be copied to the target. | ||
| 595 | +Currently, there are four different kinds: | ||
| 596 | + | ||
| 597 | +(1) ``full`` -- Synchronize the content of entire disk image chain to | ||
| 598 | + the target | ||
| 599 | + | ||
| 600 | +(2) ``top`` -- Synchronize only the contents of the top-most disk image | ||
| 601 | + in the chain to the target | ||
| 602 | + | ||
| 603 | +(3) ``none`` -- Synchronize only the new writes from this point on. | ||
| 604 | + | ||
| 605 | + .. note:: In the case of ``drive-backup`` (or ``blockdev-backup``), | ||
| 606 | + the behavior of ``none`` synchronization mode is different. | ||
| 607 | + Normally, a ``backup`` job consists of two parts: Anything | ||
| 608 | + that is overwritten by the guest is first copied out to | ||
| 609 | + the backup, and in the background the whole image is | ||
| 610 | + copied from start to end. With ``sync=none``, it's only | ||
| 611 | + the first part. | ||
| 612 | + | ||
| 613 | +(4) ``incremental`` -- Synchronize content that is described by the | ||
| 614 | + dirty bitmap | ||
| 615 | + | ||
| 616 | +.. note:: | ||
| 617 | + Refer to the :doc:`bitmaps` document in the QEMU source | ||
| 618 | + tree to learn about the detailed workings of the ``incremental`` | ||
| 619 | + synchronization mode. | ||
| 620 | + | ||
| 621 | + | ||
| 622 | +QMP invocation for ``drive-mirror`` | ||
| 623 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 624 | + | ||
| 625 | +To copy the contents of the entire disk image chain, from [A] all the | ||
| 626 | +way to [D], to a new target (``drive-mirror`` will create the destination | ||
| 627 | +file, if it doesn't already exist), call it [E]:: | ||
| 628 | + | ||
| 629 | + (QEMU) drive-mirror device=node-D target=e.qcow2 sync=full job-id=job0 | ||
| 630 | + { | ||
| 631 | + "execute": "drive-mirror", | ||
| 632 | + "arguments": { | ||
| 633 | + "device": "node-D", | ||
| 634 | + "job-id": "job0", | ||
| 635 | + "target": "e.qcow2", | ||
| 636 | + "sync": "full" | ||
| 637 | + } | ||
| 638 | + } | ||
| 639 | + | ||
| 640 | +The ``"sync": "full"``, from the above, means: copy the *entire* chain | ||
| 641 | +to the destination. | ||
| 642 | + | ||
| 643 | +Following the above, querying for active block jobs will show that a | ||
| 644 | +'mirror' job is "ready" to be completed (and QEMU will also emit an | ||
| 645 | +event, ``BLOCK_JOB_READY``):: | ||
| 646 | + | ||
| 647 | + (QEMU) query-block-jobs | ||
| 648 | + { | ||
| 649 | + "execute": "query-block-jobs", | ||
| 650 | + "arguments": {} | ||
| 651 | + } | ||
| 652 | + { | ||
| 653 | + "return": [ | ||
| 654 | + { | ||
| 655 | + "busy": false, | ||
| 656 | + "type": "mirror", | ||
| 657 | + "len": 21757952, | ||
| 658 | + "paused": false, | ||
| 659 | + "ready": true, | ||
| 660 | + "io-status": "ok", | ||
| 661 | + "offset": 21757952, | ||
| 662 | + "device": "job0", | ||
| 663 | + "speed": 0 | ||
| 664 | + } | ||
| 665 | + ] | ||
| 666 | + } | ||
| 667 | + | ||
| 668 | +And, as noted in the previous section, there are two possible actions | ||
| 669 | +at this point: | ||
| 670 | + | ||
| 671 | +(a) Create a point-in-time snapshot by ending the synchronization. The | ||
| 672 | + point-in-time is at the time of *ending* the sync. (The result of | ||
| 673 | + the following being: the target image, [E], will be populated with | ||
| 674 | + content from the entire chain, [A] to [D]):: | ||
| 675 | + | ||
| 676 | + (QEMU) block-job-cancel device=job0 | ||
| 677 | + { | ||
| 678 | + "execute": "block-job-cancel", | ||
| 679 | + "arguments": { | ||
| 680 | + "device": "job0" | ||
| 681 | + } | ||
| 682 | + } | ||
| 683 | + | ||
| 684 | +(b) Or, complete the operation and pivot the live QEMU to the target | ||
| 685 | + copy:: | ||
| 686 | + | ||
| 687 | + (QEMU) block-job-complete device=job0 | ||
| 688 | + | ||
| 689 | +In either of the above cases, if you once again run the | ||
| 690 | +`query-block-jobs` command, there should not be any active block | ||
| 691 | +operation. | ||
| 692 | + | ||
| 693 | +Comparing 'commit' and 'mirror': In both then cases, the overlay images | ||
| 694 | +can be discarded. However, with 'commit', the *existing* base image | ||
| 695 | +will be modified (by updating it with contents from overlays); while in | ||
| 696 | +the case of 'mirror', a *new* target image is populated with the data | ||
| 697 | +from the disk image chain. | ||
| 698 | + | ||
| 699 | + | ||
| 700 | +QMP invocation for live storage migration with ``drive-mirror`` + NBD | ||
| 701 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 702 | + | ||
| 703 | +Live storage migration (without shared storage setup) is one of the most | ||
| 704 | +common use-cases that takes advantage of the ``drive-mirror`` primitive | ||
| 705 | +and QEMU's built-in Network Block Device (NBD) server. Here's a quick | ||
| 706 | +walk-through of this setup. | ||
| 707 | + | ||
| 708 | +Given the disk image chain:: | ||
| 709 | + | ||
| 710 | + [A] <-- [B] <-- [C] <-- [D] | ||
| 711 | + | ||
| 712 | +Instead of copying content from the entire chain, synchronize *only* the | ||
| 713 | +contents of the *top*-most disk image (i.e. the active layer), [D], to a | ||
| 714 | +target, say, [TargetDisk]. | ||
| 715 | + | ||
| 716 | +.. important:: | ||
| 717 | + The destination host must already have the contents of the backing | ||
| 718 | + chain, involving images [A], [B], and [C], visible via other means | ||
| 719 | + -- whether by ``cp``, ``rsync``, or by some storage array-specific | ||
| 720 | + command.) | ||
| 721 | + | ||
| 722 | +Sometimes, this is also referred to as "shallow copy" -- because only | ||
| 723 | +the "active layer", and not the rest of the image chain, is copied to | ||
| 724 | +the destination. | ||
| 725 | + | ||
| 726 | +.. note:: | ||
| 727 | + In this example, for the sake of simplicity, we'll be using the same | ||
| 728 | + ``localhost`` as both source and destination. | ||
| 729 | + | ||
| 730 | +As noted earlier, on the destination host the contents of the backing | ||
| 731 | +chain -- from images [A] to [C] -- are already expected to exist in some | ||
| 732 | +form (e.g. in a file called, ``Contents-of-A-B-C.qcow2``). Now, on the | ||
| 733 | +destination host, let's create a target overlay image (with the image | ||
| 734 | +``Contents-of-A-B-C.qcow2`` as its backing file), to which the contents | ||
| 735 | +of image [D] (from the source QEMU) will be mirrored to:: | ||
| 736 | + | ||
| 737 | + $ qemu-img create -f qcow2 -b ./Contents-of-A-B-C.qcow2 \ | ||
| 738 | + -F qcow2 ./target-disk.qcow2 | ||
| 739 | + | ||
| 740 | +And start the destination QEMU (we already have the source QEMU running | ||
| 741 | +-- discussed in the section: `Interacting with a QEMU instance`_) | ||
| 742 | +instance, with the following invocation. (As noted earlier, for | ||
| 743 | +simplicity's sake, the destination QEMU is started on the same host, but | ||
| 744 | +it could be located elsewhere):: | ||
| 745 | + | ||
| 746 | + $ ./x86_64-softmmu/qemu-system-x86_64 -display none -nodefconfig \ | ||
| 747 | + -M q35 -nodefaults -m 512 \ | ||
| 748 | + -blockdev node-name=node-TargetDisk,driver=qcow2,file.driver=file,file.node-name=file,file.filename=./target-disk.qcow2 \ | ||
| 749 | + -device virtio-blk,drive=node-TargetDisk,id=virtio0 \ | ||
| 750 | + -S -monitor stdio -qmp unix:./qmp-sock2,server,nowait \ | ||
| 751 | + -incoming tcp:localhost:6666 | ||
| 752 | + | ||
| 753 | +Given the disk image chain on source QEMU:: | ||
| 754 | + | ||
| 755 | + [A] <-- [B] <-- [C] <-- [D] | ||
| 756 | + | ||
| 757 | +On the destination host, it is expected that the contents of the chain | ||
| 758 | +``[A] <-- [B] <-- [C]`` are *already* present, and therefore copy *only* | ||
| 759 | +the content of image [D]. | ||
| 760 | + | ||
| 761 | +(1) [On *destination* QEMU] As part of the first step, start the | ||
| 762 | + built-in NBD server on a given host (local host, represented by | ||
| 763 | + ``::``)and port:: | ||
| 764 | + | ||
| 765 | + (QEMU) nbd-server-start addr={"type":"inet","data":{"host":"::","port":"49153"}} | ||
| 766 | + { | ||
| 767 | + "execute": "nbd-server-start", | ||
| 768 | + "arguments": { | ||
| 769 | + "addr": { | ||
| 770 | + "data": { | ||
| 771 | + "host": "::", | ||
| 772 | + "port": "49153" | ||
| 773 | + }, | ||
| 774 | + "type": "inet" | ||
| 775 | + } | ||
| 776 | + } | ||
| 777 | + } | ||
| 778 | + | ||
| 779 | +(2) [On *destination* QEMU] And export the destination disk image using | ||
| 780 | + QEMU's built-in NBD server:: | ||
| 781 | + | ||
| 782 | + (QEMU) nbd-server-add device=node-TargetDisk writable=true | ||
| 783 | + { | ||
| 784 | + "execute": "nbd-server-add", | ||
| 785 | + "arguments": { | ||
| 786 | + "device": "node-TargetDisk" | ||
| 787 | + } | ||
| 788 | + } | ||
| 789 | + | ||
| 790 | +(3) [On *source* QEMU] Then, invoke ``drive-mirror`` (NB: since we're | ||
| 791 | + running ``drive-mirror`` with ``mode=existing`` (meaning: | ||
| 792 | + synchronize to a pre-created file, therefore 'existing', file on the | ||
| 793 | + target host), with the synchronization mode as 'top' (``"sync: | ||
| 794 | + "top"``):: | ||
| 795 | + | ||
| 796 | + (QEMU) drive-mirror device=node-D target=nbd:localhost:49153:exportname=node-TargetDisk sync=top mode=existing job-id=job0 | ||
| 797 | + { | ||
| 798 | + "execute": "drive-mirror", | ||
| 799 | + "arguments": { | ||
| 800 | + "device": "node-D", | ||
| 801 | + "mode": "existing", | ||
| 802 | + "job-id": "job0", | ||
| 803 | + "target": "nbd:localhost:49153:exportname=node-TargetDisk", | ||
| 804 | + "sync": "top" | ||
| 805 | + } | ||
| 806 | + } | ||
| 807 | + | ||
| 808 | +(4) [On *source* QEMU] Once ``drive-mirror`` copies the entire data, and the | ||
| 809 | + event ``BLOCK_JOB_READY`` is emitted, issue ``block-job-cancel`` to | ||
| 810 | + gracefully end the synchronization, from source QEMU:: | ||
| 811 | + | ||
| 812 | + (QEMU) block-job-cancel device=job0 | ||
| 813 | + { | ||
| 814 | + "execute": "block-job-cancel", | ||
| 815 | + "arguments": { | ||
| 816 | + "device": "job0" | ||
| 817 | + } | ||
| 818 | + } | ||
| 819 | + | ||
| 820 | +(5) [On *destination* QEMU] Then, stop the NBD server:: | ||
| 821 | + | ||
| 822 | + (QEMU) nbd-server-stop | ||
| 823 | + { | ||
| 824 | + "execute": "nbd-server-stop", | ||
| 825 | + "arguments": {} | ||
| 826 | + } | ||
| 827 | + | ||
| 828 | +(6) [On *destination* QEMU] Finally, resume the guest vCPUs by issuing the | ||
| 829 | + QMP command `cont`:: | ||
| 830 | + | ||
| 831 | + (QEMU) cont | ||
| 832 | + { | ||
| 833 | + "execute": "cont", | ||
| 834 | + "arguments": {} | ||
| 835 | + } | ||
| 836 | + | ||
| 837 | +.. note:: | ||
| 838 | + Higher-level libraries (e.g. libvirt) automate the entire above | ||
| 839 | + process (although note that libvirt does not allow same-host | ||
| 840 | + migrations to localhost for other reasons). | ||
| 841 | + | ||
| 842 | + | ||
| 843 | +Notes on ``blockdev-mirror`` | ||
| 844 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 845 | + | ||
| 846 | +The ``blockdev-mirror`` command is equivalent in core functionality to | ||
| 847 | +``drive-mirror``, except that it operates at node-level in a BDS graph. | ||
| 848 | + | ||
| 849 | +Also: for ``blockdev-mirror``, the 'target' image needs to be explicitly | ||
| 850 | +created (using ``qemu-img``) and attach it to live QEMU via | ||
| 851 | +``blockdev-add``, which assigns a name to the to-be created target node. | ||
| 852 | + | ||
| 853 | +E.g. the sequence of actions to create a point-in-time backup of an | ||
| 854 | +entire disk image chain, to a target, using ``blockdev-mirror`` would be: | ||
| 855 | + | ||
| 856 | +(0) Create the QCOW2 overlays, to arrive at a backing chain of desired | ||
| 857 | + depth | ||
| 858 | + | ||
| 859 | +(1) Create the target image (using ``qemu-img``), say, ``e.qcow2`` | ||
| 860 | + | ||
| 861 | +(2) Attach the above created file (``e.qcow2``), run-time, using | ||
| 862 | + ``blockdev-add`` to QEMU | ||
| 863 | + | ||
| 864 | +(3) Perform ``blockdev-mirror`` (use ``"sync": "full"`` to copy the | ||
| 865 | + entire chain to the target). And notice the event | ||
| 866 | + ``BLOCK_JOB_READY`` | ||
| 867 | + | ||
| 868 | +(4) Optionally, query for active block jobs, there should be a 'mirror' | ||
| 869 | + job ready to be completed | ||
| 870 | + | ||
| 871 | +(5) Gracefully complete the 'mirror' block device job, and notice the | ||
| 872 | + the event ``BLOCK_JOB_COMPLETED`` | ||
| 873 | + | ||
| 874 | +(6) Shutdown the guest by issuing the QMP ``quit`` command so that | ||
| 875 | + caches are flushed | ||
| 876 | + | ||
| 877 | +(7) Then, finally, compare the contents of the disk image chain, and | ||
| 878 | + the target copy with ``qemu-img compare``. You should notice: | ||
| 879 | + "Images are identical" | ||
| 880 | + | ||
| 881 | + | ||
| 882 | +QMP invocation for ``blockdev-mirror`` | ||
| 883 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 884 | + | ||
| 885 | +Given the disk image chain:: | ||
| 886 | + | ||
| 887 | + [A] <-- [B] <-- [C] <-- [D] | ||
| 888 | + | ||
| 889 | +To copy the contents of the entire disk image chain, from [A] all the | ||
| 890 | +way to [D], to a new target, call it [E]. The following is the flow. | ||
| 891 | + | ||
| 892 | +Create the overlay images, [B], [C], and [D]:: | ||
| 893 | + | ||
| 894 | + (QEMU) blockdev-snapshot-sync node-name=node-A snapshot-file=b.qcow2 snapshot-node-name=node-B format=qcow2 | ||
| 895 | + (QEMU) blockdev-snapshot-sync node-name=node-B snapshot-file=c.qcow2 snapshot-node-name=node-C format=qcow2 | ||
| 896 | + (QEMU) blockdev-snapshot-sync node-name=node-C snapshot-file=d.qcow2 snapshot-node-name=node-D format=qcow2 | ||
| 897 | + | ||
| 898 | +Create the target image, [E]:: | ||
| 899 | + | ||
| 900 | + $ qemu-img create -f qcow2 e.qcow2 39M | ||
| 901 | + | ||
| 902 | +Add the above created target image to QEMU, via ``blockdev-add``:: | ||
| 903 | + | ||
| 904 | + (QEMU) blockdev-add driver=qcow2 node-name=node-E file={"driver":"file","filename":"e.qcow2"} | ||
| 905 | + { | ||
| 906 | + "execute": "blockdev-add", | ||
| 907 | + "arguments": { | ||
| 908 | + "node-name": "node-E", | ||
| 909 | + "driver": "qcow2", | ||
| 910 | + "file": { | ||
| 911 | + "driver": "file", | ||
| 912 | + "filename": "e.qcow2" | ||
| 913 | + } | ||
| 914 | + } | ||
| 915 | + } | ||
| 916 | + | ||
| 917 | +Perform ``blockdev-mirror``, and notice the event ``BLOCK_JOB_READY``:: | ||
| 918 | + | ||
| 919 | + (QEMU) blockdev-mirror device=node-B target=node-E sync=full job-id=job0 | ||
| 920 | + { | ||
| 921 | + "execute": "blockdev-mirror", | ||
| 922 | + "arguments": { | ||
| 923 | + "device": "node-D", | ||
| 924 | + "job-id": "job0", | ||
| 925 | + "target": "node-E", | ||
| 926 | + "sync": "full" | ||
| 927 | + } | ||
| 928 | + } | ||
| 929 | + | ||
| 930 | +Query for active block jobs, there should be a 'mirror' job ready:: | ||
| 931 | + | ||
| 932 | + (QEMU) query-block-jobs | ||
| 933 | + { | ||
| 934 | + "execute": "query-block-jobs", | ||
| 935 | + "arguments": {} | ||
| 936 | + } | ||
| 937 | + { | ||
| 938 | + "return": [ | ||
| 939 | + { | ||
| 940 | + "busy": false, | ||
| 941 | + "type": "mirror", | ||
| 942 | + "len": 21561344, | ||
| 943 | + "paused": false, | ||
| 944 | + "ready": true, | ||
| 945 | + "io-status": "ok", | ||
| 946 | + "offset": 21561344, | ||
| 947 | + "device": "job0", | ||
| 948 | + "speed": 0 | ||
| 949 | + } | ||
| 950 | + ] | ||
| 951 | + } | ||
| 952 | + | ||
| 953 | +Gracefully complete the block device job operation, and notice the | ||
| 954 | +event ``BLOCK_JOB_COMPLETED``:: | ||
| 955 | + | ||
| 956 | + (QEMU) block-job-complete device=job0 | ||
| 957 | + { | ||
| 958 | + "execute": "block-job-complete", | ||
| 959 | + "arguments": { | ||
| 960 | + "device": "job0" | ||
| 961 | + } | ||
| 962 | + } | ||
| 963 | + { | ||
| 964 | + "return": {} | ||
| 965 | + } | ||
| 966 | + | ||
| 967 | +Shutdown the guest, by issuing the ``quit`` QMP command:: | ||
| 968 | + | ||
| 969 | + (QEMU) quit | ||
| 970 | + { | ||
| 971 | + "execute": "quit", | ||
| 972 | + "arguments": {} | ||
| 973 | + } | ||
| 974 | + | ||
| 975 | + | ||
| 976 | +Live disk backup --- ``drive-backup`` and ``blockdev-backup`` | ||
| 977 | +------------------------------------------------------------- | ||
| 978 | + | ||
| 979 | +The ``drive-backup`` (and its newer equivalent ``blockdev-backup``) allows | ||
| 980 | +you to create a point-in-time snapshot. | ||
| 981 | + | ||
| 982 | +In this case, the point-in-time is when you *start* the ``drive-backup`` | ||
| 983 | +(or its newer equivalent ``blockdev-backup``) command. | ||
| 984 | + | ||
| 985 | + | ||
| 986 | +QMP invocation for ``drive-backup`` | ||
| 987 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 988 | + | ||
| 989 | +Yet again, starting afresh with our example disk image chain:: | ||
| 990 | + | ||
| 991 | + [A] <-- [B] <-- [C] <-- [D] | ||
| 992 | + | ||
| 993 | +To create a target image [E], with content populated from image [A] to | ||
| 994 | +[D], from the above chain, the following is the syntax. (If the target | ||
| 995 | +image does not exist, ``drive-backup`` will create it):: | ||
| 996 | + | ||
| 997 | + (QEMU) drive-backup device=node-D sync=full target=e.qcow2 job-id=job0 | ||
| 998 | + { | ||
| 999 | + "execute": "drive-backup", | ||
| 1000 | + "arguments": { | ||
| 1001 | + "device": "node-D", | ||
| 1002 | + "job-id": "job0", | ||
| 1003 | + "sync": "full", | ||
| 1004 | + "target": "e.qcow2" | ||
| 1005 | + } | ||
| 1006 | + } | ||
| 1007 | + | ||
| 1008 | +Once the above ``drive-backup`` has completed, a ``BLOCK_JOB_COMPLETED`` event | ||
| 1009 | +will be issued, indicating the live block device job operation has | ||
| 1010 | +completed, and no further action is required. | ||
| 1011 | + | ||
| 1012 | + | ||
| 1013 | +Notes on ``blockdev-backup`` | ||
| 1014 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 1015 | + | ||
| 1016 | +The ``blockdev-backup`` command is equivalent in functionality to | ||
| 1017 | +``drive-backup``, except that it operates at node-level in a Block Driver | ||
| 1018 | +State (BDS) graph. | ||
| 1019 | + | ||
| 1020 | +E.g. the sequence of actions to create a point-in-time backup | ||
| 1021 | +of an entire disk image chain, to a target, using ``blockdev-backup`` | ||
| 1022 | +would be: | ||
| 1023 | + | ||
| 1024 | +(0) Create the QCOW2 overlays, to arrive at a backing chain of desired | ||
| 1025 | + depth | ||
| 1026 | + | ||
| 1027 | +(1) Create the target image (using ``qemu-img``), say, ``e.qcow2`` | ||
| 1028 | + | ||
| 1029 | +(2) Attach the above created file (``e.qcow2``), run-time, using | ||
| 1030 | + ``blockdev-add`` to QEMU | ||
| 1031 | + | ||
| 1032 | +(3) Perform ``blockdev-backup`` (use ``"sync": "full"`` to copy the | ||
| 1033 | + entire chain to the target). And notice the event | ||
| 1034 | + ``BLOCK_JOB_COMPLETED`` | ||
| 1035 | + | ||
| 1036 | +(4) Shutdown the guest, by issuing the QMP ``quit`` command, so that | ||
| 1037 | + caches are flushed | ||
| 1038 | + | ||
| 1039 | +(5) Then, finally, compare the contents of the disk image chain, and | ||
| 1040 | + the target copy with ``qemu-img compare``. You should notice: | ||
| 1041 | + "Images are identical" | ||
| 1042 | + | ||
| 1043 | +The following section shows an example QMP invocation for | ||
| 1044 | +``blockdev-backup``. | ||
| 1045 | + | ||
| 1046 | +QMP invocation for ``blockdev-backup`` | ||
| 1047 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 1048 | + | ||
| 1049 | +Given a disk image chain of depth 1 where image [B] is the active | ||
| 1050 | +overlay (live QEMU is writing to it):: | ||
| 1051 | + | ||
| 1052 | + [A] <-- [B] | ||
| 1053 | + | ||
| 1054 | +The following is the procedure to copy the content from the entire chain | ||
| 1055 | +to a target image (say, [E]), which has the full content from [A] and | ||
| 1056 | +[B]. | ||
| 1057 | + | ||
| 1058 | +Create the overlay [B]:: | ||
| 1059 | + | ||
| 1060 | + (QEMU) blockdev-snapshot-sync node-name=node-A snapshot-file=b.qcow2 snapshot-node-name=node-B format=qcow2 | ||
| 1061 | + { | ||
| 1062 | + "execute": "blockdev-snapshot-sync", | ||
| 1063 | + "arguments": { | ||
| 1064 | + "node-name": "node-A", | ||
| 1065 | + "snapshot-file": "b.qcow2", | ||
| 1066 | + "format": "qcow2", | ||
| 1067 | + "snapshot-node-name": "node-B" | ||
| 1068 | + } | ||
| 1069 | + } | ||
| 1070 | + | ||
| 1071 | + | ||
| 1072 | +Create a target image that will contain the copy:: | ||
| 1073 | + | ||
| 1074 | + $ qemu-img create -f qcow2 e.qcow2 39M | ||
| 1075 | + | ||
| 1076 | +Then add it to QEMU via ``blockdev-add``:: | ||
| 1077 | + | ||
| 1078 | + (QEMU) blockdev-add driver=qcow2 node-name=node-E file={"driver":"file","filename":"e.qcow2"} | ||
| 1079 | + { | ||
| 1080 | + "execute": "blockdev-add", | ||
| 1081 | + "arguments": { | ||
| 1082 | + "node-name": "node-E", | ||
| 1083 | + "driver": "qcow2", | ||
| 1084 | + "file": { | ||
| 1085 | + "driver": "file", | ||
| 1086 | + "filename": "e.qcow2" | ||
| 1087 | + } | ||
| 1088 | + } | ||
| 1089 | + } | ||
| 1090 | + | ||
| 1091 | +Then invoke ``blockdev-backup`` to copy the contents from the entire | ||
| 1092 | +image chain, consisting of images [A] and [B] to the target image | ||
| 1093 | +'e.qcow2':: | ||
| 1094 | + | ||
| 1095 | + (QEMU) blockdev-backup device=node-B target=node-E sync=full job-id=job0 | ||
| 1096 | + { | ||
| 1097 | + "execute": "blockdev-backup", | ||
| 1098 | + "arguments": { | ||
| 1099 | + "device": "node-B", | ||
| 1100 | + "job-id": "job0", | ||
| 1101 | + "target": "node-E", | ||
| 1102 | + "sync": "full" | ||
| 1103 | + } | ||
| 1104 | + } | ||
| 1105 | + | ||
| 1106 | +Once the above 'backup' operation has completed, the event, | ||
| 1107 | +``BLOCK_JOB_COMPLETED`` will be emitted, signalling successful | ||
| 1108 | +completion. | ||
| 1109 | + | ||
| 1110 | +Next, query for any active block device jobs (there should be none):: | ||
| 1111 | + | ||
| 1112 | + (QEMU) query-block-jobs | ||
| 1113 | + { | ||
| 1114 | + "execute": "query-block-jobs", | ||
| 1115 | + "arguments": {} | ||
| 1116 | + } | ||
| 1117 | + | ||
| 1118 | +Shutdown the guest:: | ||
| 1119 | + | ||
| 1120 | + (QEMU) quit | ||
| 1121 | + { | ||
| 1122 | + "execute": "quit", | ||
| 1123 | + "arguments": {} | ||
| 1124 | + } | ||
| 1125 | + "return": {} | ||
| 1126 | + } | ||
| 1127 | + | ||
| 1128 | +.. note:: | ||
| 1129 | + The above step is really important; if forgotten, an error, "Failed | ||
| 1130 | + to get shared "write" lock on e.qcow2", will be thrown when you do | ||
| 1131 | + ``qemu-img compare`` to verify the integrity of the disk image | ||
| 1132 | + with the backup content. | ||
| 1133 | + | ||
| 1134 | + | ||
| 1135 | +The end result will be the image 'e.qcow2' containing a | ||
| 1136 | +point-in-time backup of the disk image chain -- i.e. contents from | ||
| 1137 | +images [A] and [B] at the time the ``blockdev-backup`` command was | ||
| 1138 | +initiated. | ||
| 1139 | + | ||
| 1140 | +One way to confirm the backup disk image contains the identical content | ||
| 1141 | +with the disk image chain is to compare the backup and the contents of | ||
| 1142 | +the chain, you should see "Images are identical". (NB: this is assuming | ||
| 1143 | +QEMU was launched with ``-S`` option, which will not start the CPUs at | ||
| 1144 | +guest boot up):: | ||
| 1145 | + | ||
| 1146 | + $ qemu-img compare b.qcow2 e.qcow2 | ||
| 1147 | + Warning: Image size mismatch! | ||
| 1148 | + Images are identical. | ||
| 1149 | + | ||
| 1150 | +NOTE: The "Warning: Image size mismatch!" is expected, as we created the | ||
| 1151 | +target image (e.qcow2) with 39M size. | ||
| 1152 | diff --git a/docs/live-block-ops.txt b/docs/live-block-ops.txt | ||
| 1153 | deleted file mode 100644 | ||
| 1154 | index XXXXXXX..XXXXXXX | ||
| 1155 | --- a/docs/live-block-ops.txt | ||
| 1156 | +++ /dev/null | ||
| 1157 | @@ -XXX,XX +XXX,XX @@ | ||
| 1158 | -LIVE BLOCK OPERATIONS | ||
| 1159 | -===================== | ||
| 1160 | - | ||
| 1161 | -High level description of live block operations. Note these are not | ||
| 1162 | -supported for use with the raw format at the moment. | ||
| 1163 | - | ||
| 1164 | -Note also that this document is incomplete and it currently only | ||
| 1165 | -covers the 'stream' operation. Other operations supported by QEMU such | ||
| 1166 | -as 'commit', 'mirror' and 'backup' are not described here yet. Please | ||
| 1167 | -refer to the qapi/block-core.json file for an overview of those. | ||
| 1168 | - | ||
| 1169 | -Snapshot live merge | ||
| 1170 | -=================== | ||
| 1171 | - | ||
| 1172 | -Given a snapshot chain, described in this document in the following | ||
| 1173 | -format: | ||
| 1174 | - | ||
| 1175 | -[A] <- [B] <- [C] <- [D] <- [E] | ||
| 1176 | - | ||
| 1177 | -Where the rightmost object ([E] in the example) described is the current | ||
| 1178 | -image which the guest OS has write access to. To the left of it is its base | ||
| 1179 | -image, and so on accordingly until the leftmost image, which has no | ||
| 1180 | -base. | ||
| 1181 | - | ||
| 1182 | -The snapshot live merge operation transforms such a chain into a | ||
| 1183 | -smaller one with fewer elements, such as this transformation relative | ||
| 1184 | -to the first example: | ||
| 1185 | - | ||
| 1186 | -[A] <- [E] | ||
| 1187 | - | ||
| 1188 | -Data is copied in the right direction with destination being the | ||
| 1189 | -rightmost image, but any other intermediate image can be specified | ||
| 1190 | -instead. In this example data is copied from [C] into [D], so [D] can | ||
| 1191 | -be backed by [B]: | ||
| 1192 | - | ||
| 1193 | -[A] <- [B] <- [D] <- [E] | ||
| 1194 | - | ||
| 1195 | -The operation is implemented in QEMU through image streaming facilities. | ||
| 1196 | - | ||
| 1197 | -The basic idea is to execute 'block_stream virtio0' while the guest is | ||
| 1198 | -running. Progress can be monitored using 'info block-jobs'. When the | ||
| 1199 | -streaming operation completes it raises a QMP event. 'block_stream' | ||
| 1200 | -copies data from the backing file(s) into the active image. When finished, | ||
| 1201 | -it adjusts the backing file pointer. | ||
| 1202 | - | ||
| 1203 | -The 'base' parameter specifies an image which data need not be | ||
| 1204 | -streamed from. This image will be used as the backing file for the | ||
| 1205 | -destination image when the operation is finished. | ||
| 1206 | - | ||
| 1207 | -In the first example above, the command would be: | ||
| 1208 | - | ||
| 1209 | -(qemu) block_stream virtio0 file-A.img | ||
| 1210 | - | ||
| 1211 | -In order to specify a destination image different from the active | ||
| 1212 | -(rightmost) one we can use its node name instead. | ||
| 1213 | - | ||
| 1214 | -In the second example above, the command would be: | ||
| 1215 | - | ||
| 1216 | -(qemu) block_stream node-D file-B.img | ||
| 1217 | - | ||
| 1218 | -Live block copy | ||
| 1219 | -=============== | ||
| 1220 | - | ||
| 1221 | -To copy an in use image to another destination in the filesystem, one | ||
| 1222 | -should create a live snapshot in the desired destination, then stream | ||
| 1223 | -into that image. Example: | ||
| 1224 | - | ||
| 1225 | -(qemu) snapshot_blkdev ide0-hd0 /new-path/disk.img qcow2 | ||
| 1226 | - | ||
| 1227 | -(qemu) block_stream ide0-hd0 | ||
| 1228 | - | ||
| 1229 | - | ||
| 1230 | -- | 39 | -- |
| 1231 | 2.9.4 | 40 | 2.48.1 |
| 1232 | |||
| 1233 | diff view generated by jsdifflib |