[Libguestfs] Proposed virt-resize tool (manual page)
Richard W.M. Jones
rjones at redhat.com
Wed Mar 17 19:57:45 UTC 2010
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.
More information about the Libguestfs
mailing list