Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

21.14. virt-sparsify: Reclaiming Empty Disk Space

The virt-sparsify command-line tool can be used to make a virtual machine disk (or any disk image) sparse. This is also known as thin-provisioning. Free disk space on the disk image is converted to free space on the host.
The virt-sparsify command can work with most filesystems, such as ext2, ext3, ext4, btrfs, NTFS. It also works with LVM physical volumes. virt-sparsify can operate on any disk image, not just virtual machine disk images.

Warning

Using virt-sparsify on live virtual machines, or concurrently with other disk editing tools can cause disk corruption. The virtual machine must be shut down before using this command. In addition, disk images should not be edited concurrently.
The command can also be used to convert between some disk formats. For example, virt-sparsify can convert a raw disk image to a thin-provisioned qcow2 image.

Note

If a virtual machine has multiple disks and uses volume management, virt-sparsify will work, but it will not be very effective.
If the input is raw, then the default output is raw sparse. The size of the output image must be checked using a tool that understands sparseness.
$ ls -lh test1.img
-rw-rw-r--. 1 rjones rjones 100M Aug  8 08:08 test1.img
$ du -sh test1.img
3.6M   test1.img
Note that the ls command shows the image size to be 100M. However, the du command correctly shows the image size to be 3.6M.

Important limitations

The following is a list of important limitations:
  • The virtual machine must be shutdown before using virt-sparsify.
  • In a worst case scenario, virt-sparsify may require up to twice the virtual size of the source disk image. One for the temporary copy and one for the destination image.
    If you use the --in-place option, large amounts of temporary space are not needed.
  • virt-sparsify cannot be used to resize disk images. To resize disk images, use virt-resize. For information about virt-resize, see Section 21.8, “virt-resize: Resizing Guest Virtual Machines Offline”.
  • virt-sparsify does not work with encrypted disks, because encrypted disks cannot be sparsified.
  • virt-sparsify cannot sparsify the space between partitions. This space is often used for critical items like bootloaders, so it is not really unused space.
  • In copy mode, qcow2 internal snapshots are not copied to the destination image.

Examples

To install virt-sparsify, run one of the following commands:
# yum install /usr/bin/virt-sparsify
or
# yum install libguestfs-tools-c
To sparsify a disk:
# virt-sparsify /dev/sda1 /dev/device
Copies the contents of /dev/sda1 to /dev/device, making the output sparse. If /dev/device already exists, it is overwritten. The format of /dev/sda1 is detected and used as the format for /dev/device.
To convert between formats:
# virt-sparsify disk.raw --convert qcow2 disk.qcow2
Tries to zero and sparsify free space on every filesystem it can find within the source disk image.
To prevent free space from being overwritten with zeros on certain filesystems:
# virt-sparsify --ignore /dev/device /dev/sda1 /dev/device
Creates sparsified disk images from all filesystems in the disk image, without overwriting free space on the filesystems with zeros.
To make a disk image sparse without creating a temporary copy:
# virt-sparsify --in-place disk.img
Makes the specified disk image sparse, overwriting the image file.

virt-sparsify options

The following command options are available to use with virt-sparsify:

Table 21.4. virt-sparsify options

Command Description Example
--help Displays a brief help entry about a particular command or about the virt-sparsify utility. For additional help, see the virt-sparsify man page. $ virt-sparsify --help
--check-tmpdir ignore|continue|warn|fail Estimates if tmpdir has enough space to complete the operation. The specified option determines the behavior if there is not enough space to complete the operation.
  • ignore: The issue is ignored and the operation continues.
  • continue: Reports an error and the operation continues.
  • warn: Reports an error and waits for the user to press Enter.
  • fail: Reports an error and aborts the operation.
This option cannot be used with the ‑‑in-place option.
$ virt-sparsify --check-tmpdir ignore /dev/sda1 /dev/device
$ virt-sparsify --check-tmpdir continue /dev/sda1 /dev/device
$ virt-sparsify --check-tmpdir warn /dev/sda1 /dev/device
$ virt-sparsify --check-tmpdir fail /dev/sda1 /dev/device
--compress Compresses the output file. This only works if the output format is qcow2. This option cannot be used with the ‑‑in-place option. $ virt-sparsify --compress /dev/sda1 /dev/device
--convert
Creates the sparse image using a specified format. If no format is specified, the input format is used.
The following output formats are supported and known to work: raw, qcow, vdi
You can use any format supported by the QEMU emulator.
It is recommended that you use the --convert option. This way, virt-sparsify does not need to guess the input format.
This option cannot be used with the ‑‑in-place option.
$ virt-sparsify --convert raw /dev/sda1 /dev/device
$ virt-sparsify --convert qcow2 /dev/sda1 /dev/device
$ virt-sparsify --convert other_format indisk outdisk
--format Specifies the format of the input disk image. If not specified, the format is detected from the image. When working with untrusted raw-format guest disk images, ensure to specify the format.
$ virt-sparsify --format raw /dev/sda1 /dev/device
$ virt-sparsify --format qcow2 /dev/sda1 /dev/device
--ignore
Ignores the specified file system or volume group.
When a filesystem is specified and the --in-place option is not specified, free space on the filesystem is not zeroed. However, existing blocks of zeroes are sparsified. When the ‑‑in-place option is specified, the filesystem is completely ignored.
When a volume group is specified, the volume group is ignored. The volume group name should be used without the /dev/ prefix. For example, ‑‑ignore vg_foo
The --ignore option can be included in the command multiple times.
$ virt-sparsify --ignore filesystem1 /dev/sda1 /dev/device
$ virt-sparsify --ignore volume_group/dev/sda1 /dev/device
--in-place
Makes an image sparse in-place, instead of making a temporary copy. Although in-place sparsification is more efficient than copying sparsification, it cannot recover quite as much disk space as copying sparsification. In-place sparsification works using discard (also known as trim or unmap) support.
To use in-place sparsification, specify a disk image that will be sparsified in-place.
When specifying in-place sparsification, the following options cannot be used:
  • --convert and --compress, because they require wholesale disk format changes.
    --check-tmpdir, because large amounts of temporary space are not required.
$ virt-sparsify --in-place disk.img
-x Enables tracing of libguestfs API calls. $ virt-sparsify -x filesystem1 /dev/sda1 /dev/device
For more information, including additional options, see libguestfs.org.