473c5824f27d3beb6b2eb7654ea0d4e7ab9446bd
[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<-d>
226
227 =item B<--debug>
228
229 Enable debugging messages.
230
231 =item B<--delete part>
232
233 Delete the named partition.  It would be more accurate to describe
234 this as "don't copy it over", since virt-resize doesn't do in-place
235 changes and the original disk image is left intact.
236
237 Note that when you delete a partition, then anything contained in the
238 partition is also deleted.  Furthermore, this causes any partitions
239 that come after to be I<renumbered>, which can easily make your guest
240 unbootable.
241
242 You can give this option multiple times.
243
244 =item B<--expand part>
245
246 Expand the named partition so it uses up all extra space (space left
247 over after any other resize changes that you request have been done).
248
249 If virt-resize knows how, it will expand the direct content of the
250 partition.  For example, if the partition is an LVM PV, it will expand
251 the PV to fit (like calling L<pvresize(8)>).  Virt-resize leaves any
252 other content it doesn't know about alone.
253
254 Currently virt-resize can resize:
255
256 =over 4
257
258 =item *
259
260 ext2, ext3 and ext4 filesystems when they are contained
261 directly inside a partition.
262
263 =item *
264
265 NTFS filesystems contained directly in a partition, if libguestfs was
266 compiled with support for NTFS.
267
268 The filesystem must have been shut down consistently last time it was
269 used.  Additionally, L<ntfsresize(8)> marks the resized filesystem as
270 requiring a consistency check, so at the first boot after resizing
271 Windows will check the disk.
272
273 =item *
274
275 LVM PVs (physical volumes).  virt-resize does not usually resize
276 anything inside the PV, but see the I<--LV-expand> option.  The user
277 could also resize LVs as desired after boot.
278
279 =back
280
281 Note that you cannot use I<--expand> and I<--shrink> together.
282
283 =item B<--format> raw
284
285 Specify the format of the input disk image.  If this flag is not
286 given then it is auto-detected from the image itself.
287
288 If working with untrusted raw-format guest disk images, you should
289 ensure the format is always specified.
290
291 Note that this option I<does not> affect the output format.
292 See L</QCOW2 AND NON-SPARSE RAW FORMATS>.
293
294 =item B<--ignore part>
295
296 Ignore the named partition.  Effectively this means the partition is
297 allocated on the destination disk, but the content is not copied
298 across from the source disk.  The content of the partition will be
299 blank (all zero bytes).
300
301 You can give this option multiple times.
302
303 =item B<--LV-expand logvol>
304
305 This takes the logical volume and, as a final step, expands it to fill
306 all the space available in its volume group.  A typical usage,
307 assuming a Linux guest with a single PV C</dev/sda2> and a root device
308 called C</dev/vg_guest/lv_root> would be:
309
310  virt-resize indisk outdisk \
311    --expand /dev/sda2 --LV-expand /dev/vg_guest/lv_root
312
313 This would first expand the partition (and PV), and then expand the
314 root device to fill the extra space in the PV.
315
316 The contents of the LV are also resized if virt-resize knows how to do
317 that.  You can stop virt-resize from trying to expand the content by
318 using the option I<--no-expand-content>.
319
320 Use L<virt-filesystems(1)> to list the filesystems in the guest.
321
322 You can give this option multiple times, I<but> it doesn't
323 make sense to do this unless the logical volumes you specify
324 are all in different volume groups.
325
326 =item B<-n>
327
328 =item B<--dryrun>
329
330 Print a summary of what would be done, but don't do anything.
331
332 =item B<--no-copy-boot-loader>
333
334 By default, virt-resize copies over some sectors at the start of the
335 disk (up to the beginning of the first partition).  Commonly these
336 sectors contain the Master Boot Record (MBR) and the boot loader, and
337 are required in order for the guest to boot correctly.
338
339 If you specify this flag, then this initial copy is not done.  You may
340 need to reinstall the boot loader in this case.
341
342 =item B<--no-extra-partition>
343
344 By default, virt-resize creates an extra partition if there is any
345 extra, unused space after all resizing has happened.  Use this option
346 to prevent the extra partition from being created.  If you do this
347 then the extra space will be inaccessible until you run fdisk, parted,
348 or some other partitioning tool in the guest.
349
350 Note that if the surplus space is smaller than 10 MB, no extra
351 partition will be created.
352
353 =item B<--no-expand-content>
354
355 By default, virt-resize will try to expand the direct contents
356 of partitions, if it knows how (see I<--expand> option above).
357
358 If you give the I<--no-expand-content> option then virt-resize
359 will not attempt this.
360
361 =item B<--ntfsresize-force>
362
363 Pass the I<--force> option to L<ntfsresize(8)>, allowing resizing
364 even if the NTFS disk is marked as needing a consistency check.
365 You have to use this option if you want to resize a Windows
366 guest multiple times without booting into Windows between each
367 resize.
368
369 =item B<--output-format> raw
370
371 Specify the format of the output disk image.  If this flag is not
372 given then it is auto-detected from the image itself.
373
374 If working with untrusted raw-format guest disk images, you should
375 ensure the format is always specified.
376
377 Note that this option I<does not create> the output format.  This
378 option just tells libguestfs what it is so it doesn't try to guess it.
379 You still need to create the output disk with the right format.  See
380 L</QCOW2 AND NON-SPARSE RAW FORMATS>.
381
382 =item B<-q>
383
384 =item B<--quiet>
385
386 Don't print the summary.
387
388 =item B<--resize part=size>
389
390 Resize the named partition (expanding or shrinking it) so that it has
391 the given size.
392
393 C<size> can be expressed as an absolute number followed by
394 b/K/M/G to mean bytes, Kilobytes, Megabytes, or Gigabytes;
395 or as a percentage of the current size;
396 or as a relative number or percentage.
397 For example:
398
399  --resize /dev/sda2=10G
400
401  --resize /dev/sda4=90%
402
403  --resize /dev/sda2=+1G
404
405  --resize /dev/sda2=-200M
406
407  --resize /dev/sda1=+128K
408
409  --resize /dev/sda1=+10%
410
411  --resize /dev/sda1=-10%
412
413 You can increase the size of any partition.  Virt-resize will expand
414 the direct content of the partition if it knows how (see I<--expand>
415 below).
416
417 You can only I<decrease> the size of partitions that contain
418 filesystems or PVs which have already been shrunk.  Virt-resize will
419 check this has been done before proceeding, or else will print an
420 error (see also I<--resize-force>).
421
422 You can give this option multiple times.
423
424 =item B<--resize-force part=size>
425
426 This is the same as I<--resize> except that it will let you decrease
427 the size of any partition.  Generally this means you will lose any
428 data which was at the end of the partition you shrink, but you may not
429 care about that (eg. if shrinking an unused partition, or if you can
430 easily recreate it such as a swap partition).
431
432 See also the I<--ignore> option.
433
434 =item B<--shrink part>
435
436 Shrink the named partition until the overall disk image fits in the
437 destination.  The named partition B<must> contain a filesystem or PV
438 which has already been shrunk using another tool (eg. L<guestfish(1)>
439 or other online tools).  Virt-resize will check this and give an error
440 if it has not been done.
441
442 The amount by which the overall disk must be shrunk (after carrying
443 out all other operations requested by the user) is called the
444 "deficit".  For example, a straight copy (assume no other operations)
445 from a 5GB disk image to a 4GB disk image results in a 1GB deficit.
446 In this case, virt-resize would give an error unless the user
447 specified a partition to shrink and that partition had more than a
448 gigabyte of free space.
449
450 Note that you cannot use I<--expand> and I<--shrink> together.
451
452 =item B<-V>
453
454 =item B<--version>
455
456 Display version number and exit.
457
458 =back
459
460 =head1 NOTES
461
462 =head2 "Partition 1 does not end on cylinder boundary."
463
464 Virt-resize aligns partitions to multiples of 64 sectors.  Usually
465 this means the partitions will not be aligned to the ancient CHS
466 geometry.  However CHS geometry is meaningless for disks manufactured
467 since the early 1990s, and doubly so for virtual hard drives.
468 Alignment of partitions to cylinders is not required by any modern
469 operating system.
470
471 =head2 RESIZING WINDOWS VIRTUAL MACHINES
472
473 In Windows Vista and later versions, Microsoft switched to using a
474 separate boot partition.  In these VMs, typically C</dev/sda1> is the
475 boot partition and C</dev/sda2> is the main (C:) drive.  We have not
476 had any luck resizing the boot partition.  Doing so seems to break the
477 guest completely.  However expanding the second partition (ie. C:
478 drive) should work.
479
480 Windows may initiate a lengthy "chkdsk" on first boot after a resize,
481 if NTFS partitions have been expanded.  This is just a safety check
482 and (unless it find errors) is nothing to worry about.
483
484 =head2 GUEST BOOT STUCK AT "GRUB"
485
486 If a Linux guest does not boot after resizing, and the boot is stuck
487 after printing C<GRUB> on the console, try reinstalling grub.  This
488 sometimes happens on older (RHEL 5-era) guests, for reasons we don't
489 fully understand, although we think is to do with partition alignment.
490
491  guestfish -i -a newdisk
492  ><fs> cat /boot/grub/device.map
493  # check the contents of this file are sensible or
494  # edit the file if necessary
495  ><fs> grub-install / /dev/vda
496  ><fs> exit
497
498 For more flexible guest reconfiguration, including if you need to
499 specify other parameters to grub-install, use L<virt-rescue(1)>.
500
501 =head1 ALTERNATIVE TOOLS
502
503 There are several proprietary tools for resizing partitions.  We
504 won't mention any here.
505
506 L<parted(8)> and its graphical shell gparted can do some types of
507 resizing operations on disk images.  They can resize and move
508 partitions, but I don't think they can do anything with the contents,
509 and they certainly don't understand LVM.
510
511 L<guestfish(1)> can do everything that virt-resize can do and a lot
512 more, but at a much lower level.  You will probably end up
513 hand-calculating sector offsets, which is something that virt-resize
514 was designed to avoid.  If you want to see the guestfish-equivalent
515 commands that virt-resize runs, use the I<--debug> flag.
516
517 =head1 SHELL QUOTING
518
519 Libvirt guest names can contain arbitrary characters, some of which
520 have meaning to the shell such as C<#> and space.  You may need to
521 quote or escape these characters on the command line.  See the shell
522 manual page L<sh(1)> for details.
523
524 =head1 SEE ALSO
525
526 L<virt-filesystems(1)>,
527 L<virt-df(1)>,
528 L<guestfs(3)>,
529 L<guestfish(1)>,
530 L<lvm(8)>,
531 L<pvresize(8)>,
532 L<lvresize(8)>,
533 L<resize2fs(8)>,
534 L<ntfsresize(8)>,
535 L<virsh(1)>,
536 L<parted(8)>,
537 L<truncate(1)>,
538 L<fallocate(1)>,
539 L<grub(8)>,
540 L<grub-install(8)>,
541 L<virt-rescue(1)>,
542 L<http://libguestfs.org/>.
543
544 =head1 AUTHOR
545
546 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
547
548 =head1 COPYRIGHT
549
550 Copyright (C) 2010-2011 Red Hat Inc.
551
552 This program is free software; you can redistribute it and/or modify
553 it under the terms of the GNU General Public License as published by
554 the Free Software Foundation; either version 2 of the License, or
555 (at your option) any later version.
556
557 This program is distributed in the hope that it will be useful,
558 but WITHOUT ANY WARRANTY; without even the implied warranty of
559 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
560 GNU General Public License for more details.
561
562 You should have received a copy of the GNU General Public License
563 along with this program; if not, write to the Free Software
564 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.