path: root/examples/guestfs-recipes.pod

=encoding utf8

=begin comment

We break with tradition here and don't use ALL CAPS for the section
headings, as this makes them much easier to read.

=end comment

=head1 NAME

guestfs-recipes - libguestfs, guestfish and virt tools recipes

=head1 DESCRIPTION

This page contains recipes for and links to things you can do using
libguestfs, L<guestfish(1)> and the virt tools.

=head1 Audit a virtual machine for setuid files

See: L<virt-ls(1)/EXAMPLES>.

=head1 Change the background image in a Windows XP VM

The links below explain how to use L<guestfish(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.

L<https://lists.fedoraproject.org/pipermail/virt/2011-May/002655.html>
L<https://lists.fedoraproject.org/pipermail/virt/2011-May/002658.html>

=head1 Checksum a file or device within a disk image

To checksum a whole device, or a partition, LV etc within a disk image:

 guestfish --ro -a disk.img run : checksum-device md5 /dev/sda1

Replace C<md5> with the type of checksum you want.  See
L<guestfs(3)/guestfs_checksum_device> for a list of supported types.

C</dev/sda1> means "the first partition".  You could use C</dev/sda>
to checksum the whole disk image, or the name of a logical volume or
RAID device.

To checksum a single file:

 guestfish --ro -a disk.img -i checksum sha256 /etc/passwd

or for a Windows guest:

 guestfish --ro -a disk.img -i \
   checksum sha256 'win:\windows\system32\config\SOFTWARE'

=head1 Cloning a virtual machine

Use a combination of tools like L<cp(1)>, L<dd(1)>, and
virt tools like L<virt-sysprep(1)>, L<virt-sparsify(1)>
and L<virt-resize(1)>.

For more details, see: L<virt-sysprep(1)/COPYING AND CLONING>.

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

This converts input C<cd.iso> to output C<cd.tar.gz>:

 guestfish --ro -a cd.iso -m /dev/sda tgz-out / cd.tar.gz

To export just a subdirectory, eg. C</files>, do:

 guestfish --ro -a cd.iso -m /dev/sda tgz-out /files cd.tar.gz

=head1 Create empty disk images

The L<virt-format(1)> tool can do this directly.

Use L<virt-make-fs(1)> to create a disk image with content.  This can
also create some standard disk images such as virtual floppy devices
(VFDs).

You can also use the L<guestfish(1)> I<-N> option to create empty disk
images.  The useful guide below explains the options available.

L<https://rwmj.wordpress.com/2010/09/08/new-guestfish-n-options-in-1-5-9/#content>

=head1 Delete a file (or other simple file operations)

Use guestfish.  To delete a file:

 guestfish -a disk.img -i rm /file/to/delete

To touch a file (bring it up to date or create it):

 guestfish -a disk.img -i touch /file/to/touch

To stat a file.  Since this is a read-only operation, we can make it
safer by adding the I<--ro> flag.

 guestfish --ro -a disk.img -i stat /file/to/stat

There are dozens of these commands.  See L<guestfish(1)> or the output
of C<guestfish -h>

=head1 Diff two guests; compare a snapshot to the current version

L<virt-ls(1)> provides a simple way to find the differences between
two guests (for example if they were originally cloned from the same
source), or between two snapshots from the same guest.  See
L<virt-ls(1)/DIFFERENCES IN SNAPSHOTS AND BACKING FILES>.

There are also experimental patches on the mailing list for a
"virt-diff" tool.

=head1 Dump raw filesystem content from inside a disk image or VM

You can use the L<guestfish(1)> C<download> 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):

 guestfish --ro -a disk.img run : download /dev/sda1 sda1.img

 guestfish --ro -d Guest run : download /dev/vg_guest/lv_root lv.img

To download to stdout, replace the filename with a C<-> character:

 guestfish --ro -a disk.img run : download /dev/sda1 - | gzip > sda1.gz

To list the filesystems in a disk image, use L<virt-filesystems(1)>.

See also L</Uploading raw filesystem content>.

=head1 Edit grub configuration in a VM

