protocol: Memory leak: Free temporary buffer along recv_discard path.

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

diff --git a/resize/virt-resize.pod b/resize/virt-resize.pod
index c84e40f..abf190e 100644 (file)
--- a/resize/virt-resize.pod
+++ b/resize/virt-resize.pod
@@ -26,24 +26,48 @@ those manual pages first.
 
 =head1 EXAMPLES
 
 
 =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.
 
 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
  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
 
  # 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:
 
 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 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 above, but the output format will be uncompressed qcow2:
+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
 
 
  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
 =head1 DETAILED USAGE
 
 =head2 EXPANDING A VIRTUAL MACHINE DISK


@@ -133,9 +157,9 @@ to fill the rest of the available space:
 If the expanded partition in the image contains a filesystem or LVM
 PV, then if virt-resize knows how, it will resize the contents, the
 equivalent of calling a command such as L<pvresize(8)>,
 If the expanded partition in the image contains a filesystem or LVM
 PV, then if virt-resize knows how, it will resize the contents, the
 equivalent of calling a command such as L<pvresize(8)>,

-L<resize2fs(8)> or L<ntfsresize(8)>.  However virt-resize does not
-know how to resize some filesystems, so you would have to online
-resize them after booting the guest.
+L<resize2fs(8)>, L<ntfsresize(8)> or L<btrfs(8)>.  However virt-resize
+does not know how to resize some filesystems, so you would have to
+online resize them after booting the guest.

 
 Other options are covered below.
 
 
 Other options are covered below.
 


@@ -214,6 +238,27 @@ Similarly, to get non-sparse raw output use:
 (on older systems that don't have the L<fallocate(1)> command use
 C<dd if=/dev/zero of=outdisk bs=1M count=..>)
 
 (on older systems that don't have the L<fallocate(1)> command use
 C<dd if=/dev/zero of=outdisk bs=1M count=..>)
 

+=head2 LOGICAL PARTITIONS
+
+Logical partitions (a.k.a. C</dev/sda5+> on disks using DOS partition
+tables) cannot be resized.
+
+To understand what is going on, firstly one of the four partitions
+C</dev/sda1-4> will have MBR partition type C<05> or C<0f>.  This is
+called the B<extended partition>.  Use L<virt-filesystems(1)> to see
+the MBR partition type.
+
+Logical partitions live inside the extended partition.
+
+The extended partition can be expanded, but not shrunk (unless you
+force it, which is not advisable).  When the extended partition is
+copied across, all the logical partitions contained inside are copied
+over implicitly.  Virt-resize does not look inside the extended
+partition, so it copies the logical partitions blindly.
+
+You cannot specify a logical partition (C</dev/sda5+>) at all on the
+command line.  Doing so will give an error.
+

 =head1 OPTIONS
 
 =over 4
 =head1 OPTIONS
 
 =over 4


@@ -222,57 +267,80 @@ C<dd if=/dev/zero of=outdisk bs=1M count=..>)
 
 Display help.
 
 
 Display help.
 

-=item B<-V>
+=item B<--align-first auto>

 
 

-=item B<--version>
+=item B<--align-first never>

 
 

-Display version number and exit.
+=item B<--align-first always>

 
 

-=item B<--resize part=size>
+Align the first partition for improved performance (see also the
+I<--alignment> option).

 
 

-Resize the named partition (expanding or shrinking it) so that it has
-the given size.
+The default is I<--align-first auto> which only aligns the first
+partition if it is safe to do so.  That is, only when we know how to
+fix the bootloader automatically, and at the moment that can only be
+done for Windows guests.

 
 

-C<size> can be expressed as an absolute number followed by
-b/K/M/G to mean bytes, Kilobytes, Megabytes, or Gigabytes;
-or as a percentage of the current size;
-or as a relative number or percentage.
-For example:
+I<--align-first never> means we never move the first partition.
+This is the safest option.  Try this if the guest does not boot
+after resizing.

 
 

- --resize /dev/sda2=10G
+I<--align-first always> means we always align the first partition (if
+it needs to be aligned).  For some guests this will break the
+bootloader, making the guest unbootable.

 
 

- --resize /dev/sda4=90%
+=item B<--alignment N>

 
 

- --resize /dev/sda2=+1G
+Set the alignment of partitions to C<N> sectors.  The default in
+virt-resize E<lt> 1.13.19 was 64 sectors, and after that is 128
+sectors.

 
 

- --resize /dev/sda2=-200M
+Assuming 512 byte sector size inside the guest, here are some
+suitable values for this:

 
 

- --resize /dev/sda1=+128K
+=over 4

 
 

- --resize /dev/sda1=+10%
+=item I<--alignment 1> (512 bytes)

 
 

