.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "guestfs-recipes 1"
.TH guestfs-recipes 1 "2013-12-07" "libguestfs-1.18.1" "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, \fIguestfish\fR\|(1) and the virt tools.
.SH "Audit a virtual machine for setuid files"
.IX Header "Audit a virtual machine for setuid files"
The link below contains a small program which can be used to audit a
Linux virtual machine to see what setuid and setgid files it contains.
.PP
https://rwmj.wordpress.com/2010/12/15/tip\-audit\-virtual\-machine\-for\-setuid\-files/#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 \fIguestfish\fR\|(1) to change the
background image for a user of a Windows \s-1XP\s0 \s-1VM\s0.  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 "Cloning a virtual machine (Linux)"
.IX Header "Cloning a virtual machine (Linux)"
The guestfish technique described in the link below works well for
most Linux VMs.  Depending on the Linux distro you may need to change
the paths slightly.
.PP
https://rwmj.wordpress.com/2010/09/24/tip\-my\-procedure\-for\-cloning\-a\-fedora\-vm/#content
.PP
Avoid \fIvirt\-clone\fR\|(1).  Currently what to do about virt-clone is
under discussion.
.PP
https://www.redhat.com/archives/virt\-tools\-list/2011\-May/msg00019.html
.SH "Cloning a virtual machine (Windows)"
.IX Header "Cloning a virtual machine (Windows)"
It is possible to do a \*(L"sysprep\*(R" using libguestfs alone, although not
straightforward.  Currently there is code in the Aeolus Oz project
which does this (using libguestfs).  As part of our review of the
virt-clone tool, we may add sysprepping ability.
.PP
https://github.com/clalancette/oz
https://www.redhat.com/archives/virt\-tools\-list/2011\-May/msg00019.html
.SH "Convert a CD-ROM / DVD / ISO to a tarball"
.IX Header "Convert a CD-ROM / DVD / ISO to a tarball"
This converts input \f(CW\*(C`cd.iso\*(C'\fR to output \f(CW\*(C`cd.tar.gz\*(C'\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. \f(CW\*(C`/files\*(C'\fR, do:
.PP
.Vb 1
\& guestfish \-\-ro \-a cd.iso \-m /dev/sda tgz\-out /files cd.tar.gz
.Ve
.SH "Create empty disk images"
.IX Header "Create empty disk images"
You can use the \fIguestfish\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
.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 \fIguestfish\fR\|(1) \f(CW\*(C`download\*(C'\fR command to extract the raw
filesystem content from any filesystem in a disk image or a \s-1VM\s0 (even
one which is encrypted or buried inside an \s-1LV\s0):
.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 list the filesystems in a disk image, use \fIvirt\-filesystems\fR\|(1).
.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 \s-1VM\s0.
.IP "\(bu" 4
Change kernel command line options.
.PP
Use \fIvirt\-edit\fR\|(1) to edit the grub configuration:
.PP
.Vb 1
\& virt\-edit \-d BrokenGuest /boot/grub/grub.conf
.Ve
.PP
or for general tinkering inside an unbootable \s-1VM\s0 use \fIvirt\-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 \f(CW\*(C`/home\*(C'\fR from a \s-1VM\s0 into a local directory use
\&\fIvirt\-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 \s-1FAQ:\s0
http://libguestfs.org/FAQ.html#backup
.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 \s-1DHCP\s0 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 \f(CW\*(C`virt\-dhcp\-address.c\*(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 \f(CW\*(C`product\-name.sh\*(C'\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 \fIvirt\-inspector\fR\|(1) \s-1XML\s0 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 \s-1VM\s0.
.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 \s-1NTP\s0 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 "Install RPMs in a guest"
.IX Header "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 \*(L"firstboot\*(R"
script that installs them next time the guest is booted.  You could
use this technique to install vital security updates in an offline
guest.
.PP
https://rwmj.wordpress.com/2010/12/01/tip\-install\-rpms\-in\-a\-guest/#content
.SH "List applications installed in a VM"
.IX Header "List applications installed in a VM"
Save the following to a file \f(CW\*(C`list\-apps.sh\*(C'\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
\&\fIvirt\-inspector\fR\|(1).
.SH "List files and directories in a VM"
.IX Header "List files and directories in a VM"
This involves using the \fIguestfish\fR\|(1) \f(CW\*(C`find0\*(C'\fR command like this:
.PP
.Vb 1
\& guestfish \-\-ro \-d Guest \-i find0 / \- | tr \*(Aq\e0\*(Aq \*(Aq\en\*(Aq | sort
.Ve
.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 \s-1VM\s0, 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"
The link below contains some guides for making a disk image sparse (or
reintroducing sparseness).
.PP
https://rwmj.wordpress.com/2010/10/19/tip\-making\-a\-disk\-image\-sparse/#content
.SH "Monitor disk usage over time"
.IX Header "Monitor disk usage over time"
You can use \fIvirt\-df\fR\|(1) to monitor disk usage of your guests over
time.  The link below contains a guide.
.PP
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)"
\&\fIguestfish\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 \fIvirt\-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 domname /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 \s-1VM\s0, 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 "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 \fIguestfish\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 "Use libguestfs tools on VMware ESX guests"
.IX Header "Use libguestfs tools on VMware ESX guests"
The link below explains how to use libguestfs, \fIguestfish\fR\|(1) and the
virt tools on any VMware \s-1ESX\s0 guests, by first sharing the VMware \s-1VMFS\s0
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"
\&\fIguestfs\fR\|(3),
\&\fIguestfish\fR\|(1),
\&\fIguestfs\-examples\fR\|(3),
\&\fIguestfs\-erlang\fR\|(3),
\&\fIguestfs\-java\fR\|(3),
\&\fIguestfs\-ocaml\fR\|(3),
\&\fIguestfs\-perl\fR\|(3),
\&\fIguestfs\-python\fR\|(3),
\&\fIguestfs\-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\-2012 Red Hat Inc. <http://libguestfs.org/>
.PP
The examples in this manual page may be freely copied, modified and
distributed without any restrictions.
.PP
This library is free software; you can redistribute it and/or
modify it under the terms of the \s-1GNU\s0 Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
.PP
This library is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the \s-1GNU\s0
Lesser General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA\s0 02110\-1301 \s-1USA\s0