You can use this to:

=over 4

=item *

Fix a virtual machine that does not boot.

=item *

Change which kernel is used to boot the VM.

=item *

Change kernel command line options.

=back

Use L<virt-edit(1)> to edit the grub configuration:

 virt-edit -d BrokenGuest /boot/grub2/grub.cfg

or for general tinkering inside an unbootable VM use L<virt-rescue(1)>
like this:

 virt-rescue -d BrokenGuest

=head1 Export any directory from a VM

To export C</home> from a VM into a local directory use
L<virt-copy-out(1)>:

 virt-copy-out -d Guest /home .

Notes:

=over 4

=item *

The final dot of the command is not a printing error.  It means we
want to copy out to the current directory.

=item *

This creates a directory called C<home> under the current directory.

=back

If the guest is a Windows guest then you can use drive letters and
backslashes, but you must prefix the path with C<win:> and quote it to
protect it from the shell, like this:

 virt-copy-out -d WinGuest 'win:c:\windows\system32\config' .

To get the output as a compressed tarball, do:

 virt-tar-out -d Guest /home - | gzip --best > home.tar.gz

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:
L<http://libguestfs.org/FAQ.html#backup>

=head1 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:

 #!/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 '\t'
     guestfish --remote du "$dir/$d";
 done | sort -nr -k 2
 
 guestfish --remote exit

=head1 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.

L<https://rwmj.wordpress.com/2011/03/31/tip-code-for-getting-dhcp-address-from-a-virtual-machine-disk-image/#content>

In the libguestfs source examples directory you will find the latest
version of the C<virt-dhcp-address.c> program.

=head1 Get the operating system product name string

Save the following script into a file called C<product-name.sh>:

 #!/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

Make the script executable and run it on a named guest:

 # product-name.sh RHEL60x64
 Red Hat Enterprise Linux Server release 6.0 (Santiago)

You can also use an XPath query on the L<virt-inspector(1)> XML using
the C<xpath> command line tool or from your favourite programming
language:

 # virt-inspector RHEL60x64 > xml
 # xpath '//product_name' < xml
 Found 1 nodes:
 -- NODE --
 <product_name>Red Hat Enterprise Linux Server release 6.0 (Santiago)</product_name>

=head1 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.

L<https://rwmj.wordpress.com/2010/10/30/tip-use-augeas-to-get-the-default-boot-kernel-for-a-vm/#content>

It uses Augeas, and the technique is generally applicable for many
different tasks, such as:

=over 4

=item *

listing the user accounts in the guest

=item *

what repositories is it configured to use

=item *

what NTP servers does it connect to

=item *

what were the boot messages last time it booted

=item *

listing who was logged in recently

=back

L<http://augeas.net/>

=head1 Hanging guests

There are various ways to use libguestfs to find out why a guest
is hanging or unresponsive:

=over 4

=item 1.

Read the log files using virt-cat:

 virt-cat Guest /var/log/messages | less

=item 2.

Read the Windows Event Log (Windows Vista or later only):

L<https://rwmj.wordpress.com/2011/04/17/decoding-the-windows-event-log-using-guestfish/#content>

=item 3.

Find out which files were last updated in a guest:

L<https://rwmj.wordpress.com/2012/02/27/using-libguestfs-to-find-out-why-a-windows-guest-was-hanging/#content>

This might give you a clue as to what program is running.

=back

=head1 Hex-dumping sectors from the guest

Hex-dump the boot partition:

 guestfish --ro -a disk.img run : pread-device /dev/sda 0x200 0 |
   hexdump -C

=head1 Hex-editing sectors in the guest

Hex-edit the first sector (boot partition):

 guestfish --rw -a disk.img run : hexedit /dev/sda 0x200

=head1 Install RPMs in a guest

The link below contains a method to install RPMs in a guest.  In fact
the RPMs are just uploaded to the guest along with a "firstboot"
script that installs them next time the guest is booted.  You could
use this technique to install vital security updates in an offline
guest.

L<https://rwmj.wordpress.com/2010/12/01/tip-install-rpms-in-a-guest/#content>