- --resize /dev/sda1=-10%
+The partitions would be packed together as closely as possible, but
+would be completely unaligned.  In some cases this can cause very poor
+performance.  See L<virt-alignment-scan(1)> for further details.

 
 

-You can increase the size of any partition.  Virt-resize will expand
-the direct content of the partition if it knows how (see I<--expand>
-below).
+=item I<--alignment 8> (4K)

 
 

-You can only I<decrease> the size of partitions that contain
-filesystems or PVs which have already been shrunk.  Virt-resize will
-check this has been done before proceeding, or else will print an
-error (see also I<--resize-force>).
+This would be the minimum acceptable alignment for reasonable
+performance on modern hosts.

 
 

-You can give this option multiple times.
+=item I<--alignment 128> (64K)

 
 

-=item B<--resize-force part=size>
+This alignment provides good performance when the host is using high
+end network storage.

 
 

-This is the same as I<--resize> except that it will let you decrease
-the size of any partition.  Generally this means you will lose any
-data which was at the end of the partition you shrink, but you may not
-care about that (eg. if shrinking an unused partition, or if you can
-easily recreate it such as a swap partition).
+=item I<--alignment 2048> (1M)

 
 

-See also the I<--ignore> option.
+This is the standard alignment used by all newly installed guests
+since around 2008.
+
+=back
+
+=item B<-d>
+
+=item B<--debug>
+
+Enable debugging messages.
+
+=item B<--delete part>
+
+Delete the named partition.  It would be more accurate to describe
+this as "don't copy it over", since virt-resize doesn't do in-place
+changes and the original disk image is left intact.
+
+Note that when you delete a partition, then anything contained in the
+partition is also deleted.  Furthermore, this causes any partitions
+that come after to be I<renumbered>, which can easily make your guest
+unbootable.
+
+You can give this option multiple times.

 
 =item B<--expand part>
 
 
 =item B<--expand part>
 


@@ -290,13 +358,11 @@ Currently virt-resize can resize:
 
 =item *
 
 
 =item *
 

-ext2, ext3 and ext4 filesystems when they are contained
-directly inside a partition.
+ext2, ext3 and ext4 filesystems.

 
 =item *
 
 
 =item *
 

-NTFS filesystems contained directly in a partition, if libguestfs was
-compiled with support for NTFS.
+NTFS filesystems, if libguestfs was compiled with support for NTFS.

 
 The filesystem must have been shut down consistently last time it was
 used.  Additionally, L<ntfsresize(8)> marks the resized filesystem as
 
 The filesystem must have been shut down consistently last time it was
 used.  Additionally, L<ntfsresize(8)> marks the resized filesystem as


@@ -309,27 +375,24 @@ LVM PVs (physical volumes).  virt-resize does not usually resize
 anything inside the PV, but see the I<--LV-expand> option.  The user
 could also resize LVs as desired after boot.
 
 anything inside the PV, but see the I<--LV-expand> option.  The user
 could also resize LVs as desired after boot.
 

+=item *
+
+Btrfs filesystems, if libguestfs was compiled with support for btrfs.
+

 =back
 
 Note that you cannot use I<--expand> and I<--shrink> together.
 
 =back
 
 Note that you cannot use I<--expand> and I<--shrink> together.
 

-=item B<--shrink part>
+=item B<--format> raw

 
 

-Shrink the named partition until the overall disk image fits in the
-destination.  The named partition B<must> contain a filesystem or PV
-which has already been shrunk using another tool (eg. L<guestfish(1)>
-or other online tools).  Virt-resize will check this and give an error
-if it has not been done.
+Specify the format of the input disk image.  If this flag is not
+given then it is auto-detected from the image itself.

 
 

-The amount by which the overall disk must be shrunk (after carrying
-out all other operations requested by the user) is called the
-"deficit".  For example, a straight copy (assume no other operations)
-from a 5GB disk image to a 4GB disk image results in a 1GB deficit.
-In this case, virt-resize would give an error unless the user
-specified a partition to shrink and that partition had more than a
-gigabyte of free space.
+If working with untrusted raw-format guest disk images, you should
+ensure the format is always specified.

 
 

-Note that you cannot use I<--expand> and I<--shrink> together.
+Note that this option I<does not> affect the output format.
+See L</QCOW2 AND NON-SPARSE RAW FORMATS>.

 
 =item B<--ignore part>
 
 
 =item B<--ignore part>
 


@@ -340,19 +403,6 @@ blank (all zero bytes).
 
 You can give this option multiple times.
 
 
 You can give this option multiple times.
 

