1== General == 2 3A qcow2 image file is organized in units of constant size, which are called 4(host) clusters. A cluster is the unit in which all allocations are done, 5both for actual guest data and for image metadata. 6 7Likewise, the virtual disk as seen by the guest is divided into (guest) 8clusters of the same size. 9 10All numbers in qcow2 are stored in Big Endian byte order. 11 12 13== Header == 14 15The first cluster of a qcow2 image contains the file header: 16 17 Byte 0 - 3: magic 18 QCOW magic string ("QFI\xfb") 19 20 4 - 7: version 21 Version number (valid values are 2 and 3) 22 23 8 - 15: backing_file_offset 24 Offset into the image file at which the backing file name 25 is stored (NB: The string is not null terminated). 0 if the 26 image doesn't have a backing file. 27 28 16 - 19: backing_file_size 29 Length of the backing file name in bytes. Must not be 30 longer than 1023 bytes. Undefined if the image doesn't have 31 a backing file. 32 33 20 - 23: cluster_bits 34 Number of bits that are used for addressing an offset 35 within a cluster (1 << cluster_bits is the cluster size). 36 Must not be less than 9 (i.e. 512 byte clusters). 37 38 Note: qemu as of today has an implementation limit of 2 MB 39 as the maximum cluster size and won't be able to open images 40 with larger cluster sizes. 41 42 24 - 31: size 43 Virtual disk size in bytes 44 45 32 - 35: crypt_method 46 0 for no encryption 47 1 for AES encryption 48 2 for LUKS encryption 49 50 36 - 39: l1_size 51 Number of entries in the active L1 table 52 53 40 - 47: l1_table_offset 54 Offset into the image file at which the active L1 table 55 starts. Must be aligned to a cluster boundary. 56 57 48 - 55: refcount_table_offset 58 Offset into the image file at which the refcount table 59 starts. Must be aligned to a cluster boundary. 60 61 56 - 59: refcount_table_clusters 62 Number of clusters that the refcount table occupies 63 64 60 - 63: nb_snapshots 65 Number of snapshots contained in the image 66 67 64 - 71: snapshots_offset 68 Offset into the image file at which the snapshot table 69 starts. Must be aligned to a cluster boundary. 70 71If the version is 3 or higher, the header has the following additional fields. 72For version 2, the values are assumed to be zero, unless specified otherwise 73in the description of a field. 74 75 72 - 79: incompatible_features 76 Bitmask of incompatible features. An implementation must 77 fail to open an image if an unknown bit is set. 78 79 Bit 0: Dirty bit. If this bit is set then refcounts 80 may be inconsistent, make sure to scan L1/L2 81 tables to repair refcounts before accessing the 82 image. 83 84 Bit 1: Corrupt bit. If this bit is set then any data 85 structure may be corrupt and the image must not 86 be written to (unless for regaining 87 consistency). 88 89 Bits 2-63: Reserved (set to 0) 90 91 80 - 87: compatible_features 92 Bitmask of compatible features. An implementation can 93 safely ignore any unknown bits that are set. 94 95 Bit 0: Lazy refcounts bit. If this bit is set then 96 lazy refcount updates can be used. This means 97 marking the image file dirty and postponing 98 refcount metadata updates. 99 100 Bits 1-63: Reserved (set to 0) 101 102 88 - 95: autoclear_features 103 Bitmask of auto-clear features. An implementation may only 104 write to an image with unknown auto-clear features if it 105 clears the respective bits from this field first. 106 107 Bit 0: Bitmaps extension bit 108 This bit indicates consistency for the bitmaps 109 extension data. 110 111 It is an error if this bit is set without the 112 bitmaps extension present. 113 114 If the bitmaps extension is present but this 115 bit is unset, the bitmaps extension data must be 116 considered inconsistent. 117 118 Bits 1-63: Reserved (set to 0) 119 120 96 - 99: refcount_order 121 Describes the width of a reference count block entry (width 122 in bits: refcount_bits = 1 << refcount_order). For version 2 123 images, the order is always assumed to be 4 124 (i.e. refcount_bits = 16). 125 This value may not exceed 6 (i.e. refcount_bits = 64). 126 127 100 - 103: header_length 128 Length of the header structure in bytes. For version 2 129 images, the length is always assumed to be 72 bytes. 130 131Directly after the image header, optional sections called header extensions can 132be stored. Each extension has a structure like the following: 133 134 Byte 0 - 3: Header extension type: 135 0x00000000 - End of the header extension area 136 0xE2792ACA - Backing file format name 137 0x6803f857 - Feature name table 138 0x23852875 - Bitmaps extension 139 0x0537be77 - Full disk encryption header pointer 140 other - Unknown header extension, can be safely 141 ignored 142 143 4 - 7: Length of the header extension data 144 145 8 - n: Header extension data 146 147 n - m: Padding to round up the header extension size to the next 148 multiple of 8. 149 150Unless stated otherwise, each header extension type shall appear at most once 151in the same image. 152 153If the image has a backing file then the backing file name should be stored in 154the remaining space between the end of the header extension area and the end of 155the first cluster. It is not allowed to store other data here, so that an 156implementation can safely modify the header and add extensions without harming 157data of compatible features that it doesn't support. Compatible features that 158need space for additional data can use a header extension. 159 160 161== Feature name table == 162 163The feature name table is an optional header extension that contains the name 164for features used by the image. It can be used by applications that don't know 165the respective feature (e.g. because the feature was introduced only later) to 166display a useful error message. 167 168The number of entries in the feature name table is determined by the length of 169the header extension data. Each entry look like this: 170 171 Byte 0: Type of feature (select feature bitmap) 172 0: Incompatible feature 173 1: Compatible feature 174 2: Autoclear feature 175 176 1: Bit number within the selected feature bitmap (valid 177 values: 0-63) 178 179 2 - 47: Feature name (padded with zeros, but not necessarily null 180 terminated if it has full length) 181 182 183== Bitmaps extension == 184 185The bitmaps extension is an optional header extension. It provides the ability 186to store bitmaps related to a virtual disk. For now, there is only one bitmap 187type: the dirty tracking bitmap, which tracks virtual disk changes from some 188point in time. 189 190The data of the extension should be considered consistent only if the 191corresponding auto-clear feature bit is set, see autoclear_features above. 192 193The fields of the bitmaps extension are: 194 195 Byte 0 - 3: nb_bitmaps 196 The number of bitmaps contained in the image. Must be 197 greater than or equal to 1. 198 199 Note: Qemu currently only supports up to 65535 bitmaps per 200 image. 201 202 4 - 7: Reserved, must be zero. 203 204 8 - 15: bitmap_directory_size 205 Size of the bitmap directory in bytes. It is the cumulative 206 size of all (nb_bitmaps) bitmap directory entries. 207 208 16 - 23: bitmap_directory_offset 209 Offset into the image file at which the bitmap directory 210 starts. Must be aligned to a cluster boundary. 211 212== Full disk encryption header pointer == 213 214The full disk encryption header must be present if, and only if, the 215'crypt_method' header requires metadata. Currently this is only true 216of the 'LUKS' crypt method. The header extension must be absent for 217other methods. 218 219This header provides the offset at which the crypt method can store 220its additional data, as well as the length of such data. 221 222 Byte 0 - 7: Offset into the image file at which the encryption 223 header starts in bytes. Must be aligned to a cluster 224 boundary. 225 Byte 8 - 15: Length of the written encryption header in bytes. 226 Note actual space allocated in the qcow2 file may 227 be larger than this value, since it will be rounded 228 to the nearest multiple of the cluster size. Any 229 unused bytes in the allocated space will be initialized 230 to 0. 231 232For the LUKS crypt method, the encryption header works as follows. 233 234The first 592 bytes of the header clusters will contain the LUKS 235partition header. This is then followed by the key material data areas. 236The size of the key material data areas is determined by the number of 237stripes in the key slot and key size. Refer to the LUKS format 238specification ('docs/on-disk-format.pdf' in the cryptsetup source 239package) for details of the LUKS partition header format. 240 241In the LUKS partition header, the "payload-offset" field will be 242calculated as normal for the LUKS spec. ie the size of the LUKS 243header, plus key material regions, plus padding, relative to the 244start of the LUKS header. This offset value is not required to be 245qcow2 cluster aligned. Its value is currently never used in the 246context of qcow2, since the qcow2 file format itself defines where 247the real payload offset is, but none the less a valid payload offset 248should always be present. 249 250In the LUKS key slots header, the "key-material-offset" is relative 251to the start of the LUKS header clusters in the qcow2 container, 252not the start of the qcow2 file. 253 254Logically the layout looks like 255 256 +-----------------------------+ 257 | QCow2 header | 258 | QCow2 header extension X | 259 | QCow2 header extension FDE | 260 | QCow2 header extension ... | 261 | QCow2 header extension Z | 262 +-----------------------------+ 263 | ....other QCow2 tables.... | 264 . . 265 . . 266 +-----------------------------+ 267 | +-------------------------+ | 268 | | LUKS partition header | | 269 | +-------------------------+ | 270 | | LUKS key material 1 | | 271 | +-------------------------+ | 272 | | LUKS key material 2 | | 273 | +-------------------------+ | 274 | | LUKS key material ... | | 275 | +-------------------------+ | 276 | | LUKS key material 8 | | 277 | +-------------------------+ | 278 +-----------------------------+ 279 | QCow2 cluster payload | 280 . . 281 . . 282 . . 283 | | 284 +-----------------------------+ 285 286== Data encryption == 287 288When an encryption method is requested in the header, the image payload 289data must be encrypted/decrypted on every write/read. The image headers 290and metadata are never encrypted. 291 292The algorithms used for encryption vary depending on the method 293 294 - AES: 295 296 The AES cipher, in CBC mode, with 256 bit keys. 297 298 Initialization vectors generated using plain64 method, with 299 the virtual disk sector as the input tweak. 300 301 This format is no longer supported in QEMU system emulators, due 302 to a number of design flaws affecting its security. It is only 303 supported in the command line tools for the sake of back compatibility 304 and data liberation. 305 306 - LUKS: 307 308 The algorithms are specified in the LUKS header. 309 310 Initialization vectors generated using the method specified 311 in the LUKS header, with the physical disk sector as the 312 input tweak. 313 314== Host cluster management == 315 316qcow2 manages the allocation of host clusters by maintaining a reference count 317for each host cluster. A refcount of 0 means that the cluster is free, 1 means 318that it is used, and >= 2 means that it is used and any write access must 319perform a COW (copy on write) operation. 320 321The refcounts are managed in a two-level table. The first level is called 322refcount table and has a variable size (which is stored in the header). The 323refcount table can cover multiple clusters, however it needs to be contiguous 324in the image file. 325 326It contains pointers to the second level structures which are called refcount 327blocks and are exactly one cluster in size. 328 329Given an offset into the image file, the refcount of its cluster can be 330obtained as follows: 331 332 refcount_block_entries = (cluster_size * 8 / refcount_bits) 333 334 refcount_block_index = (offset / cluster_size) % refcount_block_entries 335 refcount_table_index = (offset / cluster_size) / refcount_block_entries 336 337 refcount_block = load_cluster(refcount_table[refcount_table_index]); 338 return refcount_block[refcount_block_index]; 339 340Refcount table entry: 341 342 Bit 0 - 8: Reserved (set to 0) 343 344 9 - 63: Bits 9-63 of the offset into the image file at which the 345 refcount block starts. Must be aligned to a cluster 346 boundary. 347 348 If this is 0, the corresponding refcount block has not yet 349 been allocated. All refcounts managed by this refcount block 350 are 0. 351 352Refcount block entry (x = refcount_bits - 1): 353 354 Bit 0 - x: Reference count of the cluster. If refcount_bits implies a 355 sub-byte width, note that bit 0 means the least significant 356 bit in this context. 357 358 359== Cluster mapping == 360 361Just as for refcounts, qcow2 uses a two-level structure for the mapping of 362guest clusters to host clusters. They are called L1 and L2 table. 363 364The L1 table has a variable size (stored in the header) and may use multiple 365clusters, however it must be contiguous in the image file. L2 tables are 366exactly one cluster in size. 367 368Given an offset into the virtual disk, the offset into the image file can be 369obtained as follows: 370 371 l2_entries = (cluster_size / sizeof(uint64_t)) 372 373 l2_index = (offset / cluster_size) % l2_entries 374 l1_index = (offset / cluster_size) / l2_entries 375 376 l2_table = load_cluster(l1_table[l1_index]); 377 cluster_offset = l2_table[l2_index]; 378 379 return cluster_offset + (offset % cluster_size) 380 381L1 table entry: 382 383 Bit 0 - 8: Reserved (set to 0) 384 385 9 - 55: Bits 9-55 of the offset into the image file at which the L2 386 table starts. Must be aligned to a cluster boundary. If the 387 offset is 0, the L2 table and all clusters described by this 388 L2 table are unallocated. 389 390 56 - 62: Reserved (set to 0) 391 392 63: 0 for an L2 table that is unused or requires COW, 1 if its 393 refcount is exactly one. This information is only accurate 394 in the active L1 table. 395 396L2 table entry: 397 398 Bit 0 - 61: Cluster descriptor 399 400 62: 0 for standard clusters 401 1 for compressed clusters 402 403 63: 0 for clusters that are unused, compressed or require COW. 404 1 for standard clusters whose refcount is exactly one. 405 This information is only accurate in L2 tables 406 that are reachable from the active L1 table. 407 408Standard Cluster Descriptor: 409 410 Bit 0: If set to 1, the cluster reads as all zeros. The host 411 cluster offset can be used to describe a preallocation, 412 but it won't be used for reading data from this cluster, 413 nor is data read from the backing file if the cluster is 414 unallocated. 415 416 With version 2, this is always 0. 417 418 1 - 8: Reserved (set to 0) 419 420 9 - 55: Bits 9-55 of host cluster offset. Must be aligned to a 421 cluster boundary. If the offset is 0, the cluster is 422 unallocated. 423 424 56 - 61: Reserved (set to 0) 425 426 427Compressed Clusters Descriptor (x = 62 - (cluster_bits - 8)): 428 429 Bit 0 - x-1: Host cluster offset. This is usually _not_ aligned to a 430 cluster or sector boundary! 431 432 x - 61: Number of additional 512-byte sectors used for the 433 compressed data, beyond the sector containing the offset 434 in the previous field. Some of these sectors may reside 435 in the next contiguous host cluster. 436 437 Note that the compressed data does not necessarily occupy 438 all of the bytes in the final sector; rather, decompression 439 stops when it has produced a cluster of data. 440 441 Another compressed cluster may map to the tail of the final 442 sector used by this compressed cluster. 443 444If a cluster is unallocated, read requests shall read the data from the backing 445file (except if bit 0 in the Standard Cluster Descriptor is set). If there is 446no backing file or the backing file is smaller than the image, they shall read 447zeros for all parts that are not covered by the backing file. 448 449 450== Snapshots == 451 452qcow2 supports internal snapshots. Their basic principle of operation is to 453switch the active L1 table, so that a different set of host clusters are 454exposed to the guest. 455 456When creating a snapshot, the L1 table should be copied and the refcount of all 457L2 tables and clusters reachable from this L1 table must be increased, so that 458a write causes a COW and isn't visible in other snapshots. 459 460When loading a snapshot, bit 63 of all entries in the new active L1 table and 461all L2 tables referenced by it must be reconstructed from the refcount table 462as it doesn't need to be accurate in inactive L1 tables. 463 464A directory of all snapshots is stored in the snapshot table, a contiguous area 465in the image file, whose starting offset and length are given by the header 466fields snapshots_offset and nb_snapshots. The entries of the snapshot table 467have variable length, depending on the length of ID, name and extra data. 468 469Snapshot table entry: 470 471 Byte 0 - 7: Offset into the image file at which the L1 table for the 472 snapshot starts. Must be aligned to a cluster boundary. 473 474 8 - 11: Number of entries in the L1 table of the snapshots 475 476 12 - 13: Length of the unique ID string describing the snapshot 477 478 14 - 15: Length of the name of the snapshot 479 480 16 - 19: Time at which the snapshot was taken in seconds since the 481 Epoch 482 483 20 - 23: Subsecond part of the time at which the snapshot was taken 484 in nanoseconds 485 486 24 - 31: Time that the guest was running until the snapshot was 487 taken in nanoseconds 488 489 32 - 35: Size of the VM state in bytes. 0 if no VM state is saved. 490 If there is VM state, it starts at the first cluster 491 described by first L1 table entry that doesn't describe a 492 regular guest cluster (i.e. VM state is stored like guest 493 disk content, except that it is stored at offsets that are 494 larger than the virtual disk presented to the guest) 495 496 36 - 39: Size of extra data in the table entry (used for future 497 extensions of the format) 498 499 variable: Extra data for future extensions. Unknown fields must be 500 ignored. Currently defined are (offset relative to snapshot 501 table entry): 502 503 Byte 40 - 47: Size of the VM state in bytes. 0 if no VM 504 state is saved. If this field is present, 505 the 32-bit value in bytes 32-35 is ignored. 506 507 Byte 48 - 55: Virtual disk size of the snapshot in bytes 508 509 Version 3 images must include extra data at least up to 510 byte 55. 511 512 variable: Unique ID string for the snapshot (not null terminated) 513 514 variable: Name of the snapshot (not null terminated) 515 516 variable: Padding to round up the snapshot table entry size to the 517 next multiple of 8. 518 519 520== Bitmaps == 521 522As mentioned above, the bitmaps extension provides the ability to store bitmaps 523related to a virtual disk. This section describes how these bitmaps are stored. 524 525All stored bitmaps are related to the virtual disk stored in the same image, so 526each bitmap size is equal to the virtual disk size. 527 528Each bit of the bitmap is responsible for strictly defined range of the virtual 529disk. For bit number bit_nr the corresponding range (in bytes) will be: 530 531 [bit_nr * bitmap_granularity .. (bit_nr + 1) * bitmap_granularity - 1] 532 533Granularity is a property of the concrete bitmap, see below. 534 535 536=== Bitmap directory === 537 538Each bitmap saved in the image is described in a bitmap directory entry. The 539bitmap directory is a contiguous area in the image file, whose starting offset 540and length are given by the header extension fields bitmap_directory_offset and 541bitmap_directory_size. The entries of the bitmap directory have variable 542length, depending on the lengths of the bitmap name and extra data. 543 544Structure of a bitmap directory entry: 545 546 Byte 0 - 7: bitmap_table_offset 547 Offset into the image file at which the bitmap table 548 (described below) for the bitmap starts. Must be aligned to 549 a cluster boundary. 550 551 8 - 11: bitmap_table_size 552 Number of entries in the bitmap table of the bitmap. 553 554 12 - 15: flags 555 Bit 556 0: in_use 557 The bitmap was not saved correctly and may be 558 inconsistent. 559 560 1: auto 561 The bitmap must reflect all changes of the virtual 562 disk by any application that would write to this qcow2 563 file (including writes, snapshot switching, etc.). The 564 type of this bitmap must be 'dirty tracking bitmap'. 565 566 2: extra_data_compatible 567 This flags is meaningful when the extra data is 568 unknown to the software (currently any extra data is 569 unknown to Qemu). 570 If it is set, the bitmap may be used as expected, extra 571 data must be left as is. 572 If it is not set, the bitmap must not be used, but 573 both it and its extra data be left as is. 574 575 Bits 3 - 31 are reserved and must be 0. 576 577 16: type 578 This field describes the sort of the bitmap. 579 Values: 580 1: Dirty tracking bitmap 581 582 Values 0, 2 - 255 are reserved. 583 584 17: granularity_bits 585 Granularity bits. Valid values: 0 - 63. 586 587 Note: Qemu currently supports only values 9 - 31. 588 589 Granularity is calculated as 590 granularity = 1 << granularity_bits 591 592 A bitmap's granularity is how many bytes of the image 593 accounts for one bit of the bitmap. 594 595 18 - 19: name_size 596 Size of the bitmap name. Must be non-zero. 597 598 Note: Qemu currently doesn't support values greater than 599 1023. 600 601 20 - 23: extra_data_size 602 Size of type-specific extra data. 603 604 For now, as no extra data is defined, extra_data_size is 605 reserved and should be zero. If it is non-zero the 606 behavior is defined by extra_data_compatible flag. 607 608 variable: extra_data 609 Extra data for the bitmap, occupying extra_data_size bytes. 610 Extra data must never contain references to clusters or in 611 some other way allocate additional clusters. 612 613 variable: name 614 The name of the bitmap (not null terminated), occupying 615 name_size bytes. Must be unique among all bitmap names 616 within the bitmaps extension. 617 618 variable: Padding to round up the bitmap directory entry size to the 619 next multiple of 8. All bytes of the padding must be zero. 620 621 622=== Bitmap table === 623 624Each bitmap is stored using a one-level structure (as opposed to two-level 625structures like for refcounts and guest clusters mapping) for the mapping of 626bitmap data to host clusters. This structure is called the bitmap table. 627 628Each bitmap table has a variable size (stored in the bitmap directory entry) 629and may use multiple clusters, however, it must be contiguous in the image 630file. 631 632Structure of a bitmap table entry: 633 634 Bit 0: Reserved and must be zero if bits 9 - 55 are non-zero. 635 If bits 9 - 55 are zero: 636 0: Cluster should be read as all zeros. 637 1: Cluster should be read as all ones. 638 639 1 - 8: Reserved and must be zero. 640 641 9 - 55: Bits 9 - 55 of the host cluster offset. Must be aligned to 642 a cluster boundary. If the offset is 0, the cluster is 643 unallocated; in that case, bit 0 determines how this 644 cluster should be treated during reads. 645 646 56 - 63: Reserved and must be zero. 647 648 649=== Bitmap data === 650 651As noted above, bitmap data is stored in separate clusters, described by the 652bitmap table. Given an offset (in bytes) into the bitmap data, the offset into 653the image file can be obtained as follows: 654 655 image_offset(bitmap_data_offset) = 656 bitmap_table[bitmap_data_offset / cluster_size] + 657 (bitmap_data_offset % cluster_size) 658 659This offset is not defined if bits 9 - 55 of bitmap table entry are zero (see 660above). 661 662Given an offset byte_nr into the virtual disk and the bitmap's granularity, the 663bit offset into the image file to the corresponding bit of the bitmap can be 664calculated like this: 665 666 bit_offset(byte_nr) = 667 image_offset(byte_nr / granularity / 8) * 8 + 668 (byte_nr / granularity) % 8 669 670If the size of the bitmap data is not a multiple of the cluster size then the 671last cluster of the bitmap data contains some unused tail bits. These bits must 672be zero. 673 674 675=== Dirty tracking bitmaps === 676 677Bitmaps with 'type' field equal to one are dirty tracking bitmaps. 678 679When the virtual disk is in use dirty tracking bitmap may be 'enabled' or 680'disabled'. While the bitmap is 'enabled', all writes to the virtual disk 681should be reflected in the bitmap. A set bit in the bitmap means that the 682corresponding range of the virtual disk (see above) was written to while the 683bitmap was 'enabled'. An unset bit means that this range was not written to. 684 685The software doesn't have to sync the bitmap in the image file with its 686representation in RAM after each write. Flag 'in_use' should be set while the 687bitmap is not synced. 688 689In the image file the 'enabled' state is reflected by the 'auto' flag. If this 690flag is set, the software must consider the bitmap as 'enabled' and start 691tracking virtual disk changes to this bitmap from the first write to the 692virtual disk. If this flag is not set then the bitmap is disabled. 693