1guestfs-recipes(1) Virtualization Support guestfs-recipes(1)
2
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 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 guestfish --ro -a disk.img run : checksum-device md5 /dev/sda1
38 Replace "md5" with the type of checksum you want. See
40 "guestfs_checksum_device" in guestfs(3) for a list of supported types.
41 /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 To checksum a single file:
47 guestfish --ro -a disk.img -i checksum sha256 /etc/passwd
49 or for a Windows guest:
51 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 For more details, see: "COPYING AND CLONING" in virt-sysprep(1).
60
62 This converts input cd.iso to output cd.tar.gz:
63 guestfish --ro -a cd.iso -m /dev/sda tgz-out / cd.tar.gz
65 To export just a subdirectory, eg. /files, do:
67 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 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 First create the formatted-but-empty target disk:
80 truncate -s 10G target.img
82 virt-format -a target.img --partition=mbr --lvm --filesystem=ext3
83 Now, pipe two guestfish instances together to transfer the old data to
85 the new disk:
86 guestfish --ro -a source.img -m /dev/sda1 -- tar-out / - | \
88 guestfish --rw -a target.img -m /dev/VG/LV -- tar-in - /
89 To browse the final disk image, do:
91 guestfish --ro -a target.img -m /dev/VG/LV
93 ><fs> ll /
94 This technique is quite powerful, allowing you for example to split up
96 source directories over the target filesystems.
97 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 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 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 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 You can also use the guestfish(1) -N option to create empty disk
137 images. The useful guide below explains the options available.
138 https://rwmj.wordpress.com/2010/09/08/new-guestfish-n-options-in-1-5-9/#content
140 virt-builder(1) can create minimal guests.
142
144 Use guestfish. To delete a file:
145 guestfish -a disk.img -i rm /file/to/delete
147 To touch a file (bring it up to date or create it):
149 guestfish -a disk.img -i touch /file/to/touch
151 To stat a file. Since this is a read-only operation, we can make it
153 safer by adding the --ro flag.
154 guestfish --ro -a disk.img -i stat /file/to/stat
156 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 guestfish -a disk.img -i \
171 ln-sf /dev/null /etc/systemd/system/cloud-init.service
172 To disable tmp-on-tmpfs:
174 guestfish -a disk.img -i \
176 ln-sf /dev/null /etc/systemd/system/tmp.mount
177 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 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 #!/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 You can use the script like this:
214 $ mkdir /tmp/mnt
216 $ ./drive-letters.pl /tmp/mnt windows7.img
217 filesystem ready on /tmp/mnt
218 In another window:
220 $ 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 guestfish --ro -a disk.img run : download /dev/sda1 sda1.img
240 guestfish --ro -d Guest run : download /dev/vg_guest/lv_root lv.img
242 To download to stdout, replace the filename with a "-" character:
244 guestfish --ro -a disk.img run : download /dev/sda1 - | gzip > sda1.gz
246 To list the filesystems in a disk image, use virt-filesystems(1).
248 See also "Uploading raw filesystem content".
250
252 You can use this to:
253 • Fix a virtual machine that does not boot.
255 • Change which kernel is used to boot the VM.
257 • Change kernel command line options.
259 Use virt-edit(1) to edit the grub configuration:
261 virt-edit -d BrokenGuest /boot/grub2/grub.cfg
263 or for general tinkering inside an unbootable VM use virt-rescue(1)
265 like this:
266 virt-rescue -d BrokenGuest
268
270 To export /home from a VM into a local directory use virt-copy-out(1):
271 virt-copy-out -d Guest /home .
273 Notes:
275 • The final dot of the command is not a printing error. It means we
277 want to copy out to the current directory.
278 • This creates a directory called "home" under the current directory.
280 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 virt-copy-out -d WinGuest 'win:c:\windows\system32\config' .
286 To get the output as a compressed tarball, do:
288 virt-tar-out -d Guest /home - | gzip --best > home.tar.gz
290 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 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 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 #!/bin/sh -
315 set -e
317 vm="$1"
319 dir=/home
320 eval $(guestfish --ro -d "$vm" -i --listen)
322 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 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 https://rwmj.wordpress.com/2011/03/31/tip-code-for-getting-dhcp-address-from-a-virtual-machine-disk-image/#content
336 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 #!/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 Make the script executable and run it on a named guest:
351 # product-name.sh RHEL60x64
353 Red Hat Enterprise Linux Server release 6.0 (Santiago)
354 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 # 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 https://rwmj.wordpress.com/2010/10/30/tip-use-augeas-to-get-the-default-boot-kernel-for-a-vm/#content
369 It uses Augeas, and the technique is generally applicable for many
371 different tasks, such as:
372 • listing the user accounts in the guest
374 • what repositories is it configured to use
376 • what NTP servers does it connect to
378 • what were the boot messages last time it booted
380 • listing who was logged in recently
382 http://augeas.net/
384
386 There are various ways to use libguestfs to find out why a guest is
387 hanging or unresponsive:
388 1. Read the log files using virt-cat:
390 virt-cat Guest /var/log/messages | less
392 2. Read the Windows Event Log (Windows Vista or later only):
394 https://rwmj.wordpress.com/2011/04/17/decoding-the-windows-event-log-using-guestfish/#content
396 3. Find out which files were last updated in a guest:
398 https://rwmj.wordpress.com/2012/02/27/using-libguestfs-to-find-out-why-a-windows-guest-was-hanging/#content
400 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 guestfish --ro -a disk.img run : pread-device /dev/sda 0x200 0 |
407 hexdump -C
408 (0x200 = 512 bytes which is the size of traditional PC sectors)
410 To hexdump the N'th partition, substitute a number for "N" in the
412 following command:
413 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 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 For example:
430 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 For example this would install packages from the updates-testing
439 repository in Fedora:
440 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 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 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 DEFAULT linux
462 LABEL linux
463 SAY Booting the kernel
464 KERNEL vmlinuz
465 INITRD initrd
466 APPEND ro root=/dev/sda3
467 Locate the syslinux master boot record (a file called something like
469 /usr/share/syslinux/mbr.bin).
470 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 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 #!/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 Make the file executable and then you can run it on any named virtual
496 machine:
497 # 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 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 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 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 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 virt-edit -d domname /etc/passwd -e 's/^root:.*?:/root::/'
563 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 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 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 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 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 guestfish --rw -a disk.img run : upload sda1.img /dev/sda1
602 guestfish --rw -d Guest run : upload lv.img /dev/vg_guest/lv_root
604 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 guestfish --rw -d Guest run : \
612 upload lv.img /dev/vg_guest/lv_root : \
613 resize2fs /dev/vg_guest/lv_root
614 (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 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-2020 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 To report a new bug against libguestfs, use this link:
646 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
647 When reporting a bug, please supply:
649 • The version of libguestfs.
651 • Where you got libguestfs (eg. which Linux distro, compiled from
653 source, etc)
654 • Describe the bug accurately and give a way to reproduce it.
656 • Run libguestfs-test-tool(1) and paste the complete, unedited output
658 into the bug report.
659libguestfs-1.46.0 2021-09-23 guestfs-recipes(1)