-=item B<--delete part>
-
-Delete the named partition.  It would be more accurate to describe
-this as "don't copy it over", since virt-resize doesn't do in-place
-changes and the original disk image is left intact.
-
-Note that when you delete a partition, then anything contained in the
-partition is also deleted.  Furthermore, this causes any partitions
-that come after to be I<renumbered>, which can easily make your guest
-unbootable.
-
-You can give this option multiple times.
-

 =item B<--LV-expand logvol>
 
 This takes the logical volume and, as a final step, expands it to fill
 =item B<--LV-expand logvol>
 
 This takes the logical volume and, as a final step, expands it to fill


@@ -376,6 +426,18 @@ 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.
 
 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>
+
+Print a summary of what would be done, but don't do anything.
+

 =item B<--no-copy-boot-loader>
 
 By default, virt-resize copies over some sectors at the start of the
 =item B<--no-copy-boot-loader>
 
 By default, virt-resize copies over some sectors at the start of the


@@ -405,17 +467,26 @@ of partitions, if it knows how (see I<--expand> option above).
 If you give the I<--no-expand-content> option then virt-resize
 will not attempt this.
 
 If you give the I<--no-expand-content> option then virt-resize
 will not attempt this.
 

-=item B<-d>
+=item B<--ntfsresize-force>

 
 

-=item B<--debug>
+Pass the I<--force> option to L<ntfsresize(8)>, allowing resizing
+even if the NTFS disk is marked as needing a consistency check.
+You have to use this option if you want to resize a Windows
+guest multiple times without booting into Windows between each
+resize.

 
 

-Enable debugging messages.
+=item B<--output-format> raw

 
 

-=item B<-n>
+Specify the format of the output disk image.  If this flag is not
+given then it is auto-detected from the image itself.

 
 

-=item B<--dryrun>
+If working with untrusted raw-format guest disk images, you should
+ensure the format is always specified.

 
 

-Print a summary of what would be done, but don't do anything.
+Note that this option I<does not create> the output format.  This
+option just tells libguestfs what it is so it doesn't try to guess it.
+You still need to create the output disk with the right format.  See
+L</QCOW2 AND NON-SPARSE RAW FORMATS>.

 
 =item B<-q>
 
 
 =item B<-q>
 


@@ -423,51 +494,149 @@ Print a summary of what would be done, but don't do anything.
 
 Don't print the summary.
 
 
 Don't print the summary.
 

-=item B<--format> raw
+=item B<--resize part=size>

 
 

-Specify the format of the input disk image.  If this flag is not
-given then it is auto-detected from the image itself.
+Resize the named partition (expanding or shrinking it) so that it has
+the given size.

 
 

-If working with untrusted raw-format guest disk images, you should
-ensure the format is always specified.
+C<size> can be expressed as an absolute number followed by
+b/K/M/G to mean bytes, Kilobytes, Megabytes, or Gigabytes;
+or as a percentage of the current size;
+or as a relative number or percentage.
+For example:

 
 

-Note that this option I<does not> affect the output format.
-See L</QCOW2 AND NON-SPARSE RAW FORMATS>.
+ --resize /dev/sda2=10G

 
 

-=item B<--output-format> raw
+ --resize /dev/sda4=90%

 
 

-Specify the format of the output disk image.  If this flag is not
-given then it is auto-detected from the image itself.
+ --resize /dev/sda2=+1G

 
 

-If working with untrusted raw-format guest disk images, you should
-ensure the format is always specified.
+ --resize /dev/sda2=-200M

 
 

-Note that this option I<does not create> the output format.  This
-option just tells libguestfs what it is so it doesn't try to guess it.
-You still need to create the output disk with the right format.  See
-L</QCOW2 AND NON-SPARSE RAW FORMATS>.
+ --resize /dev/sda1=+128K
+
+ --resize /dev/sda1=+10%
+
+ --resize /dev/sda1=-10%
+
+You can increase the size of any partition.  Virt-resize will expand
+the direct content of the partition if it knows how (see I<--expand>
+below).
+
+You can only I<decrease> the size of partitions that contain
+filesystems or PVs which have already been shrunk.  Virt-resize will
+check this has been done before proceeding, or else will print an
+error (see also I<--resize-force>).
+
+You can give this option multiple times.
+
+=item B<--resize-force part=size>
+
+This is the same as I<--resize> except that it will let you decrease
+the size of any partition.  Generally this means you will lose any
+data which was at the end of the partition you shrink, but you may not
+care about that (eg. if shrinking an unused partition, or if you can
+easily recreate it such as a swap partition).
+
+See also the I<--ignore> option.
+
+=item B<--shrink part>
+
+Shrink the named partition until the overall disk image fits in the
+destination.  The named partition B<must> contain a filesystem or PV
+which has already been shrunk using another tool (eg. L<guestfish(1)>
+or other online tools).  Virt-resize will check this and give an error
+if it has not been done.
+
+The amount by which the overall disk must be shrunk (after carrying
+out all other operations requested by the user) is called the
+"deficit".  For example, a straight copy (assume no other operations)
+from a 5GB disk image to a 4GB disk image results in a 1GB deficit.
+In this case, virt-resize would give an error unless the user
+specified a partition to shrink and that partition had more than a
+gigabyte of free space.
+
+Note that you cannot use I<--expand> and I<--shrink> together.
+
+=item B<-V>
+
+=item B<--version>
+
+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
 
 
 =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."
 
 =head1 NOTES
 
 =head2 "Partition 1 does not end on cylinder boundary."
 

