=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:
Display help.
-=item B<-V>
-
-=item B<--version>
-
-Display version number and exit.
-
-=item B<--resize part=size>
-
-Resize the named partition (expanding or shrinking it) so that it has
-the given size.
-
-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:
-
- --resize /dev/sda2=10G
-
- --resize /dev/sda4=90%
-
- --resize /dev/sda2=+1G
-
- --resize /dev/sda2=-200M
+=item B<-d>
- --resize /dev/sda1=+128K
+=item B<--debug>
- --resize /dev/sda1=+10%
+Enable debugging messages.
- --resize /dev/sda1=-10%
+=item B<--delete part>
-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).
+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.
-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>).
+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<--resize-force part=size>
-
-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).
-
-See also the C<--ignore> option.
-
=item B<--expand part>
Expand the named partition so it uses up all extra space (space left
=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."
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<http://libguestfs.org/>.
=head1 AUTHOR
git.annexia.org / libguestfs.git / blobdiff