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,
5 both for actual guest data and for image metadata.
7 Likewise, the virtual disk as seen by the guest is divided into (guest)
8 clusters of the same size.
10 All numbers in qcow2 are stored in Big Endian byte order.
15 The first cluster of a qcow2 image contains the file header:
18 QCOW magic string ("QFI\xfb")
21 Version number (valid values are 2 and 3)
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.
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
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).
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.
43 Virtual disk size in bytes
50 Number of entries in the active L1 table
52 40 - 47: l1_table_offset
53 Offset into the image file at which the active L1 table
54 starts. Must be aligned to a cluster boundary.
56 48 - 55: refcount_table_offset
57 Offset into the image file at which the refcount table
58 starts. Must be aligned to a cluster boundary.
60 56 - 59: refcount_table_clusters
61 Number of clusters that the refcount table occupies
64 Number of snapshots contained in the image
66 64 - 71: snapshots_offset
67 Offset into the image file at which the snapshot table
68 starts. Must be aligned to a cluster boundary.
70 If the version is 3 or higher, the header has the following additional fields.
71 For version 2, the values are assumed to be zero, unless specified otherwise
72 in the description of a field.
74 72 - 79: incompatible_features
75 Bitmask of incompatible features. An implementation must
76 fail to open an image if an unknown bit is set.
78 Bit 0: Dirty bit. If this bit is set then refcounts
79 may be inconsistent, make sure to scan L1/L2
80 tables to repair refcounts before accessing the
83 Bits 1-63: Reserved (set to 0)
85 80 - 87: compatible_features
86 Bitmask of compatible features. An implementation can
87 safely ignore any unknown bits that are set.
89 Bits 0-63: Reserved (set to 0)
91 88 - 95: autoclear_features
92 Bitmask of auto-clear features. An implementation may only
93 write to an image with unknown auto-clear features if it
94 clears the respective bits from this field first.
96 Bits 0-63: Reserved (set to 0)
98 96 - 99: refcount_order
99 Describes the width of a reference count block entry (width
100 in bits = 1 << refcount_order). For version 2 images, the
101 order is always assumed to be 4 (i.e. the width is 16 bits).
103 100 - 103: header_length
104 Length of the header structure in bytes. For version 2
105 images, the length is always assumed to be 72 bytes.
107 Directly after the image header, optional sections called header extensions can
108 be stored. Each extension has a structure like the following:
110 Byte 0 - 3: Header extension type:
111 0x00000000 - End of the header extension area
112 0xE2792ACA - Backing file format name
113 0x6803f857 - Feature name table
114 other - Unknown header extension, can be safely
117 4 - 7: Length of the header extension data
119 8 - n: Header extension data
121 n - m: Padding to round up the header extension size to the next
124 Unless stated otherwise, each header extension type shall appear at most once
127 The remaining space between the end of the header extension area and the end of
128 the first cluster can be used for the backing file name. It is not allowed to
129 store other data here, so that an implementation can safely modify the header
130 and add extensions without harming data of compatible features that it
131 doesn't support. Compatible features that need space for additional data can
132 use a header extension.
135 == Feature name table ==
137 The feature name table is an optional header extension that contains the name
138 for features used by the image. It can be used by applications that don't know
139 the respective feature (e.g. because the feature was introduced only later) to
140 display a useful error message.
142 The number of entries in the feature name table is determined by the length of
143 the header extension data. Each entry look like this:
145 Byte 0: Type of feature (select feature bitmap)
146 0: Incompatible feature
147 1: Compatible feature
150 1: Bit number within the selected feature bitmap (valid
153 2 - 47: Feature name (padded with zeros, but not necessarily null
154 terminated if it has full length)
157 == Host cluster management ==
159 qcow2 manages the allocation of host clusters by maintaining a reference count
160 for each host cluster. A refcount of 0 means that the cluster is free, 1 means
161 that it is used, and >= 2 means that it is used and any write access must
162 perform a COW (copy on write) operation.
164 The refcounts are managed in a two-level table. The first level is called
165 refcount table and has a variable size (which is stored in the header). The
166 refcount table can cover multiple clusters, however it needs to be contiguous
169 It contains pointers to the second level structures which are called refcount
170 blocks and are exactly one cluster in size.
172 Given a offset into the image file, the refcount of its cluster can be obtained
175 refcount_block_entries = (cluster_size / sizeof(uint16_t))
177 refcount_block_index = (offset / cluster_size) % refcount_block_entries
178 refcount_table_index = (offset / cluster_size) / refcount_block_entries
180 refcount_block = load_cluster(refcount_table[refcount_table_index]);
181 return refcount_block[refcount_block_index];
183 Refcount table entry:
185 Bit 0 - 8: Reserved (set to 0)
187 9 - 63: Bits 9-63 of the offset into the image file at which the
188 refcount block starts. Must be aligned to a cluster
191 If this is 0, the corresponding refcount block has not yet
192 been allocated. All refcounts managed by this refcount block
195 Refcount block entry (x = refcount_bits - 1):
197 Bit 0 - x: Reference count of the cluster. If refcount_bits implies a
198 sub-byte width, note that bit 0 means the least significant
202 == Cluster mapping ==
204 Just as for refcounts, qcow2 uses a two-level structure for the mapping of
205 guest clusters to host clusters. They are called L1 and L2 table.
207 The L1 table has a variable size (stored in the header) and may use multiple
208 clusters, however it must be contiguous in the image file. L2 tables are
209 exactly one cluster in size.
211 Given a offset into the virtual disk, the offset into the image file can be
214 l2_entries = (cluster_size / sizeof(uint64_t))
216 l2_index = (offset / cluster_size) % l2_entries
217 l1_index = (offset / cluster_size) / l2_entries
219 l2_table = load_cluster(l1_table[l1_index]);
220 cluster_offset = l2_table[l2_index];
222 return cluster_offset + (offset % cluster_size)
226 Bit 0 - 8: Reserved (set to 0)
228 9 - 55: Bits 9-55 of the offset into the image file at which the L2
229 table starts. Must be aligned to a cluster boundary. If the
230 offset is 0, the L2 table and all clusters described by this
231 L2 table are unallocated.
233 56 - 62: Reserved (set to 0)
235 63: 0 for an L2 table that is unused or requires COW, 1 if its
236 refcount is exactly one. This information is only accurate
237 in the active L1 table.
241 Bit 0 - 61: Cluster descriptor
243 62: 0 for standard clusters
244 1 for compressed clusters
246 63: 0 for a cluster that is unused or requires COW, 1 if its
247 refcount is exactly one. This information is only accurate
248 in L2 tables that are reachable from the the active L1
251 Standard Cluster Descriptor:
253 Bit 0: If set to 1, the cluster reads as all zeros. The host
254 cluster offset can be used to describe a preallocation,
255 but it won't be used for reading data from this cluster,
256 nor is data read from the backing file if the cluster is
259 With version 2, this is always 0.
261 1 - 8: Reserved (set to 0)
263 9 - 55: Bits 9-55 of host cluster offset. Must be aligned to a
264 cluster boundary. If the offset is 0, the cluster is
267 56 - 61: Reserved (set to 0)
270 Compressed Clusters Descriptor (x = 62 - (cluster_bits - 8)):
272 Bit 0 - x: Host cluster offset. This is usually _not_ aligned to a
275 x+1 - 61: Compressed size of the images in sectors of 512 bytes
277 If a cluster is unallocated, read requests shall read the data from the backing
278 file (except if bit 0 in the Standard Cluster Descriptor is set). If there is
279 no backing file or the backing file is smaller than the image, they shall read
280 zeros for all parts that are not covered by the backing file.
285 qcow2 supports internal snapshots. Their basic principle of operation is to
286 switch the active L1 table, so that a different set of host clusters are
287 exposed to the guest.
289 When creating a snapshot, the L1 table should be copied and the refcount of all
290 L2 tables and clusters reachable from this L1 table must be increased, so that
291 a write causes a COW and isn't visible in other snapshots.
293 When loading a snapshot, bit 63 of all entries in the new active L1 table and
294 all L2 tables referenced by it must be reconstructed from the refcount table
295 as it doesn't need to be accurate in inactive L1 tables.
297 A directory of all snapshots is stored in the snapshot table, a contiguous area
298 in the image file, whose starting offset and length are given by the header
299 fields snapshots_offset and nb_snapshots. The entries of the snapshot table
300 have variable length, depending on the length of ID, name and extra data.
302 Snapshot table entry:
304 Byte 0 - 7: Offset into the image file at which the L1 table for the
305 snapshot starts. Must be aligned to a cluster boundary.
307 8 - 11: Number of entries in the L1 table of the snapshots
309 12 - 13: Length of the unique ID string describing the snapshot
311 14 - 15: Length of the name of the snapshot
313 16 - 19: Time at which the snapshot was taken in seconds since the
316 20 - 23: Subsecond part of the time at which the snapshot was taken
319 24 - 31: Time that the guest was running until the snapshot was
322 32 - 35: Size of the VM state in bytes. 0 if no VM state is saved.
323 If there is VM state, it starts at the first cluster
324 described by first L1 table entry that doesn't describe a
325 regular guest cluster (i.e. VM state is stored like guest
326 disk content, except that it is stored at offsets that are
327 larger than the virtual disk presented to the guest)
329 36 - 39: Size of extra data in the table entry (used for future
330 extensions of the format)
332 variable: Extra data for future extensions. Unknown fields must be
333 ignored. Currently defined are (offset relative to snapshot
336 Byte 40 - 47: Size of the VM state in bytes. 0 if no VM
337 state is saved. If this field is present,
338 the 32-bit value in bytes 32-35 is ignored.
340 Byte 48 - 55: Virtual disk size of the snapshot in bytes
342 Version 3 images must include extra data at least up to
345 variable: Unique ID string for the snapshot (not null terminated)
347 variable: Name of the snapshot (not null terminated)