-Virt-resize aligns partitions to multiples of 64 sectors.  Usually
-this means the partitions will not be aligned to the ancient CHS
-geometry.  However CHS geometry is meaningless for disks manufactured
-since the early 1990s, and doubly so for virtual hard drives.
-Alignment of partitions to cylinders is not required by any modern
-operating system.
+Virt-resize aligns partitions to multiples of 128 sectors (see the
+I<--alignment> parameter).  Usually this means the partitions will not
+be aligned to the ancient CHS geometry.  However CHS geometry is
+meaningless for disks manufactured since the early 1990s, and doubly
+so for virtual hard drives.  Alignment of partitions to cylinders is
+not required by any modern operating system.

 
 =head2 RESIZING WINDOWS VIRTUAL MACHINES
 
 In Windows Vista and later versions, Microsoft switched to using a
 separate boot partition.  In these VMs, typically C</dev/sda1> is the
 
 =head2 RESIZING WINDOWS VIRTUAL MACHINES
 
 In Windows Vista and later versions, Microsoft switched to using a
 separate boot partition.  In these VMs, typically C</dev/sda1> is the

-boot partition and C</dev/sda2> is the main (C:) drive.  We have not
-had any luck resizing the boot partition.  Doing so seems to break the
-guest completely.  However expanding the second partition (ie. C:
-drive) should work.
+boot partition and C</dev/sda2> is the main (C:) drive.  Resizing the
+first (boot) partition causes the bootloader to fail with
+C<0xC0000225> error.  Resizing the second partition (ie. C: drive)
+should work.

 
 Windows may initiate a lengthy "chkdsk" on first boot after a resize,
 if NTFS partitions have been expanded.  This is just a safety check
 
 Windows may initiate a lengthy "chkdsk" on first boot after a resize,
 if NTFS partitions have been expanded.  This is just a safety check


@@ -476,9 +645,7 @@ and (unless it find errors) is nothing to worry about.
 =head2 GUEST BOOT STUCK AT "GRUB"
 
 If a Linux guest does not boot after resizing, and the boot is stuck
 =head2 GUEST BOOT STUCK AT "GRUB"
 
 If a Linux guest does not boot after resizing, and the boot is stuck

-after printing C<GRUB> on the console, try reinstalling grub.  This
-sometimes happens on older (RHEL 5-era) guests, for reasons we don't
-fully understand, although we think is to do with partition alignment.
+after printing C<GRUB> on the console, try reinstalling grub.

 
  guestfish -i -a newdisk
  ><fs> cat /boot/grub/device.map
 
  guestfish -i -a newdisk
  ><fs> cat /boot/grub/device.map


@@ -513,6 +680,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.
 
 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)>,
 =head1 SEE ALSO
 
 L<virt-filesystems(1)>,


@@ -524,6 +696,7 @@ L<pvresize(8)>,
 L<lvresize(8)>,
 L<resize2fs(8)>,
 L<ntfsresize(8)>,
 L<lvresize(8)>,
 L<resize2fs(8)>,
 L<ntfsresize(8)>,

+L<btrfs(8)>,

 L<virsh(1)>,
 L<parted(8)>,
 L<truncate(1)>,
 L<virsh(1)>,
 L<parted(8)>,
 L<truncate(1)>,


@@ -531,6 +704,8 @@ L<fallocate(1)>,
 L<grub(8)>,
 L<grub-install(8)>,
 L<virt-rescue(1)>,
 L<grub(8)>,
 L<grub-install(8)>,
 L<virt-rescue(1)>,

+L<virt-sparsify(1)>,
+L<virt-alignment-scan(1)>,

 L<http://libguestfs.org/>.
 
 =head1 AUTHOR
 L<http://libguestfs.org/>.
 
 =head1 AUTHOR


@@ -553,4 +728,4 @@ 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
 
 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.
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.