1guestfs-recipes(1) Virtualization Support guestfs-recipes(1)
2
6 guestfs-recipes - libguestfs, guestfish and virt tools recipes
7
9 This page contains recipes for and links to things you can do using
10 libguestfs, guestfish(1) and the virt tools.
11
13 See: "EXAMPLES" in virt-ls(1).
14
16 The links below explain how to use guestfish(1) to change the
17 background image for a user of a Windows XP VM. Unfortunately the
18 technique appears to be substantially different for each version of
19 Windows.
20 https://lists.fedoraproject.org/pipermail/virt/2011-May/002655.html
22 https://lists.fedoraproject.org/pipermail/virt/2011-May/002658.html
23
25 To checksum a whole device, or a partition, LV etc within a disk image:
26 guestfish --ro -a disk.img run : checksum-device md5 /dev/sda1
28 Replace "md5" with the type of checksum you want. See
30 "guestfs_checksum_device" in guestfs(3) for a list of supported types.
31 "/dev/sda1" means "the first partition". You could use "/dev/sda" to
33 checksum the whole disk image, or the name of a logical volume or RAID
34 device.
35 To checksum a single file:
37 guestfish --ro -a disk.img -i checksum sha256 /etc/passwd
39 or for a Windows guest:
41 guestfish --ro -a disk.img -i \
43 checksum sha256 'win:\windows\system32\config\SOFTWARE'
44
46 Use a combination of tools like cp(1), dd(1), and virt tools like
47 virt-sysprep(1), virt-sparsify(1) and virt-resize(1).
48 For more details, see: "COPYING AND CLONING" in virt-sysprep(1).
50
52 This converts input "cd.iso" to output "cd.tar.gz":
53 guestfish --ro -a cd.iso -m /dev/sda tgz-out / cd.tar.gz
55 To export just a subdirectory, eg. "/files", do:
57 guestfish --ro -a cd.iso -m /dev/sda tgz-out /files cd.tar.gz
59
61 If you have a data disk in one format / filesystem / partition / volume
62 manager, you can convert it another using this technique.
63 In this example, we start with a data disk that has a single partition
65 containing a filesystem, and we want to create another disk that
66 contains the same files but on an ext3 filesystem embedded in a logical
67 volume on a sparse raw-format disk.
68 First create the formatted-but-empty target disk:
70 truncate -s 10G target.img
72 virt-format -a target.img --partition=mbr --lvm --filesystem=ext3
73 Now, pipe two guestfish instances together to transfer the old data to
75 the new disk:
76 guestfish --ro -a source.img -m /dev/sda1 -- tar-out / - | \
78 guestfish --rw -a target.img -m /dev/VG/LV -- tar-in - /
79 To browse the final disk image, do:
81 guestfish --ro -a target.img -m /dev/VG/LV
83 ><fs> ll /
84 This technique is quite powerful, allowing you for example to split up
86 source directories over the target filesystems.
87 Note this won't work (at least, not directly) for bootable virtual
89 machine disks because it doesn't copy over the boot loader.
90
92 The virt-format(1) tool can do this directly.
93 Use virt-make-fs(1) to create a disk image with content. This can also
95 create some standard disk images such as virtual floppy devices (VFDs).
96 You can also use the guestfish(1) -N option to create empty disk
98 images. The useful guide below explains the options available.
99 https://rwmj.wordpress.com/2010/09/08/new-guestfish-n-options-in-1-5-9/#content
101
103 Use guestfish. To delete a file:
104 guestfish -a disk.img -i rm /file/to/delete
106 To touch a file (bring it up to date or create it):
108 guestfish -a disk.img -i touch /file/to/touch
110 To stat a file. Since this is a read-only operation, we can make it
112 safer by adding the --ro flag.
113 guestfish --ro -a disk.img -i stat /file/to/stat
115 There are dozens of these commands. See guestfish(1) or the output of
117 "guestfish -h"
118
120 virt-ls(1) provides a simple way to find the differences between two
121 guests (for example if they were originally cloned from the same
122 source), or between two snapshots from the same guest. See
123 "DIFFERENCES IN SNAPSHOTS AND BACKING FILES" in virt-ls(1).
124 There are also experimental patches on the mailing list for a "virt-
126 diff" tool.
127
129 You can use the guestfish(1) "download" command to extract the raw
130 filesystem content from any filesystem in a disk image or a VM (even
131 one which is encrypted or buried inside an LV or RAID device):
132 guestfish --ro -a disk.img run : download /dev/sda1 sda1.img
134 guestfish --ro -d Guest run : download /dev/vg_guest/lv_root lv.img
136 To download to stdout, replace the filename with a "-" character:
138 guestfish --ro -a disk.img run : download /dev/sda1 - | gzip > sda1.gz
140 To list the filesystems in a disk image, use virt-filesystems(1).
142 See also "Uploading raw filesystem content".
144
146 You can use this to:
147 · Fix a virtual machine that does not boot.
149 · Change which kernel is used to boot the VM.
151 · Change kernel command line options.
153 Use virt-edit(1) to edit the grub configuration:
155 virt-edit -d BrokenGuest /boot/grub2/grub.cfg
157 or for general tinkering inside an unbootable VM use virt-rescue(1)
159 like this:
160 virt-rescue -d BrokenGuest
162
164 To export "/home" from a VM into a local directory use
165 virt-copy-out(1):
166 virt-copy-out -d Guest /home .
168 Notes:
170 · The final dot of the command is not a printing error. It means we
172 want to copy out to the current directory.
173 · This creates a directory called "home" under the current directory.
175 If the guest is a Windows guest then you can use drive letters and
177 backslashes, but you must prefix the path with "win:" and quote it to
178 protect it from the shell, like this:
179 virt-copy-out -d WinGuest 'win:c:\windows\system32\config' .
181 To get the output as a compressed tarball, do:
183 virt-tar-out -d Guest /home - | gzip --best > home.tar.gz
185 Although it sounds tempting, this is usually not a reliable way to get
187 a backup from a running guest. See the entry in the FAQ:
188 http://libguestfs.org/FAQ.html#backup
189
191 This simple script examines a Linux guest to find out which user is
192 using the most space in their home directory:
193 #!/bin/sh -
195 set -e
197 vm="$1"
199 dir=/home
200 eval $(guestfish --ro -d "$vm" -i --listen)
202 for d in $(guestfish --remote ls "$dir"); do
204 echo -n "$dir/$d"
205 echo -ne '\t'
206 guestfish --remote du "$dir/$d";
207 done | sort -nr -k 2
208 guestfish --remote exit
210
212 The link below explains the many different possible techniques for
213 getting the last assigned DHCP address of a virtual machine.
214 https://rwmj.wordpress.com/2011/03/31/tip-code-for-getting-dhcp-address-from-a-virtual-machine-disk-image/#content
216 In the libguestfs source examples directory you will find the latest
218 version of the "virt-dhcp-address.c" program.
219
221 Save the following script into a file called "product-name.sh":
222 #!/bin/sh -
224 set -e
225 eval "$(guestfish --ro -d "$1" --i --listen)"
226 root="$(guestfish --remote inspect-get-roots)"
227 guestfish --remote inspect-get-product-name "$root"
228 guestfish --remote exit
229 Make the script executable and run it on a named guest:
231 # product-name.sh RHEL60x64
233 Red Hat Enterprise Linux Server release 6.0 (Santiago)
234 You can also use an XPath query on the virt-inspector(1) XML using the
236 "xpath" command line tool or from your favourite programming language:
237 # virt-inspector RHEL60x64 > xml
239 # xpath '//product_name' < xml
240 Found 1 nodes:
241 -- NODE --
242 <product_name>Red Hat Enterprise Linux Server release 6.0 (Santiago)</product_name>
243
245 The link below contains a program to print the default boot kernel for
246 a Linux VM.
247 https://rwmj.wordpress.com/2010/10/30/tip-use-augeas-to-get-the-default-boot-kernel-for-a-vm/#content
249 It uses Augeas, and the technique is generally applicable for many
251 different tasks, such as:
252 · listing the user accounts in the guest
254 · what repositories is it configured to use
256 · what NTP servers does it connect to
258 · what were the boot messages last time it booted
260 · listing who was logged in recently
262 http://augeas.net/
264
266 There are various ways to use libguestfs to find out why a guest is
267 hanging or unresponsive:
268 1. Read the log files using virt-cat:
270 virt-cat Guest /var/log/messages | less
272 2. Read the Windows Event Log (Windows Vista or later only):
274 https://rwmj.wordpress.com/2011/04/17/decoding-the-windows-event-log-using-guestfish/#content
276 3. Find out which files were last updated in a guest:
278 https://rwmj.wordpress.com/2012/02/27/using-libguestfs-to-find-out-why-a-windows-guest-was-hanging/#content
280 This might give you a clue as to what program is running.
282
284 Hex-dump the boot partition:
285 guestfish --ro -a disk.img run : pread-device /dev/sda 0x200 0 |
287 hexdump -C
288
290 Hex-edit the first sector (boot partition):
291 guestfish --rw -a disk.img run : hexedit /dev/sda 0x200
293
295 The link below contains a method to install RPMs in a guest. In fact
296 the RPMs are just uploaded to the guest along with a "firstboot" script
297 that installs them next time the guest is booted. You could use this
298 technique to install vital security updates in an offline guest.
299 https://rwmj.wordpress.com/2010/12/01/tip-install-rpms-in-a-guest/#content
301 Since libguestfs 1.20, virt-sysprep(1) has an option for installing
303 firstboot scripts in Linux guests.
304
306 Save the following to a file "list-apps.sh":
307 #!/bin/sh -
309 set -e
310 eval "$(guestfish --ro -d "$1" --i --listen)"
311 root="$(guestfish --remote inspect-get-roots)"
312 guestfish --remote inspect-list-applications "$root"
313 guestfish --remote exit
314 Make the file executable and then you can run it on any named virtual
316 machine:
317 # list-apps.sh WinGuest
319 [0] = {
320 app_name: Mozilla Firefox (3.6.12)
321 app_display_name: Mozilla Firefox (3.6.12)
322 app_epoch: 0
323 app_version: 3.6.12 (en-GB)
324 app_release:
325 app_install_path: C:\Program Files\Mozilla Firefox
326 app_trans_path:
327 app_publisher: Mozilla
328 app_url: http://www.mozilla.com/en-GB/
329 app_source_package:
330 app_summary:
331 app_description: Mozilla Firefox
332 }
333 [1] = {
334 app_name: VLC media player
335 app_display_name: VLC media player 1.1.5
336 app_epoch: 0
337 app_version: 1.1.5
338 app_release:
339 app_install_path: C:\Program Files\VideoLAN\VLC
340 app_trans_path:
341 app_publisher: VideoLAN
342 app_url: http://www.videolan.org/
343 app_source_package:
344 app_summary:
345 app_description:
346 }
347 If you want to run the script on disk images (instead of libvirt
349 virtual machines), change "-d "$1"" to "-a "$1"". See also
350 virt-inspector(1).
351
353 Use virt-ls(1).
354
356 The link below contains a script that can be used to list out the
357 services from a Windows VM, and whether those services run at boot time
358 or are loaded on demand.
359 https://rwmj.wordpress.com/2010/12/10/tip-list-services-in-a-windows-guest/#content
361
363 Use virt-sparsify(1).
364
366 You can use virt-df(1) to monitor disk usage of your guests over time.
367 The link below contains a guide.
368 http://virt-tools.org/learning/advanced-virt-df/
370
372 guestfish(1) plus the tools described in the link below can be used to
373 read out the Windows Event Log from any virtual machine running Windows
374 Vista or a later version.
375 https://rwmj.wordpress.com/2011/04/17/decoding-the-windows-event-log-using-guestfish/#content
377
379 Using the virt-edit(1) -e option you can do simple replacements on
380 files. One use is to remove the root password from a Linux guest:
381 virt-edit domname /etc/passwd -e 's/^root:.*?:/root::/'
383
385 The link below contains one technique for removing the Administrator
386 password from a Windows VM, or to be more precise, it gives you a
387 command prompt the next time you log in which you can use to bypass any
388 security:
389 https://mdbooth.wordpress.com/2010/10/18/resetting-a-windows-guests-administrator-password-with-guestfish/
391
393 It is possible to do a "sysprep" using libguestfs alone, although not
394 straightforward. Currently there is code in the Aeolus Oz project
395 which does this (using libguestfs). It is likely we will add this to
396 virt-sysprep(1) in future.
397 https://github.com/clalancette/oz
399 https://www.redhat.com/archives/virt-tools-list/2011-May/msg00019.html
400
402 Linux live CDs often contain multiple layers of disk images wrapped
403 like a Russian doll. You can use guestfish(1) to look inside these
404 multiple layers, as outlined in the guide below.
405 https://rwmj.wordpress.com/2009/07/15/unpack-the-russian-doll-of-a-f11-live-cd/#content
407
409 The link below contains general tips on uploading (copying in) and
410 downloading (copying out) files from VMs.
411 https://rwmj.wordpress.com/2010/12/02/tip-uploading-and-downloading/#content
413
415 You can use guestfish(1) to upload whole filesystems into a VM, even
416 into a filesystem which is encrypted or buried inside an LV or RAID
417 device:
418 guestfish --rw -a disk.img run : upload sda1.img /dev/sda1
420 guestfish --rw -d Guest run : upload lv.img /dev/vg_guest/lv_root
422 One common problem is that the filesystem isn't the right size for the
424 target. If it is too large, there's not much you can do with
425 libguestfs - you have to prepare the filesystem differently. But if
426 the filesystem needs to expand into the target, you can use guestfish
427 to resize it to the right size:
428 guestfish --rw -d Guest run : \
430 upload lv.img /dev/vg_guest/lv_root : \
431 resize2fs /dev/vg_guest/lv_root
432 (or use "ntfsresize" if the filesystem is NTFS).
434
436 The link below explains how to use libguestfs, guestfish(1) and the
437 virt tools on any VMware ESX guests, by first sharing the VMware VMFS
438 over sshfs.
439 https://rwmj.wordpress.com/2011/05/10/tip-use-libguestfs-on-vmware-esx-guests/#content
441
443 guestfs(3), guestfish(1), guestfs-examples(3), guestfs-erlang(3),
444 guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3), guestfs-perl(3),
445 guestfs-python(3), guestfs-ruby(3), http://libguestfs.org/.
446
448 Richard W.M. Jones ("rjones at redhat dot com")
449
451 Copyright (C) 2009-2013 Red Hat Inc.
452
454 This manual page contains examples which we hope you will use in your
455 programs. The examples may be freely copied, modified and distributed
456 for any purpose without any restrictions.
457
459 To get a list of bugs against libguestfs, use this link:
460 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
461 To report a new bug against libguestfs, use this link:
463 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
464 When reporting a bug, please supply:
466 · The version of libguestfs.
468 · Where you got libguestfs (eg. which Linux distro, compiled from
470 source, etc)
471 · Describe the bug accurately and give a way to reproduce it.
473 · Run libguestfs-test-tool(1) and paste the complete, unedited output
475 into the bug report.
476libguestfs-1.20.11 2013-08-27 guestfs-recipes(1)