At least libvirt 0.10.2 has a bug where it can be provoked into attempting to search for extension headers (in particular, the backing file format header) without first validating that a particular file is qcow2 version 2. Fortunately, to date, this probe always ends early when feeding a version 3 file to this version of libvirt: the version 2 file treats bytes 72-75 as the magic number for an extension header, while version 3 treats it as the upper half of the 8-byte incompatible_features field. As long as we don't have that many incompatible features, these bytes are always 0, which aligns with the end-of-extension magic number, and forces the broken libvirt to quit looking for other headers in its v2 view of the world. But as future extensions may conceivably contain contents that would cause broken libvirt to misbehave if it kept looking for headers, it is better to codify this into the qcow2 v3 specification.
No qemu code changes are required by this doc patch - anyone setting bits within bytes 72-75 already causes the file to be rejected as an invalid qcow2 v3 file by all current v3 implementations. And cutting the field from 8 bytes to 4 has no real serious consequence - if we ever have that many incompatible bits in the future, we can always declare bit 31 as an incompatible feature bit that says where else to look for any further needed incompatible feature bits. [If we had a time machine, I would propose that we make bytes 72-79 of the version 3 header resemble a well-formed extension header of version 2, and move incompatible_features to offset 80 or later - but that's what we get for having hindsight.] * docs/specs/qcow2.txt: Formally define what happened to be an accidental feature protecting us from buggy v2 clients. Signed-off-by: Eric Blake <ebl...@redhat.com> --- docs/specs/qcow2.txt | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/specs/qcow2.txt b/docs/specs/qcow2.txt index f19536a..3acb46e 100644 --- a/docs/specs/qcow2.txt +++ b/docs/specs/qcow2.txt @@ -71,9 +71,23 @@ If the version is 3 or higher, the header has the following additional fields. For version 2, the values are assumed to be zero, unless specified otherwise in the description of a field. - 72 - 79: incompatible_features + 72 - 75: zero + This field must be 0; it occupies the same + position as the first extension header in version + 2 files, and using all 0 contents minimizes the + damage done by buggy v2 clients that fail to check + the version field, since they will stop trying to + look for other extension headers. + + 76 - 79: incompatible_features Bitmask of incompatible features. An implementation must fail to open an image if an unknown bit is set. + Note that this field is only 4 bytes, while the + other feature fields are 8 bytes; but if more than + 31 incompatible features are ever defined, it is + trivial to define the final bit of this field as + an incompatible feature that says where to look + for other incompatible feature bits. Bit 0: Dirty bit. If this bit is set then refcounts may be inconsistent, make sure to scan L1/L2 @@ -85,7 +99,9 @@ in the description of a field. be written to (unless for regaining consistency). - Bits 2-63: Reserved (set to 0) + Bits 2-31: Reserved (set to 0). Note that this + field + 80 - 87: compatible_features Bitmask of compatible features. An implementation can -- 1.8.4.2