X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=resize%2Fvirt-resize.pod;h=abf190e6ee88d9df281ce25ee2a6577d8825baba;hb=d81c0829ea4a99aadb98df37be9543a973269041;hp=6a93e4687159ae9ba7a7a5cefb426087b469dee9;hpb=08910ee60cfac9aa648e59dda5dbb429825c561e;p=libguestfs.git diff --git a/resize/virt-resize.pod b/resize/virt-resize.pod index 6a93e46..abf190e 100644 --- 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 to C, 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 @@ -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, -L or L. However virt-resize does not -know how to resize some filesystems, so you would have to online -resize them after booting the guest. +L, L or L. 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. @@ -214,6 +238,27 @@ Similarly, to get non-sparse raw output use: (on older systems that don't have the L command use C
) +=head2 LOGICAL PARTITIONS + +Logical partitions (a.k.a. C on disks using DOS partition +tables) cannot be resized. + +To understand what is going on, firstly one of the four partitions +C will have MBR partition type C<05> or C<0f>. This is +called the B. Use L 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) at all on the +command line. Doing so will give an error. + =head1 OPTIONS =over 4 @@ -222,6 +267,62 @@ C
) 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 sectors. The default in +virt-resize E 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 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> @@ -274,6 +375,10 @@ 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. +=item * + +Btrfs filesystems, if libguestfs was compiled with support for btrfs. + =back Note that you cannot use I<--expand> and I<--shrink> together. @@ -321,6 +426,12 @@ You can give this option multiple times, I 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 below. + =item B<-n> =item B<--dryrun> @@ -455,25 +566,77 @@ 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 is the -boot partition and C 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 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 @@ -482,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 -after printing C 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 on the console, try reinstalling grub. guestfish -i -a newdisk > cat /boot/grub/device.map @@ -519,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 for details. +=head1 EXIT STATUS + +This program returns 0 if successful, or non-zero if there was an +error. + =head1 SEE ALSO L, @@ -530,6 +696,7 @@ L, L, L, L, +L, L, L, L, @@ -537,6 +704,8 @@ L, L, L, L, +L, +L, L. =head1 AUTHOR @@ -559,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 -Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.