1guestfs-faq(1) Virtualization Support guestfs-faq(1)
2
6 guestfs-faq - libguestfs Frequently Asked Questions (FAQ)
7
9 What is libguestfs?
10 libguestfs is a way to create, access and modify disk images. You can
11 look inside disk images, modify the files they contain, create them
12 from scratch, resize them, and much more. It's especially useful from
13 scripts and programs and from the command line.
14 libguestfs is a C library (hence "lib-"), and a set of tools built on
16 this library, and bindings for many common programming languages.
17 For more information about what libguestfs can do read the introduction
19 on the home page (http://libguestfs.org).
20 What are the virt tools?
22 Virt tools (website: http://virt-tools.org) are a whole set of
23 virtualization management tools aimed at system administrators. Some
24 of them come from libguestfs, some from libvirt and many others from
25 other open source projects. So virt tools is a superset of libguestfs.
26 However libguestfs comes with many important tools. See
27 http://libguestfs.org for a full list.
28 Does libguestfs need { libvirt / KVM / Red Hat / Fedora }?
30 No!
31 libvirt is not a requirement for libguestfs.
33 libguestfs works with any disk image, including ones created in VMware,
35 KVM, qemu, VirtualBox, Xen, and many other hypervisors, and ones which
36 you have created from scratch.
37 Red Hat sponsors (ie. pays for) development of libguestfs and a huge
39 number of other open source projects. But you can run libguestfs and
40 the virt tools on many different Linux distros and Mac OS X. We try
41 our best to support all Linux distros as first-class citizens. Some
42 virt tools have been ported to Windows.
43 How does libguestfs compare to other tools?
45 vs. kpartx
46 Libguestfs takes a different approach from kpartx. kpartx needs
47 root, and mounts filesystems on the host kernel (which can be
48 insecure - see "SECURITY" in guestfs(3)). Libguestfs isolates your
49 host kernel from guests, is more flexible, scriptable, supports
50 LVM, doesn't require root, is isolated from other processes, and
51 cleans up after itself. Libguestfs is more than just file access
52 because you can use it to create images from scratch.
53 vs. vdfuse
55 vdfuse is like kpartx but for VirtualBox images. See the kpartx
56 comparison above. You can use libguestfs on the partition files
57 exposed by vdfuse, although it's not necessary since libguestfs can
58 access VirtualBox images directly.
59 vs. qemu-nbd
61 NBD (Network Block Device) is a protocol for exporting block
62 devices over the network. qemu-nbd is an NBD server which can
63 handle any disk format supported by qemu (eg. raw, qcow2). You can
64 use libguestfs and qemu-nbd together to access block devices over
65 the network, for example: "guestfish -a nbd://remote"
66 vs. mounting filesystems in the host
68 Mounting guest filesystems in the host is insecure and should be
69 avoided completely for untrusted guests. Use libguestfs to provide
70 a layer of protection against filesystem exploits. See also
71 guestmount(1).
72 vs. parted
74 Libguestfs supports LVM. Libguestfs uses parted and provides most
75 parted features through the libguestfs API.
76
78 How do I know what version I'm using?
79 The simplest method is:
80 guestfish --version
82 Libguestfs development happens along an unstable branch and we
84 periodically create a stable branch which we backport stable patches
85 to. To find out more, read "LIBGUESTFS VERSION NUMBERS" in guestfs(3).
86 How can I get help?
88 What mailing lists or chat rooms are available?
89 If you are a Red Hat customer using Red Hat Enterprise Linux, please
90 contact Red Hat Support: http://redhat.com/support
91 There is a mailing list, mainly for development, but users are also
93 welcome to ask questions about libguestfs and the virt tools:
94 https://www.redhat.com/mailman/listinfo/libguestfs
95 You can also talk to us on IRC channel "#libguestfs" on FreeNode.
97 We're not always around, so please stay in the channel after asking
98 your question and someone will get back to you.
99 For other virt tools (not ones supplied with libguestfs) there is a
101 general virt tools mailing list:
102 https://www.redhat.com/mailman/listinfo/virt-tools-list
103 How do I report bugs?
105 Please use the following link to enter a bug in Bugzilla:
106 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
108 Include as much detail as you can and a way to reproduce the problem.
110 Include the full output of libguestfs-test-tool(1).
112
114 See also "LIBGUESTFS GOTCHAS" in guestfs(3) for some "gotchas" with
115 using the libguestfs API.
116 "Could not allocate dynamic translator buffer"
118 This obscure error is in fact an SELinux failure. You have to enable
119 the following SELinux boolean:
120 setsebool -P virt_use_execmem=on
122 For more information see
124 https://bugzilla.redhat.com/show_bug.cgi?id=806106.
125 "child process died unexpectedly"
127 This error indicates that qemu failed or the host kernel could not
128 boot. To get further information about the failure, you have to run:
129 libguestfs-test-tool
131 If, after using this, you still don't understand the failure, contact
133 us (see previous section).
134 libguestfs: error: cannot find any suitable libguestfs supermin, fixed or
136 old-style appliance on LIBGUESTFS_PATH
137 If you see this error on Debian/Ubuntu, you need to run the following
138 command as root:
139 update-guestfs-appliance
141 Non-ASCII characters don't appear on VFAT filesystems.
143 Typical symptoms of this problem:
144 · You get an error when you create a file where the filename contains
146 non-ASCII characters, particularly non 8-bit characters from Asian
147 languages (Chinese, Japanese, etc). The filesystem is VFAT.
148 · When you list a directory from a VFAT filesystem, filenames appear
150 as question marks.
151 This is a design flaw of the GNU/Linux system.
153 VFAT stores long filenames as UTF-16 characters. When opening or
155 returning filenames, the Linux kernel has to translate these to some
156 form of 8 bit string. UTF-8 would be the obvious choice, except for
157 Linux users who persist in using non-UTF-8 locales (the user's locale
158 is not known to the kernel because it's a function of libc).
159 Therefore you have to tell the kernel what translation you want done
161 when you mount the filesystem. The two methods are the "iocharset"
162 parameter (which is not relevant to libguestfs) and the "utf8" flag.
163 So to use a VFAT filesystem you must add the "utf8" flag when mounting.
165 From guestfish, use:
166 ><fs> mount-options utf8 /dev/sda1 /
168 or on the guestfish command line:
170 guestfish [...] -m /dev/sda1:/:utf8
172 or from the API:
174 guestfs_mount_options (g, "utf8", "/dev/sda1", "/");
176 The kernel will then translate filenames to and from UTF-8 strings.
178 We considered adding this mount option transparently, but unfortunately
180 there are several problems with doing that:
181 · On some Linux systems, the "utf8" mount option doesn't work. We
183 don't precisely understand what systems or why, but this was
184 reliably reported by one user.
185 · It would prevent you from using the "iocharset" parameter because
187 it is incompatible with "utf8". It is probably not a good idea to
188 use this parameter, but we don't want to prevent it.
189 Non-ASCII characters appear as underscore (_) on ISO9660 filesystems.
191 The filesystem was not prepared correctly with mkisofs or genisoimage.
192 Make sure the filesystem was created using Joliet and/or Rock Ridge
193 extensions. libguestfs does not require any special mount options to
194 handle the filesystem.
195
197 Where can I get the latest binaries for ...?
198 Fedora ≥ 11
199 Use:
200 yum install '*guestf*'
202 For the latest builds, see:
204 http://koji.fedoraproject.org/koji/packageinfo?packageID=8391
205 Red Hat Enterprise Linux
207 RHEL 5
208 The version shipped in official RHEL 5 is very old and should
209 not be used except in conjunction with virt-v2v. Use the up-
210 to-date libguestfs 1.20 package in EPEL 5:
211 https://fedoraproject.org/wiki/EPEL
212 RHEL 6
214 It is part of the default install. On RHEL 6 and 7 (only) you
215 have to install "libguestfs-winsupport" to get Windows guest
216 support.
217 RHEL 6.5
219 There is a preview repository available for people who want
220 to see what packages will be in RHEL 6.5. Follow the
221 instructions here:
222 https://www.redhat.com/archives/libguestfs/2013-May/msg00100.html
224 RHEL 7
226 It will be part of the default install, and based on
227 libguestfs 1.22. You will need to install
228 "libguestfs-winsupport" separately to get Windows guest
229 support.
230 Debian and Ubuntu
232 Debian Squeeze (6)
233 Hilko Bengen has built libguestfs in squeeze backports:
234 http://packages.debian.org/search?keywords=guestfs&searchon=names§ion=all&suite=squeeze-backports
235 Debian Wheezy and later (7+)
237 Hilko Bengen supports libguestfs on Debian. Official Debian
238 packages are available:
239 http://packages.debian.org/search?keywords=libguestfs
240 Ubuntu
242 We don't have a full time Ubuntu maintainer, and the packages
243 supplied by Canonical (which are outside our control) are
244 sometimes broken.
245 Canonical decided to change the permissions on the kernel so
247 that it's not readable except by root. This is completely
248 stupid, but they won't change it
249 (https://bugs.launchpad.net/ubuntu/+source/linux/+bug/759725).
250 So every user should do this:
251 sudo chmod 0644 /boot/vmlinuz*
253 Ubuntu 12.04
255 libguestfs in this version of Ubuntu works, but you need to
256 update febootstrap and seabios to the latest versions.
257 You need febootstrap ≥ 3.14-2 from:
259 http://packages.ubuntu.com/precise/febootstrap
260 After installing or updating febootstrap, rebuild the
262 appliance:
263 sudo update-guestfs-appliance
265 You need seabios ≥ 0.6.2-0ubuntu2.1 or ≥ 0.6.2-0ubuntu3
267 from: http://packages.ubuntu.com/precise-updates/seabios or
268 http://packages.ubuntu.com/quantal/seabios
269 Also you need to do (see above):
271 sudo chmod 0644 /boot/vmlinuz*
273 Gentoo
275 Libguestfs was added to Gentoo in 2012-07 by Andreis Vinogradovs
276 (libguestfs) and Maxim Koltsov (mainly hivex). Do:
277 emerge libguestfs
279 SuSE
281 Libguestfs was added to SuSE in 2012 by Olaf Hering.
282 ArchLinux
284 Libguestfs was added to the AUR in 2010.
285 Other Linux distro
287 Compile from source (next section).
288 Other non-Linux distro
290 You'll have to compile from source, and port it.
291 How can I compile and install libguestfs from source?
293 If your Linux distro has a working port of supermin (that is, Fedora,
294 Red Hat Enterprise Linux ≥ 6.3, Debian, Ubuntu and ArchLinux) then you
295 should just be able to compile from source in the usual way. Download
296 the latest tarball from http://libguestfs.org/download, unpack it, and
297 start by reading the README file.
298 If you don't have supermin, you will need to use the "fixed appliance
300 method". See: http://libguestfs.org/download/binaries/appliance/
301 Patches to port supermin to more Linux distros are welcome.
303 Why do I get an error when I try to rebuild from the source RPMs supplied
305 by Red Hat / Fedora?
306 Note: This issue is fixed in Fedora ≥ 19 and RHEL ≥ 6.5.
307 Because of the complexity of building the libguestfs appliance, the
309 source RPMs provided cannot be rebuilt directly using "rpmbuild" or
310 "mock".
311 If you use Koji (which is open source software and may be installed
313 locally), then the SRPMs can be rebuilt in Koji.
314 https://fedoraproject.org/wiki/Koji
315 If you don't have or want to use Koji, then you have to give libguestfs
317 access to the network so it can download the RPMs for building the
318 appliance. You also need to set an RPM macro to tell libguestfs to use
319 the network. Put the following line into a file called
320 "$HOME/.rpmmacros":
321 %libguestfs_buildnet 1
323 If you are using mock, do:
325 mock -D '%libguestfs_buildnet 1' [etc]
327 How can I add support for sVirt?
329 Note for Fedora/RHEL users: This configuration is the default starting
330 with Fedora 18 and RHEL 7. If you find any problems, please let us
331 know or file a bug.
332 SVirt provides a hardened appliance using SELinux, making it very hard
334 for a rogue disk image to "escape" from the confinement of libguestfs
335 and damage the host (it's fair to say that even in standard libguestfs
336 this would be hard, but sVirt provides an extra layer of protection for
337 the host and more importantly protects virtual machines on the same
338 host from each other).
339 Currently to enable sVirt you will need libvirt ≥ 0.10.2 (1.0 or later
341 preferred), libguestfs ≥ 1.20, and the SELinux policies from recent
342 Fedora. If you are not running Fedora 18+, you will need to make
343 changes to your SELinux policy - contact us on the mailing list.
344 Once you have the requirements, do:
346 ./configure --with-default-attach-method=libvirt
348 make
349 Set SELinux to Enforcing mode, and sVirt should be used automatically.
351 All, or almost all, features of libguestfs should work under sVirt.
353 There is one known shortcoming: virt-rescue(1) will not use libvirt
354 (hence sVirt), but falls back to direct launch of qemu. So you won't
355 currently get the benefit of sVirt protection when using virt-rescue.
356 You can check if sVirt is being used by enabling libvirtd logging (see
358 "/etc/libvirt/libvirtd.log"), killing and restarting libvirtd, and
359 checking the log files for "Setting SELinux context on ..." messages.
360 In theory sVirt should support AppArmor, but we have not tried it. It
362 will almost certainly require patching libvirt and writing an AppArmor
363 policy.
364 Libguestfs has a really long list of dependencies!
366 That's because it does a lot of things.
367 Libguestfs -- as it is packaged for Fedora -- satisfies the following
369 conditions:
370 1. The Fedora package is full featured, that is, it supports every
372 possible feature of libguestfs (every filesystem, every filesystem
373 tool, etc.)
374 A common request is to split up libguestfs into separate feature
376 areas so you could, say, install XFS support and NTFS support
377 separately. This is not possible right now.
378 2. The download size of the libguestfs package is relatively small
380 (ie. not ten's of megabytes as it would be if it included a
381 complete, "statically linked" appliance).
382 3. The Fedora package automatically updates itself if there is a
384 security update. It doesn't include a huge static blob that has to
385 be rebuilt and users have to re-download if there is an update.
386 4. Able to be installed without needing direct network access. This
388 is important when using closed networks, privately mirrored
389 repositories or RHN Satellite.
390 5. The Fedora package can be tested during the build.
392 If you want to drop any one of those conditions, then you can package
394 libguestfs differently and make it have fewer dependencies, fewer
395 features or a faster start up time:
396 1. (full featured)
398 Take "appliance/packagelist.in" in the source, and comment out any
399 features you don't actually care about. For example if you never
400 anticipate editing a Windows guest, remove all the ntfs-related
401 packages. You can get away with fewer dependencies.
402 2. (download size) / 3. (updates)
404 Use libguestfs-make-fixed-appliance(1) to build a compressed
405 appliance. Bundle this with your package and set $LIBGUESTFS_PATH
406 to point to it. Users will have to download this large appliance,
407 but no dependencies are needed, and supermin-helper(1) is not used.
408 4. (network access)
410 Reconstruct and cache the appliance once during package install.
411 The Debian packaging currently works like this, but requires
412 network access during package install.
413 5. (tests)
415 Don't run any tests during the build. The build will be much
416 faster, but also less likely to work correctly.
417 Note that running the tests in "tests/qemu" is probably a good
419 idea, since those are sanity tests. Also you should do
420 "make quickcheck" to ensure libguestfs is basically working.
421 Errors during launch on Fedora ≥ 18, RHEL ≥ 7
423 In Fedora ≥ 18 and RHEL ≥ 7, libguestfs uses libvirt to manage the
424 appliance. Previously (and upstream) libguestfs runs qemu directly:
425 +----------------------------------+
427 | libguestfs |
428 +----------------+-----------------+
429 | direct backend | libvirt backend |
430 +----------------+-----------------+
431 | |
432 v v
433 +-------+ +----------+
434 | qemu | | libvirtd |
435 +-------+ +----------+
436 |
437 v
438 +-------+
439 | qemu |
440 +-------+
441 upstream Fedora 18+
443 non-Fedora RHEL 7+
444 non-RHEL
445 The libvirt backend is more sophisticated, supporting SELinux/sVirt
447 (see above), hotplugging and more. It is, however, more complex and so
448 less robust.
449 If you have permissions problems using the libvirt backend, you can
451 switch to the direct backend by setting this environment variable:
452 export LIBGUESTFS_BACKEND=direct
454 before running any libguestfs program or virt tool.
456 How can I switch to a fixed / prebuilt appliance?
458 This may improve the stability and performance of libguestfs on Fedora
459 and RHEL.
460 Any time after installing libguestfs, run the following commands as
462 root:
463 mkdir -p /usr/local/lib/guestfs/appliance
465 libguestfs-make-fixed-appliance /usr/local/lib/guestfs/appliance
466 ls -l /usr/local/lib/guestfs/appliance
467 Now set the following environment variable before using libguestfs or
469 any virt tool:
470 export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance
472 Of course you can change the path to any directory you want. You can
474 share the appliance across machines that have the same architecture
475 (eg. all x86-64), but note that libvirt will prevent you from sharing
476 the appliance across NFS because of permissions problems (so either
477 switch to the direct backend or don't use NFS).
478 How can I speed up libguestfs builds?
480 By far the most important thing you can do is to install and properly
481 configure Squid. Note that the default configuration that ships with
482 Squid is rubbish, so configuring it is not optional.
483 A very good place to start with Squid configuration is here:
485 https://fedoraproject.org/wiki/Extras/MockTricks#Using_Squid_to_Speed_Up_Mock_package_downloads
486 Make sure Squid is running, and that the environment variables
488 $http_proxy and $ftp_proxy are pointing to it.
489 With Squid running and correctly configured, appliance builds should be
491 reduced to a few minutes.
492 How can I speed up libguestfs builds (Debian)?
494 Hilko Bengen suggests using "approx" which is a Debian archive proxy
496 (http://packages.debian.org/approx). This tool is documented on Debian
497 in the approx(8) manual page.
498
500 Note: Most of the information in this section has moved:
501 guestfs-performance(1).
502 Upload or write seem very slow.
504 In libguestfs < 1.13.16, the mount command ("guestfs_mount" in
505 guestfs(3)) enabled option "-o sync" implicitly. This causes very poor
506 write performance, and was one of the main gotchas for new libguestfs
507 users.
508 For libguestfs < 1.13.16, replace mount with "mount-options", leaving
510 the first parameter as an empty string.
511 You can also do this with more recent versions of libguestfs, but if
513 you know that you are using libguestfs ≥ 1.13.16 then it's safe to use
514 plain mount.
515 If the underlying disk is not fully allocated (eg. sparse raw or qcow2)
517 then writes can be slow because the host operating system has to do
518 costly disk allocations while you are writing. The solution is to use a
519 fully allocated format instead, ie. non-sparse raw, or qcow2 with the
520 "preallocation=metadata" option.
521 Libguestfs uses too much disk space!
523 libguestfs caches a large-ish appliance in:
524 /var/tmp/.guestfs-<UID>
526 If the environment variable "TMPDIR" is defined, then
528 "$TMPDIR/.guestfs-<UID>" is used instead.
529 It is safe to delete this directory when you are not using libguestfs.
531 virt-sparsify seems to make the image grow to the full size of the virtual
533 disk
534 If the input to virt-sparsify(1) is raw, then the output will be raw
535 sparse. Make sure you are measuring the output with a tool which
536 understands sparseness such as "du -sh". It can make a huge
537 difference:
538 $ ls -lh test1.img
540 -rw-rw-r--. 1 rjones rjones 100M Aug 8 08:08 test1.img
541 $ du -sh test1.img
542 3.6M test1.img
543 (Compare the apparent size 100M vs the actual size 3.6M)
545 If all this confuses you, use a non-sparse output format by specifying
547 the --convert option, eg:
548 virt-sparsify --convert qcow2 disk.raw disk.qcow2
550 Why doesn't virt-resize work on the disk image in-place?
552 Resizing a disk image is very tricky -- especially making sure that you
553 don't lose data or break the bootloader. The current method
554 effectively creates a new disk image and copies the data plus
555 bootloader from the old one. If something goes wrong, you can always
556 go back to the original.
557 If we were to make virt-resize work in-place then there would have to
559 be limitations: for example, you wouldn't be allowed to move existing
560 partitions (because moving data across the same disk is most likely to
561 corrupt data in the event of a power failure or crash), and LVM would
562 be very difficult to support (because of the almost arbitrary mapping
563 between LV content and underlying disk blocks).
564 Another method we have considered is to place a snapshot over the
566 original disk image, so that the original data is untouched and only
567 differences are recorded in the snapshot. You can do this today using
568 "qemu-img create" + "virt-resize", but qemu currently isn't smart
569 enough to recognize when the same block is written back to the snapshot
570 as already exists in the backing disk, so you will find that this
571 doesn't save you any space or time.
572 In summary, this is a hard problem, and what we have now mostly works
574 so we are reluctant to change it.
575 Why doesn't virt-sparsify work on the disk image in-place?
577 Eventually we plan to make virt-sparsify work on disk images in-place,
578 instead of copying the disk image. However it requires several changes
579 to both the Linux kernel and qemu which are slowly making their way
580 upstream (thanks to the tireless efforts of Paolo Bonzini). Then we
581 will have to modify virt-sparsify to support this. Finally there will
582 be some integration work required to make sure all the pieces work
583 together.
584 Even with this implemented there may be some limitations: For example,
586 it requires completely different steps (and is probably harder) to
587 sparsify a disk image that is stored on a SAN LUN, compared to one
588 which is stored in a local raw image file, so you can expect that
589 different storage and backing formats will become supported at
590 different times. Some backing filesystems / formats may never support
591 sparsification (eg. disk images stored on VFAT, old-style non-thin
592 LVs).
593
595 The API has hundreds of methods, where do I start?
596 We recommend you start by reading the API overview: "API OVERVIEW" in
597 guestfs(3).
598 Although the API overview covers the C API, it is still worth reading
600 even if you are going to use another programming language, because the
601 API is the same, just with simple logical changes to the names of the
602 calls:
603 C guestfs_ln_sf (g, target, linkname);
605 Python g.ln_sf (target, linkname);
606 OCaml g#ln_sf target linkname;
607 Perl $g->ln_sf (target, linkname);
608 Shell (guestfish) ln-sf target linkname
609 PHP guestfs_ln_sf ($g, $target, $linkname);
610 Once you're familiar with the API overview, you should look at this
612 list of starting points for other language bindings: "USING LIBGUESTFS
613 WITH OTHER PROGRAMMING LANGUAGES" in guestfs(3).
614 Can I use libguestfs in my proprietary / closed source / commercial
616 program?
617 In general, yes. However this is not legal advice - read the license
618 that comes with libguestfs, and if you have specific questions contact
619 a lawyer.
620 In the source tree the license is in the file "COPYING.LIB" (LGPLv2+
622 for the library and bindings) and "COPYING" (GPLv2+ for the standalone
623 programs).
624
626 Help, it's not working!
627 Please supply all the information in this checklist, in an email sent
628 to "libguestfs" @ "redhat.com":
629 · What are you trying to achieve?
631 · What exact commands did you run?
633 · What was the precise error / output of these commands?
635 · Enable debugging, run the commands again, and capture the complete
637 output. Do not edit the output.
638 export LIBGUESTFS_DEBUG=1
640 export LIBGUESTFS_TRACE=1
641 · Include the version of libguestfs, the operating system version,
643 and how you installed libguestfs (eg. from source, "yum install",
644 etc.)
645 · If no libguestfs program seems to work at all, run the program
647 below and paste the complete, unedited output into the email:
648 libguestfs-test-tool
650 How do I debug when using any libguestfs program or tool (eg. virt-v2v or
652 virt-df)?
653 There are two "LIBGUESTFS_*" environment variables you can set in order
654 to get more information from libguestfs.
655 "LIBGUESTFS_TRACE"
657 Set this to 1 and libguestfs will print out each command / API call
658 in a format which is similar to guestfish commands.
659 "LIBGUESTFS_DEBUG"
661 Set this to 1 in order to enable massive amounts of debug messages.
662 If you think there is some problem inside the libguestfs appliance,
663 then you should use this option.
664 To set these from the shell, do this before running the program:
666 export LIBGUESTFS_TRACE=1
668 export LIBGUESTFS_DEBUG=1
669 For csh/tcsh the equivalent commands would be:
671 setenv LIBGUESTFS_TRACE 1
673 setenv LIBGUESTFS_DEBUG 1
674 For further information, see: "ENVIRONMENT VARIABLES" in guestfs(3).
676 How do I debug when using guestfish?
678 You can use the same environment variables above. Alternatively use
679 the guestfish options -x (to trace commands) or -v (to get the full
680 debug output), or both.
681 For further information, see: guestfish(1).
683 How do I debug when using the API?
685 Call "guestfs_set_trace" in guestfs(3) to enable command traces, and/or
686 "guestfs_set_verbose" in guestfs(3) to enable debug messages.
687 For best results, call these functions as early as possible, just after
689 creating the guestfs handle if you can, and definitely before calling
690 launch.
691 How do I capture debug output and put it into my logging system?
693 Use the event API. For examples, see: "SETTING CALLBACKS TO HANDLE
694 EVENTS" in guestfs(3) and the "examples/debug-logging.c" program in the
695 libguestfs sources.
696 Digging deeper into the appliance boot process.
698 Enable debugging and then read this documentation on the appliance boot
699 process: "INTERNALS" in guestfs(3).
700 libguestfs hangs or fails during run/launch.
702 Enable debugging and look at the full output. If you cannot work out
703 what is going on, file a bug report, including the complete output of
704 libguestfs-test-tool(1).
705
707 Why don't you do everything through the FUSE / filesystem interface?
708 We offer a command called guestmount(1) which lets you mount guest
709 filesystems on the host. This is implemented as a FUSE module. Why
710 don't we just implement the whole of libguestfs using this mechanism,
711 instead of having the large and rather complicated API?
712 The reasons are twofold. Firstly, libguestfs offers API calls for
714 doing things like creating and deleting partitions and logical volumes,
715 which don't fit into a filesystem model very easily. Or rather, you
716 could fit them in: for example, creating a partition could be mapped to
717 "mkdir /fs/hda1" but then you'd have to specify some method to choose
718 the size of the partition (maybe "echo 100M > /fs/hda1/.size"), and the
719 partition type, start and end sectors etc., but once you've done that
720 the filesystem-based API starts to look more complicated than the call-
721 based API we currently have.
722 The second reason is for efficiency. FUSE itself is reasonably
724 efficient, but it does make lots of small, independent calls into the
725 FUSE module. In guestmount these have to be translated into messages
726 to the libguestfs appliance which has a big overhead (in time and round
727 trips). For example, reading a file in 64 KB chunks is inefficient
728 because each chunk would turn into a single round trip. In the
729 libguestfs API it is much more efficient to download an entire file or
730 directory through one of the streaming calls like "guestfs_download" or
731 "guestfs_tar_out".
732 Why don't you do everything through GVFS?
734 The problems are similar to the problems with FUSE.
735 GVFS is a better abstraction than POSIX/FUSE. There is an FTP backend
737 for GVFS, which is encouraging because FTP is conceptually similar to
738 the libguestfs API. However the GVFS FTP backend makes multiple
739 simultaneous connections in order to keep interactivity, which we can't
740 easily do with libguestfs.
741 Why can I write to the disk, even though I added it read-only?
743 Why does "--ro" appear to have no effect?
744 When you add a disk read-only, libguestfs places a writable overlay on
745 top of the underlying disk. Writes go into this overlay, and are
746 discarded when the handle is closed (or "guestfish" etc. exits).
747 There are two reasons for doing it this way: Firstly read-only disks
749 aren't possible in many cases (eg. IDE simply doesn't support them, so
750 you couldn't have an IDE-emulated read-only disk, although this is not
751 common in real libguestfs installations).
752 Secondly and more importantly, even if read-only disks were possible,
754 you wouldn't want them. Mounting any filesystem that has a journal,
755 even "mount -o ro", causes writes to the filesystem because the journal
756 has to be replayed and metadata updated. If the disk was truly read-
757 only, you wouldn't be able to mount a dirty filesystem.
758 To make it usable, we create the overlay as a place to temporarily
760 store these writes, and then we discard it afterwards. This ensures
761 that the underlying disk is always untouched.
762 Note also that there is a regression test for this when building
764 libguestfs (in "tests/qemu"). This is one reason why it's important
765 for packagers to run the test suite.
766 Does "--ro" make all disks read-only?
768 No! The "--ro" option only affects disks added on the command line,
769 ie. using "-a" and "-d" options.
770 In guestfish, if you use the "add" command, then disk is added read-
772 write (unless you specify the "readonly:true" flag explicitly with the
773 command).
774 Can I use "guestfish --ro" as a way to backup my virtual machines?
776 Usually this is not a good idea. The question is answered in more
777 detail in this mailing list posting:
778 https://www.redhat.com/archives/libguestfs/2010-August/msg00024.html
779 See also the next question.
781 Why can't I run fsck on a live filesystem using "guestfish --ro"?
783 This command will usually not work:
784 guestfish --ro -a /dev/vg/my_root_fs run : fsck /dev/sda
786 The reason for this is that qemu creates a snapshot over the original
788 filesystem, but it doesn't create a strict point-in-time snapshot.
789 Blocks of data on the underlying filesystem are read by qemu at
790 different times as the fsck operation progresses, with host writes in
791 between. The result is that fsck sees massive corruption (imaginary,
792 not real!) and fails.
793 What you have to do is to create a point-in-time snapshot. If it's a
795 logical volume, use an LVM2 snapshot. If the filesystem is located
796 inside something like a btrfs/ZFS file, use a btrfs/ZFS snapshot, and
797 then run the fsck on the snapshot. In practice you don't need to use
798 libguestfs for this -- just run "/sbin/fsck" directly.
799 Creating point-in-time snapshots of host devices and files is outside
801 the scope of libguestfs, although libguestfs can operate on them once
802 they are created.
803 What's the difference between guestfish and virt-rescue?
805 A lot of people are confused by the two superficially similar tools we
806 provide:
807 $ guestfish --ro -a guest.img
809 ><fs> run
810 ><fs> fsck /dev/sda1
811 $ virt-rescue --ro guest.img
813 ><rescue> /sbin/fsck /dev/sda1
814 And the related question which then arises is why you can't type in
816 full shell commands with all the --options in guestfish (but you can in
817 virt-rescue(1)).
818 guestfish(1) is a program providing structured access to the guestfs(3)
820 API. It happens to be a nice interactive shell too, but its primary
821 purpose is structured access from shell scripts. Think of it more like
822 a language binding, like Python and other bindings, but for shell. The
823 key differentiating factor of guestfish (and the libguestfs API in
824 general) is the ability to automate changes.
825 virt-rescue(1) is a free-for-all freeform way to boot the libguestfs
827 appliance and make arbitrary changes to your VM. It's not structured,
828 you can't automate it, but for making quick ad-hoc fixes to your
829 guests, it can be quite useful.
830 But, libguestfs also has a "backdoor" into the appliance allowing you
832 to send arbitrary shell commands. It's not as flexible as virt-rescue,
833 because you can't interact with the shell commands, but here it is
834 anyway:
835 ><fs> debug sh "cmd arg1 arg2 ..."
837 Note that you should not rely on this. It could be removed or changed
839 in future. If your program needs some operation, please add it to the
840 libguestfs API instead.
841 What's the deal with "guestfish -i"?
843 Why does virt-cat only work on a real VM image, but virt-df works on any
844 disk image?
845 What does "no root device found in this operating system image" mean?
846 These questions are all related at a fundamental level which may not be
847 immediately obvious.
848 At the guestfs(3) API level, a "disk image" is just a pile of
850 partitions and filesystems.
851 In contrast, when the virtual machine boots, it mounts those
853 filesystems into a consistent hierarchy such as:
854 / (/dev/sda2)
856 |
857 +-- /boot (/dev/sda1)
858 |
859 +-- /home (/dev/vg_external/Homes)
860 |
861 +-- /usr (/dev/vg_os/lv_usr)
862 |
863 +-- /var (/dev/vg_os/lv_var)
864 (or drive letters on Windows).
866 The API first of all sees the disk image at the "pile of filesystems"
868 level. But it also has a way to inspect the disk image to see if it
869 contains an operating system, and how the disks are mounted when the
870 operating system boots: "INSPECTION" in guestfs(3).
871 Users expect some tools (like virt-cat(1)) to work with VM paths:
873 virt-cat fedora.img /var/log/messages
875 How does virt-cat know that "/var" is a separate partition? The trick
877 is that virt-cat performs inspection on the disk image, and uses that
878 to translate the path correctly.
879 Some tools (including virt-cat(1), virt-edit(1), virt-ls(1)) use
881 inspection to map VM paths. Other tools, such as virt-df(1) and
882 virt-filesystems(1) operate entirely at the raw "big pile of
883 filesystems" level of the libguestfs API, and don't use inspection.
884 guestfish(1) is in an interesting middle ground. If you use the -a and
886 -m command line options, then you have to tell guestfish exactly how to
887 add disk images and where to mount partitions. This is the raw API
888 level.
889 If you use the -i option, libguestfs performs inspection and mounts the
891 filesystems for you.
892 The error "no root device found in this operating system image" is
894 related to this. It means inspection was unable to locate an operating
895 system within the disk image you gave it. You might see this from
896 programs like virt-cat if you try to run them on something which is
897 just a disk image, not a virtual machine disk image.
898 What do these "debug*" and "internal-*" functions do?
900 There are some functions which are used for debugging and internal
901 purposes which are not part of the stable API.
902 The "debug*" (or "guestfs_debug*") functions, primarily "guestfs_debug"
904 in guestfs(3) and a handful of others, are used for debugging
905 libguestfs. Although they are not part of the stable API and thus may
906 change or be removed at any time, some programs may want to call these
907 while waiting for features to be added to libguestfs.
908 The "internal-*" (or "guestfs_internal_*") functions are purely to be
910 used by libguestfs itself. There is no reason for programs to call
911 them, and programs should not try to use them. Using them will often
912 cause bad things to happen, as well as not being part of the documented
913 stable API.
914
916 Where do I send patches?
917 Please send patches to the libguestfs mailing list
918 https://www.redhat.com/mailman/listinfo/libguestfs. You don't have to
919 be subscribed, but there will be a delay until your posting is manually
920 approved.
921 Please don't use github pull requests - they will be ignored. The
923 reasons are (a) we want to discuss and dissect patches on the mailing
924 list, and (b) github pull requests turn into merge commits but we
925 prefer to have a linear history.
926 How do I propose a feature?
928 Large new features that you intend to contribute should be discussed on
929 the mailing list first
930 (https://www.redhat.com/mailman/listinfo/libguestfs). This avoids
931 disappointment and wasted work if we don't think the feature would fit
932 into the libguestfs project.
933 If you want to suggest a useful feature but don't want to write the
935 code, you can file a bug (see "GETTING HELP AND REPORTING BUGS") with
936 "RFE: " at the beginning of the Summary line.
937 Who can commit to libguestfs git?
939 About 5 people have commit access to github. Patches should be posted
940 on the list first and ACKed. The policy for ACKing and pushing patches
941 is outlined here:
942 https://www.redhat.com/archives/libguestfs/2012-January/msg00023.html
944 Can I fork libguestfs?
946 Of course you can. Git makes it easy to fork libguestfs. Github makes
947 it even easier. It's nice if you tell us on the mailing list about
948 forks and the reasons for them.
949
951 guestfish(1), guestfs(3), http://libguestfs.org/.
952
954 Richard W.M. Jones ("rjones at redhat dot com")
955
957 Copyright (C) 2012-2013 Red Hat Inc.
958
960 This library is free software; you can redistribute it and/or modify it
961 under the terms of the GNU Lesser General Public License as published
962 by the Free Software Foundation; either version 2 of the License, or
963 (at your option) any later version.
964 This library is distributed in the hope that it will be useful, but
966 WITHOUT ANY WARRANTY; without even the implied warranty of
967 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
968 Lesser General Public License for more details.
969 You should have received a copy of the GNU Lesser General Public
971 License along with this library; if not, write to the Free Software
972 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
973 02110-1301 USA
974
976 To get a list of bugs against libguestfs, use this link:
977 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
978 To report a new bug against libguestfs, use this link:
980 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
981 When reporting a bug, please supply:
983 · The version of libguestfs.
985 · Where you got libguestfs (eg. which Linux distro, compiled from
987 source, etc)
988 · Describe the bug accurately and give a way to reproduce it.
990 · Run libguestfs-test-tool(1) and paste the complete, unedited output
992 into the bug report.
993libguestfs-1.20.11 2013-08-27 guestfs-faq(1)