Libguestfs - Mar 2010 - Proposed virt-resize tool (manual page)

I like to write documentation before I write the actual programs.
This is a proposed new tool to handle resizing virtual machines which
has been requested by a couple of users.

Let me know what you think of the features (ones included and any
others you need), command line usability, etc.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming blog: http://rwmj.wordpress.com
Fedora now supports 80 OCaml packages (the OPEN alternative to F#)
http://cocan.org/getting_started_with_ocaml_on_red_hat_and_fedora
-------------- next part --------------
NAME
    virt-resize - Resize a virtual machine disk

SYNOPSIS
     virt-resize [--options] indisk outdisk

DESCRIPTION
    Virt-resize is a tool which can resize a virtual machine disk, making it
    larger or smaller overall, and resizing or deleting any partitions and
    filesystems contained within.

    Virt-resize cannot resize disk images in-place. Virt-resize should not
    be used on live virtual machines - for consistent results, shut the
    virtual machine down before resizing it.

    This program is intended to be used in conjunction with
    virt-list-filesystems(1) and virt-df(1). You should read the manpages
    for those tools if you are not already familiar with them.

  BASIC USAGE
    1. Locate disk image
        Locate the disk image that you want to resize. It could be in a
        local file or device. If the guest is managed by libvirt, you can
        use "virsh dumpxml" like this to find the disk image name:

         # virsh dumpxml guestname | xpath /domain/devices/disk/source
         Found 1 nodes:
         -- NODE --
         <source dev="/dev/vg/lv_guest" />

    2. Look at current sizing
        Use virt-list-filesystems(1) and/or virt-df(1) on the disk image to
        find out what is currently inside the disk image, and how much free
        space is available. For example:

         # virt-df -h /dev/vg/lv_guest
         Filesystem                      Size       Used  Available  Use%
         /dev/vg/lv_guest:/dev/sda1     98.7M      35.4M      58.3M 41.0%
         /dev/vg/lv_guest:/dev/VolGroup00/LogVol00
                                         8.6G       8.0G       0.1G 98.8%

        In this example the filesystems are called "/dev/sda1" and
        "/dev/VolGroup00/LogVol00".

    3. Create destination disk
        Virt-resize cannot do in-place disk modifications. You have to have
        space to store the resized destination disk.

        To store the resized disk image in a file, create a file of a
        suitable size:

         # truncate -s 10G outdisk

        Use lvcreate(1) to create a logical volume:

         # lvcreate -L 10G -n lv_name vg_name

        Or use virsh(1) vol-create-as to create a libvirt storage volume:

         # virsh pool-list
         # virsh vol-create-as poolname newvol 10G

    4. Resize
         virt-resize indisk outdisk

        This command just copies disk image "indisk" to disk image
"outdisk"
        *without* resizing or changing any existing partitions or
        filesystems. If "outdisk" is larger, then an extra, empty
partition
        is created at the end of the disk covering the extra space. If
        "outdisk" is smaller, then it will give an error.

        To resize, you need to pass extra options (for the full list see the
        "OPTIONS" section below).

        "--expand" is the most useful option. It expands the named
        filesystem within the disk to fill any extra space:

         virt-resize --expand /dev/sda1 indisk outdisk

        (In this case, an extra partition is *not* created at the end of the
        disk, because there will be no unused space). If "/dev/sda1"
in the
        image contains a filesystem, then the filesystem is resized (if
        possible because only some filesystem types support resizing).

        Other options are covered below.

    5. Test
        Thoroughly test the new disk image *before* discarding the old one.

        If you are using libvirt, edit the XML to point at the new disk:

         # virsh edit guestname

        Change <source ...>, see
        <http://libvirt.org/formatdomain.html#elementsDisks>

        Then start up the domain with the new, resized disk:

         # virsh start guestname

        and check that it still works.

OPTIONS
    In the options below, "fs" means some filesystem name, eg.
"/dev/sda1"
    or "/dev/VolGroup00/LogVol00". Use virt-list-filesystems(1) and/or
    virt-df(1) to list the names of filesystems within an image.

    --help
        Display brief help.

    --version
        Display version number and exit.

    --resize fs=size
        Resize the named filesystem (expanding or shrinking it) so that it
        has the given size.

        "size" can be expressed as an absolute number followed by
        s/K/M/G/T/P/E to mean sectors, Kilobytes, Megabytes, Gigabytes,
        Terabytes, Petabytes or Exabytes; or as a percentage of the current
        size; or as a relative number or percentage. For example:

         --resize /dev/sda2=10G

         --resize /dev/VolGroup00/LogVol00=90%

         --resize /dev/sda2=+1G

         --resize /dev/sda2=-200M

         --resize /dev/sda1=+128s

         --resize /dev/VolGroup00/LogVol00=+10%

         --resize /dev/VolGroup00/LogVol00=-10%

        You can increase the size of anything: filesystems, partitions, PVs
        or LVs.

        If you increase the size of a filesystem, then virt-resize will try
        to resize the filesystem itself to fit the extra space. This is only
        possible for ext2/3/4, NTFS and LVM PV.

        You can *only* decrease the size of ext2/3/4 filesystems, NTFS and
        LVM PVs, and then only if there is free space in the filesystem or
        PV to shrink it.

        You can give this option multiple times.

    --resize-force fs=size
        This is the same as "--resize" except that it will let you
decrease
        the size of anything. Generally this means you will lose any data
        which was at the end of the thing 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).

    --expand fs
    --expand percent:fs
        Expand the named filesystem so it uses up all extra space (space
        left over after any other filesystem changes that you request have
        been done).

        You can give this option multiple times:

         --expand fs1 --expand fs2

        which divides the extra space equally between fs1 and fs2.

        You can also prefix each filesystem with a percentage, thus:

         --expand 20:fs1 --expand 50:fs2

        will give 20% of the extra space to fs1, 50% to fs2, and the
        remainder (30%) will go into an extra partition.

        If possible, we resize the filesystem to fit the extra space. This
        can be done for ext2/3/4 and NTFS filesystems, and LVM PVs.

        You can also expand partitions and LVM LVs.

        Note that you cannot use "--expand" and "--shrink"
