configure: Add --with-extra flag to allow setting the extra version string.
[libguestfs.git] / resize / virt-resize.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 virt-resize - Resize a virtual machine disk
6
7 =head1 SYNOPSIS
8
9  virt-resize [--resize /dev/sdaN=[+/-]<size>[%]]
10    [--expand /dev/sdaN] [--shrink /dev/sdaN]
11    [--ignore /dev/sdaN] [--delete /dev/sdaN] [...] indisk outdisk
12
13 =head1 DESCRIPTION
14
15 Virt-resize is a tool which can resize a virtual machine disk, making
16 it larger or smaller overall, and resizing or deleting any partitions
17 contained within.
18
19 Virt-resize B<cannot> resize disk images in-place.  Virt-resize
20 B<should not> be used on live virtual machines - for consistent
21 results, shut the virtual machine down before resizing it.
22
23 If you are not familiar with the associated tools:
24 L<virt-filesystems(1)> and L<virt-df(1)>, we recommend you go and read
25 those manual pages first.
26
27 =head1 EXAMPLES
28
29 Copy C<olddisk> to C<newdisk>, extending one of the guest's partitions
30 to fill the extra 5GB of space.
31
32  truncate -r olddisk newdisk; truncate -s +5G newdisk
33  virt-filesystems --long -h --all -a olddisk
34  # Note "/dev/sda2" is a partition inside the "olddisk" file.
35  virt-resize --expand /dev/sda2 olddisk newdisk
36
37 As above, but make the /boot partition 200MB bigger, while giving the
38 remaining space to /dev/sda2:
39
40  virt-resize --resize /dev/sda1=+200M --expand /dev/sda2 olddisk newdisk
41
42 As above, but the output format will be uncompressed qcow2:
43
44  qemu-img create -f qcow2 newdisk.qcow2 15G
45  virt-resize --expand /dev/sda2 olddisk newdisk.qcow2
46
47 =head1 DETAILED USAGE
48
49 =head2 EXPANDING A VIRTUAL MACHINE DISK
50
51 =over 4
52
53 =item 1. Shut down the virtual machine
54
55 =item 2. Locate input disk image
56
57 Locate the input disk image (ie. the file or device on the host
58 containing the guest's disk).  If the guest is managed by libvirt, you
59 can use C<virsh dumpxml> like this to find the disk image name:
60
61  # virsh dumpxml guestname | xpath /domain/devices/disk/source
62  Found 1 nodes:
63  -- NODE --
64  <source dev="/dev/vg/lv_guest" />
65
66 =item 3. Look at current sizing
67
68 Use L<virt-filesystems(1)> to display the current partitions and
69 sizes:
70
71  # virt-filesystems --long --parts --blkdevs -h -a /dev/vg/lv_guest
72  Name       Type       Size  Parent
73  /dev/sda1  partition  101M  /dev/sda
74  /dev/sda2  partition  7.9G  /dev/sda
75  /dev/sda   device     8.0G  -
76
77 (This example is a virtual machine with an 8 GB disk which we would
78 like to expand up to 10 GB).
79
80 =item 4. Create output disk
81
82 Virt-resize cannot do in-place disk modifications.  You have to have
83 space to store the resized output disk.
84
85 To store the resized disk image in a file, create a file of a suitable
86 size:
87
88  # rm -f outdisk
89  # truncate -s 10G outdisk
90
91 Or use L<lvcreate(1)> to create a logical volume:
92
93  # lvcreate -L 10G -n lv_name vg_name
94
95 Or use L<virsh(1)> vol-create-as to create a libvirt storage volume:
96
97  # virsh pool-list
98  # virsh vol-create-as poolname newvol 10G
99
100 =item 5. Resize
101
102 virt-resize takes two mandatory parameters, the input disk (eg. device
103 or file) and the output disk.  The output disk is the one created in
104 the previous step.
105
106  # virt-resize indisk outdisk
107
108 This command just copies disk image C<indisk> to disk image C<outdisk>
109 I<without> resizing or changing any existing partitions.  If
110 C<outdisk> is larger, then an extra, empty partition is created at the
111 end of the disk covering the extra space.  If C<outdisk> is smaller,
112 then it will give an error.
113
114 More realistically you'd want to expand existing partitions in the
115 disk image by passing extra options (for the full list see the
116 L</OPTIONS> section below).
117
118 L</--expand> is the most useful option.  It expands the named
119 partition within the disk to fill any extra space:
120
121  # virt-resize --expand /dev/sda2 indisk outdisk
122
123 (In this case, an extra partition is I<not> created at the end of the
124 disk, because there will be no unused space).
125
126 L</--resize> is the other commonly used option.  The following would
127 increase the size of /dev/sda1 by 200M, and expand /dev/sda2
128 to fill the rest of the available space:
129
130  # virt-resize --resize /dev/sda1=+200M --expand /dev/sda2 \
131      indisk outdisk
132
133 If the expanded partition in the image contains a filesystem or LVM
134 PV, then if virt-resize knows how, it will resize the contents, the
135 equivalent of calling a command such as L<pvresize(8)>,
136 L<resize2fs(8)> or L<ntfsresize(8)>.  However virt-resize does not
137 know how to resize some filesystems, so you would have to online
138 resize them after booting the guest.
139
140 Other options are covered below.
141
142 =item 6. Test
143
144 Thoroughly test the new disk image I<before> discarding the old one.
145
146 If you are using libvirt, edit the XML to point at the new disk:
147
148  # virsh edit guestname
149
150 Change E<lt>source ...E<gt>, see
151 L<http://libvirt.org/formatdomain.html#elementsDisks>
152
153 Then start up the domain with the new, resized disk:
154
155  # virsh start guestname
156
157 and check that it still works.  See also the L</NOTES> section below
158 for additional information.
159
160 =item 7. Resize LVs etc inside the guest
161
162 (This can also be done offline using L<guestfish(1)>)
163
164 Once the guest has booted you should see the new space available, at
165 least for filesystems that virt-resize knows how to resize, and for
166 PVs.  The user may need to resize LVs inside PVs, and also resize
167 filesystem types that virt-resize does not know how to expand.
168
169 =back
170
171 =head2 SHRINKING A VIRTUAL MACHINE DISK
172
173 Shrinking is somewhat more complex than expanding, and only an
174 overview is given here.
175
176 Firstly virt-resize will not attempt to shrink any partition content
177 (PVs, filesystems).  The user has to shrink content before passing the
178 disk image to virt-resize, and virt-resize will check that the content
179 has been shrunk properly.
180
181 (Shrinking can also be done offline using L<guestfish(1)>)
182
183 After shrinking PVs and filesystems, shut down the guest, and proceed
184 with steps 3 and 4 above to allocate a new disk image.
185
186 Then run virt-resize with any of the I<--shrink> and/or I<--resize>
187 options.
188
189 =head2 IGNORING OR DELETING PARTITIONS
190
191 virt-resize also gives a convenient way to ignore or delete partitions
192 when copying from the input disk to the output disk.  Ignoring a
193 partition speeds up the copy where you don't care about the existing
194 contents of a partition.  Deleting a partition removes it completely,
195 but note that it also renumbers any partitions after the one which is
196 deleted, which can leave some guests unbootable.
197
198 =head2 QCOW2 AND NON-SPARSE RAW FORMATS
199
200 If the input disk is in qcow2 format, then you may prefer that the
201 output is in qcow2 format as well.  Alternately, virt-resize can
202 convert the format on the fly.  The output format is simply determined
203 by the format of the empty output container that you provide.  Thus to
204 create qcow2 output, use:
205
206  qemu-img create [-c] -f qcow2 outdisk [size]
207
208 instead of the truncate command (use I<-c> for a compressed disk).
209
210 Similarly, to get non-sparse raw output use:
211
212  fallocate -l size outdisk
213
214 (on older systems that don't have the L<fallocate(1)> command use
215 C<dd if=/dev/zero of=outdisk bs=1M count=..>)
216
217 =head1 OPTIONS
218
219 =over 4
220
221 =item B<--help>
222
223 Display help.
224
225 =item B<-V>
226
227 =item B<--version>
228
229 Display version number and exit.
230
231 =item B<--resize part=size>
232
233 Resize the named partition (expanding or shrinking it) so that it has
234 the given size.
235
236 C<size> can be expressed as an absolute number followed by
237 b/K/M/G to mean bytes, Kilobytes, Megabytes, or Gigabytes;
238 or as a percentage of the current size;
239 or as a relative number or percentage.
240 For example:
241
242  --resize /dev/sda2=10G
243
244  --resize /dev/sda4=90%
245
246  --resize /dev/sda2=+1G
247
248  --resize /dev/sda2=-200M
249
250  --resize /dev/sda1=+128K
251
252  --resize /dev/sda1=+10%
253
254  --resize /dev/sda1=-10%
255
256 You can increase the size of any partition.  Virt-resize will expand
257 the direct content of the partition if it knows how (see I<--expand>
258 below).
259
260 You can only I<decrease> the size of partitions that contain
261 filesystems or PVs which have already been shrunk.  Virt-resize will
262 check this has been done before proceeding, or else will print an
263 error (see also I<--resize-force>).
264
265 You can give this option multiple times.
266
267 =item B<--resize-force part=size>
268
269 This is the same as I<--resize> except that it will let you decrease
270 the size of any partition.  Generally this means you will lose any
271 data which was at the end of the partition you shrink, but you may not
272 care about that (eg. if shrinking an unused partition, or if you can
273 easily recreate it such as a swap partition).
274
275 See also the I<--ignore> option.
276
277 =item B<--expand part>
278
279 Expand the named partition so it uses up all extra space (space left
280 over after any other resize changes that you request have been done).
281
282 If virt-resize knows how, it will expand the direct content of the
283 partition.  For example, if the partition is an LVM PV, it will expand
284 the PV to fit (like calling L<pvresize(8)>).  Virt-resize leaves any
285 other content it doesn't know about alone.
286
287 Currently virt-resize can resize:
288
289 =over 4
290
291 =item *
292
293 ext2, ext3 and ext4 filesystems when they are contained
294 directly inside a partition.
295
296 =item *
297
298 NTFS filesystems contained directly in a partition, if libguestfs was
299 compiled with support for NTFS.
300
301 The filesystem must have been shut down consistently last time it was
302 used.  Additionally, L<ntfsresize(8)> marks the resized filesystem as
303 requiring a consistency check, so at the first boot after resizing
304 Windows will check the disk.
305
306 =item *
307
308 LVM PVs (physical volumes).  virt-resize does not usually resize
309 anything inside the PV, but see the I<--LV-expand> option.  The user
310 could also resize LVs as desired after boot.
311
312 =back
313
314 Note that you cannot use I<--expand> and I<--shrink> together.
315
316 =item B<--shrink part>
317
318 Shrink the named partition until the overall disk image fits in the
319 destination.  The named partition B<must> contain a filesystem or PV
320 which has already been shrunk using another tool (eg. L<guestfish(1)>
321 or other online tools).  Virt-resize will check this and give an error
322 if it has not been done.
323
324 The amount by which the overall disk must be shrunk (after carrying
325 out all other operations requested by the user) is called the
326 "deficit".  For example, a straight copy (assume no other operations)
327 from a 5GB disk image to a 4GB disk image results in a 1GB deficit.
328 In this case, virt-resize would give an error unless the user
329 specified a partition to shrink and that partition had more than a
330 gigabyte of free space.
331
332 Note that you cannot use I<--expand> and I<--shrink> together.
333
334 =item B<--ignore part>
335
336 Ignore the named partition.  Effectively this means the partition is
337 allocated on the destination disk, but the content is not copied
338 across from the source disk.  The content of the partition will be
339 blank (all zero bytes).
340
341 You can give this option multiple times.
342
343 =item B<--delete part>
344
345 Delete the named partition.  It would be more accurate to describe
346 this as "don't copy it over", since virt-resize doesn't do in-place
347 changes and the original disk image is left intact.
348
349 Note that when you delete a partition, then anything contained in the
350 partition is also deleted.  Furthermore, this causes any partitions
351 that come after to be I<renumbered>, which can easily make your guest
352 unbootable.
353
354 You can give this option multiple times.
355
356 =item B<--LV-expand logvol>
357
358 This takes the logical volume and, as a final step, expands it to fill
359 all the space available in its volume group.  A typical usage,
360 assuming a Linux guest with a single PV C</dev/sda2> and a root device
361 called C</dev/vg_guest/lv_root> would be:
362
363  virt-resize indisk outdisk \
364    --expand /dev/sda2 --LV-expand /dev/vg_guest/lv_root
365
366 This would first expand the partition (and PV), and then expand the
367 root device to fill the extra space in the PV.
368
369 The contents of the LV are also resized if virt-resize knows how to do
370 that.  You can stop virt-resize from trying to expand the content by
371 using the option I<--no-expand-content>.
372
373 Use L<virt-filesystems(1)> to list the filesystems in the guest.
374
375 You can give this option multiple times, I<but> it doesn't
376 make sense to do this unless the logical volumes you specify
377 are all in different volume groups.
378
379 =item B<--no-copy-boot-loader>
380
381 By default, virt-resize copies over some sectors at the start of the
382 disk (up to the beginning of the first partition).  Commonly these
383 sectors contain the Master Boot Record (MBR) and the boot loader, and
384 are required in order for the guest to boot correctly.
385
386 If you specify this flag, then this initial copy is not done.  You may
387 need to reinstall the boot loader in this case.
388
389 =item B<--no-extra-partition>
390
391 By default, virt-resize creates an extra partition if there is any
392 extra, unused space after all resizing has happened.  Use this option
393 to prevent the extra partition from being created.  If you do this
394 then the extra space will be inaccessible until you run fdisk, parted,
395 or some other partitioning tool in the guest.
396
397 Note that if the surplus space is smaller than 10 MB, no extra
398 partition will be created.
399
400 =item B<--no-expand-content>
401
402 By default, virt-resize will try to expand the direct contents
403 of partitions, if it knows how (see I<--expand> option above).
404
405 If you give the I<--no-expand-content> option then virt-resize
406 will not attempt this.
407
408 =item B<-d>
409
410 =item B<--debug>
411
412 Enable debugging messages.
413
414 =item B<-n>
415
416 =item B<--dryrun>
417
418 Print a summary of what would be done, but don't do anything.
419
420 =item B<-q>
421
422 =item B<--quiet>
423
424 Don't print the summary.
425
426 =item B<--format> raw
427
428 Specify the format of the input disk image.  If this flag is not
429 given then it is auto-detected from the image itself.
430
431 If working with untrusted raw-format guest disk images, you should
432 ensure the format is always specified.
433
434 Note that this option I<does not> affect the output format.
435 See L</QCOW2 AND NON-SPARSE RAW FORMATS>.
436
437 =item B<--output-format> raw
438
439 Specify the format of the output disk image.  If this flag is not
440 given then it is auto-detected from the image itself.
441
442 If working with untrusted raw-format guest disk images, you should
443 ensure the format is always specified.
444
445 Note that this option I<does not create> the output format.  This
446 option just tells libguestfs what it is so it doesn't try to guess it.
447 You still need to create the output disk with the right format.  See
448 L</QCOW2 AND NON-SPARSE RAW FORMATS>.
449
450 =back
451
452 =head1 NOTES
453
454 =head2 "Partition 1 does not end on cylinder boundary."
455
456 Virt-resize aligns partitions to multiples of 64 sectors.  Usually
457 this means the partitions will not be aligned to the ancient CHS
458 geometry.  However CHS geometry is meaningless for disks manufactured
459 since the early 1990s, and doubly so for virtual hard drives.
460 Alignment of partitions to cylinders is not required by any modern
461 operating system.
462
463 =head2 RESIZING WINDOWS VIRTUAL MACHINES
464
465 In Windows Vista and later versions, Microsoft switched to using a
466 separate boot partition.  In these VMs, typically C</dev/sda1> is the
467 boot partition and C</dev/sda2> is the main (C:) drive.  We have not
468 had any luck resizing the boot partition.  Doing so seems to break the
469 guest completely.  However expanding the second partition (ie. C:
470 drive) should work.
471
472 Windows may initiate a lengthy "chkdsk" on first boot after a resize,
473 if NTFS partitions have been expanded.  This is just a safety check
474 and (unless it find errors) is nothing to worry about.
475
476 =head2 GUEST BOOT STUCK AT "GRUB"
477
478 If a Linux guest does not boot after resizing, and the boot is stuck
479 after printing C<GRUB> on the console, try reinstalling grub.  This
480 sometimes happens on older (RHEL 5-era) guests, for reasons we don't
481 fully understand, although we think is to do with partition alignment.
482
483  guestfish -i -a newdisk
484  ><fs> cat /boot/grub/device.map
485  # check the contents of this file are sensible or
486  # edit the file if necessary
487  ><fs> grub-install / /dev/vda
488  ><fs> exit
489
490 For more flexible guest reconfiguration, including if you need to
491 specify other parameters to grub-install, use L<virt-rescue(1)>.
492
493 =head1 ALTERNATIVE TOOLS
494
495 There are several proprietary tools for resizing partitions.  We
496 won't mention any here.
497
498 L<parted(8)> and its graphical shell gparted can do some types of
499 resizing operations on disk images.  They can resize and move
500 partitions, but I don't think they can do anything with the contents,
501 and they certainly don't understand LVM.
502
503 L<guestfish(1)> can do everything that virt-resize can do and a lot
504 more, but at a much lower level.  You will probably end up
505 hand-calculating sector offsets, which is something that virt-resize
506 was designed to avoid.  If you want to see the guestfish-equivalent
507 commands that virt-resize runs, use the I<--debug> flag.
508
509 =head1 SHELL QUOTING
510
511 Libvirt guest names can contain arbitrary characters, some of which
512 have meaning to the shell such as C<#> and space.  You may need to
513 quote or escape these characters on the command line.  See the shell
514 manual page L<sh(1)> for details.
515
516 =head1 SEE ALSO
517
518 L<virt-filesystems(1)>,
519 L<virt-df(1)>,
520 L<guestfs(3)>,
521 L<guestfish(1)>,
522 L<lvm(8)>,
523 L<pvresize(8)>,
524 L<lvresize(8)>,
525 L<resize2fs(8)>,
526 L<ntfsresize(8)>,
527 L<virsh(1)>,
528 L<parted(8)>,
529 L<truncate(1)>,
530 L<fallocate(1)>,
531 L<grub(8)>,
532 L<grub-install(8)>,
533 L<virt-rescue(1)>,
534 L<http://libguestfs.org/>.
535
536 =head1 AUTHOR
537
538 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
539
540 =head1 COPYRIGHT
541
542 Copyright (C) 2010-2011 Red Hat Inc.
543
544 This program is free software; you can redistribute it and/or modify
545 it under the terms of the GNU General Public License as published by
546 the Free Software Foundation; either version 2 of the License, or
547 (at your option) any later version.
548
549 This program is distributed in the hope that it will be useful,
550 but WITHOUT ANY WARRANTY; without even the implied warranty of
551 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
552 GNU General Public License for more details.
553
554 You should have received a copy of the GNU General Public License
555 along with this program; if not, write to the Free Software
556 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.