[Qemu-devel] qcow2 corruption analysis tool

[Qemu-devel] qcow2 corruption analysis tool

[John Snow]

This may not be particularly exciting, but I recently had occasion to
learn some of the specifics of the qcow2 file format. Instead of
augmenting the existing qemu-img check tool, I took the chance to write
a little standalone tool as a learning exercise.

I have polished up the fruits of my labor and uploaded it to github:
https://github.com/jnsnow/qcheck

Please feel free to comment or critique as you see fit. If you see
things of-use that should be backported in qemu, report that here
on-list. If you have suggestions, comments etc to improve the standalone
tool, you can comment on the github issue tracker (or send me a mail to
my personal address, if you happen to know it.)

This is my 'initial commit' and still has a lot of stray threads of
various past incarnations, so there's a lot of cleanup that could be done.

I have released it as GPLv2, because I yanked the RBTree data structure
out of the Linux kernel. There is always the understanding that if the
non-kernel bits of source are interesting to you that you may ask me to
re-license those files.

I took no particular care to be compatible on Windows, OSX or BSD, so
odds are good that it isn't...

==

qcheck as a utility takes a qcow2 file as input and attempts to validate
the header, metadata, and all data pointers for simple errors and
problems like alignment, overlaps and collisions, and a few other simple
problems.

It is currently a read-only tool, it does not attempt to /repair/
problems, just report them in a verbose way to help identify the root
cause of failure in a corruption incident.

It does not use or attempt to invoke any qemu component, to hopefully be
slightly more tolerant of errant files.

It keeps a full map of the entire file with regards to what clusters are
metadata, guest data, vacant, leaked and so on. In the future I may
augment this with visualizations.

It does not currently support or attempt to validate snapshot tables or
VMState data. It probably has a lot of bugs regarding the handling and
analysis of V2/V3 qcow2 files.

==

Usage:

./qcheck [opts] <qcow2_file>

Additional logging presets and filters can be used:

Logging presets: these are all mutually exclusive, except for debug.
	-s --silent: No output whatsoever.
	-q --quiet: Fatal and nonfatal qcheck errors. (--log fw)
	-b --basic: Basic analysis and summaries. This is the default.
			(--log fwshiHLR)
	-v --verbose: Detailed problem analysis. (--log fwshiHLRpc)
	-x --deluge: Everything except debug output.
	-d --debug: The same as `--log d`.
		`--deluge --debug` or `-xd` enables all output.

-l [...] --log=[...]: detailed logging filters. Specify individual
output streams.
All filters are additive and will combine with presets.
-e [...] --exclude=[...]: exclude these filters.
	Will subtract filters from presets.

	'f': Fatal errors
	'w': Nonfatal errors
	's': Analysis summaries
	'h': Section headers
	'i': Info / misc.
	'p': Detailed problems reports
	'c': Successful test messages (Confirmation)
	'd': Debugging messages
	'H': qcow2 header information
	'L': L1 table
	'l': L2 tables
	'R': Refcount Table
	'2': Refcount Block entries (if 2+)
	'1': Refcount Block entries (if 1)
	'0': Refcount Block entries (if 0)
	'M': Dump metadata rangeset
	'D': Dump guest data rangeset
	'V': Dump vacant rangeset
	'F': Dump leaked ([F]orgotten) rangeset
	'A': Dump allocated rangeset
	'U': Dump unallocated rangeset
	'E': Dump entire rangeset



Thanks,
--js