X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=sparsify%2Fvirt-sparsify.pod;fp=sparsify%2Fvirt-sparsify.pod;h=3d88a5fef43a5c8f1cb55d46949521d729cadbe5;hb=fac15924f59a076c903d453d20305e00e1ae258a;hp=0000000000000000000000000000000000000000;hpb=293772bf7511dee41a1f3e842424678c1a6bf9e4;p=libguestfs.git diff --git a/sparsify/virt-sparsify.pod b/sparsify/virt-sparsify.pod new file mode 100644 index 0000000..3d88a5f --- /dev/null +++ b/sparsify/virt-sparsify.pod @@ -0,0 +1,284 @@ +=encoding utf8 + +=head1 NAME + +virt-sparsify - Make a virtual machine disk sparse + +=head1 SYNOPSIS + + virt-sparsify [--options] indisk outdisk + +=head1 DESCRIPTION + +Virt-sparsify is a tool which can make a virtual machine disk (or any +disk image) sparse a.k.a. thin-provisioned. This means that free +space within the disk image can be converted back to free space on the +host. + +Virt-sparsify can locate and sparsify free space in most filesystems +(eg. ext2/3/4, btrfs, NTFS, etc.), and also in LVM physical volumes. + +Virt-sparsify can also convert between some disk formats, for example +converting a raw disk image to a thin-provisioned qcow2 image. + +Virt-sparsify can operate on any disk image, not just ones from +virtual machines. If a virtual machine has multiple disk images, then +you must sparsify each one separately. + +=head2 IMPORTANT LIMITATIONS + +=over 4 + +=item * + +Virt-sparsify does not do in-place modifications. It copies from a +source image to a destination image, leaving the source unchanged. +I. + +=item * + +The virtual machine I before using this tool. + +=item * + +Virt-sparsify may require up to 2x the virtual size of the source disk +image (1 temporary copy + 1 destination image). This is in the worst +case and usually much less space is required. + +=item * + +Virt-sparsify cannot resize disk images. To do that, use +L. + +=item * + +Virt-sparsify cannot handle encrypted disks. + +=item * + +Virt-sparsify cannot yet sparsify the space between partitions. Note +that this space is often used for critical items like bootloaders so +it's not really unused. + +=item * + +Virt-sparsify does not yet know how to sparsify swapspace. It is not +safe to do this unless we can be sure there is no hibernation data, so +at the moment swap partitions are ignored. + +=back + +You may also want to read the manual pages for the associated tools +L and L before starting. + +=head1 EXAMPLES + +Typical usage is: + + virt-sparsify indisk outdisk + +which copies C to C, making the output sparse. +C is created, or overwritten if it already exists. The +format of the input disk is detected (eg. qcow2) and the same format +is used for the output disk. + +To convert between formats, use the I<--convert> option: + + virt-sparsify disk.raw --convert qcow2 disk.qcow2 + +Virt-sparsify tries to zero and sparsify free space on every +filesystem it can find within the source disk image. You can get it +to ignore (don't zero free space on) certain filesystems by doing: + + virt-sparsify --ignore /dev/sda1 indisk outdisk + +See L to get a list of filesystems within a disk +image. + +=head1 OPTIONS + +=over 4 + +=item B<--help> + +Display help. + +=item B<--convert> raw + +=item B<--convert> qcow2 + +=item B<--convert> [other formats] + +Use C as the format for the destination image. If this +is not specified, then the input format is used. + +Supported and known-working output formats are: C, C. + +You can also use any format supported by the L program, +eg. C or C, but support for other formats is reliant on +qemu. + +Specifying the I<--convert> option is usually a good idea, because +then virt-sparsify doesn't need to try to guess the input format. + +=item B<--format> raw + +=item B<--format> qcow2 + +Specify the format of the input disk image. If this flag is not +given then it is auto-detected from the image itself. + +If working with untrusted raw-format guest disk images, you should +ensure the format is always specified. + +=item B<--ignore> filesystem + +=item B<--ignore> volgroup + +Ignore the named filesystem. Free space on the filesystem will not be +zeroed, but existing blocks of zeroes will still be sparsified. + +In the second form, this ignores the named volume group. Use the +volume group name without the C prefix, eg. I<--ignore vg_foo> + +You can give this option multiple times. + +=item B<--machine-readable> + +This option is used to make the output more machine friendly +when being parsed by other programs. See +L below. + +=item B<-q> + +=item B<--quiet> + +This disables progress bars and other unnecessary output. + +=item B<-v> + +=item B<--verbose> + +Enable verbose messages for debugging. + +=item B<-V> + +=item B<--version> + +Display version number and exit. + +=item B<-x> + +Enable tracing of libguestfs API calls. + +=back + +=head1 MACHINE READABLE OUTPUT + +The I<--machine-readable> option can be used to make the output more +machine friendly, which is useful when calling virt-sparsify from +other programs, GUIs etc. + +There are two ways to use this option. + +Firstly use the option on its own to query the capabilities of the +virt-sparsify binary. Typical output looks like this: + + $ virt-sparsify --machine-readable + virt-sparsify + ntfs + btrfs + +A list of features is printed, one per line, and the program exits +with status 0. + +Secondly use the option in conjunction with other options to make the +regular program output more machine friendly. + +At the moment this means: + +=over 4 + +=item 1. + +Progress bar messages can be parsed from stdout by looking for this +regular expression: + + ^[0-9]+/[0-9]+$ + +=item 2. + +The calling program should treat messages sent to stdout (except for +progress bar messages) as status messages. They can be logged and/or +displayed to the user. + +=item 3. + +The calling program should treat messages sent to stderr as error +messages. In addition, virt-sparsify exits with a non-zero status +code if there was a fatal error. + +=back + +All versions of virt-sparsify have supported the I<--machine-readable> +option. + +=head1 EXIT STATUS + +This program returns 0 if successful, or non-zero if there was an +error. + +=head1 ENVIRONMENT VARIABLES + +=over 4 + +=item TMPDIR + +Location of the temporary directory used for the potentially large +temporary overlay file. + +You should ensure there is enough free space in the worst case for a +full copy of the source disk (I size), or else set C<$TMPDIR> +to point to another directory that has enough space. + +This defaults to C. + +=back + +For other environment variables, see L. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, +L, +L, +L. + +=head1 AUTHOR + +Richard W.M. Jones L + +=head1 COPYRIGHT + +Copyright (C) 2011 Red Hat Inc. + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.