configure: Remove -Wmissing-noreturn warning.
[libguestfs.git] / 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