22.13. virt-diff: Listing the Differences between Virtual Machine Files

The virt-diff command-line tool can be used to lists the differences between files in two virtual machines disk images. The output shows the changes to a virtual machine's disk images after it has been running. The command can also be used to show the difference between overlays.

Note

You can use virt-diff safely on live guest virtual machines, because it only needs read-only access.
This tool finds the differences in file names, file sizes, checksums, extended attributes, file content and more between the running virtual machine and the selected image.

Note

The virt-diff command does not check the boot loader, unused space between partitions or within file systems, or "hidden" sectors. Therefore, it is recommended that you do not use this as a security or forensics tool.
To install virt-diff, run one of the following commands:
# yum install /usr/bin/virt-diff
or
# yum install libguestfs-tools-c
To specify two guests, you have to use the -a or -d option for the first guest, and the -A or -D option for the second guest. For example:
$ virt-diff -a old.img -A new.img
You can also use names known to libvirt. For example:
$ virt-diff -d oldguest -D newguest
The following command options are available to use with virt-diff:

Table 22.3. virt-diff options

Command Description Example
--help Displays a brief help entry about a particular command or about the virt-diff package. For additional help, see the virt-diff man page. $ virt-diff --help
-a [file] or --add [file]
Adds the specified file, which should be a disk image from the first virtual machine. If the virtual machine has multiple block devices, you must supply all of them with separate -a options.
The format of the disk image is auto-detected. To override this and force a particular format, use the --format option.
$ virt-customize --add /dev/vms/original.img -A /dev/vms/new.img
-a [URI] or --add [URI] Adds a remote disk. The URI format is compatible with guestfish. For more information, refer to Section 22.4.2, “Adding Files with guestfish”. $ virt-diff -a rbd://example.com[:port]/pool/newdisk -A rbd://example.com[:port]/pool/olddisk
--all Same as --extra-stats --times --uids --xattrs. $ virt-diff --all
--atime By default, virt-diff ignores changes in file access times, since those are unlikely to be interesting. Use the --atime option to show access time differences. $ virt-diff --atime
-A [file] Adds the specified file or URI, which should be a disk image from the second virtual machine. $ virt-diff --add /dev/vms/original.img -A /dev/vms/new.img
-c [URI] or --connect [URI] Connects to the given URI, if using libvirt. If omitted, then it connects to the default libvirt hypervisor. If you specify guest block devices directly (virt-diff -a), then libvirt is not used at all. $ virt-diff -c qemu:///system
--csv Provides the results in a comma-separated values (CSV) format. This format can be imported easily into databases and spreadsheets. For further information, see Note. virt-diff --csv
-d [guest] or --domain [guest] Adds all the disks from the specified guest virtual machine as the first guest virtual machine. Domain UUIDs can be used instead of domain names. $ virt-diff --domain 90df2f3f-8857-5ba9-2714-7d95907b1c9e
-D [guest] Adds all the disks from the specified guest virtual machine as the second guest virtual machine. Domain UUIDs can be used instead of domain names. $ virt-diff --D 90df2f3f-8857-5ba9-2714-7d95907b1cd4
--extra-stats Displays extra statistics. $ virt-diff --extra-stats
--format or --format=[raw|qcow2] The default for the -a/-A option is to auto-detect the format of the disk image. Using this forces the disk format for -a/-A options that follow on the command line. Using --format auto switches back to auto-detection for subsequent -a options (see the -a command above). $ virt-diff --format raw -a new.img -A old.img forces raw format (no auto-detection) for new.img and old.img, but virt-diff --format raw -a new.img --format auto -a old.img forces raw format (no auto-detection) for new.img and reverts to auto-detection for old.img. If you have untrusted raw-format guest disk images, you should use this option to specify the disk format. This avoids a possible security problem with malicious guests.
-h or --human-readable Displays file sizes in human-readable format. $ virt-diff -h
--time-days
Displays time fields for changed files as days before now (negative if in the future).
Note that 0 in the output means between 86,399 seconds (23 hours, 59 minutes, and 59 seconds) before now and 86,399 seconds in the future.
$ virt-diff --time-days
-v or --verbose Enables verbose messages for debugging purposes. $ virt-diff --verbose
-V or --version Displays the virt-diff version number and exits. $ virt-diff -V
-x Enables tracing of libguestfs API calls. $ virt-diff -x

Note

The comma-separated values (CSV) format can be difficult to parse. Therefore, it is recommended that for shell scripts, you should use csvtool and for other languages, use a CSV processing library (such as Text::CSV for Perl or Python's built-in csv library). In addition, most spreadsheets and databases can import CSV directly.
For more information, including additional options, refer to libguestfs.org.