1guestfs-faq(1)              Virtualization Support              guestfs-faq(1)
2
3
4

NAME

6       guestfs-faq - libguestfs Frequently Asked Questions (FAQ)
7

ABOUT LIBGUESTFS

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
15       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
18       For more information about what libguestfs can do read the introduction
19       on the home page (http://libguestfs.org).
20
21   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
29   Does libguestfs need { libvirt / KVM / Red Hat / Fedora }?
30       No!
31
32       libvirt is not a requirement for libguestfs.
33
34       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
38       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
44   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
54       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
60       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
67       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
73       vs. parted
74           Libguestfs supports LVM.  Libguestfs uses parted and provides most
75           parted features through the libguestfs API.
76

GETTING HELP AND REPORTING BUGS

78   How do I know what version I'm using?
79       The simplest method is:
80
81        guestfish --version
82
83       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
87   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
92       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
96       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
100       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
104   How do I report bugs?
105       Please use the following link to enter a bug in Bugzilla:
106
107       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
108
109       Include as much detail as you can and a way to reproduce the problem.
110
111       Include the full output of libguestfs-test-tool(1).
112

COMMON PROBLEMS

114       See also "LIBGUESTFS GOTCHAS" in guestfs(3) for some "gotchas" with
115       using the libguestfs API.
116
117   "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
121        setsebool -P virt_use_execmem=on
122
123       For more information see
124       https://bugzilla.redhat.com/show_bug.cgi?id=806106.
125
126   "child process died unexpectedly"
127       [This error message was changed in libguestfs 1.21.18 to something more
128       explanatory.]
129
130       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
133        libguestfs-test-tool
134
135       If, after using this, you still don’t understand the failure, contact
136       us (see previous section).
137
138   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
144       If you see any of these errors on Debian/Ubuntu, you need to run the
145       following command:
146
147        sudo update-guestfs-appliance
148
149   "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
153       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
159       There is a bug open against libvirt to fix this:
160       https://bugzilla.redhat.com/show_bug.cgi?id=1045069
161
162       You can work around this by one of the following methods:
163
164       ·   Switch to the direct backend:
165
166            export LIBGUESTFS_BACKEND=direct
167
168       ·   Don’t run libguestfs as root.
169
170       ·   Chmod the disk image and any parent directories so that the qemu
171           user can access them.
172
173       ·   (Nasty) Edit /etc/libvirt/qemu.conf and change the "user" setting.
174
175   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
181       This error happens during the supermin boot phase of starting the
182       appliance:
183
184        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
190       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
197       Diagnosing the problem involves studying the libraries needed by
198       /bin/bash, ie:
199
200        ldd /bin/bash
201
202       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
207       You should also check that files like /init and /bin/bash (in the
208       appliance) are executable.  The debug output shows file modes.
209

DOWNLOADING, INSTALLING, COMPILING LIBGUESTFS

211   Where can I get the latest binaries for ...?
212       Fedora ≥ 11
213           Use:
214
215            yum install '*guestf*'
216
217           For the latest builds, see:
218           http://koji.fedoraproject.org/koji/packageinfo?packageID=8391
219
220       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
227           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
233       Debian and Ubuntu
234           For libguestfs < 1.26, after installing libguestfs you need to do:
235
236            sudo update-guestfs-appliance
237
238           (This script has been removed on Debian/Ubuntu with libguestfs ≥
239           1.26 and instead the appliance is built on demand.)
240
241           On Ubuntu only:
242
243            sudo chmod 0644 /boot/vmlinuz*
244
245           You may need to add yourself to the "kvm" group:
246
247            sudo usermod -a -G kvm yourlogin
248
249           Debian Squeeze (6)
250               Hilko Bengen has built libguestfs in squeeze backports:
251               http://packages.debian.org/search?keywords=guestfs&searchon=names&section=all&suite=squeeze-backports
252
253           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
258           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
263               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
269                sudo chmod 0644 /boot/vmlinuz*
270
271               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
275                   You need febootstrap ≥ 3.14-2 from:
276                   http://packages.ubuntu.com/precise/febootstrap
277
278                   After installing or updating febootstrap, rebuild the
279                   appliance:
280
281                    sudo update-guestfs-appliance
282
283                   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
287                   Also you need to do (see above):
288
289                    sudo chmod 0644 /boot/vmlinuz*
290
291       Gentoo
292           Libguestfs was added to Gentoo in 2012-07 by Andreis Vinogradovs
293           (libguestfs) and Maxim Koltsov (mainly hivex).  Do:
294
295            emerge libguestfs
296
297       SuSE
298           Libguestfs was added to SuSE in 2012 by Olaf Hering.
299
300       ArchLinux
301           Libguestfs was added to the AUR in 2010.
302
303       Other Linux distro
304           Compile from source (next section).
305
306       Other non-Linux distro
307           You'll have to compile from source, and port it.
308
309   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
313       Git: https://github.com/libguestfs/libguestfs Source tarballs:
314       http://libguestfs.org/download
315
316       Don’t run "make install"!  Use the "./run" script instead (see README).
317
318   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
323       First compile qemu, supermin and/or the kernel from source.  You do not
324       need to "make install" them.
325
326       In the libguestfs source directory, create two files.  "localconfigure"
327       should contain:
328
329        source localenv
330        #export PATH=/tmp/qemu/x86_64-softmmu:$PATH
331        ./autogen.sh --prefix /usr "$@"
332
333       Make "localconfigure" executable.
334
335       "localenv" should contain:
336
337        #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
343       Uncomment and adjust these lines as required to use the alternate
344       programs you have compiled.
345
346       Use "./localconfigure" instead of "./configure", but otherwise you
347       compile libguestfs as usual.
348
349       Don’t run "make install"!  Use the "./run" script instead (see README).
350
351   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
355       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
365       For pre-compiled appliances, see also:
366       http://libguestfs.org/download/binaries/appliance/.
367
368       Patches to port supermin to more Linux distros are welcome.
369
370   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
375       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
382       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
387       Once you have the requirements, do:
388
389        ./configure --with-default-backend=libvirt       # libguestfs >= 1.22
390        ./configure --with-default-attach-method=libvirt # libguestfs <= 1.20
391        make
392
393       Set SELinux to Enforcing mode, and sVirt should be used automatically.
394
395       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
400       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
404       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
408   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
412       1.  Libguestfs has to be able to read and edit many different disk
413           formats.  For example, XFS support requires XFS tools.
414
415       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
419       3.  There are some optional library features which can be disabled.
420
421       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
427   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
431        ┌──────────────────────────────────┐
432        │ libguestfs                       │
433        ├────────────────┬─────────────────┤
434        │ direct backend │ libvirt backend │
435        └────────────────┴─────────────────┘
436               ↓                  ↓
437           ┌───────┐         ┌──────────┐
438           │ qemu  │         │ libvirtd │
439           └───────┘         └──────────┘
440
441                              ┌───────┐
442                              │ qemu  │
443                              └───────┘
444
445           upstream          Fedora 18+
446           non-Fedora         RHEL 7+
447           non-RHEL
448
449       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
453       If you have permissions problems using the libvirt backend, you can
454       switch to the direct backend by setting this environment variable:
455
456        export LIBGUESTFS_BACKEND=direct
457
458       before running any libguestfs program or virt tool.
459
460   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
464       Any time after installing libguestfs, run the following commands as
465       root:
466
467        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
471       Now set the following environment variable before using libguestfs or
472       any virt tool:
473
474        export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance
475
476       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
482   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
487       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
490       Make sure Squid is running, and that the environment variables
491       $http_proxy and $ftp_proxy are pointing to it.
492
493       With Squid running and correctly configured, appliance builds should be
494       reduced to a few minutes.
495
496       How can I speed up libguestfs builds (Debian)?
497
498       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

SPEED, DISK SPACE USED BY LIBGUESTFS

503       Note: Most of the information in this section has moved:
504       guestfs-performance(1).
505
506   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
513   Libguestfs uses too much disk space!
514       libguestfs caches a large-ish appliance in:
515
516        /var/tmp/.guestfs-<UID>
517
518       If the environment variable "TMPDIR" is defined, then
519       $TMPDIR/.guestfs-<UID> is used instead.
520
521       It is safe to delete this directory when you are not using libguestfs.
522
523   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
530        $ 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
535       (Compare the apparent size 100M vs the actual size 3.6M)
536
537       If all this confuses you, use a non-sparse output format by specifying
538       the --convert option, eg:
539
540        virt-sparsify --convert qcow2 disk.raw disk.qcow2
541
542   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
549       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
556       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
564       In summary, this is a hard problem, and what we have now mostly works
565       so we are reluctant to change it.
566
567   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
571        virt-sparsify --in-place disk.img
572
573       But first you should read "IN-PLACE SPARSIFICATION" in
574       virt-sparsify(1).
575

PROBLEMS OPENING DISK IMAGES

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
581        guestfish -c qemu://remote/system -d Guest
582
583       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
586        remote$ qemu-nbd -t -p 10809 guest.img
587         local$ guestfish -a nbd://remote:10809 -i
588
589       Other possibilities include ssh (if qemu is recent enough), NFS or
590       iSCSI.  See "REMOTE STORAGE" in guestfs(3).
591
592   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
598       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
603        guestfish -a nbd://remote
604
605       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
610   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
615       Ideally someone would fix qemu to support the latest VMDK features, but
616       in the meantime you have three options:
617
618       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
622           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
626       2.  Use VMware’s proprietary vdiskmanager tool to convert the image to
627           raw format.
628
629       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
633   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
638       You have to pass the right "ufstype" mount option when mounting these
639       filesystems.
640
641       See https://www.kernel.org/doc/Documentation/filesystems/ufs.txt
642
643   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
649   Non-ASCII characters don’t appear on VFAT filesystems.
650       Typical symptoms of this problem:
651
652       ·   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
656       ·   When you list a directory from a VFAT filesystem, filenames appear
657           as question marks.
658
659       This is a design flaw of the GNU/Linux system.
660
661       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
667       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
671       So to use a VFAT filesystem you must add the "utf8" flag when mounting.
672       From guestfish, use:
673
674        ><fs> mount-options utf8 /dev/sda1 /
675
676       or on the guestfish command line:
677
678        guestfish [...] -m /dev/sda1:/:utf8
679
680       or from the API:
681
682        guestfs_mount_options (g, "utf8", "/dev/sda1", "/");
683
684       The kernel will then translate filenames to and from UTF-8 strings.
685
686       We considered adding this mount option transparently, but unfortunately
687       there are several problems with doing that:
688
689       ·   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
693       ·   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
697   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
703   Cannot open Windows guests which use NTFS.
704       You see errors like:
705
706        mount: unknown filesystem type 'ntfs'
707
708       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
712   "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
719        mount: unsupported filesystem type
720
721       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
725       You may compile your own libguestfs removing this restriction, but that
726       won't be endorsed or supported by Red Hat.
727
728   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

USING LIBGUESTFS IN YOUR OWN PROGRAMS

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
738       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
743                         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
750       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
754   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
760       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

DEBUGGING LIBGUESTFS

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
770        libguestfs-test-tool
771
772       If a particular operation fails, supply all the information in this
773       checklist, in an email to "libguestfs" @ "redhat.com":
774
775       1.  What are you trying to do?
776
777       2.  What exact command(s) did you run?
778
779       3.  What was the precise error or output of these commands?
780
781       4.  Enable debugging, run the commands again, and capture the complete
782           output.  Do not edit the output.
783
784            export LIBGUESTFS_DEBUG=1
785            export LIBGUESTFS_TRACE=1
786
787       5.  Include the version of libguestfs, the operating system version,
788           and how you installed libguestfs (eg. from source, "yum install",
789           etc.)
790
791   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
796       "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
800       "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
805       To set these from the shell, do this before running the program:
806
807        export LIBGUESTFS_TRACE=1
808        export LIBGUESTFS_DEBUG=1
809
810       For csh/tcsh the equivalent commands would be:
811
812        setenv LIBGUESTFS_TRACE 1
813        setenv LIBGUESTFS_DEBUG 1
814
815       For further information, see: "ENVIRONMENT VARIABLES" in guestfs(3).
816
817   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
822       For further information, see: guestfish(1).
823
824   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
828       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
832   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
837   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
841   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
846   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
850       If you are running as non-root, then you have to edit a different file.
851       Create ~/.config/libvirt/libvirtd.conf containing:
852
853        log_level=1
854        log_outputs="1:file:/tmp/libvirtd.log"
855
856       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
860   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
864        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
870   Broken qemu, or trying a different qemu.
871       You can choose a different qemu by setting the hypervisor environment
872       variable:
873
874        export LIBGUESTFS_HV=/path/to/qemu-system-x86_64
875        libguestfs-test-tool
876

DESIGN/INTERNALS OF LIBGUESTFS

878       See also guestfs-internals(1).
879
880   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
886       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
896       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
906   Why don’t you do everything through GVFS?
907       The problems are similar to the problems with FUSE.
908
909       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
915   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
921       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
926       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
932       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
936       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
940   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
944       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
948   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
953       See also the next question.
954
955   Why can’t I run fsck on a live filesystem using "guestfish --ro"?
956       This command will usually not work:
957
958        guestfish --ro -a /dev/vg/my_root_fs run : fsck /dev/sda
959
960       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
967       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
973       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
977   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
981        $ guestfish --ro -a guest.img
982        ><fs> run
983        ><fs> fsck /dev/sda1
984
985        $ virt-rescue --ro guest.img
986        ><rescue> /sbin/fsck /dev/sda1
987
988       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
992       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
999       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
1004       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
1009        ><fs> debug sh "cmd arg1 arg2 ..."
1010
1011       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
1015   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
1022       At the guestfs(3) API level, a "disk image" is just a pile of
1023       partitions and filesystems.
1024
1025       In contrast, when the virtual machine boots, it mounts those
1026       filesystems into a consistent hierarchy such as:
1027
1028        /          (/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
1038       (or drive letters on Windows).
1039
1040       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
1045       Users expect some tools (like virt-cat(1)) to work with VM paths:
1046
1047        virt-cat fedora.img /var/log/messages
1048
1049       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
1053       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
1058       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
1063       If you use the -i option, libguestfs performs inspection and mounts the
1064       filesystems for you.
1065
1066       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
1072   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
1076       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
1082       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

DEVELOPERS

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
1095       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
1100   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
1107       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
1111   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
1116       https://www.redhat.com/archives/libguestfs/2012-January/msg00023.html
1117
1118   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

MISCELLANEOUS QUESTIONS

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
1130                   ┌─────────────────────────────────────┐
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
1144       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
1148       i.  The VM kernel (1) can cache data in memory, so it doesn't appear in
1149           the disk image.
1150
1151       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
1155       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
1161       There are some unsupported hacks you can try if relaunching the
1162       appliance is really too costly:
1163
1164       ·   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
1168           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
1173       ·   Use a tool like virt-bmap instead.
1174
1175       ·   Run an agent inside the guest.
1176
1177       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
1181       (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

SEE ALSO

1186       guestfish(1), guestfs(3), http://libguestfs.org/.
1187

AUTHORS

1189       Richard W.M. Jones ("rjones at redhat dot com")
1190
1192       Copyright (C) 2012-2019 Red Hat Inc.
1193

LICENSE

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
1200       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
1205       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

BUGS

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
1214       To report a new bug against libguestfs, use this link:
1215       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
1216
1217       When reporting a bug, please supply:
1218
1219       ·   The version of libguestfs.
1220
1221       ·   Where you got libguestfs (eg. which Linux distro, compiled from
1222           source, etc)
1223
1224       ·   Describe the bug accurately and give a way to reproduce it.
1225
1226       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
1227           into the bug report.
1228
1229
1230
1231libguestfs-1.40.1                 2019-01-17                    guestfs-faq(1)
Impressum