1guestfs-recipes(1) Virtualization Support guestfs-recipes(1)
2
3
4
6 guestfs-recipes - libguestfs, guestfish and virt tools recipes
7
9 This page contains recipes for and links to things you can do using
10 libguestfs, guestfish(1) and the virt tools.
11
13 If the disk image is on a remote server which is accessible using SSH,
14 HTTP, FTP, NBD, iSCSI, or similar, then you can open it directly. See
15 "ADDING REMOTE STORAGE" in guestfish(1) for several examples. This
16 requires libguestfs ≥ 1.22 and qemu ≥ 1.5.
17
19 See: "EXAMPLES" in virt-ls(1).
20
22 See:
23 https://rwmj.wordpress.com/2013/05/16/scanning-offline-guests-using-openscap-and-guestmount/#content
24
26 The links below explain how to use guestfish(1) to change the
27 background image for a user of a Windows XP VM. Unfortunately the
28 technique appears to be substantially different for each version of
29 Windows.
30
31 https://lists.fedoraproject.org/pipermail/virt/2011-May/002655.html
32 https://lists.fedoraproject.org/pipermail/virt/2011-May/002658.html
33
35 To checksum a whole device, or a partition, LV etc within a disk image:
36
37 guestfish --ro -a disk.img run : checksum-device md5 /dev/sda1
38
39 Replace "md5" with the type of checksum you want. See
40 "guestfs_checksum_device" in guestfs(3) for a list of supported types.
41
42 /dev/sda1 means "the first partition". You could use /dev/sda to
43 checksum the whole disk image, or the name of a logical volume or RAID
44 device.
45
46 To checksum a single file:
47
48 guestfish --ro -a disk.img -i checksum sha256 /etc/passwd
49
50 or for a Windows guest:
51
52 guestfish --ro -a disk.img -i \
53 checksum sha256 'win:\windows\system32\config\SOFTWARE'
54
56 Use a combination of tools like cp(1), dd(1), and virt tools like
57 virt-sysprep(1), virt-sparsify(1) and virt-resize(1).
58
59 For more details, see: "COPYING AND CLONING" in virt-sysprep(1).
60
62 This converts input cd.iso to output cd.tar.gz:
63
64 guestfish --ro -a cd.iso -m /dev/sda tgz-out / cd.tar.gz
65
66 To export just a subdirectory, eg. /files, do:
67
68 guestfish --ro -a cd.iso -m /dev/sda tgz-out /files cd.tar.gz
69
71 If you have a data disk in one format / filesystem / partition / volume
72 manager, you can convert it another using this technique.
73
74 In this example, we start with a data disk that has a single partition
75 containing a filesystem, and we want to create another disk that
76 contains the same files but on an ext3 filesystem embedded in a logical
77 volume on a sparse raw-format disk.
78
79 First create the formatted-but-empty target disk:
80
81 truncate -s 10G target.img
82 virt-format -a target.img --partition=mbr --lvm --filesystem=ext3
83
84 Now, pipe two guestfish instances together to transfer the old data to
85 the new disk:
86
87 guestfish --ro -a source.img -m /dev/sda1 -- tar-out / - | \
88 guestfish --rw -a target.img -m /dev/VG/LV -- tar-in - /
89
90 To browse the final disk image, do:
91
92 guestfish --ro -a target.img -m /dev/VG/LV
93 ><fs> ll /
94
95 This technique is quite powerful, allowing you for example to split up
96 source directories over the target filesystems.
97
98 Note this won’t work (at least, not directly) for bootable virtual
99 machine disks because it doesn't copy over the boot loader.
100
102 http://rwmj.wordpress.com/2013/05/09/tip-convert-a-windows-dvd-iso-to-a-bootable-usb-key-using-guestfish/#content
103
105 Xen disk images are often partitionless, meaning that the filesystem
106 starts directly at the beginning of the disk with no partition table.
107 You can in fact use these directly in KVM (provided the guest isn't
108 Windows), but some people like to convert them to regular partitioned
109 disk images, and this is required for Windows guests. Here is how to
110 use guestfish to do this:
111
112 guestfish
113 ><fs> add-ro input.img
114 ><fs> sparse output.img 10G # adjust the output size
115 ><fs> run
116 # Create a partition table on the output disk:
117 ><fs> part-init /dev/sdb mbr
118 ><fs> part-add /dev/sdb p 2048 -2048
119 # Copy the data to the target partition:
120 ><fs> copy-device-to-device /dev/sda /dev/sdb1 sparse:true
121 # Optionally resize the target filesystem. Use ntfsresize
122 # for Windows guests:
123 ><fs> resize2fs /dev/sdb1
124
125 Such a disk image won’t be directly bootable. You may need to boot it
126 with an external kernel and initramfs (see below). Or you can use the
127 guestfish commands "syslinux" or "extlinux" to install a SYSLINUX
128 bootloader.
129
131 The virt-format(1) tool can do this directly.
132
133 Use virt-make-fs(1) to create a disk image with content. This can also
134 create some standard disk images such as virtual floppy devices (VFDs).
135
136 You can also use the guestfish(1) -N option to create empty disk
137 images. The useful guide below explains the options available.
138
139 https://rwmj.wordpress.com/2010/09/08/new-guestfish-n-options-in-1-5-9/#content
140
141 virt-builder(1) can create minimal guests.
142
144 Use guestfish. To delete a file:
145
146 guestfish -a disk.img -i rm /file/to/delete
147
148 To touch a file (bring it up to date or create it):
149
150 guestfish -a disk.img -i touch /file/to/touch
151
152 To stat a file. Since this is a read-only operation, we can make it
153 safer by adding the --ro flag.
154
155 guestfish --ro -a disk.img -i stat /file/to/stat
156
157 There are dozens of these commands. See guestfish(1) or the output of
158 "guestfish -h"
159
161 Since libguestfs ≥ 1.26, use virt-diff(1) to look for differences
162 between two guests (for example if they were originally cloned from the
163 same source), or between two snapshots from the same guest. In earlier
164 versions of libguestfs, use virt-ls(1).
165
167 The following is the equivalent of "systemctl mask ...". To disable the
168 "cloud-init" service so it doesn't start at next boot:
169
170 guestfish -a disk.img -i \
171 ln-sf /dev/null /etc/systemd/system/cloud-init.service
172
173 To disable tmp-on-tmpfs:
174
175 guestfish -a disk.img -i \
176 ln-sf /dev/null /etc/systemd/system/tmp.mount
177
178 One problem with the commands above is there is no feedback if you get
179 the name of the service you are trying to mask wrong. But you can use
180 virt-ls(1) to list the available systemd services like this:
181
182 virt-ls -a /tmp/fedora-19.img -R /lib/systemd/system
183
185 You have a Windows guest, and you want to expose the drive letters as
186 FUSE mountpoints (/C/..., /D/... etc). Instead of guestmount(1), use
187 this Perl script:
188
189 #!/usr/bin/perl -w
190 use strict;
191 use Sys::Guestfs;
192 $| = 1;
193 die "usage: $0 mountpoint disk.img" if @ARGV < 2;
194 my $mp = shift @ARGV;
195 my $g = new Sys::Guestfs;
196 $g->add_drive_opts ($_) foreach @ARGV;
197 $g->launch;
198 my @roots = $g->inspect_os;
199 die "$0: no operating system found" if @roots != 1;
200 my $root = $roots[0];
201 die "$0: not Windows" if $g->inspect_get_type ($root) ne "windows";
202 my %map = $g->inspect_get_drive_mappings ($root);
203 foreach (keys %map) {
204 $g->mkmountpoint ("/$_");
205 eval { $g->mount ($map{$_}, "/$_") };
206 warn "$@ (ignored)\n" if $@;
207 }
208 $g->mount_local ($mp);
209 print "filesystem ready on $mp\n";
210 $g->mount_local_run;
211 $g->shutdown;
212
213 You can use the script like this:
214
215 $ mkdir /tmp/mnt
216 $ ./drive-letters.pl /tmp/mnt windows7.img
217 filesystem ready on /tmp/mnt
218
219 In another window:
220
221 $ cd /tmp/mnt
222 $ ls
223 C D
224 $ cd C
225 $ ls
226 Documents and Settings
227 PerfLogs
228 ProgramData
229 Program Files
230 [etc]
231 $ cd ../..
232 $ guestunmount /tmp/mnt
233
235 You can use the guestfish(1) "download" command to extract the raw
236 filesystem content from any filesystem in a disk image or a VM (even
237 one which is encrypted or buried inside an LV or RAID device):
238
239 guestfish --ro -a disk.img run : download /dev/sda1 sda1.img
240
241 guestfish --ro -d Guest run : download /dev/vg_guest/lv_root lv.img
242
243 To download to stdout, replace the filename with a "-" character:
244
245 guestfish --ro -a disk.img run : download /dev/sda1 - | gzip > sda1.gz
246
247 To list the filesystems in a disk image, use virt-filesystems(1).
248
249 See also "Uploading raw filesystem content".
250
252 You can use this to:
253
254 · Fix a virtual machine that does not boot.
255
256 · Change which kernel is used to boot the VM.
257
258 · Change kernel command line options.
259
260 Use virt-edit(1) to edit the grub configuration:
261
262 virt-edit -d BrokenGuest /boot/grub2/grub.cfg
263
264 or for general tinkering inside an unbootable VM use virt-rescue(1)
265 like this:
266
267 virt-rescue -d BrokenGuest
268
270 To export /home from a VM into a local directory use virt-copy-out(1):
271
272 virt-copy-out -d Guest /home .
273
274 Notes:
275
276 · The final dot of the command is not a printing error. It means we
277 want to copy out to the current directory.
278
279 · This creates a directory called "home" under the current directory.
280
281 If the guest is a Windows guest then you can use drive letters and
282 backslashes, but you must prefix the path with "win:" and quote it to
283 protect it from the shell, like this:
284
285 virt-copy-out -d WinGuest 'win:c:\windows\system32\config' .
286
287 To get the output as a compressed tarball, do:
288
289 virt-tar-out -d Guest /home - | gzip --best > home.tar.gz
290
291 Although it sounds tempting, this is usually not a reliable way to get
292 a backup from a running guest. See the entry in the FAQ:
293 http://libguestfs.org/FAQ.html#backup
294
296 If a Linux guest doesn't have a boot loader or it is broken, then you
297 can usually boot it using an external kernel and initramfs. In this
298 configuration, the hypervisor acts like a bootloader, loading the
299 kernel from the host disk into guest memory and jumping straight into
300 the kernel.
301
302 However you may wonder how to get the right kernel corresponding to the
303 disk image you have. Since libguestfs ≥ 1.24 virt-builder(1) can get
304 the latest kernel and corresponding initramfs for you:
305
306 mkdir outputdir
307 virt-builder --get-kernel disk.img -o outputdir
308 ls -lh outputdir
309
311 This simple script examines a Linux guest to find out which user is
312 using the most space in their home directory:
313
314 #!/bin/sh -
315
316 set -e
317
318 vm="$1"
319 dir=/home
320
321 eval $(guestfish --ro -d "$vm" -i --listen)
322
323 for d in $(guestfish --remote ls "$dir"); do
324 echo -n "$dir/$d"
325 echo -ne '\t'
326 guestfish --remote du "$dir/$d";
327 done | sort -nr -k 2
328
329 guestfish --remote exit
330
332 The link below explains the many different possible techniques for
333 getting the last assigned DHCP address of a virtual machine.
334
335 https://rwmj.wordpress.com/2011/03/31/tip-code-for-getting-dhcp-address-from-a-virtual-machine-disk-image/#content
336
337 In the libguestfs source examples directory you will find the latest
338 version of the virt-dhcp-address.c program.
339
341 Save the following script into a file called product-name.sh:
342
343 #!/bin/sh -
344 set -e
345 eval "$(guestfish --ro -d "$1" --i --listen)"
346 root="$(guestfish --remote inspect-get-roots)"
347 guestfish --remote inspect-get-product-name "$root"
348 guestfish --remote exit
349
350 Make the script executable and run it on a named guest:
351
352 # product-name.sh RHEL60x64
353 Red Hat Enterprise Linux Server release 6.0 (Santiago)
354
355 You can also use an XPath query on the virt-inspector(1) XML using the
356 "xpath" command line tool or from your favourite programming language:
357
358 # virt-inspector RHEL60x64 > xml
359 # xpath '//product_name' < xml
360 Found 1 nodes:
361 -- NODE --
362 <product_name>Red Hat Enterprise Linux Server release 6.0 (Santiago)</product_name>
363
365 The link below contains a program to print the default boot kernel for
366 a Linux VM.
367
368 https://rwmj.wordpress.com/2010/10/30/tip-use-augeas-to-get-the-default-boot-kernel-for-a-vm/#content
369
370 It uses Augeas, and the technique is generally applicable for many
371 different tasks, such as:
372
373 · listing the user accounts in the guest
374
375 · what repositories is it configured to use
376
377 · what NTP servers does it connect to
378
379 · what were the boot messages last time it booted
380
381 · listing who was logged in recently
382
383 http://augeas.net/
384
386 There are various ways to use libguestfs to find out why a guest is
387 hanging or unresponsive:
388
389 1. Read the log files using virt-cat:
390
391 virt-cat Guest /var/log/messages | less
392
393 2. Read the Windows Event Log (Windows Vista or later only):
394
395 https://rwmj.wordpress.com/2011/04/17/decoding-the-windows-event-log-using-guestfish/#content
396
397 3. Find out which files were last updated in a guest:
398
399 https://rwmj.wordpress.com/2012/02/27/using-libguestfs-to-find-out-why-a-windows-guest-was-hanging/#content
400
401 This might give you a clue as to what program is running.
402
404 Hex-dump the boot partition (Master Boot Record / first sector):
405
406 guestfish --ro -a disk.img run : pread-device /dev/sda 0x200 0 |
407 hexdump -C
408
409 (0x200 = 512 bytes which is the size of traditional PC sectors)
410
411 To hexdump the N'th partition, substitute a number for "N" in the
412 following command:
413
414 guestfish --ro -a disk.img \
415 run : pread-device /dev/sda 0x200 $((N*0x200)) |
416 hexdump -C
417
419 Hex-edit the boot partition (Master Boot Record / first sector):
420
421 guestfish --rw -a disk.img run : hexedit /dev/sda 0x200
422
424 Since libguestfs 1.26, virt-builder(1), virt-customize(1) and
425 virt-sysprep(1) have an --install option for installing packages in
426 Linux guests. (Use virt-customize if you have an existing guest, or
427 virt-builder if you want to create a guest from scratch).
428
429 For example:
430
431 virt-builder fedora-20 --install emacs
432
434 Since libguestfs 1.26, you can use virt-builder(1), virt-customize(1)
435 or virt-sysprep(1) --edit option to edit repository metadata before
436 installing packages
437
438 For example this would install packages from the updates-testing
439 repository in Fedora:
440
441 virt-builder fedora-20 \
442 --edit '/etc/yum.repos.d/fedora-updates-testing.repo:
443 s/enabled=0/enabled=1/' \
444 --install emacs
445
447 SYSLINUX is a small, easy to configure bootloader for Linux and Windows
448 guests. If your guest is not bootable, you can install the SYSLINUX
449 bootloader using either the guestfish commands "syslinux" (for FAT-
450 based guests) or "extlinux" (for ext2/3/4 and btrfs-based guests).
451
452 This guide assumes a Linux guest where /dev/sda1 is /boot,
453 /boot/vmlinuz is the guest kernel, and /dev/sda3 is the root partition.
454 For a Windows guest you would need a FAT-formatted boot partition and
455 you would need to use the "syslinux" command instead.
456
457 Create a syslinux.cfg configuration file. You should check the
458 SYSLINUX documentation at http://www.syslinux.org but it may look
459 something like this:
460
461 DEFAULT linux
462 LABEL linux
463 SAY Booting the kernel
464 KERNEL vmlinuz
465 INITRD initrd
466 APPEND ro root=/dev/sda3
467
468 Locate the syslinux master boot record (a file called something like
469 /usr/share/syslinux/mbr.bin).
470
471 guestfish -a disk.img -i
472 # Upload the master boot record and configuration file:
473 ><fs> upload ..../mbr.bin /boot/mbr.bin
474 ><fs> upload ..../syslinux.cfg /boot/syslinux.cfg
475 # Put the MBR into the boot sector:
476 ><fs> copy-file-to-device /boot/mbr.bin /dev/sda size:440
477 # Install syslinux on the first partition:
478 ><fs> extlinux /boot
479 # Set the first partition as bootable:
480 ><fs> part-set-bootable /dev/sda 1 true
481
482 See also:
483 http://rwmj.wordpress.com/2013/04/04/new-in-libguestfs-use-syslinux-or-extlinux-to-make-bootable-guests/#content
484
486 Save the following to a file list-apps.sh:
487
488 #!/bin/sh -
489 set -e
490 eval "$(guestfish --ro -d "$1" --i --listen)"
491 root="$(guestfish --remote inspect-get-roots)"
492 guestfish --remote inspect-list-applications "$root"
493 guestfish --remote exit
494
495 Make the file executable and then you can run it on any named virtual
496 machine:
497
498 # list-apps.sh WinGuest
499 [0] = {
500 app_name: Mozilla Firefox (3.6.12)
501 app_display_name: Mozilla Firefox (3.6.12)
502 app_epoch: 0
503 app_version: 3.6.12 (en-GB)
504 app_release:
505 app_install_path: C:\Program Files\Mozilla Firefox
506 app_trans_path:
507 app_publisher: Mozilla
508 app_url: http://www.mozilla.com/en-GB/
509 app_source_package:
510 app_summary:
511 app_description: Mozilla Firefox
512 }
513 [1] = {
514 app_name: VLC media player
515 app_display_name: VLC media player 1.1.5
516 app_epoch: 0
517 app_version: 1.1.5
518 app_release:
519 app_install_path: C:\Program Files\VideoLAN\VLC
520 app_trans_path:
521 app_publisher: VideoLAN
522 app_url: http://www.videolan.org/
523 app_source_package:
524 app_summary:
525 app_description:
526 }
527
528 If you want to run the script on disk images (instead of libvirt
529 virtual machines), change "-d "$1"" to "-a "$1"". See also
530 virt-inspector(1).
531
533 Use virt-ls(1).
534
536 The link below contains a script that can be used to list out the
537 services from a Windows VM, and whether those services run at boot time
538 or are loaded on demand.
539
540 https://rwmj.wordpress.com/2010/12/10/tip-list-services-in-a-windows-guest/#content
541
543 Use virt-sparsify(1).
544
546 You can use virt-df(1) to monitor disk usage of your guests over time.
547 The link below contains a guide.
548
549 http://web.archive.org/web/20130214073726/http://virt-tools.org/learning/advanced-virt-df/
550
552 guestfish(1) plus the tools described in the link below can be used to
553 read out the Windows Event Log from any virtual machine running Windows
554 Vista or a later version.
555
556 https://rwmj.wordpress.com/2011/04/17/decoding-the-windows-event-log-using-guestfish/#content
557
559 Using the virt-edit(1) -e option you can do simple replacements on
560 files. One use is to remove the root password from a Linux guest:
561
562 virt-edit -d domname /etc/passwd -e 's/^root:.*?:/root::/'
563
564 virt-edit -a disk.img /etc/passwd -e 's/^root:.*?:/root::/'
565
567 The link below contains one technique for removing the Administrator
568 password from a Windows VM, or to be more precise, it gives you a
569 command prompt the next time you log in which you can use to bypass any
570 security:
571
572 https://mdbooth.wordpress.com/2010/10/18/resetting-a-windows-guests-administrator-password-with-guestfish/
573
575 It is possible to do a "sysprep" using libguestfs alone, although not
576 straightforward. Currently there is code in the Aeolus Oz project
577 which does this (using libguestfs). It is likely we will add this to
578 virt-sysprep(1) in future.
579
580 https://github.com/clalancette/oz
581 https://www.redhat.com/archives/virt-tools-list/2011-May/msg00019.html
582
584 Linux live CDs often contain multiple layers of disk images wrapped
585 like a Russian doll. You can use guestfish(1) to look inside these
586 multiple layers, as outlined in the guide below.
587
588 https://rwmj.wordpress.com/2009/07/15/unpack-the-russian-doll-of-a-f11-live-cd/#content
589
591 The link below contains general tips on uploading (copying in) and
592 downloading (copying out) files from VMs.
593
594 https://rwmj.wordpress.com/2010/12/02/tip-uploading-and-downloading/#content
595
597 You can use guestfish(1) to upload whole filesystems into a VM, even
598 into a filesystem which is encrypted or buried inside an LV or RAID
599 device:
600
601 guestfish --rw -a disk.img run : upload sda1.img /dev/sda1
602
603 guestfish --rw -d Guest run : upload lv.img /dev/vg_guest/lv_root
604
605 One common problem is that the filesystem isn't the right size for the
606 target. If it is too large, there’s not much you can do with
607 libguestfs - you have to prepare the filesystem differently. But if
608 the filesystem needs to expand into the target, you can use guestfish
609 to resize it to the right size:
610
611 guestfish --rw -d Guest run : \
612 upload lv.img /dev/vg_guest/lv_root : \
613 resize2fs /dev/vg_guest/lv_root
614
615 (or use "ntfsresize" if the filesystem is NTFS).
616
618 The link below explains how to use libguestfs, guestfish(1) and the
619 virt tools on any VMware ESX guests, by first sharing the VMware VMFS
620 over sshfs.
621
622 https://rwmj.wordpress.com/2011/05/10/tip-use-libguestfs-on-vmware-esx-guests/#content
623
625 guestfs(3), guestfish(1), guestfs-examples(3), guestfs-erlang(3),
626 guestfs-gobject(3), guestfs-golang(3), guestfs-java(3), guestfs-lua(3),
627 guestfs-ocaml(3), guestfs-perl(3), guestfs-python(3), guestfs-ruby(3),
628 http://libguestfs.org/.
629
631 Richard W.M. Jones ("rjones at redhat dot com")
632
634 Copyright (C) 2009-2019 Red Hat Inc.
635
637 This manual page contains examples which we hope you will use in your
638 programs. The examples may be freely copied, modified and distributed
639 for any purpose without any restrictions.
640
642 To get a list of bugs against libguestfs, use this link:
643 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
644
645 To report a new bug against libguestfs, use this link:
646 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
647
648 When reporting a bug, please supply:
649
650 · The version of libguestfs.
651
652 · Where you got libguestfs (eg. which Linux distro, compiled from
653 source, etc)
654
655 · Describe the bug accurately and give a way to reproduce it.
656
657 · Run libguestfs-test-tool(1) and paste the complete, unedited output
658 into the bug report.
659
660
661
662libguestfs-1.40.2 2019-02-07 guestfs-recipes(1)