=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 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
-As above, but the output format will be uncompressed qcow2:
+=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.
After shrinking PVs and filesystems, shut down the guest, and proceed
with steps 3 and 4 above to allocate a new disk image.
-Then run virt-resize with any of the C<--shrink> and/or C<--resize>
+Then run virt-resize with any of the I<--shrink> and/or I<--resize>
options.
=head2 IGNORING OR DELETING PARTITIONS
qemu-img create [-c] -f qcow2 outdisk [size]
-instead of the truncate command (use C<-c> for a compressed disk).
+instead of the truncate command (use I<-c> for a compressed disk).
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=..>)
+=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<-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 C<--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 C<--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 C<--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)
+
+This is the standard alignment used by all newly installed guests
+since around 2008.
+
+=back
-See also the C<--ignore> option.
+=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 *
-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
=item *
LVM PVs (physical volumes). virt-resize does not usually resize
-anything inside the PV, but see the C<--LV-expand> option. The user
+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 C<--expand> and C<--shrink> together.
+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 C<--expand> and C<--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>
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
The contents of the LV are also resized if virt-resize knows how to do
that. You can stop virt-resize from trying to expand the content by
-using the option C<--no-expand-content>.
+using the option I<--no-expand-content>.
Use L<virt-filesystems(1)> to list the filesystems in the guest.
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-expand-content>
By default, virt-resize will try to expand the direct contents
-of partitions, if it knows how (see C<--expand> option above).
+of partitions, if it knows how (see I<--expand> option above).
-If you give the C<--no-expand-content> option then virt-resize
+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>
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
+
+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
more, but at a much lower level. You will probably end up
hand-calculating sector offsets, which is something that virt-resize
was designed to avoid. If you want to see the guestfish-equivalent
-commands that virt-resize runs, use the C<--debug> flag.
+commands that virt-resize runs, use the I<--debug> flag.
=head1 SHELL QUOTING
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
git.annexia.org / libguestfs.git / blobdiff