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