Since libguestfs 1.20, L<virt-sysprep(1)> has an option for installing
firstboot scripts in Linux guests.

=head1 List applications installed in a VM

Save the following to a file C<list-apps.sh>:

 #!/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

Make the file executable and then you can run it on any named
virtual machine:

 # 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:\Program Files\Mozilla 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:\Program Files\VideoLAN\VLC
   app_trans_path:
   app_publisher: VideoLAN
   app_url: http://www.videolan.org/
   app_source_package:
   app_summary:
   app_description:
 }

If you want to run the script on disk images (instead of libvirt
virtual machines), change C<-d "$1"> to C<-a "$1">.  See also
L<virt-inspector(1)>.

=head1 List files and directories in a VM

Use L<virt-ls(1)>.

=head1 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.

L<https://rwmj.wordpress.com/2010/12/10/tip-list-services-in-a-windows-guest/#content>

=head1 Make a disk image sparse

Use L<virt-sparsify(1)>.

=head1 Monitor disk usage over time

You can use L<virt-df(1)> to monitor disk usage of your guests over
time.  The link below contains a guide.

L<http://virt-tools.org/learning/advanced-virt-df/>

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

L<guestfish(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.

L<https://rwmj.wordpress.com/2011/04/17/decoding-the-windows-event-log-using-guestfish/#content>

=head1 Remove root password (Linux)

Using the L<virt-edit(1)> I<-e> option you can do simple replacements
on files.  One use is to remove the root password from a Linux guest:

 virt-edit domname /etc/passwd -e 's/^root:.*?:/root::/'

=head1 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:

L<https://mdbooth.wordpress.com/2010/10/18/resetting-a-windows-guests-administrator-password-with-guestfish/>

=head1 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
L<virt-sysprep(1)> in future.

L<https://github.com/clalancette/oz>
L<https://www.redhat.com/archives/virt-tools-list/2011-May/msg00019.html>

=head1 Unpack a live CD

Linux live CDs often contain multiple layers of disk images wrapped
like a Russian doll.  You can use L<guestfish(1)> to look inside these
multiple layers, as outlined in the guide below.

L<https://rwmj.wordpress.com/2009/07/15/unpack-the-russian-doll-of-a-f11-live-cd/#content>

=head1 Uploading and downloading files

The link below contains general tips on uploading (copying in)
and downloading (copying out) files from VMs.

L<https://rwmj.wordpress.com/2010/12/02/tip-uploading-and-downloading/#content>

=head1 Uploading raw filesystem content

You can use L<guestfish(1)> to upload whole filesystems into a VM,
even into a filesystem which is encrypted or buried inside an LV or
RAID device:

 guestfish --rw -a disk.img run : upload sda1.img /dev/sda1

 guestfish --rw -d Guest run : upload lv.img /dev/vg_guest/lv_root

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:

 guestfish --rw -d Guest run : \
   upload lv.img /dev/vg_guest/lv_root : \
   resize2fs /dev/vg_guest/lv_root

(or use C<ntfsresize> if the filesystem is NTFS).

=head1 Use libguestfs tools on VMware ESX guests

The link below explains how to use libguestfs, L<guestfish(1)> and the
virt tools on any VMware ESX guests, by first sharing the VMware VMFS
over sshfs.

L<https://rwmj.wordpress.com/2011/05/10/tip-use-libguestfs-on-vmware-esx-guests/#content>

=head1 SEE ALSO

L<guestfs(3)>,
L<guestfish(1)>,
L<guestfs-examples(3)>,
L<guestfs-erlang(3)>,
L<guestfs-java(3)>,
L<guestfs-lua(3)>,
L<guestfs-ocaml(3)>,
L<guestfs-perl(3)>,
L<guestfs-python(3)>,
L<guestfs-ruby(3)>,
L<http://libguestfs.org/>.

=head1 AUTHORS

Richard W.M. Jones (C<rjones at redhat dot com>)

=head1 COPYRIGHT

Copyright (C) 2009-2012 Red Hat Inc.