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 guestfs-security(1)). Libguestfs isolates your host
49 kernel from guests, is more flexible, scriptable, supports LVM,
50 doesn't require root, is isolated from other processes, and cleans
51 up after itself. Libguestfs is more than just file access because
52 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 or nbdkit together to access block
65 devices over 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 message was changed in libguestfs 1.21.18 to something more
128 explanatory.]
129 This error indicates that qemu failed or the host kernel could not
131 boot. To get further information about the failure, you have to run:
132 libguestfs-test-tool
134 If, after using this, you still don’t understand the failure, contact
136 us (see previous section).
137 libguestfs: error: cannot find any suitable libguestfs supermin, fixed or
139 old-style appliance on LIBGUESTFS_PATH
140 febootstrap-supermin-helper: ext2: parent directory not found
141 supermin-helper: ext2: parent directory not found
142 [This issue is fixed permanently in libguestfs ≥ 1.26.]
143 If you see any of these errors on Debian/Ubuntu, you need to run the
145 following command:
146 sudo update-guestfs-appliance
148 "Permission denied" when running libguestfs as root
150 You get a permission denied error when opening a disk image, even
151 though you are running libguestfs as root.
152 This is caused by libvirt, and so only happens when using the libvirt
154 backend. When run as root, libvirt decides to run the qemu appliance
155 as user "qemu.qemu". Unfortunately this usually means that qemu cannot
156 open disk images, especially if those disk images are owned by root, or
157 are present in directories which require root access.
158 There is a bug open against libvirt to fix this:
160 https://bugzilla.redhat.com/show_bug.cgi?id=1045069
161 You can work around this by one of the following methods:
163 • Switch to the direct backend:
165 export LIBGUESTFS_BACKEND=direct
167 • Don’t run libguestfs as root.
169 • Chmod the disk image and any parent directories so that the qemu
171 user can access them.
172 • (Nasty) Edit /etc/libvirt/qemu.conf and change the "user" setting.
174 execl: /init: Permission denied
176 Note: If this error happens when you are using a distro package of
177 libguestfs (eg. from Fedora, Debian, etc) then file a bug against the
178 distro. This is not an error which normal users should ever see if the
179 distro package has been prepared correctly.
180 This error happens during the supermin boot phase of starting the
182 appliance:
183 supermin: mounting new root on /root
185 supermin: chroot
186 execl: /init: Permission denied
187 supermin: debug: listing directory /
188 [...followed by a lot of debug output...]
189 This is a complicated bug related to supermin(1) appliances. The
191 appliance is constructed by copying files like /bin/bash and many
192 libraries from the host. The file "hostfiles" lists the files that
193 should be copied from the host into the appliance. If some files don't
194 exist on the host then they are missed out, but if these files are
195 needed in order to (eg) run /bin/bash then you'll see the above error.
196 Diagnosing the problem involves studying the libraries needed by
198 /bin/bash, ie:
199 ldd /bin/bash
201 comparing that with "hostfiles", with the files actually available in
203 the host filesystem, and with the debug output printed in the error
204 message. Once you've worked out which file is missing, install that
205 file using your package manager and try again.
206 You should also check that files like /init and /bin/bash (in the
208 appliance) are executable. The debug output shows file modes.
209
211 Where can I get the latest binaries for ...?
212 Fedora ≥ 11
213 Use:
214 yum install '*guestf*'
216 For the latest builds, see:
218 http://koji.fedoraproject.org/koji/packageinfo?packageID=8391
219 Red Hat Enterprise Linux
221 RHEL 6
222 RHEL 7
223 It is part of the default install. On RHEL 6 and 7 (only) you
224 have to install "libguestfs-winsupport" to get Windows guest
225 support.
226 Debian and Ubuntu
228 For libguestfs < 1.26, after installing libguestfs you need to do:
229 sudo update-guestfs-appliance
231 (This script has been removed on Debian/Ubuntu with libguestfs ≥
233 1.26 and instead the appliance is built on demand.)
234 On Ubuntu only:
236 sudo chmod 0644 /boot/vmlinuz*
238 You may need to add yourself to the "kvm" group:
240 sudo usermod -a -G kvm yourlogin
242 Debian Squeeze (6)
244 Hilko Bengen has built libguestfs in squeeze backports:
245 http://packages.debian.org/search?keywords=guestfs&searchon=names§ion=all&suite=squeeze-backports
246 Debian Wheezy and later (7+)
248 Hilko Bengen supports libguestfs on Debian. Official Debian
249 packages are available:
250 http://packages.debian.org/search?keywords=libguestfs
251 Ubuntu
253 We don’t have a full time Ubuntu maintainer, and the packages
254 supplied by Canonical (which are outside our control) are
255 sometimes broken.
256 Canonical decided to change the permissions on the kernel so
258 that it's not readable except by root. This is completely
259 stupid, but they won't change it
260 (https://bugs.launchpad.net/ubuntu/+source/linux/+bug/759725).
261 So every user should do this:
262 sudo chmod 0644 /boot/vmlinuz*
264 Ubuntu 12.04
266 libguestfs in this version of Ubuntu works, but you need to
267 update febootstrap and seabios to the latest versions.
268 You need febootstrap ≥ 3.14-2 from:
270 http://packages.ubuntu.com/precise/febootstrap
271 After installing or updating febootstrap, rebuild the
273 appliance:
274 sudo update-guestfs-appliance
276 You need seabios ≥ 0.6.2-0ubuntu2.1 or ≥ 0.6.2-0ubuntu3
278 from: http://packages.ubuntu.com/precise-updates/seabios or
279 http://packages.ubuntu.com/quantal/seabios
280 Also you need to do (see above):
282 sudo chmod 0644 /boot/vmlinuz*
284 Gentoo
286 Libguestfs was added to Gentoo in 2012-07 by Andreis Vinogradovs
287 (libguestfs) and Maxim Koltsov (mainly hivex). Do:
288 emerge libguestfs
290 Mageia
292 Libguestfs was added to Mageia in 2013-08. Do:
293 urpmi libguestfs
295 SuSE
297 Libguestfs was added to SuSE in 2012 by Olaf Hering.
298 ArchLinux
300 Libguestfs was added to the AUR in 2010.
301 Other Linux distro
303 Compile from source (next section).
304 Other non-Linux distro
306 You'll have to compile from source, and port it.
307 How can I compile and install libguestfs from source?
309 You can compile libguestfs from git or a source tarball. Read the
310 README file before starting.
311 Git: https://github.com/libguestfs/libguestfs Source tarballs:
313 http://libguestfs.org/download
314 Don’t run "make install"! Use the "./run" script instead (see README).
316 How can I compile and install libguestfs if my distro doesn't have new
318 enough qemu/supermin/kernel?
319 Libguestfs needs supermin 5. If supermin 5 hasn't been ported to your
320 distro, then see the question below.
321 First compile qemu, supermin and/or the kernel from source. You do not
323 need to "make install" them.
324 In the libguestfs source directory, create two files. "localconfigure"
326 should contain:
327 source localenv
329 #export PATH=/tmp/qemu/x86_64-softmmu:$PATH
330 ./autogen.sh --prefix /usr "$@"
331 Make "localconfigure" executable.
333 "localenv" should contain:
335 #export SUPERMIN=/tmp/supermin/src/supermin
337 #export LIBGUESTFS_HV=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64
338 #export SUPERMIN_KERNEL=/tmp/linux/arch/x86/boot/bzImage
339 #export SUPERMIN_KERNEL_VERSION=4.XX.0
340 #export SUPERMIN_MODULES=/tmp/lib/modules/4.XX.0
341 Uncomment and adjust these lines as required to use the alternate
343 programs you have compiled.
344 Use "./localconfigure" instead of "./configure", but otherwise you
346 compile libguestfs as usual.
347 Don’t run "make install"! Use the "./run" script instead (see README).
349 How can I compile and install libguestfs without supermin?
351 If supermin 5 supports your distro, but you don’t happen to have a new
352 enough supermin installed, then see the previous question.
353 If supermin 5 doesn't support your distro at all, you will need to use
355 the "fixed appliance method" where you use a pre-compiled binary
356 appliance. To build libguestfs without supermin, you need to pass
357 "--disable-appliance --disable-daemon" to either ./autogen.sh or
358 ./configure (depending whether you are building respectively from git
359 or from tarballs). Then, when using libguestfs, you must set the
360 "LIBGUESTFS_PATH" environment variable to the directory of a pre-
361 compiled appliance, as also described in "FIXED APPLIANCE" in
362 guestfs-internals(1).
363 For pre-compiled appliances, see also:
365 http://libguestfs.org/download/binaries/appliance/.
366 Patches to port supermin to more Linux distros are welcome.
368 How can I add support for sVirt?
370 Note for Fedora/RHEL users: This configuration is the default starting
371 with Fedora 18 and RHEL 7. If you find any problems, please let us
372 know or file a bug.
373 SVirt provides a hardened appliance using SELinux, making it very hard
375 for a rogue disk image to "escape" from the confinement of libguestfs
376 and damage the host (it's fair to say that even in standard libguestfs
377 this would be hard, but sVirt provides an extra layer of protection for
378 the host and more importantly protects virtual machines on the same
379 host from each other).
380 Currently to enable sVirt you will need libvirt ≥ 0.10.2 (1.0 or later
382 preferred), libguestfs ≥ 1.20, and the SELinux policies from recent
383 Fedora. If you are not running Fedora 18+, you will need to make
384 changes to your SELinux policy - contact us on the mailing list.
385 Once you have the requirements, do:
387 ./configure --with-default-backend=libvirt # libguestfs >= 1.22
389 ./configure --with-default-attach-method=libvirt # libguestfs <= 1.20
390 make
391 Set SELinux to Enforcing mode, and sVirt should be used automatically.
393 All, or almost all, features of libguestfs should work under sVirt.
395 There is one known shortcoming: virt-rescue(1) will not use libvirt
396 (hence sVirt), but falls back to direct launch of qemu. So you won't
397 currently get the benefit of sVirt protection when using virt-rescue.
398 You can check if sVirt is being used by enabling libvirtd logging (see
400 /etc/libvirt/libvirtd.log), killing and restarting libvirtd, and
401 checking the log files for "Setting SELinux context on ..." messages.
402 In theory sVirt should support AppArmor, but we have not tried it. It
404 will almost certainly require patching libvirt and writing an AppArmor
405 policy.
406 Libguestfs has a really long list of dependencies!
408 The base library doesn't depend on very much, but there are three
409 causes of the long list of other dependencies:
410 1. Libguestfs has to be able to read and edit many different disk
412 formats. For example, XFS support requires XFS tools.
413 2. There are language bindings for many different languages, all
415 requiring their own development tools. All language bindings
416 (except C) are optional.
417 3. There are some optional library features which can be disabled.
419 Since libguestfs ≥ 1.26 it is possible to split up the appliance
421 dependencies (item 1 in the list above) and thus have (eg)
422 "libguestfs-xfs" as a separate subpackage for processing XFS disk
423 images. We encourage downstream packagers to start splitting the base
424 libguestfs package into smaller subpackages.
425 Errors during launch on Fedora ≥ 18, RHEL ≥ 7
427 In Fedora ≥ 18 and RHEL ≥ 7, libguestfs uses libvirt to manage the
428 appliance. Previously (and upstream) libguestfs runs qemu directly:
429 ┌──────────────────────────────────┐
431 │ libguestfs │
432 ├────────────────┬─────────────────┤
433 │ direct backend │ libvirt backend │
434 └────────────────┴─────────────────┘
435 ↓ ↓
436 ┌───────┐ ┌──────────┐
437 │ qemu │ │ libvirtd │
438 └───────┘ └──────────┘
439 ↓
440 ┌───────┐
441 │ qemu │
442 └───────┘
443 upstream Fedora 18+
445 non-Fedora RHEL 7+
446 non-RHEL
447 The libvirt backend is more sophisticated, supporting SELinux/sVirt
449 (see above), hotplugging and more. It is, however, more complex and so
450 less robust.
451 If you have permissions problems using the libvirt backend, you can
453 switch to the direct backend by setting this environment variable:
454 export LIBGUESTFS_BACKEND=direct
456 before running any libguestfs program or virt tool.
458 How can I switch to a fixed / prebuilt appliance?
460 This may improve the stability and performance of libguestfs on Fedora
461 and RHEL.
462 Any time after installing libguestfs, run the following commands as
464 root:
465 mkdir -p /usr/local/lib/guestfs/appliance
467 libguestfs-make-fixed-appliance /usr/local/lib/guestfs/appliance
468 ls -l /usr/local/lib/guestfs/appliance
469 Now set the following environment variable before using libguestfs or
471 any virt tool:
472 export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance
474 Of course you can change the path to any directory you want. You can
476 share the appliance across machines that have the same architecture
477 (eg. all x86-64), but note that libvirt will prevent you from sharing
478 the appliance across NFS because of permissions problems (so either
479 switch to the direct backend or don't use NFS).
480 How can I speed up libguestfs builds?
482 By far the most important thing you can do is to install and properly
483 configure Squid. Note that the default configuration that ships with
484 Squid is rubbish, so configuring it is not optional.
485 A very good place to start with Squid configuration is here:
487 https://fedoraproject.org/wiki/Extras/MockTricks#Using_Squid_to_Speed_Up_Mock_package_downloads
488 Make sure Squid is running, and that the environment variables
490 $http_proxy and $ftp_proxy are pointing to it.
491 With Squid running and correctly configured, appliance builds should be
493 reduced to a few minutes.
494 How can I speed up libguestfs builds (Debian)?
496 Hilko Bengen suggests using "approx" which is a Debian archive proxy
498 (http://packages.debian.org/approx). This tool is documented on Debian
499 in the approx(8) manual page.
500
502 Note: Most of the information in this section has moved:
503 guestfs-performance(1).
504 Upload or write seem very slow.
506 If the underlying disk is not fully allocated (eg. sparse raw or qcow2)
507 then writes can be slow because the host operating system has to do
508 costly disk allocations while you are writing. The solution is to use a
509 fully allocated format instead, ie. non-sparse raw, or qcow2 with the
510 "preallocation=metadata" option.
511 Libguestfs uses too much disk space!
513 libguestfs caches a large-ish appliance in:
514 /var/tmp/.guestfs-<UID>
516 If the environment variable "TMPDIR" is defined, then
518 $TMPDIR/.guestfs-<UID> is used instead.
519 It is safe to delete this directory when you are not using libguestfs.
521 virt-sparsify seems to make the image grow to the full size of the virtual
523 disk
524 If the input to virt-sparsify(1) is raw, then the output will be raw
525 sparse. Make sure you are measuring the output with a tool which
526 understands sparseness such as "du -sh". It can make a huge
527 difference:
528 $ ls -lh test1.img
530 -rw-rw-r--. 1 rjones rjones 100M Aug 8 08:08 test1.img
531 $ du -sh test1.img
532 3.6M test1.img
533 (Compare the apparent size 100M vs the actual size 3.6M)
535 If all this confuses you, use a non-sparse output format by specifying
537 the --convert option, eg:
538 virt-sparsify --convert qcow2 disk.raw disk.qcow2
540 Why doesn't virt-resize work on the disk image in-place?
542 Resizing a disk image is very tricky -- especially making sure that you
543 don't lose data or break the bootloader. The current method
544 effectively creates a new disk image and copies the data plus
545 bootloader from the old one. If something goes wrong, you can always
546 go back to the original.
547 If we were to make virt-resize work in-place then there would have to
549 be limitations: for example, you wouldn't be allowed to move existing
550 partitions (because moving data across the same disk is most likely to
551 corrupt data in the event of a power failure or crash), and LVM would
552 be very difficult to support (because of the almost arbitrary mapping
553 between LV content and underlying disk blocks).
554 Another method we have considered is to place a snapshot over the
556 original disk image, so that the original data is untouched and only
557 differences are recorded in the snapshot. You can do this today using
558 "qemu-img create" + "virt-resize", but qemu currently isn't smart
559 enough to recognize when the same block is written back to the snapshot
560 as already exists in the backing disk, so you will find that this
561 doesn't save you any space or time.
562 In summary, this is a hard problem, and what we have now mostly works
564 so we are reluctant to change it.
565 Why doesn't virt-sparsify work on the disk image in-place?
567 In libguestfs ≥ 1.26, virt-sparsify can now work on disk images in
568 place. Use:
569 virt-sparsify --in-place disk.img
571 But first you should read "IN-PLACE SPARSIFICATION" in
573 virt-sparsify(1).
574
576 Remote libvirt guests cannot be opened.
577 Opening remote libvirt guests is not supported at this time. For
578 example this won't work:
579 guestfish -c qemu://remote/system -d Guest
581 To open remote disks you have to export them somehow, then connect to
583 the export. For example if you decided to use NBD:
584 remote$ qemu-nbd -t -p 10809 guest.img
586 local$ guestfish -a nbd://remote:10809 -i
587 Other possibilities include ssh (if qemu is recent enough), NFS or
589 iSCSI. See "REMOTE STORAGE" in guestfs(3).
590 How can I open this strange disk source?
592 You have a disk image located inside another system that requires
593 access via a library / HTTP / REST / proprietary API, or is compressed
594 or archived in some way. (One example would be remote access to
595 OpenStack glance images without actually downloading them.)
596 We have a sister project called nbdkit
598 (https://github.com/libguestfs/nbdkit). This project lets you turn any
599 disk source into an NBD server. Libguestfs can access NBD servers
600 directly, eg:
601 guestfish -a nbd://remote
603 nbdkit is liberally licensed, so you can link it to or include it in
605 proprietary libraries and code. It also has a simple, stable plugin
606 API so you can easily write plugins against the API which will continue
607 to work in future.
608 Error opening VMDK disks: "uses a vmdk feature which is not supported by
610 this qemu version: VMDK version 3"
611 Qemu (and hence libguestfs) only supports certain VMDK disk images.
612 Others won't work, giving this or similar errors.
613 Ideally someone would fix qemu to support the latest VMDK features, but
615 in the meantime you have three options:
616 1. If the guest is hosted on a live, reachable ESX server, then locate
618 and download the disk image called somename-flat.vmdk. Despite the
619 name, this is a raw disk image, and can be opened by anything.
620 If you have a recent enough version of qemu and libguestfs, then
622 you may be able to access this disk image remotely using either
623 HTTPS or ssh. See "REMOTE STORAGE" in guestfs(3).
624 2. Use VMware’s proprietary vdiskmanager tool to convert the image to
626 raw format.
627 3. Use nbdkit with the proprietary VDDK plugin to live export the disk
629 image as an NBD source. This should allow you to read and write
630 the VMDK file.
631 UFS disks (as used by BSD) cannot be opened.
633 The UFS filesystem format has many variants, and these are not self-
634 identifying. The Linux kernel has to be told which variant of UFS it
635 has to use, which libguestfs cannot know.
636 You have to pass the right "ufstype" mount option when mounting these
638 filesystems.
639 See https://www.kernel.org/doc/Documentation/filesystems/ufs.txt
641 Windows ReFS
643 Windows ReFS is Microsoft’s ZFS/Btrfs copy. This filesystem has not
644 yet been reverse engineered and implemented in the Linux kernel, and
645 therefore libguestfs doesn't support it. At the moment it seems to be
646 very rare "in the wild".
647 Non-ASCII characters don’t appear on VFAT filesystems.
649 Typical symptoms of this problem:
650 • You get an error when you create a file where the filename contains
652 non-ASCII characters, particularly non 8-bit characters from Asian
653 languages (Chinese, Japanese, etc). The filesystem is VFAT.
654 • When you list a directory from a VFAT filesystem, filenames appear
656 as question marks.
657 This is a design flaw of the GNU/Linux system.
659 VFAT stores long filenames as UTF-16 characters. When opening or
661 returning filenames, the Linux kernel has to translate these to some
662 form of 8 bit string. UTF-8 would be the obvious choice, except for
663 Linux users who persist in using non-UTF-8 locales (the user’s locale
664 is not known to the kernel because it’s a function of libc).
665 Therefore you have to tell the kernel what translation you want done
667 when you mount the filesystem. The two methods are the "iocharset"
668 parameter (which is not relevant to libguestfs) and the "utf8" flag.
669 So to use a VFAT filesystem you must add the "utf8" flag when mounting.
671 From guestfish, use:
672 ><fs> mount-options utf8 /dev/sda1 /
674 or on the guestfish command line:
676 guestfish [...] -m /dev/sda1:/:utf8
678 or from the API:
680 guestfs_mount_options (g, "utf8", "/dev/sda1", "/");
682 The kernel will then translate filenames to and from UTF-8 strings.
684 We considered adding this mount option transparently, but unfortunately
686 there are several problems with doing that:
687 • On some Linux systems, the "utf8" mount option doesn't work. We
689 don't precisely understand what systems or why, but this was
690 reliably reported by one user.
691 • It would prevent you from using the "iocharset" parameter because
693 it is incompatible with "utf8". It is probably not a good idea to
694 use this parameter, but we don't want to prevent it.
695 Non-ASCII characters appear as underscore (_) on ISO9660 filesystems.
697 The filesystem was not prepared correctly with mkisofs or genisoimage.
698 Make sure the filesystem was created using Joliet and/or Rock Ridge
699 extensions. libguestfs does not require any special mount options to
700 handle the filesystem.
701 Cannot open Windows guests which use NTFS.
703 You see errors like:
704 mount: unknown filesystem type 'ntfs'
706 On Red Hat Enterprise Linux or CentOS < 7.2, you have to install the
708 libguestfs-winsupport package. In RHEL ≥ 7.2, "libguestfs-winsupport"
709 is part of the base RHEL distribution, but see the next question.
710 "mount: unsupported filesystem type" with NTFS in RHEL ≥ 7.2
712 In RHEL 7.2 we were able to add "libguestfs-winsupport" to the base
713 RHEL distribution, but we had to disable the ability to use it for
714 opening and editing filesystems. It is only supported when used with
715 virt-v2v(1). If you try to use guestfish(1) or guestmount(1) or some
716 other programs on an NTFS filesystem, you will see the error:
717 mount: unsupported filesystem type
719 This is not a supported configuration, and it will not be made to work
721 in RHEL. Don't bother to open a bug about it, as it will be
722 immediately "CLOSED -> WONTFIX".
723 You may compile your own libguestfs removing this restriction, but that
725 won't be endorsed or supported by Red Hat.
726 Cannot open or inspect RHEL 7 guests.
728 Cannot open Linux guests which use XFS.
729 RHEL 7 guests, and any other guests that use XFS, can be opened by
730 libguestfs, but you have to install the "libguestfs-xfs" package.
731
733 The API has hundreds of methods, where do I start?
734 We recommend you start by reading the API overview: "API OVERVIEW" in
735 guestfs(3).
736 Although the API overview covers the C API, it is still worth reading
738 even if you are going to use another programming language, because the
739 API is the same, just with simple logical changes to the names of the
740 calls:
741 C guestfs_ln_sf (g, target, linkname);
743 Python g.ln_sf (target, linkname);
744 OCaml g#ln_sf target linkname;
745 Perl $g->ln_sf (target, linkname);
746 Shell (guestfish) ln-sf target linkname
747 PHP guestfs_ln_sf ($g, $target, $linkname);
748 Once you're familiar with the API overview, you should look at this
750 list of starting points for other language bindings: "USING LIBGUESTFS
751 WITH OTHER PROGRAMMING LANGUAGES" in guestfs(3).
752 Can I use libguestfs in my proprietary / closed source / commercial
754 program?
755 In general, yes. However this is not legal advice - read the license
756 that comes with libguestfs, and if you have specific questions contact
757 a lawyer.
758 In the source tree the license is in the file "COPYING.LIB" (LGPLv2+
760 for the library and bindings) and "COPYING" (GPLv2+ for the standalone
761 programs).
762
764 Help, it’s not working!
765 If no libguestfs program seems to work at all, run the program below
766 and paste the complete, unedited output into an email to "libguestfs" @
767 "redhat.com":
768 libguestfs-test-tool
770 If a particular operation fails, supply all the information in this
772 checklist, in an email to "libguestfs" @ "redhat.com":
773 1. What are you trying to do?
775 2. What exact command(s) did you run?
777 3. What was the precise error or output of these commands?
779 4. Enable debugging, run the commands again, and capture the complete
781 output. Do not edit the output.
782 export LIBGUESTFS_DEBUG=1
784 export LIBGUESTFS_TRACE=1
785 5. Include the version of libguestfs, the operating system version,
787 and how you installed libguestfs (eg. from source, "yum install",
788 etc.)
789 How do I debug when using any libguestfs program or tool (eg. virt-
791 customize or virt-df)?
792 There are two "LIBGUESTFS_*" environment variables you can set in order
793 to get more information from libguestfs.
794 "LIBGUESTFS_TRACE"
796 Set this to 1 and libguestfs will print out each command / API call
797 in a format which is similar to guestfish commands.
798 "LIBGUESTFS_DEBUG"
800 Set this to 1 in order to enable massive amounts of debug messages.
801 If you think there is some problem inside the libguestfs appliance,
802 then you should use this option.
803 To set these from the shell, do this before running the program:
805 export LIBGUESTFS_TRACE=1
807 export LIBGUESTFS_DEBUG=1
808 For csh/tcsh the equivalent commands would be:
810 setenv LIBGUESTFS_TRACE 1
812 setenv LIBGUESTFS_DEBUG 1
813 For further information, see: "ENVIRONMENT VARIABLES" in guestfs(3).
815 How do I debug when using guestfish?
817 You can use the same environment variables above. Alternatively use
818 the guestfish options -x (to trace commands) or -v (to get the full
819 debug output), or both.
820 For further information, see: guestfish(1).
822 How do I debug when using the API?
824 Call "guestfs_set_trace" in guestfs(3) to enable command traces, and/or
825 "guestfs_set_verbose" in guestfs(3) to enable debug messages.
826 For best results, call these functions as early as possible, just after
828 creating the guestfs handle if you can, and definitely before calling
829 launch.
830 How do I capture debug output and put it into my logging system?
832 Use the event API. For examples, see: "SETTING CALLBACKS TO HANDLE
833 EVENTS" in guestfs(3) and the examples/debug-logging.c program in the
834 libguestfs sources.
835 Digging deeper into the appliance boot process.
837 Enable debugging and then read this documentation on the appliance boot
838 process: guestfs-internals(1).
839 libguestfs hangs or fails during run/launch.
841 Enable debugging and look at the full output. If you cannot work out
842 what is going on, file a bug report, including the complete output of
843 libguestfs-test-tool(1).
844 Debugging libvirt
846 If you are using the libvirt backend, and libvirt is failing, then you
847 can enable debugging by editing /etc/libvirt/libvirtd.conf.
848 If you are running as non-root, then you have to edit a different file.
850 Create ~/.config/libvirt/libvirtd.conf containing:
851 log_level=1
853 log_outputs="1:file:/tmp/libvirtd.log"
854 Kill any session (non-root) libvirtd that is running, and next time you
856 run the libguestfs command, you should see a large amount of useful
857 debugging information from libvirtd in /tmp/libvirtd.log
858 Broken kernel, or trying a different kernel.
860 You can choose a different kernel for the appliance by setting some
861 supermin environment variables:
862 export SUPERMIN_KERNEL_VERSION=4.8.0-1.fc25.x86_64
864 export SUPERMIN_KERNEL=/boot/vmlinuz-$SUPERMIN_KERNEL_VERSION
865 export SUPERMIN_MODULES=/lib/modules/$SUPERMIN_KERNEL_VERSION
866 rm -rf /var/tmp/.guestfs-*
867 libguestfs-test-tool
868 Broken qemu, or trying a different qemu.
870 You can choose a different qemu by setting the hypervisor environment
871 variable:
872 export LIBGUESTFS_HV=/path/to/qemu-system-x86_64
874 libguestfs-test-tool
875
877 See also guestfs-internals(1).
878 Why don’t you do everything through the FUSE / filesystem interface?
880 We offer a command called guestmount(1) which lets you mount guest
881 filesystems on the host. This is implemented as a FUSE module. Why
882 don't we just implement the whole of libguestfs using this mechanism,
883 instead of having the large and rather complicated API?
884 The reasons are twofold. Firstly, libguestfs offers API calls for
886 doing things like creating and deleting partitions and logical volumes,
887 which don't fit into a filesystem model very easily. Or rather, you
888 could fit them in: for example, creating a partition could be mapped to
889 "mkdir /fs/hda1" but then you'd have to specify some method to choose
890 the size of the partition (maybe "echo 100M > /fs/hda1/.size"), and the
891 partition type, start and end sectors etc., but once you've done that
892 the filesystem-based API starts to look more complicated than the call-
893 based API we currently have.
894 The second reason is for efficiency. FUSE itself is reasonably
896 efficient, but it does make lots of small, independent calls into the
897 FUSE module. In guestmount these have to be translated into messages
898 to the libguestfs appliance which has a big overhead (in time and round
899 trips). For example, reading a file in 64 KB chunks is inefficient
900 because each chunk would turn into a single round trip. In the
901 libguestfs API it is much more efficient to download an entire file or
902 directory through one of the streaming calls like "guestfs_download" or
903 "guestfs_tar_out".
904 Why don’t you do everything through GVFS?
906 The problems are similar to the problems with FUSE.
907 GVFS is a better abstraction than POSIX/FUSE. There is an FTP backend
909 for GVFS, which is encouraging because FTP is conceptually similar to
910 the libguestfs API. However the GVFS FTP backend makes multiple
911 simultaneous connections in order to keep interactivity, which we can't
912 easily do with libguestfs.
913 Why can I write to the disk, even though I added it read-only?
915 Why does "--ro" appear to have no effect?
916 When you add a disk read-only, libguestfs places a writable overlay on
917 top of the underlying disk. Writes go into this overlay, and are
918 discarded when the handle is closed (or "guestfish" etc. exits).
919 There are two reasons for doing it this way: Firstly read-only disks
921 aren't possible in many cases (eg. IDE simply doesn't support them, so
922 you couldn't have an IDE-emulated read-only disk, although this is not
923 common in real libguestfs installations).
924 Secondly and more importantly, even if read-only disks were possible,
926 you wouldn't want them. Mounting any filesystem that has a journal,
927 even "mount -o ro", causes writes to the filesystem because the journal
928 has to be replayed and metadata updated. If the disk was truly read-
929 only, you wouldn't be able to mount a dirty filesystem.
930 To make it usable, we create the overlay as a place to temporarily
932 store these writes, and then we discard it afterwards. This ensures
933 that the underlying disk is always untouched.
934 Note also that there is a regression test for this when building
936 libguestfs (in "tests/qemu"). This is one reason why it’s important
937 for packagers to run the test suite.
938 Does "--ro" make all disks read-only?
940 No! The "--ro" option only affects disks added on the command line,
941 ie. using "-a" and "-d" options.
942 In guestfish, if you use the "add" command, then disk is added read-
944 write (unless you specify the "readonly:true" flag explicitly with the
945 command).
946 Can I use "guestfish --ro" as a way to backup my virtual machines?
948 Usually this is not a good idea. The question is answered in more
949 detail in this mailing list posting:
950 https://www.redhat.com/archives/libguestfs/2010-August/msg00024.html
951 See also the next question.
953 Why can’t I run fsck on a live filesystem using "guestfish --ro"?
955 This command will usually not work:
956 guestfish --ro -a /dev/vg/my_root_fs run : fsck /dev/sda
958 The reason for this is that qemu creates a snapshot over the original
960 filesystem, but it doesn't create a strict point-in-time snapshot.
961 Blocks of data on the underlying filesystem are read by qemu at
962 different times as the fsck operation progresses, with host writes in
963 between. The result is that fsck sees massive corruption (imaginary,
964 not real!) and fails.
965 What you have to do is to create a point-in-time snapshot. If it’s a
967 logical volume, use an LVM2 snapshot. If the filesystem is located
968 inside something like a btrfs/ZFS file, use a btrfs/ZFS snapshot, and
969 then run the fsck on the snapshot. In practice you don't need to use
970 libguestfs for this -- just run /sbin/fsck directly.
971 Creating point-in-time snapshots of host devices and files is outside
973 the scope of libguestfs, although libguestfs can operate on them once
974 they are created.
975 What’s the difference between guestfish and virt-rescue?
977 A lot of people are confused by the two superficially similar tools we
978 provide:
979 $ guestfish --ro -a guest.img
981 ><fs> run
982 ><fs> fsck /dev/sda1
983 $ virt-rescue --ro guest.img
985 ><rescue> /sbin/fsck /dev/sda1
986 And the related question which then arises is why you can’t type in
988 full shell commands with all the --options in guestfish (but you can in
989 virt-rescue(1)).
990 guestfish(1) is a program providing structured access to the guestfs(3)
992 API. It happens to be a nice interactive shell too, but its primary
993 purpose is structured access from shell scripts. Think of it more like
994 a language binding, like Python and other bindings, but for shell. The
995 key differentiating factor of guestfish (and the libguestfs API in
996 general) is the ability to automate changes.
997 virt-rescue(1) is a free-for-all freeform way to boot the libguestfs
999 appliance and make arbitrary changes to your VM. It’s not structured,
1000 you can't automate it, but for making quick ad-hoc fixes to your
1001 guests, it can be quite useful.
1002 But, libguestfs also has a "backdoor" into the appliance allowing you
1004 to send arbitrary shell commands. It’s not as flexible as virt-rescue,
1005 because you can't interact with the shell commands, but here it is
1006 anyway:
1007 ><fs> debug sh "cmd arg1 arg2 ..."
1009 Note that you should not rely on this. It could be removed or changed
1011 in future. If your program needs some operation, please add it to the
1012 libguestfs API instead.
1013 What’s the deal with "guestfish -i"?
1015 Why does virt-cat only work on a real VM image, but virt-df works on any
1016 disk image?
1017 What does "no root device found in this operating system image" mean?
1018 These questions are all related at a fundamental level which may not be
1019 immediately obvious.
1020 At the guestfs(3) API level, a "disk image" is just a pile of
1022 partitions and filesystems.
1023 In contrast, when the virtual machine boots, it mounts those
1025 filesystems into a consistent hierarchy such as:
1026 / (/dev/sda2)
1028 │
1029 ├── /boot (/dev/sda1)
1030 │
1031 ├── /home (/dev/vg_external/Homes)
1032 │
1033 ├── /usr (/dev/vg_os/lv_usr)
1034 │
1035 └── /var (/dev/vg_os/lv_var)
1036 (or drive letters on Windows).
1038 The API first of all sees the disk image at the "pile of filesystems"
1040 level. But it also has a way to inspect the disk image to see if it
1041 contains an operating system, and how the disks are mounted when the
1042 operating system boots: "INSPECTION" in guestfs(3).
1043 Users expect some tools (like virt-cat(1)) to work with VM paths:
1045 virt-cat fedora.img /var/log/messages
1047 How does virt-cat know that /var is a separate partition? The trick is
1049 that virt-cat performs inspection on the disk image, and uses that to
1050 translate the path correctly.
1051 Some tools (including virt-cat(1), virt-edit(1), virt-ls(1)) use
1053 inspection to map VM paths. Other tools, such as virt-df(1) and
1054 virt-filesystems(1) operate entirely at the raw "big pile of
1055 filesystems" level of the libguestfs API, and don't use inspection.
1056 guestfish(1) is in an interesting middle ground. If you use the -a and
1058 -m command line options, then you have to tell guestfish exactly how to
1059 add disk images and where to mount partitions. This is the raw API
1060 level.
1061 If you use the -i option, libguestfs performs inspection and mounts the
1063 filesystems for you.
1064 The error "no root device found in this operating system image" is
1066 related to this. It means inspection was unable to locate an operating
1067 system within the disk image you gave it. You might see this from
1068 programs like virt-cat if you try to run them on something which is
1069 just a disk image, not a virtual machine disk image.
1070 What do these "debug*" and "internal-*" functions do?
1072 There are some functions which are used for debugging and internal
1073 purposes which are not part of the stable API.
1074 The "debug*" (or "guestfs_debug*") functions, primarily "guestfs_debug"
1076 in guestfs(3) and a handful of others, are used for debugging
1077 libguestfs. Although they are not part of the stable API and thus may
1078 change or be removed at any time, some programs may want to call these
1079 while waiting for features to be added to libguestfs.
1080 The "internal-*" (or "guestfs_internal_*") functions are purely to be
1082 used by libguestfs itself. There is no reason for programs to call
1083 them, and programs should not try to use them. Using them will often
1084 cause bad things to happen, as well as not being part of the documented
1085 stable API.
1086
1088 Where do I send patches?
1089 Please send patches to the libguestfs mailing list
1090 https://www.redhat.com/mailman/listinfo/libguestfs. You don't have to
1091 be subscribed, but there will be a delay until your posting is manually
1092 approved.
1093 Please don’t use github pull requests - they will be ignored. The
1095 reasons are (a) we want to discuss and dissect patches on the mailing
1096 list, and (b) github pull requests turn into merge commits but we
1097 prefer to have a linear history.
1098 How do I propose a feature?
1100 Large new features that you intend to contribute should be discussed on
1101 the mailing list first
1102 (https://www.redhat.com/mailman/listinfo/libguestfs). This avoids
1103 disappointment and wasted work if we don't think the feature would fit
1104 into the libguestfs project.
1105 If you want to suggest a useful feature but don’t want to write the
1107 code, you can file a bug (see "GETTING HELP AND REPORTING BUGS") with
1108 "RFE: " at the beginning of the Summary line.
1109 Who can commit to libguestfs git?
1111 About 5 people have commit access to github. Patches should be posted
1112 on the list first and ACKed. The policy for ACKing and pushing patches
1113 is outlined here:
1114 https://www.redhat.com/archives/libguestfs/2012-January/msg00023.html
1116 Can I fork libguestfs?
1118 Of course you can. Git makes it easy to fork libguestfs. Github makes
1119 it even easier. It’s nice if you tell us on the mailing list about
1120 forks and the reasons for them.
1121
1123 Can I monitor the live disk activity of a virtual machine using libguestfs?
1124 A common request is to be able to use libguestfs to monitor the live
1125 disk activity of a guest, for example, to get notified every time a
1126 guest creates a new file. Libguestfs does not work in the way some
1127 people imagine, as you can see from this diagram:
1128 ┌─────────────────────────────────────┐
1130 │ monitoring program using libguestfs │
1131 └─────────────────────────────────────┘
1132 ↓
1133 ┌───────────┐ ┌──────────────────────┐
1134 │ live VM │ │ libguestfs appliance │
1135 ├───────────┤ ├──────────────────────┤
1136 │ kernel (1)│ │ appliance kernel (2) │
1137 └───────────┘ └──────────────────────┘
1138 ↓ ↓ (r/o connection)
1139 ┌──────────────────────┐
1140 | disk image |
1141 └──────────────────────┘
1142 This scenario is safe (as long as you set the "readonly" flag when
1144 adding the drive). However the libguestfs appliance kernel (2) does
1145 not see all the changes made to the disk image, for two reasons:
1146 i. The VM kernel (1) can cache data in memory, so it doesn't appear in
1148 the disk image.
1149 ii. The libguestfs appliance kernel (2) doesn't expect that the disk
1151 image is changing underneath it, so its own cache is not magically
1152 updated even when the VM kernel (1) does update the disk image.
1153 The only supported solution is to restart the entire libguestfs
1155 appliance whenever you want to look at changes in the disk image. At
1156 the API level that corresponds to calling "guestfs_shutdown" followed
1157 by "guestfs_launch", which is a heavyweight operation (see also
1158 guestfs-performance(3)).
1159 There are some unsupported hacks you can try if relaunching the
1161 appliance is really too costly:
1162 • Call "guestfs_drop_caches (g, 3)". This causes all cached data
1164 help by the libguestfs appliance kernel (2) to be discarded, so it
1165 goes back to the disk image.
1166 However this on its own is not sufficient, because qemu also caches
1168 some data. You will also need to patch libguestfs to (re-)enable
1169 the "cache=none" mode. See:
1170 https://rwmj.wordpress.com/2013/09/02/new-in-libguestfs-allow-cache-mode-to-be-selected/
1171 • Use a tool like virt-bmap instead.
1173 • Run an agent inside the guest.
1175 Nothing helps if the guest is making more fundamental changes (eg.
1177 deleting filesystems). For those kinds of things you must relaunch the
1178 appliance.
1179 (Note there is a third problem that you need to use consistent
1181 snapshots to really examine live disk images, but that’s a general
1182 problem with using libguestfs against any live disk image.)
1183
1185 guestfish(1), guestfs(3), http://libguestfs.org/.
1186
1188 Richard W.M. Jones ("rjones at redhat dot com")
1189
1191 Copyright (C) 2012-2020 Red Hat Inc.
1192
1194 This library is free software; you can redistribute it and/or modify it
1195 under the terms of the GNU Lesser General Public License as published
1196 by the Free Software Foundation; either version 2 of the License, or
1197 (at your option) any later version.
1198 This library is distributed in the hope that it will be useful, but
1200 WITHOUT ANY WARRANTY; without even the implied warranty of
1201 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1202 Lesser General Public License for more details.
1203 You should have received a copy of the GNU Lesser General Public
1205 License along with this library; if not, write to the Free Software
1206 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
1207 02110-1301 USA
1208
1210 To get a list of bugs against libguestfs, use this link:
1211 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
1212 To report a new bug against libguestfs, use this link:
1214 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
1215 When reporting a bug, please supply:
1217 • The version of libguestfs.
1219 • Where you got libguestfs (eg. which Linux distro, compiled from
1221 source, etc)
1222 • Describe the bug accurately and give a way to reproduce it.
1224 • Run libguestfs-test-tool(1) and paste the complete, unedited output
1226 into the bug report.
1227libguestfs-1.45.4 2021-04-03 guestfs-faq(1)