examples/guestfs-recipes.pod

   1 =encoding utf8
   2
   3 =begin comment
   4
   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.
   8
   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.
  11
  12 =end comment
  13
  14 =head1 NAME
  15
  16 guestfs-recipes - libguestfs, guestfish and virt tools recipes
  17
  18 =head1 DESCRIPTION
  19
  20 This page contains recipes for and links to things you can do using
  21 libguestfs, L<guestfish(1)> and the virt tools.
  22
  23 =head1 Audit a virtual machine for setuid files
  24
  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.
  27
  28 https://rwmj.wordpress.com/2010/12/15/tip-audit-virtual-machine-for-setuid-files/#content
  29
  30 =head1 Change the background image in a Windows XP VM
  31
  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
  35 Windows.
  36
  37 https://lists.fedoraproject.org/pipermail/virt/2011-May/002655.html
  38 https://lists.fedoraproject.org/pipermail/virt/2011-May/002658.html
  39
  40 =head1 Cloning a virtual machine (Linux)
  41
  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
  44 the paths slightly.
  45
  46 https://rwmj.wordpress.com/2010/09/24/tip-my-procedure-for-cloning-a-fedora-vm/#content
  47
  48 Avoid L<virt-clone(1)>.  Currently what to do about virt-clone is
  49 under discussion.
  50
  51 https://www.redhat.com/archives/virt-tools-list/2011-May/msg00019.html
  52
  53 =head1 Cloning a virtual machine (Windows)
  54
  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.
  59
  60 https://github.com/clalancette/oz
  61 https://www.redhat.com/archives/virt-tools-list/2011-May/msg00019.html
  62
  63 =head1 Convert a CD-ROM / DVD / ISO to a tarball
  64
  65 This converts input C<cd.iso> to output C<cd.tar.gz>:
  66
  67  guestfish --ro -a cd.iso -m /dev/sda tgz-out / cd.tar.gz
  68
  69 To export just a subdirectory, eg. C</files>, do:
  70
  71  guestfish --ro -a cd.iso -m /dev/sda tgz-out /files cd.tar.gz
  72
  73 =head1 Create empty disk images
  74
  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.
  77
  78 https://rwmj.wordpress.com/2010/09/08/new-guestfish-n-options-in-1-5-9/#content
  79
  80 =head1 Dump raw filesystem content from inside a disk image or VM
  81
  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):
  85
  86  guestfish --ro -a disk.img run : download /dev/sda1 sda1.img
  87
  88  guestfish --ro -d Guest run : download /dev/vg_guest/lv_root lv.img
  89
  90 To list the filesystems in a disk image, use L<virt-filesystems(1)>.
  91
  92 =head1 Edit grub configuration in a VM
  93
  94 You can use this to:
  95
  96 =over 4
  97
  98 =item *
  99
 100 Fix a virtual machine that does not boot.
 101
 102 =item *
 103
 104 Change which kernel is used to boot the VM.
 105
 106 =item *
 107
 108 Change kernel command line options.
 109
 110 =back
 111
 112 Use L<virt-edit(1)> to edit the grub configuration:
 113
 114  virt-edit -d BrokenGuest /boot/grub/grub.conf
 115
 116 or for general tinkering inside an unbootable VM use L<virt-rescue(1)>
 117 like this:
 118
 119  virt-rescue -d BrokenGuest
 120
 121 =head1 Export any directory from a VM
 122
 123 To export C</home> from a VM into a local directory use
 124 L<virt-copy-out(1)>:
 125
 126  virt-copy-out -d Guest /home .
 127
 128 Notes:
 129
 130 =over 4
 131
 132 =item *
 133
 134 The final dot of the command is not a printing error.  It means we
 135 want to copy out to the current directory.
 136
 137 =item *
 138
 139 This creates a directory called C<home> under the current directory.
 140
 141 =back
 142
 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:
 146
 147  virt-copy-out -d WinGuest 'win:c:\windows\system32\config' .
 148
 149 To get the output as a compressed tarball, do:
 150
 151  virt-tar-out -d Guest /home - | gzip --best > home.tar.gz
 152
 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
 156
 157 =head1 Find out which user is using the most space
 158
 159 This simple script examines a Linux guest to find out which user is
 160 using the most space in their home directory:
 161
 162  #!/bin/sh -
 163
 164  set -e
 165
 166  vm="$1"
 167  dir=/home
 168
 169  eval $(guestfish --ro -d "$vm" -i --listen)
 170
 171  for d in $(guestfish --remote ls "$dir"); do
 172      echo -n "$dir/$d"
 173      echo -ne '\t'
 174      guestfish --remote du "$dir/$d";
 175  done | sort -nr -k 2
 176
 177  guestfish --remote exit
 178
 179 =head1 Get DHCP address from a VM
 180
 181 The link below explains the many different possible techniques for
 182 getting the last assigned DHCP address of a virtual machine.
 183
 184 https://rwmj.wordpress.com/2011/03/31/tip-code-for-getting-dhcp-address-from-a-virtual-machine-disk-image/#content
 185
 186 In the libguestfs source examples directory you will find the latest
 187 version of the C<virt-dhcp-address.c> program.
 188
 189 =head1 Get the operating system product name string
 190
 191 Save the following script into a file called C<product-name.sh>:
 192
 193  #!/bin/sh -
 194  set -e
 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
 199
 200 Make the script executable and run it on a named guest:
 201
 202  # product-name.sh RHEL60x64
 203  Red Hat Enterprise Linux Server release 6.0 (Santiago)
 204
 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
 207 language:
 208
 209  # virt-inspector RHEL60x64 > xml
 210  # xpath '//product_name' < xml
 211  Found 1 nodes:
 212  -- NODE --
 213  <product_name>Red Hat Enterprise Linux Server release 6.0 (Santiago)</product_name>
 214
 215 =head1 Get the default boot kernel for a Linux VM
 216
 217 The link below contains a program to print the default boot kernel for
 218 a Linux VM.
 219
 220 https://rwmj.wordpress.com/2010/10/30/tip-use-augeas-to-get-the-default-boot-kernel-for-a-vm/#content
 221
 222 It uses Augeas, and the technique is generally applicable for many
 223 different tasks, such as:
 224
 225 =over 4
 226
 227 =item *
 228
 229 listing the user accounts in the guest
 230
 231 =item *
 232
 233 what repositories is it configured to use
 234
 235 =item *
 236
 237 what NTP servers does it connect to
 238
 239 =item *
 240
 241 what were the boot messages last time it booted
 242
 243 =item *
 244
 245 listing who was logged in recently
 246
 247 =back
 248
 249 http://augeas.net/
 250
 251 =head1 Install RPMs in a guest
 252
 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
 257 guest.
 258
 259 https://rwmj.wordpress.com/2010/12/01/tip-install-rpms-in-a-guest/#content
 260
 261 =head1 List applications installed in a VM
 262
 263 Save the following to a file C<list-apps.sh>:
 264
 265  #!/bin/sh -
 266  set -e
 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
 271
 272 Make the file executable and then you can run it on any named
 273 virtual machine:
 274
 275  # list-apps.sh WinGuest
 276  [0] = {
 277    app_name: Mozilla Firefox (3.6.12)
 278    app_display_name: Mozilla Firefox (3.6.12)
 279    app_epoch: 0
 280    app_version: 3.6.12 (en-GB)
 281    app_release:
 282    app_install_path: C:\Program Files\Mozilla Firefox
 283    app_trans_path:
 284    app_publisher: Mozilla
 285    app_url: http://www.mozilla.com/en-GB/
 286    app_source_package:
 287    app_summary:
 288    app_description: Mozilla Firefox
 289  }
 290  [1] = {
 291    app_name: VLC media player
 292    app_display_name: VLC media player 1.1.5
 293    app_epoch: 0
 294    app_version: 1.1.5
 295    app_release:
 296    app_install_path: C:\Program Files\VideoLAN\VLC
 297    app_trans_path:
 298    app_publisher: VideoLAN
 299    app_url: http://www.videolan.org/
 300    app_source_package:
 301    app_summary:
 302    app_description:
 303  }
 304
 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)>.
 308
 309 =head1 List files and directories in a VM
 310
 311 This involves using the L<guestfish(1)> C<find0> command like this:
 312
 313  guestfish --ro -d Guest -i find0 / - | tr '\0' '\n' | sort
 314
 315 =head1 List services in a Windows VM
 316
 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.
 320
 321 https://rwmj.wordpress.com/2010/12/10/tip-list-services-in-a-windows-guest/#content
 322
 323 =head1 Make a disk image sparse
 324
 325 The link below contains some guides for making a disk image sparse (or
 326 reintroducing sparseness).
 327
 328 https://rwmj.wordpress.com/2010/10/19/tip-making-a-disk-image-sparse/#content
 329
 330 =head1 Monitor disk usage over time
 331
 332 You can use L<virt-df(1)> to monitor disk usage of your guests over
 333 time.  The link below contains a guide.
 334
 335 http://virt-tools.org/learning/advanced-virt-df/
 336
 337 =head1 Reading the Windows Event Log from Windows Vista (or later)
 338
 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.
 342
 343 https://rwmj.wordpress.com/2011/04/17/decoding-the-windows-event-log-using-guestfish/#content
 344
 345 =head1 Remove root password (Linux)
 346
 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:
 349
 350  virt-edit domname /etc/passwd -e 's/^root:.*?:/root::/'
 351
 352 =head1 Remove Administrator password (Windows)
 353
 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
 357 any security:
 358
 359 https://mdbooth.wordpress.com/2010/10/18/resetting-a-windows-guests-administrator-password-with-guestfish/
 360
 361 =head1 Unpack a live CD
 362
 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.
 366
 367 https://rwmj.wordpress.com/2009/07/15/unpack-the-russian-doll-of-a-f11-live-cd/#content
 368
 369 =head1 Uploading and downloading files
 370
 371 The link below contains general tips on uploading (copying in)
 372 and downloading (copying out) files from VMs.
 373
 374 https://rwmj.wordpress.com/2010/12/02/tip-uploading-and-downloading/#content
 375
 376 =head1 Use libguestfs tools on VMware ESX guests
 377
 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
 380 over sshfs.
 381
 382 https://rwmj.wordpress.com/2011/05/10/tip-use-libguestfs-on-vmware-esx-guests/#content
 383
 384 =head1 SEE ALSO
 385
 386 L<guestfs(3)>,
 387 L<guestfish(1)>,
 388 L<guestfs-examples(3)>,
 389 L<guestfs-java(3)>,
 390 L<guestfs-ocaml(3)>,
 391 L<guestfs-perl(3)>,
 392 L<guestfs-python(3)>,
 393 L<guestfs-ruby(3)>,
 394 L<http://libguestfs.org/>.
 395
 396 =head1 AUTHORS
 397
 398 Richard W.M. Jones (C<rjones at redhat dot com>)
 399
 400 =head1 COPYRIGHT
 401
 402 Copyright (C) 2009-2011 Red Hat Inc. L<http://libguestfs.org/>
 403
 404 The examples in this manual page may be freely copied, modified and
 405 distributed without any restrictions.
 406
 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.
 411
 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.
 416
 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