.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.52.0 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "guestfs-recipes 1"
.TH guestfs-recipes 1 2024-01-05 libguestfs-1.52.0 "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
guestfs\-recipes \- libguestfs, guestfish and virt tools recipes
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This page contains recipes for and links to things you can do using
libguestfs, \fBguestfish\fR\|(1) and the virt tools.
.SH "Access a remote disk image using guestfish"
.IX Header "Access a remote disk image using guestfish"
If the disk image is on a remote server which is accessible using SSH,
HTTP, FTP, NBD, iSCSI, or similar, then you can open it directly.  See
"ADDING REMOTE STORAGE" in \fBguestfish\fR\|(1) for several examples.  This
requires libguestfs ≥ 1.22 and qemu ≥ 1.5.
.SH "Audit a virtual machine for setuid files"
.IX Header "Audit a virtual machine for setuid files"
See: "EXAMPLES" in \fBvirt\-ls\fR\|(1).
.SH "Audit a virtual machine for vulnerabilities and security problems"
.IX Header "Audit a virtual machine for vulnerabilities and security problems"
See:
https://rwmj.wordpress.com/2013/05/16/scanning\-offline\-guests\-using\-openscap\-and\-guestmount/#content
.SH "Change the background image in a Windows XP VM"
.IX Header "Change the background image in a Windows XP VM"
The links below explain how to use \fBguestfish\fR\|(1) to change the
background image for a user of a Windows XP VM.  Unfortunately the
technique appears to be substantially different for each version of
Windows.
.PP
https://lists.fedoraproject.org/pipermail/virt/2011\-May/002655.html
https://lists.fedoraproject.org/pipermail/virt/2011\-May/002658.html
.SH "Checksum a file or device within a disk image"
.IX Header "Checksum a file or device within a disk image"
To checksum a whole device, or a partition, LV etc within a disk image:
.PP
.Vb 1
\& guestfish \-\-ro \-a disk.img run : checksum\-device md5 /dev/sda1
.Ve
.PP
Replace \f(CW\*(C`md5\*(C'\fR with the type of checksum you want.  See
"guestfs_checksum_device" in \fBguestfs\fR\|(3) for a list of supported types.
.PP
\&\fI/dev/sda1\fR means "the first partition".  You could use \fI/dev/sda\fR
to checksum the whole disk image, or the name of a logical volume or
RAID device.
.PP
To checksum a single file:
.PP
.Vb 1
\& guestfish \-\-ro \-a disk.img \-i checksum sha256 /etc/passwd
.Ve
.PP
or for a Windows guest:
.PP
.Vb 2
\& guestfish \-\-ro \-a disk.img \-i \e
\&   checksum sha256 \*(Aqwin:\ewindows\esystem32\econfig\eSOFTWARE\*(Aq
.Ve
.SH "Cloning a virtual machine"
.IX Header "Cloning a virtual machine"
Use a combination of tools like \fBcp\fR\|(1), \fBdd\fR\|(1), and
virt tools like \fBvirt\-sysprep\fR\|(1), \fBvirt\-sparsify\fR\|(1)
and \fBvirt\-resize\fR\|(1).
.PP
For more details, see: "COPYING AND CLONING" in \fBvirt\-sysprep\fR\|(1).
.SH "Convert a CD-ROM / DVD / ISO to a tarball"
.IX Header "Convert a CD-ROM / DVD / ISO to a tarball"
This converts input \fIcd.iso\fR to output \fIcd.tar.gz\fR:
.PP
.Vb 1
\& guestfish \-\-ro \-a cd.iso \-m /dev/sda tgz\-out / cd.tar.gz
.Ve
.PP
To export just a subdirectory, eg. \fI/files\fR, do:
.PP
.Vb 1
\& guestfish \-\-ro \-a cd.iso \-m /dev/sda tgz\-out /files cd.tar.gz
.Ve
.SH "Convert from one format/filesystem to another"
.IX Header "Convert from one format/filesystem to another"
If you have a data disk in one format / filesystem / partition /
volume manager, you can convert it another using this technique.
.PP
In this example, we start with a data disk that has a single partition
containing a filesystem, and we want to create another disk that
contains the same files but on an ext3 filesystem embedded in a
logical volume on a sparse raw-format disk.
.PP
First create the formatted-but-empty target disk:
.PP
.Vb 2
\& truncate \-s 10G target.img
\& virt\-format \-a target.img \-\-partition=mbr \-\-lvm \-\-filesystem=ext3
.Ve
.PP
Now, pipe two guestfish instances together to transfer the old data to
the new disk:
.PP
.Vb 2
\& guestfish \-\-ro \-a source.img \-m /dev/sda1  \-\- tar\-out / \- | \e
\& guestfish \-\-rw \-a target.img \-m /dev/VG/LV \-\- tar\-in \- /
.Ve
.PP
To browse the final disk image, do:
.PP
.Vb 2
\& guestfish \-\-ro \-a target.img \-m /dev/VG/LV
\& ><fs> ll /
.Ve
.PP
This technique is quite powerful, allowing you for example to split up
source directories over the target filesystems.
.PP
Note this won’t work (at least, not directly) for bootable virtual
machine disks because it doesn't copy over the boot loader.
.SH "Convert Windows DVD to bootable USB key"
.IX Header "Convert Windows DVD to bootable USB key"
http://rwmj.wordpress.com/2013/05/09/tip\-convert\-a\-windows\-dvd\-iso\-to\-a\-bootable\-usb\-key\-using\-guestfish/#content
.SH "Convert Xen-style partitionless image to partitioned disk image"
.IX Header "Convert Xen-style partitionless image to partitioned disk image"
Xen disk images are often partitionless, meaning that the filesystem
starts directly at the beginning of the disk with no partition table.
You can in fact use these directly in KVM (provided the guest isn't
Windows), but some people like to convert them to regular partitioned
disk images, and this is required for Windows guests.  Here is how to
use guestfish to do this:
.PP
.Vb 12
\& guestfish
\& ><fs> add\-ro input.img
\& ><fs> sparse output.img 10G     # adjust the output size
\& ><fs> run
\& # Create a partition table on the output disk:
\& ><fs> part\-init /dev/sdb mbr
\& ><fs> part\-add /dev/sdb p 2048 \-2048
\& # Copy the data to the target partition:
\& ><fs> copy\-device\-to\-device /dev/sda /dev/sdb1 sparse:true
\& # Optionally resize the target filesystem.  Use ntfsresize
\& # for Windows guests:
\& ><fs> resize2fs /dev/sdb1
.Ve
.PP
Such a disk image won’t be directly bootable.  You may need to boot it
with an external kernel and initramfs (see below).  Or you can use the
guestfish commands \f(CW\*(C`syslinux\*(C'\fR or \f(CW\*(C`extlinux\*(C'\fR to install a SYSLINUX
bootloader.
.SH "Create empty disk images"
.IX Header "Create empty disk images"
The \fBvirt\-format\fR\|(1) tool can do this directly.
.PP
Use \fBvirt\-make\-fs\fR\|(1) to create a disk image with content.  This can
also create some standard disk images such as virtual floppy devices
(VFDs).
.PP
You can also use the \fBguestfish\fR\|(1) \fI\-N\fR option to create empty disk
images.  The useful guide below explains the options available.
.PP
https://rwmj.wordpress.com/2010/09/08/new\-guestfish\-n\-options\-in\-1\-5\-9/#content
.PP
\&\fBvirt\-builder\fR\|(1) can create minimal guests.
.SH "Delete a file (or other simple file operations)"
.IX Header "Delete a file (or other simple file operations)"
Use guestfish.  To delete a file:
.PP
.Vb 1
\& guestfish \-a disk.img \-i rm /file/to/delete
.Ve
.PP
To touch a file (bring it up to date or create it):
.PP
.Vb 1
\& guestfish \-a disk.img \-i touch /file/to/touch
.Ve
.PP
To stat a file.  Since this is a read-only operation, we can make it
safer by adding the \fI\-\-ro\fR flag.
.PP
.Vb 1
\& guestfish \-\-ro \-a disk.img \-i stat /file/to/stat
.Ve
.PP
There are dozens of these commands.  See \fBguestfish\fR\|(1) or the output
of \f(CW\*(C`guestfish \-h\*(C'\fR
.SH "Diff two guests; compare a snapshot to the current version"
.IX Header "Diff two guests; compare a snapshot to the current version"
Since libguestfs ≥ 1.26, use \fBvirt\-diff\fR\|(1) to look for
differences between two guests (for example if they were originally
cloned from the same source), or between two snapshots from the same
guest.  In earlier versions of libguestfs, use \fBvirt\-ls\fR\|(1).
.SH "Disable a systemd service"
.IX Header "Disable a systemd service"
The following is the equivalent of \f(CW\*(C`systemctl mask ...\*(C'\fR. To disable
the \f(CW\*(C`cloud\-init\*(C'\fR service so it doesn't start at next boot:
.PP
.Vb 2
\& guestfish \-a disk.img \-i \e
\&     ln\-sf /dev/null /etc/systemd/system/cloud\-init.service
.Ve
.PP
To disable tmp-on-tmpfs:
.PP
.Vb 2
\& guestfish \-a disk.img \-i \e
\&     ln\-sf /dev/null /etc/systemd/system/tmp.mount
.Ve
.PP
One problem with the commands above is there is no feedback if you get
the name of the service you are trying to mask wrong.  But you can use
\&\fBvirt\-ls\fR\|(1) to list the available systemd services like this:
.PP
.Vb 1
\& virt\-ls \-a /tmp/fedora\-19.img \-R /lib/systemd/system
.Ve
.SH "Drive letters over FUSE"
.IX Header "Drive letters over FUSE"
You have a Windows guest, and you want to expose the drive letters as
FUSE mountpoints (\fI/C/...\fR, \fI/D/...\fR etc).  Instead of
\&\fBguestmount\fR\|(1), use this Perl script:
.PP
.Vb 10
\& #!/usr/bin/perl \-w
\& use strict;
\& use Sys::Guestfs;
\& $| = 1;
\& die "usage: $0 mountpoint disk.img" if @ARGV < 2;
\& my $mp = shift @ARGV;
\& my $g = new Sys::Guestfs;
\& $g\->add_drive_opts ($_) foreach @ARGV;
\& $g\->launch;
\& my @roots = $g\->inspect_os;
\& die "$0: no operating system found" if @roots != 1;
\& my $root = $roots[0];
\& die "$0: not Windows" if $g\->inspect_get_type ($root) ne "windows";
\& my %map = $g\->inspect_get_drive_mappings ($root);
\& foreach (keys %map) {
\&     $g\->mkmountpoint ("/$_");
\&     eval { $g\->mount ($map{$_}, "/$_") };
\&     warn "$@ (ignored)\en" if $@;
\& }
\& $g\->mount_local ($mp);
\& print "filesystem ready on $mp\en";
\& $g\->mount_local_run;
\& $g\->shutdown;
.Ve
.PP
You can use the script like this:
.PP
.Vb 3
\& $ mkdir /tmp/mnt
\& $ ./drive\-letters.pl /tmp/mnt windows7.img
\& filesystem ready on /tmp/mnt
.Ve
.PP
In another window:
.PP
.Vb 12
\& $ cd /tmp/mnt
\& $ ls
\& C  D
\& $ cd C
\& $ ls
\& Documents and Settings
\& PerfLogs
\& ProgramData
\& Program Files
\& [etc]
\& $ cd ../..
\& $ guestunmount /tmp/mnt
.Ve
.SH "Dump raw filesystem content from inside a disk image or VM"
.IX Header "Dump raw filesystem content from inside a disk image or VM"
You can use the \fBguestfish\fR\|(1) \f(CW\*(C`download\*(C'\fR command to extract the raw
filesystem content from any filesystem in a disk image or a VM (even
one which is encrypted or buried inside an LV or RAID device):
.PP
.Vb 1
\& guestfish \-\-ro \-a disk.img run : download /dev/sda1 sda1.img
\&
\& guestfish \-\-ro \-d Guest run : download /dev/vg_guest/lv_root lv.img
.Ve
.PP
To download to stdout, replace the filename with a \f(CW\*(C`\-\*(C'\fR character:
.PP
.Vb 1
\& guestfish \-\-ro \-a disk.img run : download /dev/sda1 \- | gzip > sda1.gz
.Ve
.PP
To list the filesystems in a disk image, use \fBvirt\-filesystems\fR\|(1).
.PP
See also "Uploading raw filesystem content".
.SH "Edit grub configuration in a VM"
.IX Header "Edit grub configuration in a VM"
You can use this to:
.IP \(bu 4
Fix a virtual machine that does not boot.
.IP \(bu 4
Change which kernel is used to boot the VM.
.IP \(bu 4
Change kernel command line options.
.PP
Use \fBvirt\-edit\fR\|(1) to edit the grub configuration:
.PP
.Vb 1
\& virt\-edit \-d BrokenGuest /boot/grub2/grub.cfg
.Ve
.PP
or for general tinkering inside an unbootable VM use \fBvirt\-rescue\fR\|(1)
like this:
.PP
.Vb 1
\& virt\-rescue \-d BrokenGuest
.Ve
.SH "Export any directory from a VM"
.IX Header "Export any directory from a VM"
To export \fI/home\fR from a VM into a local directory use
\&\fBvirt\-copy\-out\fR\|(1):
.PP
.Vb 1
\& virt\-copy\-out \-d Guest /home .
.Ve
.PP
Notes:
.IP \(bu 4
The final dot of the command is not a printing error.  It means we
want to copy out to the current directory.
.IP \(bu 4
This creates a directory called \f(CW\*(C`home\*(C'\fR under the current directory.
.PP
If the guest is a Windows guest then you can use drive letters and
backslashes, but you must prefix the path with \f(CW\*(C`win:\*(C'\fR and quote it to
protect it from the shell, like this:
.PP
.Vb 1
\& virt\-copy\-out \-d WinGuest \*(Aqwin:c:\ewindows\esystem32\econfig\*(Aq .
.Ve
.PP
To get the output as a compressed tarball, do:
.PP
.Vb 1
\& virt\-tar\-out \-d Guest /home \- | gzip \-\-best > home.tar.gz
.Ve
.PP
Although it sounds tempting, this is usually not a reliable way to get
a backup from a running guest.  See the entry in the FAQ:
http://libguestfs.org/FAQ.html#backup
.SH "Export external kernel and initramfs (initrd)"
.IX Header "Export external kernel and initramfs (initrd)"
If a Linux guest doesn't have a boot loader or it is broken, then you
can usually boot it using an external kernel and initramfs.  In this
configuration, the hypervisor acts like a bootloader, loading the
kernel from the host disk into guest memory and jumping straight into
the kernel.
.PP
However you may wonder how to get the right kernel corresponding to
the disk image you have.  Since libguestfs ≥ 1.24
\&\fBvirt\-builder\fR\|(1) can get the latest kernel and corresponding
initramfs for you:
.PP
.Vb 3
\& mkdir outputdir
\& virt\-builder \-\-get\-kernel disk.img \-o outputdir
\& ls \-lh outputdir
.Ve
.SH "Find out which user is using the most space"
.IX Header "Find out which user is using the most space"
This simple script examines a Linux guest to find out which user is
using the most space in their home directory:
.PP
.Vb 1
\& #!/bin/sh \-
\& 
\& set \-e
\& 
\& vm="$1"
\& dir=/home
\& 
\& eval $(guestfish \-\-ro \-d "$vm" \-i \-\-listen)
\& 
\& for d in $(guestfish \-\-remote ls "$dir"); do
\&     echo \-n "$dir/$d"
\&     echo \-ne \*(Aq\et\*(Aq
\&     guestfish \-\-remote du "$dir/$d";
\& done | sort \-nr \-k 2
\& 
\& guestfish \-\-remote exit
.Ve
.SH "Get DHCP address from a VM"
.IX Header "Get DHCP address from a VM"
The link below explains the many different possible techniques for
getting the last assigned DHCP address of a virtual machine.
.PP
https://rwmj.wordpress.com/2011/03/31/tip\-code\-for\-getting\-dhcp\-address\-from\-a\-virtual\-machine\-disk\-image/#content
.PP
In the libguestfs source examples directory you will find the latest
version of the \fIvirt\-dhcp\-address.c\fR program.
.SH "Get the operating system product name string"
.IX Header "Get the operating system product name string"
Save the following script into a file called \fIproduct\-name.sh\fR:
.PP
.Vb 6
\& #!/bin/sh \-
\& set \-e
\& eval "$(guestfish \-\-ro \-d "$1" \-\-i \-\-listen)"
\& root="$(guestfish \-\-remote inspect\-get\-roots)"
\& guestfish \-\-remote inspect\-get\-product\-name "$root"
\& guestfish \-\-remote exit
.Ve
.PP
Make the script executable and run it on a named guest:
.PP
.Vb 2
\& # product\-name.sh RHEL60x64
\& Red Hat Enterprise Linux Server release 6.0 (Santiago)
.Ve
.PP
You can also use an XPath query on the \fBvirt\-inspector\fR\|(1) XML using
the \f(CW\*(C`xpath\*(C'\fR command line tool or from your favourite programming
language:
.PP
.Vb 5
\& # virt\-inspector RHEL60x64 > xml
\& # xpath \*(Aq//product_name\*(Aq < xml
\& Found 1 nodes:
\& \-\- NODE \-\-
\& <product_name>Red Hat Enterprise Linux Server release 6.0 (Santiago)</product_name>
.Ve
.SH "Get the default boot kernel for a Linux VM"
.IX Header "Get the default boot kernel for a Linux VM"
The link below contains a program to print the default boot kernel for
a Linux VM.
.PP
https://rwmj.wordpress.com/2010/10/30/tip\-use\-augeas\-to\-get\-the\-default\-boot\-kernel\-for\-a\-vm/#content
.PP
It uses Augeas, and the technique is generally applicable for many
different tasks, such as:
.IP \(bu 4
listing the user accounts in the guest
.IP \(bu 4
what repositories is it configured to use
.IP \(bu 4
what NTP servers does it connect to
.IP \(bu 4
what were the boot messages last time it booted
.IP \(bu 4
listing who was logged in recently
.PP
http://augeas.net/
.SH "Hanging guests"
.IX Header "Hanging guests"
There are various ways to use libguestfs to find out why a guest
is hanging or unresponsive:
.IP 1. 4
Read the log files using virt-cat:
.Sp
.Vb 1
\& virt\-cat Guest /var/log/messages | less
.Ve
.IP 2. 4
Read the Windows Event Log (Windows Vista or later only):
.Sp
https://rwmj.wordpress.com/2011/04/17/decoding\-the\-windows\-event\-log\-using\-guestfish/#content
.IP 3. 4
Find out which files were last updated in a guest:
.Sp
https://rwmj.wordpress.com/2012/02/27/using\-libguestfs\-to\-find\-out\-why\-a\-windows\-guest\-was\-hanging/#content
.Sp
This might give you a clue as to what program is running.
.SH "Hex-dumping sectors from the guest"
.IX Header "Hex-dumping sectors from the guest"
Hex-dump the boot partition (Master Boot Record / first sector):
.PP
.Vb 2
\& guestfish \-\-ro \-a disk.img run : pread\-device /dev/sda 0x200 0 |
\&   hexdump \-C
.Ve
.PP
(\f(CW0x200\fR = 512 bytes which is the size of traditional PC sectors)
.PP
To hexdump the N'th partition, substitute a number for \f(CW\*(C`N\*(C'\fR in the
following command:
.PP
.Vb 3
\& guestfish \-\-ro \-a disk.img \e
\&     run : pread\-device /dev/sda 0x200 $((N*0x200)) |
\&   hexdump \-C
.Ve
.SH "Hex-editing sectors in the guest"
.IX Header "Hex-editing sectors in the guest"
Hex-edit the boot partition (Master Boot Record / first sector):
.PP
.Vb 1
\& guestfish \-\-rw \-a disk.img run : hexedit /dev/sda 0x200
.Ve
.SH "Install packages (RPMs, Debian packages) in a guest"
.IX Header "Install packages (RPMs, Debian packages) in a guest"
Since libguestfs 1.26, \fBvirt\-builder\fR\|(1), \fBvirt\-customize\fR\|(1) and
\&\fBvirt\-sysprep\fR\|(1) have an \fI\-\-install\fR option for installing packages
in Linux guests.  (Use virt-customize if you have an existing guest,
or virt-builder if you want to create a guest from scratch).
.PP
For example:
.PP
.Vb 1
\& virt\-builder fedora\-20 \-\-install emacs
.Ve
.SH "Install packages from an alternate repository"
.IX Header "Install packages from an alternate repository"
Since libguestfs 1.26, you can use \fBvirt\-builder\fR\|(1),
\&\fBvirt\-customize\fR\|(1) or \fBvirt\-sysprep\fR\|(1) \fI\-\-edit\fR option to edit
repository metadata before installing packages
.PP
For example this would install packages from the updates-testing
repository in Fedora:
.PP
.Vb 4
\& virt\-builder fedora\-20 \e
\&   \-\-edit \*(Aq/etc/yum.repos.d/fedora\-updates\-testing.repo:
\&             s/enabled=0/enabled=1/\*(Aq \e
\&   \-\-install emacs
.Ve
.SH "Install SYSLINUX bootloader in a guest"
.IX Header "Install SYSLINUX bootloader in a guest"
SYSLINUX is a small, easy to configure bootloader for Linux and
Windows guests.  If your guest is not bootable, you can install the
SYSLINUX bootloader using either the guestfish commands \f(CW\*(C`syslinux\*(C'\fR
(for FAT-based guests) or \f(CW\*(C`extlinux\*(C'\fR (for ext2/3/4 and btrfs-based
guests).
.PP
This guide assumes a Linux guest where \fI/dev/sda1\fR is \fI/boot\fR,
\&\fI/boot/vmlinuz\fR is the guest kernel, and \fI/dev/sda3\fR is the root
partition.  For a Windows guest you would need a FAT-formatted boot
partition and you would need to use the \f(CW\*(C`syslinux\*(C'\fR command instead.
.PP
Create a \fIsyslinux.cfg\fR configuration file.  You should check the
SYSLINUX documentation at http://www.syslinux.org but it may look
something like this:
.PP
.Vb 6
\& DEFAULT linux
\& LABEL linux
\&   SAY Booting the kernel
\&   KERNEL vmlinuz
\&   INITRD initrd
\&   APPEND ro root=/dev/sda3
.Ve
.PP
Locate the syslinux master boot record (a file called something like
\&\fI/usr/share/syslinux/mbr.bin\fR).
.PP
.Vb 10
\& guestfish \-a disk.img \-i
\& # Upload the master boot record and configuration file:
\& ><fs> upload ..../mbr.bin /boot/mbr.bin
\& ><fs> upload ..../syslinux.cfg /boot/syslinux.cfg
\& # Put the MBR into the boot sector:
\& ><fs> copy\-file\-to\-device /boot/mbr.bin /dev/sda size:440
\& # Install syslinux on the first partition:
\& ><fs> extlinux /boot
\& # Set the first partition as bootable:
\& ><fs> part\-set\-bootable /dev/sda 1 true
.Ve
.PP
See also:
http://rwmj.wordpress.com/2013/04/04/new\-in\-libguestfs\-use\-syslinux\-or\-extlinux\-to\-make\-bootable\-guests/#content
.SH "List applications installed in a VM"
.IX Header "List applications installed in a VM"
Save the following to a file \fIlist\-apps.sh\fR:
.PP
.Vb 6
\& #!/bin/sh \-
\& set \-e
\& eval "$(guestfish \-\-ro \-d "$1" \-\-i \-\-listen)"
\& root="$(guestfish \-\-remote inspect\-get\-roots)"
\& guestfish \-\-remote inspect\-list\-applications "$root"
\& guestfish \-\-remote exit
.Ve
.PP
Make the file executable and then you can run it on any named
virtual machine:
.PP
.Vb 10
\& # list\-apps.sh WinGuest
\& [0] = {
\&   app_name: Mozilla Firefox (3.6.12)
\&   app_display_name: Mozilla Firefox (3.6.12)
\&   app_epoch: 0
\&   app_version: 3.6.12 (en\-GB)
\&   app_release:
\&   app_install_path: C:\eProgram Files\eMozilla Firefox
\&   app_trans_path:
\&   app_publisher: Mozilla
\&   app_url: http://www.mozilla.com/en\-GB/
\&   app_source_package:
\&   app_summary:
\&   app_description: Mozilla Firefox
\& }
\& [1] = {
\&   app_name: VLC media player
\&   app_display_name: VLC media player 1.1.5
\&   app_epoch: 0
\&   app_version: 1.1.5
\&   app_release:
\&   app_install_path: C:\eProgram Files\eVideoLAN\eVLC
\&   app_trans_path:
\&   app_publisher: VideoLAN
\&   app_url: http://www.videolan.org/
\&   app_source_package:
\&   app_summary:
\&   app_description:
\& }
.Ve
.PP
If you want to run the script on disk images (instead of libvirt
virtual machines), change \f(CW\*(C`\-d "$1"\*(C'\fR to \f(CW\*(C`\-a "$1"\*(C'\fR.  See also
\&\fBvirt\-inspector\fR\|(1).
.SH "List files and directories in a VM"
.IX Header "List files and directories in a VM"
Use \fBvirt\-ls\fR\|(1).
.SH "List services in a Windows VM"
.IX Header "List services in a Windows VM"
The link below contains a script that can be used to list out the
services from a Windows VM, and whether those services run at boot
time or are loaded on demand.
.PP
https://rwmj.wordpress.com/2010/12/10/tip\-list\-services\-in\-a\-windows\-guest/#content
.SH "Make a disk image sparse"
.IX Header "Make a disk image sparse"
Use \fBvirt\-sparsify\fR\|(1).
.SH "Monitor disk usage over time"
.IX Header "Monitor disk usage over time"
You can use \fBvirt\-df\fR\|(1) to monitor disk usage of your guests over
time.  The link below contains a guide.
.PP
http://web.archive.org/web/20130214073726/http://virt\-tools.org/learning/advanced\-virt\-df/
.SH "Reading the Windows Event Log from Windows Vista (or later)"
.IX Header "Reading the Windows Event Log from Windows Vista (or later)"
\&\fBguestfish\fR\|(1) plus the tools described in the link below can be used
to read out the Windows Event Log from any virtual machine running
Windows Vista or a later version.
.PP
https://rwmj.wordpress.com/2011/04/17/decoding\-the\-windows\-event\-log\-using\-guestfish/#content
.SH "Remove root password (Linux)"
.IX Header "Remove root password (Linux)"
Using the \fBvirt\-edit\fR\|(1) \fI\-e\fR option you can do simple replacements
on files.  One use is to remove the root password from a Linux guest:
.PP
.Vb 1
\& virt\-edit \-d domname /etc/passwd \-e \*(Aqs/^root:.*?:/root::/\*(Aq
\&
\& virt\-edit \-a disk.img /etc/passwd \-e \*(Aqs/^root:.*?:/root::/\*(Aq
.Ve
.SH "Remove Administrator password (Windows)"
.IX Header "Remove Administrator password (Windows)"
The link below contains one technique for removing the Administrator
password from a Windows VM, or to be more precise, it gives you a
command prompt the next time you log in which you can use to bypass
any security:
.PP
https://mdbooth.wordpress.com/2010/10/18/resetting\-a\-windows\-guests\-administrator\-password\-with\-guestfish/
.SH "Sysprepping a virtual machine (Windows)"
.IX Header "Sysprepping a virtual machine (Windows)"
It is possible to do a "sysprep" using libguestfs alone, although not
straightforward.  Currently there is code in the Aeolus Oz project
which does this (using libguestfs).  It is likely we will add this to
\&\fBvirt\-sysprep\fR\|(1) in future.
.PP
https://github.com/clalancette/oz
https://www.redhat.com/archives/virt\-tools\-list/2011\-May/msg00019.html
.SH "Unpack a live CD"
.IX Header "Unpack a live CD"
Linux live CDs often contain multiple layers of disk images wrapped
like a Russian doll.  You can use \fBguestfish\fR\|(1) to look inside these
multiple layers, as outlined in the guide below.
.PP
https://rwmj.wordpress.com/2009/07/15/unpack\-the\-russian\-doll\-of\-a\-f11\-live\-cd/#content
.SH "Uploading and downloading files"
.IX Header "Uploading and downloading files"
The link below contains general tips on uploading (copying in)
and downloading (copying out) files from VMs.
.PP
https://rwmj.wordpress.com/2010/12/02/tip\-uploading\-and\-downloading/#content
.SH "Uploading raw filesystem content"
.IX Header "Uploading raw filesystem content"
You can use \fBguestfish\fR\|(1) to upload whole filesystems into a VM,
even into a filesystem which is encrypted or buried inside an LV or
RAID device:
.PP
.Vb 1
\& guestfish \-\-rw \-a disk.img run : upload sda1.img /dev/sda1
\&
\& guestfish \-\-rw \-d Guest run : upload lv.img /dev/vg_guest/lv_root
.Ve
.PP
One common problem is that the filesystem isn't the right size for the
target.  If it is too large, there’s not much you can do with
libguestfs \- you have to prepare the filesystem differently.  But if
the filesystem needs to expand into the target, you can use guestfish
to resize it to the right size:
.PP
.Vb 3
\& guestfish \-\-rw \-d Guest run : \e
\&   upload lv.img /dev/vg_guest/lv_root : \e
\&   resize2fs /dev/vg_guest/lv_root
.Ve
.PP
(or use \f(CW\*(C`ntfsresize\*(C'\fR if the filesystem is NTFS).
.SH "Use libguestfs tools on VMware ESX guests"
.IX Header "Use libguestfs tools on VMware ESX guests"
The link below explains how to use libguestfs, \fBguestfish\fR\|(1) and the
virt tools on any VMware ESX guests, by first sharing the VMware VMFS
over sshfs.
.PP
https://rwmj.wordpress.com/2011/05/10/tip\-use\-libguestfs\-on\-vmware\-esx\-guests/#content
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBguestfs\fR\|(3),
\&\fBguestfish\fR\|(1),
\&\fBguestfs\-examples\fR\|(3),
\&\fBguestfs\-erlang\fR\|(3),
\&\fBguestfs\-gobject\fR\|(3),
\&\fBguestfs\-golang\fR\|(3),
\&\fBguestfs\-java\fR\|(3),
\&\fBguestfs\-lua\fR\|(3),
\&\fBguestfs\-ocaml\fR\|(3),
\&\fBguestfs\-perl\fR\|(3),
\&\fBguestfs\-python\fR\|(3),
\&\fBguestfs\-ruby\fR\|(3),
http://libguestfs.org/.
.SH AUTHORS
.IX Header "AUTHORS"
Richard W.M. Jones (\f(CW\*(C`rjones at redhat dot com\*(C'\fR)
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2009\-2023 Red Hat Inc.
.SH LICENSE
.IX Header "LICENSE"
This manual page contains examples which we hope you will use in
your programs.  The examples may be freely copied, modified and
distributed for any purpose without any restrictions.
.SH BUGS
.IX Header "BUGS"
To get a list of bugs against libguestfs, use this link:
https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
.PP
To report a new bug against libguestfs, use this link:
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
.PP
When reporting a bug, please supply:
.IP \(bu 4
The version of libguestfs.
.IP \(bu 4
Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
.IP \(bu 4
Describe the bug accurately and give a way to reproduce it.
.IP \(bu 4
Run \fBlibguestfs\-test\-tool\fR\|(1) and paste the \fBcomplete, unedited\fR
output into the bug report.