=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
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.
(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
Display help.
+=item B<--align-first auto>
+
+=item B<--align-first never>
+
+=item B<--align-first always>
+
+Align the first partition for improved performance (see also the
+I<--alignment> option).
+
+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.
+
+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.
+
+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.
+
+=item B<--alignment N>
+
+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.
+
+Assuming 512 byte sector size inside the guest, here are some
+suitable values for this:
+
+=over 4
+
+=item I<--alignment 1> (512 bytes)
+
+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.
+
+=item I<--alignment 8> (4K)
+
+This would be the minimum acceptable alignment for reasonable
+performance on modern hosts.
+
+=item I<--alignment 128> (64K)
+
+This alignment provides good performance when the host is using high
+end network storage.
+
+=item I<--alignment 2048> (1M)
+
+This is the standard alignment used by all newly installed guests
+since around 2008.
+
+=back
+
=item B<-d>
=item B<--debug>
=item *
-ext2, ext3 and ext4 filesystems when they are contained
-directly inside a partition.
+ext2, ext3 and ext4 filesystems.
=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
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.
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>
=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."
-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
-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
=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
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)>,
L<lvresize(8)>,
L<resize2fs(8)>,
L<ntfsresize(8)>,
+L<btrfs(8)>,
L<virsh(1)>,
L<parted(8)>,
L<truncate(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
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.