together.

    --shrink fs
    --shrink percent:fs
        Shrink the named filesystem until the overall disk image fits in the
        destination. The named filesystem must be ext2/3/4, NTFS or an LVM
        PV, and it must have enough free space to allow it to be shrunk.

        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 at least one filesystem to shrink and that filesystem had
        more than a gigabyte of free space.

        You can give this option multiple times:

         --shrink fs1 --shrink fs2

        which divides the deficit equally between fs1 and fs2.

        You can also prefix each filesystem with a percentage in order to
        spread the deficit unequally:

         --shrink 20:fs1 --shrink 80:fs2

        Note that you cannot use "--expand" and "--shrink"
together.

    --zero fs
        Zero out the named filesystem. Effectively this means the filesystem
        is created on the destination disk, but the content is not copied
        across from the source disk.

        You can zero out partitions, filesystems or any LVM object. This
        applies recursively, so for example if you zero out an LVM VG, then
        none of the LVs or filesystems inside that VG are copied over.

        You can give this option multiple times.

    --delete fs
        Delete the named filesystem, partition or LVM object. 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 if you delete a partition, then anything contained in the
        partition is also deleted. Furthermore, this causes any partitions
        that come after to be *renumbered*.

        Also if you delete an LVM object, then anything contained in that
        LVM object is deleted too. So for example, deleting an LVM VG
        deletes any LVs inside that VG.

        You can give this option multiple times.

    --no-copy-boot-loader
        By default, virt-resize copies over some sectors at the start of the
        disk (up to the beginning of the first partition). Commonly these
        sectors contain the Master Boot Record (MBR) and the boot loader,
        and are required in order for the guest to boot correctly.

        If you specify this flag, then this initial copy is not done. You
        may need to reinstall the boot loader in this case.

    --no-extra-partition
        By default, virt-resize creates an extra partition if there is any
        extra, unused space after all resizing has happened. Use this option
        to prevent the extra partition from being created. If you do this
        then the extra space will be inaccessible until you run
"fdisk" in
        the guest.

    --no-resize-fs
        By default, virt-resize will resize ext2/3/4 and NTFS filesystems,
        and LVM PVs (not merely the containers they are in). If you use this
        option, then only the container is resized, not the filesystem.

        Note that if this option is specified, then virt-resize will refuse
        to shrink anything unless you use "--resize-force".

    -d | --debug
        Enable debugging messages.

    -n | --dryrun
        Print a summary of what would be done, but don't do anything.

    -q | --quiet
        Don't print the summary.

SEE ALSO
    virt-list-filesystems(1), virt-df(1), guestfs(3), guestfish(1),
    Sys::Guestfs(3), Sys::Guestfs::Lib(3), <http://libguestfs.org/>.

AUTHOR
    Richard W.M. Jones <http://et.redhat.com/~rjones/>

COPYRIGHT
    Copyright (C) 2010 Red Hat Inc.

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 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.