docs/interop/qcow2.txt

3 A 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,
10 All numbers in qcow2 are stored in Big Endian byte order.
32                     Length of the backing file name in bytes. Must not be
49                     Virtual disk size in bytes.
68                     Number of entries in the active L1 table
82                     Number of snapshots contained in the image
88 For version 2, the header is exactly 72 bytes in length, and finishes here.
108                                 then stored in the external data file. For such
109                                 images, clusters in the external data file are
110                                 not refcounted. The offset field in the
165                                 of only setting the zero flag in the L2 table
176                     in bits: refcount_bits = 1 << refcount_order). For version 2
182                     Length of the header structure in bytes. For version 2
213                     All compressed clusters in an image use the same compression
226                     <https://www.zlib.net/> in QEMU. However, clusters with the
237 paragraph, i.e.  in the same manner as when this field is not present.
263 in the same image.
265 If the image has a backing file then the backing file name should be stored in
290 The number of entries in the feature name table is determined by the length of
310 point in time.
318                    The number of bitmaps contained in the image. Must be
327                    Size of the bitmap directory in bytes. It is the cumulative
345                     header starts in bytes. Must be aligned to a cluster
347     Byte  8 - 15:   Length of the written encryption header in bytes.
348                     Note actual space allocated in the qcow2 file may
351                     unused bytes in the allocated space will be initialized
359 stripes in the key slot and key size. Refer to the LUKS format
360 specification ('docs/on-disk-format.pdf' in the cryptsetup source
367 qcow2 cluster aligned. Its value is currently never used in the
373 to the start of the LUKS header clusters in the qcow2 container,
410 When an encryption method is requested in the header, the image payload
418    The AES cipher, in CBC mode, with 256 bit keys.
423    This format is no longer supported in QEMU system emulators, due
425    supported in the command line tools for the sake of back compatibility
430    The algorithms are specified in the LUKS header.
433    in the LUKS header, with the physical disk sector as the
443 The refcounts are managed in a two-level table. The first level is called
444 refcount table and has a variable size (which is stored in the header). The
446 in the image file.
449 blocks and are exactly one cluster in size.
458 4, it is unable to reference host resources beyond 2 EB (61 bits); in
489                     bit in this context.
497 The L1 table has a variable size (stored in the header) and may use multiple
498 clusters, however it must be contiguous in the image file. L2 tables are
499 exactly one cluster in size.
539                     in the active L1 table.
550                     This information is only accurate in L2 tables
589                     in the previous field. Some of these sectors may reside
590                     in the next contiguous host cluster.
593                     all of the bytes in the final sector; rather, decompression
600 file (except if bit 0 in the Standard Cluster Descriptor is set). If there is
613 subclusters so they are treated the same as in images without this feature.
621 in the previous section, with the exception of bit 0 of the standard cluster
664 a write causes a COW and isn't visible in other snapshots.
666 When loading a snapshot, bit 63 of all entries in the new active L1 table and
668 as it doesn't need to be accurate in inactive L1 tables.
670 A directory of all snapshots is stored in the snapshot table, a contiguous area
671 in the image file, whose starting offset and length are given by the header
680          8 - 11:    Number of entries in the L1 table of the snapshots
686         16 - 19:    Time at which the snapshot was taken in seconds since the
690                     in nanoseconds
693                     taken in nanoseconds
695         32 - 35:    Size of the VM state in bytes. 0 if no VM state is saved.
702         36 - 39:    Size of extra data in the table entry (used for future
709                     Byte 40 - 47:   Size of the VM state in bytes. 0 if no VM
711                                     the 32-bit value in bytes 32-35 is ignored.
713                     Byte 48 - 55:   Virtual disk size of the snapshot in bytes
736 All stored bitmaps are related to the virtual disk stored in the same image, so
740 disk. For bit number bit_nr the corresponding range (in bytes) will be:
749 Each bitmap saved in the image is described in a bitmap directory entry. The
750 bitmap directory is a contiguous area in the image file, whose starting offset
763                     Number of entries in the bitmap table of the bitmap.
824                     Extra data must never contain references to clusters or in
842 Each bitmap table has a variable size (stored in the bitmap directory entry)
843 and may use multiple clusters, however, it must be contiguous in the image
857                     unallocated; in that case, bit 0 determines how this
865 As noted above, bitmap data is stored in separate clusters, described by the
866 bitmap table. Given an offset (in bytes) into the bitmap data, the offset into
893 When the virtual disk is in use dirty tracking bitmap may be 'enabled' or
895 should be reflected in the bitmap. A set bit in the bitmap means that the
899 The software doesn't have to sync the bitmap in the image file with its
900 representation in RAM after each write or metadata change. Flag 'in_use'