New tool: virt-sparsify to make disk images sparse.

[libguestfs.git] / resize / virt-resize.pod

diff --git a/resize/virt-resize.pod b/resize/virt-resize.pod
index a071110..622d8b9 100644 (file)
--- a/resize/virt-resize.pod
+++ b/resize/virt-resize.pod
@@ -26,24 +26,48 @@ those manual pages first.
 
 =head1 EXAMPLES
 
+=over 4
+
+=item 1.
+
 Copy C<olddisk> to C<newdisk>, extending one of the guest's partitions
 to fill the extra 5GB of space.
 
- truncate -r olddisk newdisk; truncate -s +5G newdisk
  virt-filesystems --long -h --all -a olddisk
+ 
+ truncate -r olddisk newdisk
+ truncate -s +5G newdisk
+ 
  # Note "/dev/sda2" is a partition inside the "olddisk" file.
  virt-resize --expand /dev/sda2 olddisk newdisk
 
+=item 2.
+
 As above, but make the /boot partition 200MB bigger, while giving the
 remaining space to /dev/sda2:
 
- virt-resize --resize /dev/sda1=+200M --expand /dev/sda2 olddisk newdisk
+ virt-resize --resize /dev/sda1=+200M --expand /dev/sda2 \
+   olddisk newdisk
+
+=item 3.
 
-As above, but the output format will be uncompressed qcow2:
+As in the first example, but expand a logical volume as the final
+step.  This is what you would typically use for Linux guests that use
+LVM:
+
+ virt-resize --expand /dev/sda2 --LV-expand /dev/vg_guest/lv_root \
+   olddisk newdisk
+
+=item 4.
+
+As in the first example, but the output format will be qcow2 instead
+of a raw disk:
 
  qemu-img create -f qcow2 newdisk.qcow2 15G
  virt-resize --expand /dev/sda2 olddisk newdisk.qcow2
 
+=back
+
 =head1 DETAILED USAGE
 
 =head2 EXPANDING A VIRTUAL MACHINE DISK
@@ -325,6 +349,12 @@ You can give this option multiple times, I<but> it doesn't
 make sense to do this unless the logical volumes you specify
 are all in different volume groups.
 
+=item B<--machine-readable>
+
+This option is used to make the output more machine friendly
+when being parsed by other programs.  See
+L</MACHINE READABLE OUTPUT> below.
+
 =item B<-n>
 
 =item B<--dryrun>
@@ -459,6 +489,58 @@ Display version number and exit.
 
 =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-resize 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-resize binary.  Typical output looks like this:
+
+ $ virt-resize --machine-readable
+ virt-resize
+ ntfsresize-force
+ 32bitok
+ 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-resize exits with a non-zero status code
+if there was a fatal error.
+
+=back
+
+Versions of the program prior to 1.13.9 did not support the
+I<--machine-readable> option and will return an error.
+
 =head1 NOTES
 
 =head2 "Partition 1 does not end on cylinder boundary."
@@ -523,6 +605,11 @@ have meaning to the shell such as C<#> and space.  You may need to
 quote or escape these characters on the command line.  See the shell
 manual page L<sh(1)> for details.
 
+=head1 EXIT STATUS
+
+This program returns 0 if successful, or non-zero if there was an
+error.
+
 =head1 SEE ALSO
 
 L<virt-filesystems(1)>,
@@ -542,6 +629,7 @@ L<fallocate(1)>,
 L<grub(8)>,
 L<grub-install(8)>,
 L<virt-rescue(1)>,
+L<virt-sparsify(1)>,
 L<http://libguestfs.org/>.
 
 =head1 AUTHOR