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 SuSE
292 Libguestfs was added to SuSE in 2012 by Olaf Hering.
293 ArchLinux
295 Libguestfs was added to the AUR in 2010.
296 Other Linux distro
298 Compile from source (next section).
299 Other non-Linux distro
301 You'll have to compile from source, and port it.
302 How can I compile and install libguestfs from source?
304 You can compile libguestfs from git or a source tarball. Read the
305 README file before starting.
306 Git: https://github.com/libguestfs/libguestfs Source tarballs:
308 http://libguestfs.org/download
309 Don’t run "make install"! Use the "./run" script instead (see README).
311 How can I compile and install libguestfs if my distro doesn't have new
313 enough qemu/supermin/kernel?
314 Libguestfs needs supermin 5. If supermin 5 hasn't been ported to your
315 distro, then see the question below.
316 First compile qemu, supermin and/or the kernel from source. You do not
318 need to "make install" them.
319 In the libguestfs source directory, create two files. "localconfigure"
321 should contain:
322 source localenv
324 #export PATH=/tmp/qemu/x86_64-softmmu:$PATH
325 ./autogen.sh --prefix /usr "$@"
326 Make "localconfigure" executable.
328 "localenv" should contain:
330 #export SUPERMIN=/tmp/supermin/src/supermin
332 #export LIBGUESTFS_HV=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64
333 #export SUPERMIN_KERNEL=/tmp/linux/arch/x86/boot/bzImage
334 #export SUPERMIN_KERNEL_VERSION=4.XX.0
335 #export SUPERMIN_MODULES=/tmp/lib/modules/4.XX.0
336 Uncomment and adjust these lines as required to use the alternate
338 programs you have compiled.
339 Use "./localconfigure" instead of "./configure", but otherwise you
341 compile libguestfs as usual.
342 Don’t run "make install"! Use the "./run" script instead (see README).
344 How can I compile and install libguestfs without supermin?
346 If supermin 5 supports your distro, but you don’t happen to have a new
347 enough supermin installed, then see the previous question.
348 If supermin 5 doesn't support your distro at all, you will need to use
350 the "fixed appliance method" where you use a pre-compiled binary
351 appliance. To build libguestfs without supermin, you need to pass
352 "--disable-appliance --disable-daemon" to either ./autogen.sh or
353 ./configure (depending whether you are building respectively from git
354 or from tarballs). Then, when using libguestfs, you must set the
355 "LIBGUESTFS_PATH" environment variable to the directory of a pre-
356 compiled appliance, as also described in "FIXED APPLIANCE" in
357 guestfs-internals(1).
358 For pre-compiled appliances, see also:
360 http://libguestfs.org/download/binaries/appliance/.
361 Patches to port supermin to more Linux distros are welcome.
363 How can I add support for sVirt?
365 Note for Fedora/RHEL users: This configuration is the default starting
366 with Fedora 18 and RHEL 7. If you find any problems, please let us
367 know or file a bug.
368 SVirt provides a hardened appliance using SELinux, making it very hard
370 for a rogue disk image to "escape" from the confinement of libguestfs
371 and damage the host (it's fair to say that even in standard libguestfs
372 this would be hard, but sVirt provides an extra layer of protection for
373 the host and more importantly protects virtual machines on the same
374 host from each other).
375 Currently to enable sVirt you will need libvirt ≥ 0.10.2 (1.0 or later
377 preferred), libguestfs ≥ 1.20, and the SELinux policies from recent
378 Fedora. If you are not running Fedora 18+, you will need to make
379 changes to your SELinux policy - contact us on the mailing list.
380 Once you have the requirements, do:
382 ./configure --with-default-backend=libvirt # libguestfs >= 1.22
384 ./configure --with-default-attach-method=libvirt # libguestfs <= 1.20
385 make
386 Set SELinux to Enforcing mode, and sVirt should be used automatically.
388 All, or almost all, features of libguestfs should work under sVirt.
390 There is one known shortcoming: virt-rescue(1) will not use libvirt
391 (hence sVirt), but falls back to direct launch of qemu. So you won't
392 currently get the benefit of sVirt protection when using virt-rescue.
393 You can check if sVirt is being used by enabling libvirtd logging (see
395 /etc/libvirt/libvirtd.log), killing and restarting libvirtd, and
396 checking the log files for "Setting SELinux context on ..." messages.
397 In theory sVirt should support AppArmor, but we have not tried it. It
399 will almost certainly require patching libvirt and writing an AppArmor
400 policy.
401 Libguestfs has a really long list of dependencies!
403 The base library doesn't depend on very much, but there are three
404 causes of the long list of other dependencies:
405 1. Libguestfs has to be able to read and edit many different disk
407 formats. For example, XFS support requires XFS tools.
408 2. There are language bindings for many different languages, all
410 requiring their own development tools. All language bindings
411 (except C) are optional.
412 3. There are some optional library features which can be disabled.
414 Since libguestfs ≥ 1.26 it is possible to split up the appliance
416 dependencies (item 1 in the list above) and thus have (eg)
417 "libguestfs-xfs" as a separate subpackage for processing XFS disk
418 images. We encourage downstream packagers to start splitting the base
419 libguestfs package into smaller subpackages.
420 Errors during launch on Fedora ≥ 18, RHEL ≥ 7
422 In Fedora ≥ 18 and RHEL ≥ 7, libguestfs uses libvirt to manage the
423 appliance. Previously (and upstream) libguestfs runs qemu directly:
424 ┌──────────────────────────────────┐
426 │ libguestfs │
427 ├────────────────┬─────────────────┤
428 │ direct backend │ libvirt backend │
429 └────────────────┴─────────────────┘
430 ↓ ↓
431 ┌───────┐ ┌──────────┐
432 │ qemu │ │ libvirtd │
433 └───────┘ └──────────┘
434 ↓
435 ┌───────┐
436 │ qemu │
437 └───────┘
438 upstream Fedora 18+
440 non-Fedora RHEL 7+
441 non-RHEL
442 The libvirt backend is more sophisticated, supporting SELinux/sVirt
444 (see above), hotplugging and more. It is, however, more complex and so
445 less robust.
446 If you have permissions problems using the libvirt backend, you can
448 switch to the direct backend by setting this environment variable:
449 export LIBGUESTFS_BACKEND=direct
451 before running any libguestfs program or virt tool.
453 How can I switch to a fixed / prebuilt appliance?
455 This may improve the stability and performance of libguestfs on Fedora
456 and RHEL.
457 Any time after installing libguestfs, run the following commands as
459 root:
460 mkdir -p /usr/local/lib/guestfs/appliance
462 libguestfs-make-fixed-appliance /usr/local/lib/guestfs/appliance
463 ls -l /usr/local/lib/guestfs/appliance
464 Now set the following environment variable before using libguestfs or
466 any virt tool:
467 export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance
469 Of course you can change the path to any directory you want. You can
471 share the appliance across machines that have the same architecture
472 (eg. all x86-64), but note that libvirt will prevent you from sharing
473 the appliance across NFS because of permissions problems (so either
474 switch to the direct backend or don't use NFS).
475 How can I speed up libguestfs builds?
477 By far the most important thing you can do is to install and properly
478 configure Squid. Note that the default configuration that ships with
479 Squid is rubbish, so configuring it is not optional.
480 A very good place to start with Squid configuration is here:
482 https://fedoraproject.org/wiki/Extras/MockTricks#Using_Squid_to_Speed_Up_Mock_package_downloads
483 Make sure Squid is running, and that the environment variables
485 $http_proxy and $ftp_proxy are pointing to it.
486 With Squid running and correctly configured, appliance builds should be
488 reduced to a few minutes.
489 How can I speed up libguestfs builds (Debian)?
491 Hilko Bengen suggests using "approx" which is a Debian archive proxy
493 (http://packages.debian.org/approx). This tool is documented on Debian
494 in the approx(8) manual page.
495
497 Note: Most of the information in this section has moved:
498 guestfs-performance(1).
499 Upload or write seem very slow.
501 If the underlying disk is not fully allocated (eg. sparse raw or qcow2)
502 then writes can be slow because the host operating system has to do
503 costly disk allocations while you are writing. The solution is to use a
504 fully allocated format instead, ie. non-sparse raw, or qcow2 with the
505 "preallocation=metadata" option.
506 Libguestfs uses too much disk space!
508 libguestfs caches a large-ish appliance in:
509 /var/tmp/.guestfs-<UID>
511 If the environment variable "TMPDIR" is defined, then
513 $TMPDIR/.guestfs-<UID> is used instead.
514 It is safe to delete this directory when you are not using libguestfs.
516 virt-sparsify seems to make the image grow to the full size of the virtual
518 disk
519 If the input to virt-sparsify(1) is raw, then the output will be raw
520 sparse. Make sure you are measuring the output with a tool which
521 understands sparseness such as "du -sh". It can make a huge
522 difference:
523 $ ls -lh test1.img
525 -rw-rw-r--. 1 rjones rjones 100M Aug 8 08:08 test1.img
526 $ du -sh test1.img
527 3.6M test1.img
528 (Compare the apparent size 100M vs the actual size 3.6M)
530 If all this confuses you, use a non-sparse output format by specifying
532 the --convert option, eg:
533 virt-sparsify --convert qcow2 disk.raw disk.qcow2
535 Why doesn't virt-resize work on the disk image in-place?
537 Resizing a disk image is very tricky -- especially making sure that you
538 don't lose data or break the bootloader. The current method
539 effectively creates a new disk image and copies the data plus
540 bootloader from the old one. If something goes wrong, you can always
541 go back to the original.
542 If we were to make virt-resize work in-place then there would have to
544 be limitations: for example, you wouldn't be allowed to move existing
545 partitions (because moving data across the same disk is most likely to
546 corrupt data in the event of a power failure or crash), and LVM would
547 be very difficult to support (because of the almost arbitrary mapping
548 between LV content and underlying disk blocks).
549 Another method we have considered is to place a snapshot over the
551 original disk image, so that the original data is untouched and only
552 differences are recorded in the snapshot. You can do this today using
553 "qemu-img create" + "virt-resize", but qemu currently isn't smart
554 enough to recognize when the same block is written back to the snapshot
555 as already exists in the backing disk, so you will find that this
556 doesn't save you any space or time.
557 In summary, this is a hard problem, and what we have now mostly works
559 so we are reluctant to change it.
560 Why doesn't virt-sparsify work on the disk image in-place?
562 In libguestfs ≥ 1.26, virt-sparsify can now work on disk images in
563 place. Use:
564 virt-sparsify --in-place disk.img
566 But first you should read "IN-PLACE SPARSIFICATION" in
568 virt-sparsify(1).
569
571 Remote libvirt guests cannot be opened.
572 Opening remote libvirt guests is not supported at this time. For
573 example this won't work:
574 guestfish -c qemu://remote/system -d Guest
576 To open remote disks you have to export them somehow, then connect to
578 the export. For example if you decided to use NBD:
579 remote$ qemu-nbd -t -p 10809 guest.img
581 local$ guestfish -a nbd://remote:10809 -i
582 Other possibilities include ssh (if qemu is recent enough), NFS or
584 iSCSI. See "REMOTE STORAGE" in guestfs(3).
585 How can I open this strange disk source?
587 You have a disk image located inside another system that requires
588 access via a library / HTTP / REST / proprietary API, or is compressed
589 or archived in some way. (One example would be remote access to
590 OpenStack glance images without actually downloading them.)
591 We have a sister project called nbdkit
593 (https://github.com/libguestfs/nbdkit). This project lets you turn any
594 disk source into an NBD server. Libguestfs can access NBD servers
595 directly, eg:
596 guestfish -a nbd://remote
598 nbdkit is liberally licensed, so you can link it to or include it in
600 proprietary libraries and code. It also has a simple, stable plugin
601 API so you can easily write plugins against the API which will continue
602 to work in future.
603 Error opening VMDK disks: "uses a vmdk feature which is not supported by
605 this qemu version: VMDK version 3"
606 Qemu (and hence libguestfs) only supports certain VMDK disk images.
607 Others won't work, giving this or similar errors.
608 Ideally someone would fix qemu to support the latest VMDK features, but
610 in the meantime you have three options:
611 1. If the guest is hosted on a live, reachable ESX server, then locate
613 and download the disk image called somename-flat.vmdk. Despite the
614 name, this is a raw disk image, and can be opened by anything.
615 If you have a recent enough version of qemu and libguestfs, then
617 you may be able to access this disk image remotely using either
618 HTTPS or ssh. See "REMOTE STORAGE" in guestfs(3).
619 2. Use VMware’s proprietary vdiskmanager tool to convert the image to
621 raw format.
622 3. Use nbdkit with the proprietary VDDK plugin to live export the disk
624 image as an NBD source. This should allow you to read and write
625 the VMDK file.
626 UFS disks (as used by BSD) cannot be opened.
628 The UFS filesystem format has many variants, and these are not self-
629 identifying. The Linux kernel has to be told which variant of UFS it
630 has to use, which libguestfs cannot know.
631 You have to pass the right "ufstype" mount option when mounting these
633 filesystems.
634 See https://www.kernel.org/doc/Documentation/filesystems/ufs.txt
636 Windows ReFS
638 Windows ReFS is Microsoft’s ZFS/Btrfs copy. This filesystem has not
639 yet been reverse engineered and implemented in the Linux kernel, and
640 therefore libguestfs doesn't support it. At the moment it seems to be
641 very rare "in the wild".
642 Non-ASCII characters don’t appear on VFAT filesystems.
644 Typical symptoms of this problem:
645 · You get an error when you create a file where the filename contains
647 non-ASCII characters, particularly non 8-bit characters from Asian
648 languages (Chinese, Japanese, etc). The filesystem is VFAT.
649 · When you list a directory from a VFAT filesystem, filenames appear
651 as question marks.
652 This is a design flaw of the GNU/Linux system.
654 VFAT stores long filenames as UTF-16 characters. When opening or
656 returning filenames, the Linux kernel has to translate these to some
657 form of 8 bit string. UTF-8 would be the obvious choice, except for
658 Linux users who persist in using non-UTF-8 locales (the user’s locale
659 is not known to the kernel because it’s a function of libc).
660 Therefore you have to tell the kernel what translation you want done
662 when you mount the filesystem. The two methods are the "iocharset"
663 parameter (which is not relevant to libguestfs) and the "utf8" flag.
664 So to use a VFAT filesystem you must add the "utf8" flag when mounting.
666 From guestfish, use:
667 ><fs> mount-options utf8 /dev/sda1 /
669 or on the guestfish command line:
671 guestfish [...] -m /dev/sda1:/:utf8
673 or from the API:
675 guestfs_mount_options (g, "utf8", "/dev/sda1", "/");
677 The kernel will then translate filenames to and from UTF-8 strings.
679 We considered adding this mount option transparently, but unfortunately
681 there are several problems with doing that:
682 · On some Linux systems, the "utf8" mount option doesn't work. We
684 don't precisely understand what systems or why, but this was
685 reliably reported by one user.
686 · It would prevent you from using the "iocharset" parameter because
688 it is incompatible with "utf8". It is probably not a good idea to
689 use this parameter, but we don't want to prevent it.
690 Non-ASCII characters appear as underscore (_) on ISO9660 filesystems.
692 The filesystem was not prepared correctly with mkisofs or genisoimage.
693 Make sure the filesystem was created using Joliet and/or Rock Ridge
694 extensions. libguestfs does not require any special mount options to
695 handle the filesystem.
696 Cannot open Windows guests which use NTFS.
698 You see errors like:
699 mount: unknown filesystem type 'ntfs'
701 On Red Hat Enterprise Linux or CentOS < 7.2, you have to install the
703 libguestfs-winsupport package. In RHEL ≥ 7.2, "libguestfs-winsupport"
704 is part of the base RHEL distribution, but see the next question.
705 "mount: unsupported filesystem type" with NTFS in RHEL ≥ 7.2
707 In RHEL 7.2 we were able to add "libguestfs-winsupport" to the base
708 RHEL distribution, but we had to disable the ability to use it for
709 opening and editing filesystems. It is only supported when used with
710 virt-v2v(1). If you try to use guestfish(1) or guestmount(1) or some
711 other programs on an NTFS filesystem, you will see the error:
712 mount: unsupported filesystem type
714 This is not a supported configuration, and it will not be made to work
716 in RHEL. Don't bother to open a bug about it, as it will be
717 immediately "CLOSED -> WONTFIX".
718 You may compile your own libguestfs removing this restriction, but that
720 won't be endorsed or supported by Red Hat.
721 Cannot open or inspect RHEL 7 guests.
723 Cannot open Linux guests which use XFS.
724 RHEL 7 guests, and any other guests that use XFS, can be opened by
725 libguestfs, but you have to install the "libguestfs-xfs" package.
726
728 The API has hundreds of methods, where do I start?
729 We recommend you start by reading the API overview: "API OVERVIEW" in
730 guestfs(3).
731 Although the API overview covers the C API, it is still worth reading
733 even if you are going to use another programming language, because the
734 API is the same, just with simple logical changes to the names of the
735 calls:
736 C guestfs_ln_sf (g, target, linkname);
738 Python g.ln_sf (target, linkname);
739 OCaml g#ln_sf target linkname;
740 Perl $g->ln_sf (target, linkname);
741 Shell (guestfish) ln-sf target linkname
742 PHP guestfs_ln_sf ($g, $target, $linkname);
743 Once you're familiar with the API overview, you should look at this
745 list of starting points for other language bindings: "USING LIBGUESTFS
746 WITH OTHER PROGRAMMING LANGUAGES" in guestfs(3).
747 Can I use libguestfs in my proprietary / closed source / commercial
749 program?
750 In general, yes. However this is not legal advice - read the license
751 that comes with libguestfs, and if you have specific questions contact
752 a lawyer.
753 In the source tree the license is in the file "COPYING.LIB" (LGPLv2+
755 for the library and bindings) and "COPYING" (GPLv2+ for the standalone
756 programs).
757
759 Help, it’s not working!
760 If no libguestfs program seems to work at all, run the program below
761 and paste the complete, unedited output into an email to "libguestfs" @
762 "redhat.com":
763 libguestfs-test-tool
765 If a particular operation fails, supply all the information in this
767 checklist, in an email to "libguestfs" @ "redhat.com":
768 1. What are you trying to do?
770 2. What exact command(s) did you run?
772 3. What was the precise error or output of these commands?
774 4. Enable debugging, run the commands again, and capture the complete
776 output. Do not edit the output.
777 export LIBGUESTFS_DEBUG=1
779 export LIBGUESTFS_TRACE=1
780 5. Include the version of libguestfs, the operating system version,
782 and how you installed libguestfs (eg. from source, "yum install",
783 etc.)
784 How do I debug when using any libguestfs program or tool (eg. virt-
786 customize or virt-df)?
787 There are two "LIBGUESTFS_*" environment variables you can set in order
788 to get more information from libguestfs.
789 "LIBGUESTFS_TRACE"
791 Set this to 1 and libguestfs will print out each command / API call
792 in a format which is similar to guestfish commands.
793 "LIBGUESTFS_DEBUG"
795 Set this to 1 in order to enable massive amounts of debug messages.
796 If you think there is some problem inside the libguestfs appliance,
797 then you should use this option.
798 To set these from the shell, do this before running the program:
800 export LIBGUESTFS_TRACE=1
802 export LIBGUESTFS_DEBUG=1
803 For csh/tcsh the equivalent commands would be:
805 setenv LIBGUESTFS_TRACE 1
807 setenv LIBGUESTFS_DEBUG 1
808 For further information, see: "ENVIRONMENT VARIABLES" in guestfs(3).
810 How do I debug when using guestfish?
812 You can use the same environment variables above. Alternatively use
813 the guestfish options -x (to trace commands) or -v (to get the full
814 debug output), or both.
815 For further information, see: guestfish(1).
817 How do I debug when using the API?
819 Call "guestfs_set_trace" in guestfs(3) to enable command traces, and/or
820 "guestfs_set_verbose" in guestfs(3) to enable debug messages.
821 For best results, call these functions as early as possible, just after
823 creating the guestfs handle if you can, and definitely before calling
824 launch.
825 How do I capture debug output and put it into my logging system?
827 Use the event API. For examples, see: "SETTING CALLBACKS TO HANDLE
828 EVENTS" in guestfs(3) and the examples/debug-logging.c program in the
829 libguestfs sources.
830 Digging deeper into the appliance boot process.
832 Enable debugging and then read this documentation on the appliance boot
833 process: guestfs-internals(1).
834 libguestfs hangs or fails during run/launch.
836 Enable debugging and look at the full output. If you cannot work out
837 what is going on, file a bug report, including the complete output of
838 libguestfs-test-tool(1).
839 Debugging libvirt
841 If you are using the libvirt backend, and libvirt is failing, then you
842 can enable debugging by editing /etc/libvirt/libvirtd.conf.
843 If you are running as non-root, then you have to edit a different file.
845 Create ~/.config/libvirt/libvirtd.conf containing:
846 log_level=1
848 log_outputs="1:file:/tmp/libvirtd.log"
849 Kill any session (non-root) libvirtd that is running, and next time you
851 run the libguestfs command, you should see a large amount of useful
852 debugging information from libvirtd in /tmp/libvirtd.log
853 Broken kernel, or trying a different kernel.
855 You can choose a different kernel for the appliance by setting some
856 supermin environment variables:
857 export SUPERMIN_KERNEL_VERSION=4.8.0-1.fc25.x86_64
859 export SUPERMIN_KERNEL=/boot/vmlinuz-$SUPERMIN_KERNEL_VERSION
860 export SUPERMIN_MODULES=/lib/modules/$SUPERMIN_KERNEL_VERSION
861 rm -rf /var/tmp/.guestfs-*
862 libguestfs-test-tool
863 Broken qemu, or trying a different qemu.
865 You can choose a different qemu by setting the hypervisor environment
866 variable:
867 export LIBGUESTFS_HV=/path/to/qemu-system-x86_64
869 libguestfs-test-tool
870
872 See also guestfs-internals(1).
873 Why don’t you do everything through the FUSE / filesystem interface?
875 We offer a command called guestmount(1) which lets you mount guest
876 filesystems on the host. This is implemented as a FUSE module. Why
877 don't we just implement the whole of libguestfs using this mechanism,
878 instead of having the large and rather complicated API?
879 The reasons are twofold. Firstly, libguestfs offers API calls for
881 doing things like creating and deleting partitions and logical volumes,
882 which don't fit into a filesystem model very easily. Or rather, you
883 could fit them in: for example, creating a partition could be mapped to
884 "mkdir /fs/hda1" but then you'd have to specify some method to choose
885 the size of the partition (maybe "echo 100M > /fs/hda1/.size"), and the
886 partition type, start and end sectors etc., but once you've done that
887 the filesystem-based API starts to look more complicated than the call-
888 based API we currently have.
889 The second reason is for efficiency. FUSE itself is reasonably
891 efficient, but it does make lots of small, independent calls into the
892 FUSE module. In guestmount these have to be translated into messages
893 to the libguestfs appliance which has a big overhead (in time and round
894 trips). For example, reading a file in 64 KB chunks is inefficient
895 because each chunk would turn into a single round trip. In the
896 libguestfs API it is much more efficient to download an entire file or
897 directory through one of the streaming calls like "guestfs_download" or
898 "guestfs_tar_out".
899 Why don’t you do everything through GVFS?
901 The problems are similar to the problems with FUSE.
902 GVFS is a better abstraction than POSIX/FUSE. There is an FTP backend
904 for GVFS, which is encouraging because FTP is conceptually similar to
905 the libguestfs API. However the GVFS FTP backend makes multiple
906 simultaneous connections in order to keep interactivity, which we can't
907 easily do with libguestfs.
908 Why can I write to the disk, even though I added it read-only?
910 Why does "--ro" appear to have no effect?
911 When you add a disk read-only, libguestfs places a writable overlay on
912 top of the underlying disk. Writes go into this overlay, and are
913 discarded when the handle is closed (or "guestfish" etc. exits).
914 There are two reasons for doing it this way: Firstly read-only disks
916 aren't possible in many cases (eg. IDE simply doesn't support them, so
917 you couldn't have an IDE-emulated read-only disk, although this is not
918 common in real libguestfs installations).
919 Secondly and more importantly, even if read-only disks were possible,
921 you wouldn't want them. Mounting any filesystem that has a journal,
922 even "mount -o ro", causes writes to the filesystem because the journal
923 has to be replayed and metadata updated. If the disk was truly read-
924 only, you wouldn't be able to mount a dirty filesystem.
925 To make it usable, we create the overlay as a place to temporarily
927 store these writes, and then we discard it afterwards. This ensures
928 that the underlying disk is always untouched.
929 Note also that there is a regression test for this when building
931 libguestfs (in "tests/qemu"). This is one reason why it’s important
932 for packagers to run the test suite.
933 Does "--ro" make all disks read-only?
935 No! The "--ro" option only affects disks added on the command line,
936 ie. using "-a" and "-d" options.
937 In guestfish, if you use the "add" command, then disk is added read-
939 write (unless you specify the "readonly:true" flag explicitly with the
940 command).
941 Can I use "guestfish --ro" as a way to backup my virtual machines?
943 Usually this is not a good idea. The question is answered in more
944 detail in this mailing list posting:
945 https://www.redhat.com/archives/libguestfs/2010-August/msg00024.html
946 See also the next question.
948 Why can’t I run fsck on a live filesystem using "guestfish --ro"?
950 This command will usually not work:
951 guestfish --ro -a /dev/vg/my_root_fs run : fsck /dev/sda
953 The reason for this is that qemu creates a snapshot over the original
955 filesystem, but it doesn't create a strict point-in-time snapshot.
956 Blocks of data on the underlying filesystem are read by qemu at
957 different times as the fsck operation progresses, with host writes in
958 between. The result is that fsck sees massive corruption (imaginary,
959 not real!) and fails.
960 What you have to do is to create a point-in-time snapshot. If it’s a
962 logical volume, use an LVM2 snapshot. If the filesystem is located
963 inside something like a btrfs/ZFS file, use a btrfs/ZFS snapshot, and
964 then run the fsck on the snapshot. In practice you don't need to use
965 libguestfs for this -- just run /sbin/fsck directly.
966 Creating point-in-time snapshots of host devices and files is outside
968 the scope of libguestfs, although libguestfs can operate on them once
969 they are created.
970 What’s the difference between guestfish and virt-rescue?
972 A lot of people are confused by the two superficially similar tools we
973 provide:
974 $ guestfish --ro -a guest.img
976 ><fs> run
977 ><fs> fsck /dev/sda1
978 $ virt-rescue --ro guest.img
980 ><rescue> /sbin/fsck /dev/sda1
981 And the related question which then arises is why you can’t type in
983 full shell commands with all the --options in guestfish (but you can in
984 virt-rescue(1)).
985 guestfish(1) is a program providing structured access to the guestfs(3)
987 API. It happens to be a nice interactive shell too, but its primary
988 purpose is structured access from shell scripts. Think of it more like
989 a language binding, like Python and other bindings, but for shell. The
990 key differentiating factor of guestfish (and the libguestfs API in
991 general) is the ability to automate changes.
992 virt-rescue(1) is a free-for-all freeform way to boot the libguestfs
994 appliance and make arbitrary changes to your VM. It’s not structured,
995 you can't automate it, but for making quick ad-hoc fixes to your
996 guests, it can be quite useful.
997 But, libguestfs also has a "backdoor" into the appliance allowing you
999 to send arbitrary shell commands. It’s not as flexible as virt-rescue,
1000 because you can't interact with the shell commands, but here it is
1001 anyway:
1002 ><fs> debug sh "cmd arg1 arg2 ..."
1004 Note that you should not rely on this. It could be removed or changed
1006 in future. If your program needs some operation, please add it to the
1007 libguestfs API instead.
1008 What’s the deal with "guestfish -i"?
1010 Why does virt-cat only work on a real VM image, but virt-df works on any
1011 disk image?
1012 What does "no root device found in this operating system image" mean?
1013 These questions are all related at a fundamental level which may not be
1014 immediately obvious.
1015 At the guestfs(3) API level, a "disk image" is just a pile of
1017 partitions and filesystems.
1018 In contrast, when the virtual machine boots, it mounts those
1020 filesystems into a consistent hierarchy such as:
1021 / (/dev/sda2)
1023 │
1024 ├── /boot (/dev/sda1)
1025 │
1026 ├── /home (/dev/vg_external/Homes)
1027 │
1028 ├── /usr (/dev/vg_os/lv_usr)
1029 │
1030 └── /var (/dev/vg_os/lv_var)
1031 (or drive letters on Windows).
1033 The API first of all sees the disk image at the "pile of filesystems"
1035 level. But it also has a way to inspect the disk image to see if it
1036 contains an operating system, and how the disks are mounted when the
1037 operating system boots: "INSPECTION" in guestfs(3).
1038 Users expect some tools (like virt-cat(1)) to work with VM paths:
1040 virt-cat fedora.img /var/log/messages
1042 How does virt-cat know that /var is a separate partition? The trick is
1044 that virt-cat performs inspection on the disk image, and uses that to
1045 translate the path correctly.
1046 Some tools (including virt-cat(1), virt-edit(1), virt-ls(1)) use
1048 inspection to map VM paths. Other tools, such as virt-df(1) and
1049 virt-filesystems(1) operate entirely at the raw "big pile of
1050 filesystems" level of the libguestfs API, and don't use inspection.
1051 guestfish(1) is in an interesting middle ground. If you use the -a and
1053 -m command line options, then you have to tell guestfish exactly how to
1054 add disk images and where to mount partitions. This is the raw API
1055 level.
1056 If you use the -i option, libguestfs performs inspection and mounts the
1058 filesystems for you.
1059 The error "no root device found in this operating system image" is
1061 related to this. It means inspection was unable to locate an operating
1062 system within the disk image you gave it. You might see this from
1063 programs like virt-cat if you try to run them on something which is
1064 just a disk image, not a virtual machine disk image.
1065 What do these "debug*" and "internal-*" functions do?
1067 There are some functions which are used for debugging and internal
1068 purposes which are not part of the stable API.
1069 The "debug*" (or "guestfs_debug*") functions, primarily "guestfs_debug"
1071 in guestfs(3) and a handful of others, are used for debugging
1072 libguestfs. Although they are not part of the stable API and thus may
1073 change or be removed at any time, some programs may want to call these
1074 while waiting for features to be added to libguestfs.
1075 The "internal-*" (or "guestfs_internal_*") functions are purely to be
1077 used by libguestfs itself. There is no reason for programs to call
1078 them, and programs should not try to use them. Using them will often
1079 cause bad things to happen, as well as not being part of the documented
1080 stable API.
1081
1083 Where do I send patches?
1084 Please send patches to the libguestfs mailing list
1085 https://www.redhat.com/mailman/listinfo/libguestfs. You don't have to
1086 be subscribed, but there will be a delay until your posting is manually
1087 approved.
1088 Please don’t use github pull requests - they will be ignored. The
1090 reasons are (a) we want to discuss and dissect patches on the mailing
1091 list, and (b) github pull requests turn into merge commits but we
1092 prefer to have a linear history.
1093 How do I propose a feature?
1095 Large new features that you intend to contribute should be discussed on
1096 the mailing list first
1097 (https://www.redhat.com/mailman/listinfo/libguestfs). This avoids
1098 disappointment and wasted work if we don't think the feature would fit
1099 into the libguestfs project.
1100 If you want to suggest a useful feature but don’t want to write the
1102 code, you can file a bug (see "GETTING HELP AND REPORTING BUGS") with
1103 "RFE: " at the beginning of the Summary line.
1104 Who can commit to libguestfs git?
1106 About 5 people have commit access to github. Patches should be posted
1107 on the list first and ACKed. The policy for ACKing and pushing patches
1108 is outlined here:
1109 https://www.redhat.com/archives/libguestfs/2012-January/msg00023.html
1111 Can I fork libguestfs?
1113 Of course you can. Git makes it easy to fork libguestfs. Github makes
1114 it even easier. It’s nice if you tell us on the mailing list about
1115 forks and the reasons for them.
1116
1118 Can I monitor the live disk activity of a virtual machine using libguestfs?
1119 A common request is to be able to use libguestfs to monitor the live
1120 disk activity of a guest, for example, to get notified every time a
1121 guest creates a new file. Libguestfs does not work in the way some
1122 people imagine, as you can see from this diagram:
1123 ┌─────────────────────────────────────┐
1125 │ monitoring program using libguestfs │
1126 └─────────────────────────────────────┘
1127 ↓
1128 ┌───────────┐ ┌──────────────────────┐
1129 │ live VM │ │ libguestfs appliance │
1130 ├───────────┤ ├──────────────────────┤
1131 │ kernel (1)│ │ appliance kernel (2) │
1132 └───────────┘ └──────────────────────┘
1133 ↓ ↓ (r/o connection)
1134 ┌──────────────────────┐
1135 | disk image |
1136 └──────────────────────┘
1137 This scenario is safe (as long as you set the "readonly" flag when
1139 adding the drive). However the libguestfs appliance kernel (2) does
1140 not see all the changes made to the disk image, for two reasons:
1141 i. The VM kernel (1) can cache data in memory, so it doesn't appear in
1143 the disk image.
1144 ii. The libguestfs appliance kernel (2) doesn't expect that the disk
1146 image is changing underneath it, so its own cache is not magically
1147 updated even when the VM kernel (1) does update the disk image.
1148 The only supported solution is to restart the entire libguestfs
1150 appliance whenever you want to look at changes in the disk image. At
1151 the API level that corresponds to calling "guestfs_shutdown" followed
1152 by "guestfs_launch", which is a heavyweight operation (see also
1153 guestfs-performance(3)).
1154 There are some unsupported hacks you can try if relaunching the
1156 appliance is really too costly:
1157 · Call "guestfs_drop_caches (g, 3)". This causes all cached data
1159 help by the libguestfs appliance kernel (2) to be discarded, so it
1160 goes back to the disk image.
1161 However this on its own is not sufficient, because qemu also caches
1163 some data. You will also need to patch libguestfs to (re-)enable
1164 the "cache=none" mode. See:
1165 https://rwmj.wordpress.com/2013/09/02/new-in-libguestfs-allow-cache-mode-to-be-selected/
1166 · Use a tool like virt-bmap instead.
1168 · Run an agent inside the guest.
1170 Nothing helps if the guest is making more fundamental changes (eg.
1172 deleting filesystems). For those kinds of things you must relaunch the
1173 appliance.
1174 (Note there is a third problem that you need to use consistent
1176 snapshots to really examine live disk images, but that’s a general
1177 problem with using libguestfs against any live disk image.)
1178
1180 guestfish(1), guestfs(3), http://libguestfs.org/.
1181
1183 Richard W.M. Jones ("rjones at redhat dot com")
1184
1186 Copyright (C) 2012-2020 Red Hat Inc.
1187
1189 This library is free software; you can redistribute it and/or modify it
1190 under the terms of the GNU Lesser General Public License as published
1191 by the Free Software Foundation; either version 2 of the License, or
1192 (at your option) any later version.
1193 This library is distributed in the hope that it will be useful, but
1195 WITHOUT ANY WARRANTY; without even the implied warranty of
1196 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1197 Lesser General Public License for more details.
1198 You should have received a copy of the GNU Lesser General Public
1200 License along with this library; if not, write to the Free Software
1201 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
1202 02110-1301 USA
1203
1205 To get a list of bugs against libguestfs, use this link:
1206 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
1207 To report a new bug against libguestfs, use this link:
1209 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
1210 When reporting a bug, please supply:
1212 · The version of libguestfs.
1214 · Where you got libguestfs (eg. which Linux distro, compiled from
1216 source, etc)
1217 · Describe the bug accurately and give a way to reproduce it.
1219 · Run libguestfs-test-tool(1) and paste the complete, unedited output
1221 into the bug report.
1222libguestfs-1.42.0 2020-03-09 guestfs-faq(1)