Lines Matching full:the
6 (host) clusters. A cluster is the unit in which all allocations are done,
9 Likewise, the virtual disk as seen by the guest is divided into (guest)
10 clusters of the same size.
17 The first cluster of a qcow2 image contains the file header::
26 Offset into the image file at which the backing file name
27 is stored (NB: The string is not null terminated). 0 if the
34 Length of the backing file name in bytes. Must not be
35 longer than 1023 bytes. Undefined if the image doesn't have
40 within a cluster (1 << cluster_bits is the cluster size).
44 as the maximum cluster size and won't be able to open images
47 Note: if the image has Extended L2 Entries then cluster_bits
54 the maximum L1 table size. With a 2 MB cluster
70 Number of entries in the active L1 table
73 Offset into the image file at which the active L1 table
77 Offset into the image file at which the refcount table
81 Number of clusters that the refcount table occupies
84 Number of snapshots contained in the image
87 Offset into the image file at which the snapshot table
90 For version 2, the header is exactly 72 bytes in length, and finishes here.
91 For version 3 or higher, the header length is at least 104 bytes, including
92 the next fields through ``header_length``.
101 tables to repair refcounts before accessing the
105 structure may be corrupt and the image must not
111 then stored in the external data file. For such
112 images, clusters in the external data file are
113 not refcounted. The offset field in the
114 Standard Cluster Descriptor must match the
123 clusters. The compression_type field must be
128 allows subcluster-based allocation. See the
139 marking the image file dirty and postponing
147 clears the respective bits from this field first.
150 This bit indicates consistency for the bitmaps
153 It is an error if this bit is set without the
156 If the bitmaps extension is present but this
157 bit is unset, the bitmaps extension data must be
161 If this bit is set, the external data file can
163 without looking at the qcow2 metadata.
166 some operations on the image (e.g. writing
167 zeros requires writing to the data file instead
168 of only setting the zero flag in the L2 table
171 This bit may only be set if the External Data
178 Describes the width of a reference count block entry (width
180 images, the order is always assumed to be 4
185 Length of the header structure in bytes. For version 2
186 images, the length is always assumed to be 72 bytes.
194 In general, these fields are optional and may be safely ignored by the software,
197 formally, additional fields have the following compatibility rules:
199 1. If the value of the additional field must not be ignored for correct
200 handling of the file, it will be accompanied by a corresponding incompatible
205 rewriting the image header.
209 3. An explicit value of 0 will have the same behavior as when the field is not
213 to the field's offset. Also, all additional fields are not present for
220 Defines the compression method used for compressed clusters.
221 All compressed clusters in an image use the same compression
224 If the incompatible bit "Compression type" is set: the field
233 The deflate compression type is called "zlib"
234 <https://www.zlib.net/> in QEMU. However, clusters with the
242 ``header_length`` must be a multiple of 8, which means that if the end of the last
245 the padding, it will be interpreted accordingly to point `[3.] <#ref_rules_3>`_ of the previous
246 paragraph, i.e. in the same manner as when this field is not present.
252 Directly after the image header, optional sections called header extensions can
253 be stored. Each extension has a structure like the following::
256 0x00000000 - End of the header extension area
265 4 - 7: Length of the header extension data
269 n - m: Padding to round up the header extension size to the next
273 in the same image.
275 If the image has a backing file then the backing file name should be stored in
276 the remaining space between the end of the header extension area and the end of
277 the first cluster. It is not allowed to store other data here, so that an
278 implementation can safely modify the header and add extensions without harming
286 Some header extensions (such as the backing file format name and the external
287 data file name) are just a single string. In this case, the header extension
288 length is the string length and the string is not ``\0`` terminated. (The header
297 The feature name table is an optional header extension that contains the name
298 for features used by the image. It can be used by applications that don't know
299 the respective feature (e.g. because the feature was introduced only later) to
302 The number of entries in the feature name table is determined by the length of
303 the header extension data. Each entry looks like this::
310 1: Bit number within the selected feature bitmap (valid
320 The bitmaps extension is an optional header extension. It provides the ability
322 type: the dirty tracking bitmap, which tracks virtual disk changes from some
325 The data of the extension should be considered consistent only if the
328 The fields of the bitmaps extension are::
331 The number of bitmaps contained in the image. Must be
340 Size of the bitmap directory in bytes. It is the cumulative
344 Offset into the image file at which the bitmap directory
350 The full disk encryption header must be present if, and only if, the
352 of the ``LUKS`` crypt method. The header extension must be absent for
355 This header provides the offset at which the crypt method can store
356 its additional data, as well as the length of such data.
359 Byte 0 - 7: Offset into the image file at which the encryption
362 Byte 8 - 15: Length of the written encryption header in bytes.
363 Note actual space allocated in the qcow2 file may
365 to the nearest multiple of the cluster size. Any
366 unused bytes in the allocated space will be initialized
369 For the LUKS crypt method, the encryption header works as follows.
371 The first 592 bytes of the header clusters will contain the LUKS
372 partition header. This is then followed by the key material data areas.
373 The size of the key material data areas is determined by the number of
374 stripes in the key slot and key size. Refer to the LUKS format
375 specification (``docs/on-disk-format.pdf`` in the cryptsetup source
376 package) for details of the LUKS partition header format.
378 In the LUKS partition header, the ``payload-offset`` field will be
379 calculated as normal for the LUKS spec. ie the size of the LUKS
380 header, plus key material regions, plus padding, relative to the
381 start of the LUKS header. This offset value is not required to be
382 qcow2 cluster aligned. Its value is currently never used in the
383 context of qcow2, since the qcow2 file format itself defines where
384 the real payload offset is, but none the less a valid payload offset
387 In the LUKS key slots header, the ``key-material-offset`` is relative
388 to the start of the LUKS header clusters in the qcow2 container,
389 not the start of the qcow2 file.
391 Logically the layout looks like
427 When an encryption method is requested in the header, the image payload
428 data must be encrypted/decrypted on every write/read. The image headers
431 The algorithms used for encryption vary depending on the method
435 The AES cipher, in CBC mode, with 256 bit keys.
438 the virtual disk sector as the input tweak.
442 supported in the command line tools for the sake of back compatibility
447 The algorithms are specified in the LUKS header.
449 Initialization vectors generated using the method specified
450 in the LUKS header, with the physical disk sector as the
456 qcow2 manages the allocation of host clusters by maintaining a reference count
457 for each host cluster. A refcount of 0 means that the cluster is free, 1 means
461 The refcounts are managed in a two-level table. The first level is called
462 refcount table and has a variable size (which is stored in the header). The
464 in the image file.
466 It contains pointers to the second level structures which are called refcount
470 (56 bits) (assuming the underlying protocol can even be sized that
475 QEMU has an implementation limit of 8 MB as the maximum refcount
478 the worst case, with a 512 cluster size and refcount_order of 6, it is
481 Given an offset into the image file, the refcount of its cluster can be
496 9 - 63: Bits 9-63 of the offset into the image file at which the
500 If this is 0, the corresponding refcount block has not yet
506 Bit 0 - x: Reference count of the cluster. If refcount_bits implies a
507 sub-byte width, note that bit 0 means the least significant
514 Just as for refcounts, qcow2 uses a two-level structure for the mapping of
517 The L1 table has a variable size (stored in the header) and may use multiple
518 clusters, however it must be contiguous in the image file. L2 tables are
521 The L1 and L2 tables have implications on the maximum virtual file
523 the guest to have access to more space. Furthermore, a virtual
526 use). Additionally, as cluster size increases, the maximum host
531 Given an offset into the virtual disk, the offset into the image file can be
550 9 - 55: Bits 9-55 of the offset into the image file at which the L2
551 table starts. Must be aligned to a cluster boundary. If the
552 offset is 0, the L2 table and all clusters described by this
559 in the active L1 table.
571 that are reachable from the active L1 table.
574 implicit refcount of 1 (because of the fixed host = guest
580 Bit 0: If set to 1, the cluster reads as all zeros. The host
583 nor is data read from the backing file if the cluster is
586 With version 2 or with extended L2 entries (see the next
592 cluster boundary. If the offset is 0 and bit 63 is clear,
593 the cluster is unallocated. The offset may only be 0 with
607 x - 61: Number of additional 512-byte sectors used for the
608 compressed data, beyond the sector containing the offset
609 in the previous field. Some of these sectors may reside
610 in the next contiguous host cluster.
612 Note that the compressed data does not necessarily occupy
613 all of the bytes in the final sector; rather, decompression
616 Another compressed cluster may map to the tail of the final
619 If a cluster is unallocated, read requests shall read the data from the backing
620 file (except if bit 0 in the Standard Cluster Descriptor is set). If there is
621 no backing file or the backing file is smaller than the image, they shall read
622 zeros for all parts that are not covered by the backing file.
627 An image uses Extended L2 Entries if bit 4 is set on the incompatible_features
628 field of the header.
630 In these images standard data clusters are divided into 32 subclusters of the
631 same size. They are contiguous and start from the beginning of the cluster.
632 Subclusters can be allocated independently and the L2 entry contains information
633 indicating the status of each one of them. Compressed data clusters don't have
634 subclusters so they are treated the same as in images without this feature.
636 The size of an extended L2 entry is 128 bits so the number of entries per table
643 The first 64 bits have the same format as the standard L2 table entry described
644 in the previous section, with the exception of bit 0 of the standard cluster
647 The last 64 bits contain a subcluster allocation bitmap with this format:
653 1: the subcluster is allocated. In this case the
656 0: the subcluster is not allocated. In this case
657 read requests shall go to the backing file or
660 Bits are assigned starting from the least significant
665 1: the subcluster reads as zeros. In this case the
666 allocation status bit must be unset. The host
670 Bits are assigned starting from the least significant
683 switch the active L1 table, so that a different set of host clusters are
684 exposed to the guest.
686 When creating a snapshot, the L1 table should be copied and the refcount of all
690 When loading a snapshot, bit 63 of all entries in the new active L1 table and
691 all L2 tables referenced by it must be reconstructed from the refcount table
694 A directory of all snapshots is stored in the snapshot table, a contiguous area
695 in the image file, whose starting offset and length are given by the header
696 fields snapshots_offset and nb_snapshots. The entries of the snapshot table
697 have variable length, depending on the length of ID, name and extra data.
701 Byte 0 - 7: Offset into the image file at which the L1 table for the
704 8 - 11: Number of entries in the L1 table of the snapshots
706 12 - 13: Length of the unique ID string describing the snapshot
708 14 - 15: Length of the name of the snapshot
710 16 - 19: Time at which the snapshot was taken in seconds since the
713 20 - 23: Subsecond part of the time at which the snapshot was taken
716 24 - 31: Time that the guest was running until the snapshot was
719 32 - 35: Size of the VM state in bytes. 0 if no VM state is saved.
720 If there is VM state, it starts at the first cluster
724 larger than the virtual disk presented to the guest)
726 36 - 39: Size of extra data in the table entry (used for future
727 extensions of the format)
733 Byte 40 - 47: Size of the VM state in bytes. 0 if no VM
735 the 32-bit value in bytes 32-35 is ignored.
737 Byte 48 - 55: Virtual disk size of the snapshot in bytes
740 the record/replay instruction count
741 when the snapshot was taken. Set to -1
747 variable: Unique ID string for the snapshot (not null terminated)
749 variable: Name of the snapshot (not null terminated)
751 variable: Padding to round up the snapshot table entry size to the
758 As mentioned above, the bitmaps extension provides the ability to store bitmaps
761 All stored bitmaps are related to the virtual disk stored in the same image, so
762 each bitmap size is equal to the virtual disk size.
764 Each bit of the bitmap is responsible for strictly defined range of the virtual
765 disk. For bit number bit_nr the corresponding range (in bytes) will be:
771 Granularity is a property of the concrete bitmap, see below.
777 Each bitmap saved in the image is described in a bitmap directory entry. The
778 bitmap directory is a contiguous area in the image file, whose starting offset
779 and length are given by the header extension fields ``bitmap_directory_offset`` and
780 ``bitmap_directory_size``. The entries of the bitmap directory have variable
781 length, depending on the lengths of the bitmap name and extra data.
786 Offset into the image file at which the bitmap table
787 (described below) for the bitmap starts. Must be aligned to
791 Number of entries in the bitmap table of the bitmap.
796 The bitmap was not saved correctly and may be
797 inconsistent. Although the bitmap metadata is still
798 well-formed from a qcow2 perspective, the metadata
799 (such as the auto flag or bitmap size) or data
803 The bitmap must reflect all changes of the virtual
805 file (including writes, snapshot switching, etc.). The
809 This flags is meaningful when the extra data is
810 unknown to the software (currently any extra data is
812 If it is set, the bitmap may be used as expected, extra
814 If it is not set, the bitmap must not be used, but
820 This field describes the sort of the bitmap.
834 A bitmap's granularity is how many bytes of the image
835 accounts for one bit of the bitmap.
838 Size of the bitmap name. Must be non-zero.
847 reserved and should be zero. If it is non-zero the
851 Extra data for the bitmap, occupying extra_data_size bytes.
856 The name of the bitmap (not null terminated), occupying
858 within the bitmaps extension.
860 variable: Padding to round up the bitmap directory entry size to the
861 next multiple of 8. All bytes of the padding must be zero.
868 structures like for refcounts and guest clusters mapping) for the mapping of
869 bitmap data to host clusters. This structure is called the bitmap table.
871 Each bitmap table has a variable size (stored in the bitmap directory entry)
872 and may use multiple clusters, however, it must be contiguous in the image
884 9 - 55: Bits 9 - 55 of the host cluster offset. Must be aligned to
885 a cluster boundary. If the offset is 0, the cluster is
895 As noted above, bitmap data is stored in separate clusters, described by the
896 bitmap table. Given an offset (in bytes) into the bitmap data, the offset into
897 the image file can be obtained as follows::
906 Given an offset byte_nr into the virtual disk and the bitmap's granularity, the
907 bit offset into the image file to the corresponding bit of the bitmap can be
914 If the size of the bitmap data is not a multiple of the cluster size then the
915 last cluster of the bitmap data contains some unused tail bits. These bits must
924 When the virtual disk is in use dirty tracking bitmap may be ``enabled`` or
925 ``disabled``. While the bitmap is ``enabled``, all writes to the virtual disk
926 should be reflected in the bitmap. A set bit in the bitmap means that the
927 corresponding range of the virtual disk (see above) was written to while the
930 The software doesn't have to sync the bitmap in the image file with its
932 should be set while the bitmap is not synced.
934 In the image file the ``enabled`` state is reflected by the ``auto`` flag. If this
935 flag is set, the software must consider the bitmap as ``enabled`` and start
936 tracking virtual disk changes to this bitmap from the first write to the
937 virtual disk. If this flag is not set then the bitmap is disabled.