1guestfs-recipes(1)          Virtualization Support          guestfs-recipes(1)
2
3
4

NAME

6       guestfs-recipes - libguestfs, guestfish and virt tools recipes
7

DESCRIPTION

9       This page contains recipes for and links to things you can do using
10       libguestfs, guestfish(1) and the virt tools.
11

Access a remote disk image using guestfish

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

Audit a virtual machine for setuid files

19       See: "EXAMPLES" in virt-ls(1).
20

Audit a virtual machine for vulnerabilities and security problems

22       See:
23       https://rwmj.wordpress.com/2013/05/16/scanning-offline-guests-using-openscap-and-guestmount/#content
24

Change the background image in a Windows XP VM

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

Checksum a file or device within a disk image

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

Cloning a virtual machine

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

Convert a CD-ROM / DVD / ISO to a tarball

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

Convert from one format/filesystem to another

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

Convert Windows DVD to bootable USB key

102       http://rwmj.wordpress.com/2013/05/09/tip-convert-a-windows-dvd-iso-to-a-bootable-usb-key-using-guestfish/#content
103

Convert Xen-style partitionless image to partitioned disk image

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

Create empty disk images

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

Delete a file (or other simple file operations)

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

Diff two guests; compare a snapshot to the current version

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

Disable a systemd service

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

Drive letters over FUSE

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

Dump raw filesystem content from inside a disk image or VM

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

Edit grub configuration in a VM

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

Export any directory from a VM

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

Export external kernel and initramfs (initrd)

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

Find out which user is using the most space

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

Get DHCP address from a VM

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

Get the operating system product name string

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

Get the default boot kernel for a Linux VM

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

Hanging guests

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

Hex-dumping sectors from the guest

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

Hex-editing sectors in the guest

419       Hex-edit the boot partition (Master Boot Record / first sector):
420
421        guestfish --rw -a disk.img run : hexedit /dev/sda 0x200
422

Install packages (RPMs, Debian packages) in a guest

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

Install packages from an alternate repository

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

Install SYSLINUX bootloader in a guest

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

List applications installed in a VM

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

List files and directories in a VM

533       Use virt-ls(1).
534

List services in a Windows VM

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

Make a disk image sparse

543       Use virt-sparsify(1).
544

Monitor disk usage over time

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

Reading the Windows Event Log from Windows Vista (or later)

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

Remove root password (Linux)

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

Remove Administrator password (Windows)

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

Sysprepping a virtual machine (Windows)

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

Unpack a live CD

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

Uploading and downloading files

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

Uploading raw filesystem content

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

Use libguestfs tools on VMware ESX guests

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

SEE ALSO

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

AUTHORS

631       Richard W.M. Jones ("rjones at redhat dot com")
632
634       Copyright (C) 2009-2020 Red Hat Inc.
635

LICENSE

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

BUGS

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.46.0                 2021-09-23                guestfs-recipes(1)
Impressum