5 pod2man and pod2html have differing bugs which makes it hard to write
6 URLs here. The only way which works for both sorts of output is to
7 just write the URL directly. Do NOT use L<...> for URLs.
9 We break with tradition here and don't use ALL CAPS for the section
10 headings, as this makes them much easier to read.
16 guestfs-recipes - libguestfs, guestfish and virt tools recipes
20 This page contains recipes for and links to things you can do using
21 libguestfs, L<guestfish(1)> and the virt tools.
23 =head1 Audit a virtual machine for setuid files
25 The link below contains a small program which can be used to audit a
26 Linux virtual machine to see what setuid and setgid files it contains.
28 https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files/#content
30 =head1 Change the background image in a Windows XP VM
32 The links below explain how to use L<guestfish(1)> to change the
33 background image for a user of a Windows XP VM. Unfortunately the
34 technique appears to be substantially different for each version of
37 https://lists.fedoraproject.org/pipermail/virt/2011-May/002655.html
38 https://lists.fedoraproject.org/pipermail/virt/2011-May/002658.html
40 =head1 Cloning a virtual machine (Linux)
42 The guestfish technique described in the link below works well for
43 most Linux VMs. Depending on the Linux distro you may need to change
46 https://rwmj.wordpress.com/2010/09/24/tip-my-procedure-for-cloning-a-fedora-vm/#content
48 Avoid L<virt-clone(1)>. Currently what to do about virt-clone is
51 https://www.redhat.com/archives/virt-tools-list/2011-May/msg00019.html
53 =head1 Cloning a virtual machine (Windows)
55 It is possible to do a "sysprep" using libguestfs alone, although not
56 straightforward. Currently there is code in the Aeolus Oz project
57 which does this (using libguestfs). As part of our review of the
58 virt-clone tool, we may add sysprepping ability.
60 https://github.com/clalancette/oz
61 https://www.redhat.com/archives/virt-tools-list/2011-May/msg00019.html
63 =head1 Convert a CD-ROM / DVD / ISO to a tarball
65 This converts input C<cd.iso> to output C<cd.tar.gz>:
67 guestfish --ro -a cd.iso -m /dev/sda tgz-out / cd.tar.gz
69 To export just a subdirectory, eg. C</files>, do:
71 guestfish --ro -a cd.iso -m /dev/sda tgz-out /files cd.tar.gz
73 =head1 Create empty disk images
75 You can use the L<guestfish(1)> I<-N> option to create empty disk
76 images. The useful guide below explains the options available.
78 https://rwmj.wordpress.com/2010/09/08/new-guestfish-n-options-in-1-5-9/#content
80 =head1 Dump raw filesystem content from inside a disk image or VM
82 You can use the L<guestfish(1)> C<download> command to extract the raw
83 filesystem content from any filesystem in a disk image or a VM (even
84 one which is encrypted or buried inside an LV):
86 guestfish --ro -a disk.img run : download /dev/sda1 sda1.img
88 guestfish --ro -d Guest run : download /dev/vg_guest/lv_root lv.img
90 To list the filesystems in a disk image, use L<virt-filesystems(1)>.
92 =head1 Edit grub configuration in a VM
100 Fix a virtual machine that does not boot.
104 Change which kernel is used to boot the VM.
108 Change kernel command line options.
112 Use L<virt-edit(1)> to edit the grub configuration:
114 virt-edit -d BrokenGuest /boot/grub/grub.conf
116 or for general tinkering inside an unbootable VM use L<virt-rescue(1)>
119 virt-rescue -d BrokenGuest
121 =head1 Export any directory from a VM
123 To export C</home> from a VM into a local directory use
126 virt-copy-out -d Guest /home .
134 The final dot of the command is not a printing error. It means we
135 want to copy out to the current directory.
139 This creates a directory called C<home> under the current directory.
143 If the guest is a Windows guest then you can use drive letters and
144 backslashes, but you must prefix the path with C<win:> and quote it to
145 protect it from the shell, like this:
147 virt-copy-out -d WinGuest 'win:c:\windows\system32\config' .
149 To get the output as a compressed tarball, do:
151 virt-tar-out -d Guest /home - | gzip --best > home.tar.gz
153 Although it sounds tempting, this is usually not a reliable way to get
154 a backup from a running guest. See the entry in the FAQ:
155 http://libguestfs.org/FAQ.html#backup
157 =head1 Find out which user is using the most space
159 This simple script examines a Linux guest to find out which user is
160 using the most space in their home directory:
169 eval $(guestfish --ro -d "$vm" -i --listen)
171 for d in $(guestfish --remote ls "$dir"); do
174 guestfish --remote du "$dir/$d";
177 guestfish --remote exit
179 =head1 Get DHCP address from a VM
181 The link below explains the many different possible techniques for
182 getting the last assigned DHCP address of a virtual machine.
184 https://rwmj.wordpress.com/2011/03/31/tip-code-for-getting-dhcp-address-from-a-virtual-machine-disk-image/#content
186 In the libguestfs source examples directory you will find the latest
187 version of the C<virt-dhcp-address.c> program.
189 =head1 Get the operating system product name string
191 Save the following script into a file called C<product-name.sh>:
195 eval "$(guestfish --ro -d "$1" --i --listen)"
196 root="$(guestfish --remote inspect-get-roots)"
197 guestfish --remote inspect-get-product-name "$root"
198 guestfish --remote exit
200 Make the script executable and run it on a named guest:
202 # product-name.sh RHEL60x64
203 Red Hat Enterprise Linux Server release 6.0 (Santiago)
205 You can also use an XPath query on the L<virt-inspector(1)> XML using
206 the C<xpath> command line tool or from your favourite programming
209 # virt-inspector RHEL60x64 > xml
210 # xpath '//product_name' < xml
213 <product_name>Red Hat Enterprise Linux Server release 6.0 (Santiago)</product_name>
215 =head1 Get the default boot kernel for a Linux VM
217 The link below contains a program to print the default boot kernel for
220 https://rwmj.wordpress.com/2010/10/30/tip-use-augeas-to-get-the-default-boot-kernel-for-a-vm/#content
222 It uses Augeas, and the technique is generally applicable for many
223 different tasks, such as:
229 listing the user accounts in the guest
233 what repositories is it configured to use
237 what NTP servers does it connect to
241 what were the boot messages last time it booted
245 listing who was logged in recently
251 =head1 Install RPMs in a guest
253 The link below contains a method to install RPMs in a guest. In fact
254 the RPMs are just uploaded to the guest along with a "firstboot"
255 script that installs them next time the guest is booted. You could
256 use this technique to install vital security updates in an offline
259 https://rwmj.wordpress.com/2010/12/01/tip-install-rpms-in-a-guest/#content
261 =head1 List applications installed in a VM
263 Save the following to a file C<list-apps.sh>:
267 eval "$(guestfish --ro -d "$1" --i --listen)"
268 root="$(guestfish --remote inspect-get-roots)"
269 guestfish --remote inspect-list-applications "$root"
270 guestfish --remote exit
272 Make the file executable and then you can run it on any named
275 # list-apps.sh WinGuest
277 app_name: Mozilla Firefox (3.6.12)
278 app_display_name: Mozilla Firefox (3.6.12)
280 app_version: 3.6.12 (en-GB)
282 app_install_path: C:\Program Files\Mozilla Firefox
284 app_publisher: Mozilla
285 app_url: http://www.mozilla.com/en-GB/
288 app_description: Mozilla Firefox
291 app_name: VLC media player
292 app_display_name: VLC media player 1.1.5
296 app_install_path: C:\Program Files\VideoLAN\VLC
298 app_publisher: VideoLAN
299 app_url: http://www.videolan.org/
305 If you want to run the script on disk images (instead of libvirt
306 virtual machines), change C<-d "$1"> to C<-a "$1">. See also
307 L<virt-inspector(1)>.
309 =head1 List files and directories in a VM
311 This involves using the L<guestfish(1)> C<find0> command like this:
313 guestfish --ro -d Guest -i find0 / - | tr '\0' '\n' | sort
315 =head1 List services in a Windows VM
317 The link below contains a script that can be used to list out the
318 services from a Windows VM, and whether those services run at boot
319 time or are loaded on demand.
321 https://rwmj.wordpress.com/2010/12/10/tip-list-services-in-a-windows-guest/#content
323 =head1 Make a disk image sparse
325 The link below contains some guides for making a disk image sparse (or
326 reintroducing sparseness).
328 https://rwmj.wordpress.com/2010/10/19/tip-making-a-disk-image-sparse/#content
330 =head1 Monitor disk usage over time
332 You can use L<virt-df(1)> to monitor disk usage of your guests over
333 time. The link below contains a guide.
335 http://virt-tools.org/learning/advanced-virt-df/
337 =head1 Reading the Windows Event Log from Windows Vista (or later)
339 L<guestfish(1)> plus the tools described in the link below can be used
340 to read out the Windows Event Log from any virtual machine running
341 Windows Vista or a later version.
343 https://rwmj.wordpress.com/2011/04/17/decoding-the-windows-event-log-using-guestfish/#content
345 =head1 Remove root password (Linux)
347 Using the L<virt-edit(1)> I<-e> option you can do simple replacements
348 on files. One use is to remove the root password from a Linux guest:
350 virt-edit domname /etc/passwd -e 's/^root:.*?:/root::/'
352 =head1 Remove Administrator password (Windows)
354 The link below contains one technique for removing the Administrator
355 password from a Windows VM, or to be more precise, it gives you a
356 command prompt the next time you log in which you can use to bypass
359 https://mdbooth.wordpress.com/2010/10/18/resetting-a-windows-guests-administrator-password-with-guestfish/
361 =head1 Unpack a live CD
363 Linux live CDs often contain multiple layers of disk images wrapped
364 like a Russian doll. You can use L<guestfish(1)> to look inside these
365 multiple layers, as outlined in the guide below.
367 https://rwmj.wordpress.com/2009/07/15/unpack-the-russian-doll-of-a-f11-live-cd/#content
369 =head1 Uploading and downloading files
371 The link below contains general tips on uploading (copying in)
372 and downloading (copying out) files from VMs.
374 https://rwmj.wordpress.com/2010/12/02/tip-uploading-and-downloading/#content
376 =head1 Use libguestfs tools on VMware ESX guests
378 The link below explains how to use libguestfs, L<guestfish(1)> and the
379 virt tools on any VMware ESX guests, by first sharing the VMware VMFS
382 https://rwmj.wordpress.com/2011/05/10/tip-use-libguestfs-on-vmware-esx-guests/#content
388 L<guestfs-examples(3)>,
392 L<guestfs-python(3)>,
394 L<http://libguestfs.org/>.
398 Richard W.M. Jones (C<rjones at redhat dot com>)
402 Copyright (C) 2009-2011 Red Hat Inc. L<http://libguestfs.org/>
404 The examples in this manual page may be freely copied, modified and
405 distributed without any restrictions.
407 This library is free software; you can redistribute it and/or
408 modify it under the terms of the GNU Lesser General Public
409 License as published by the Free Software Foundation; either
410 version 2 of the License, or (at your option) any later version.
412 This library is distributed in the hope that it will be useful,
413 but WITHOUT ANY WARRANTY; without even the implied warranty of
414 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
415 Lesser General Public License for more details.
417 You should have received a copy of the GNU Lesser General Public
418 License along with this library; if not, write to the Free Software
419 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA