guestfs-faq(1) Virtualization Support guestfs-faq(1) (NAME) guestfs-faq - libguestfs (FAQ) LIBGUESTFS (ABOUT LIBGUESTFS) libguestfs libguestfs . . . libguestfs C ( <>) (bindings) . libguestfs (http://libguestfs.org) . virt virt (: http://virt-tools.org) . libguestfs libvirt . virt tools libguestfs . libguestfs . http://libguestfs.org . libguestfs { libvirt / KVM / Red Hat / Fedora } ! libvirt libguestfs . libguestfs VMware KVM qemu VirtualBox Xen . Red Hat libguestfs ( ). libguestfs virt Mac OS X . . virt Windows . libguestfs kpartx Libguestfs kpartx . kpartx (root) (mount) ( - guestfs-security(1) ). Libguestfs LVM (root) . Libguestfs . vdfuse vdfuse kpartx VirtualBox . kpartx . libguestfs vdfuse libguestfs VirtualBox . qemu-nbd NBD (Network Block Device) . qemu-nbd () NBD qemu ( raw qcow2) . libguestfs qemu-nbd nbdkit : "guestfish -a nbd://remote" . libguestfs . guestmount(1) . parted Libguestfs LVM . Libguestfs parted parted API libguestfs ..SH " (GETTING HELP AND REPORTING BUGS)" : guestfish --version Libguestfs (unstable) (stable) (backport) . "LIBGUESTFS VERSION NUMBERS" guestfs(3) . Red Hat Red Hat Enterprise Linux Red Hat : http://redhat.com/support (mailing list) libguestfs virt : https://lists.libguestfs.org IRC "#guestfs" Libera Chat . . virt ( libguestfs ) virt : https://www.redhat.com/mailman/listinfo/virt-tools-list Bugzilla : https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools . libguestfs-test-tool(1) . (COMMON PROBLEMS) "LIBGUESTFS GOTCHAS" guestfs(3) API libguestfs . "Could not allocate dynamic translator buffer" SELinux . (boolean) SELinux : setsebool -P virt_use_execmem=on : https://bugzilla.redhat.com/show_bug.cgi?id=806106 "child process died unexpectedly" [ libguestfs 1.21.18 .] qemu (host kernel) . : libguestfs-test-tool ( ). libguestfs: error: cannot find any suitable libguestfs supermin, fixed or old-style appliance on LIBGUESTFS_PATH febootstrap-supermin-helper: ext2: parent directory not found supermin-helper: ext2: parent directory not found [ libguestfs >= 1.26 .] Debian/Ubuntu : sudo update-guestfs-appliance "Permission denied" libguestfs (root) (disk image) libguestfs (root) (permission denied) . libvirt libvirt . libvirt appliance qemu "qemu.qemu" . qemu root root . libvirt : https://bugzilla.redhat.com/show_bug.cgi?id=1045069 : o (direct backend): export LIBGUESTFS_BACKEND=direct o libguestfs (root). o (chmod) qemu . o ( ) /etc/libvirt/qemu.conf "user". execl: /init: Permission denied : libguestfs ( Fedora Debian ) . . supermin appliance : supermin: mounting new root on /root supermin: chroot execl: /init: Permission denied supermin: debug: listing directory / [...followed by a lot of debug output...] appliance supermin(1) . appliance /bin/bash . "hostfiles" appliance . () /bin/bash . /bin/bash : ldd /bin/bash "hostfiles" . . /init /bin/bash ( appliance) (executable) . (file modes) ..SH " LIBGUESTFS (DOWNLOADING, INSTALLING, COMPILING LIBGUESTFS)" ... Fedora >= 11 : yum install '*guestf*' : http://koji.fedoraproject.org/koji/packageinfo?packageID=8391 Red Hat Enterprise Linux RHEL 6 RHEL 7 . RHEL 6 7 "libguestfs-winsupport" Windows . Debian Ubuntu libguestfs < 1.26 libguestfs : sudo update-guestfs-appliance ( Debian/Ubuntu libguestfs >= 1.26 .) Ubuntu: sudo chmod 0644 /boot/vmlinuz* "kvm" : sudo usermod -a -G kvm yourlogin Debian Squeeze (6) Hilko Bengen libguestfs squeeze backports : http://packages.debian.org/search?keywords=guestfs&searchon=names§ion=all&suite=squeeze-backports Debian Wheezy (+7) Hilko Bengen libguestfs Debian . Debian : http://packages.debian.org/search?keywords=libguestfs Ubuntu Ubuntu Canonical ( ) . Canonical (root) . (https://bugs.launchpad.net/ubuntu/+source/linux/+bug/759725). : sudo chmod 0644 /boot/vmlinuz* Ubuntu 12.04 libguestfs Ubuntu febootstrap seabios . febootstrap >= 3.14-2 : http://packages.ubuntu.com/precise/febootstrap febootstrap : sudo update-guestfs-appliance seabios >= 0.6.2-0ubuntu2.1 >= 0.6.2-0ubuntu3 : http://packages.ubuntu.com/precise-updates/seabios http://packages.ubuntu.com/quantal/seabios ( ): sudo chmod 0644 /boot/vmlinuz* Gentoo Libguestfs 2012-07 Andreis Vinogradovs ( libguestfs) Maxim Koltsov ( hivex) Gentoo . : emerge libguestfs Mageia Libguestfs 2013-08 Mageia . : urpmi libguestfs SuSE Libguestfs Olaf Hering SuSE . ArchLinux Libguestfs AUR . ( ). ..SS " libguestfs " libguestfs git tarball . README . Git: https://github.com/libguestfs/libguestfs (tarballs): http://libguestfs.org/download "make install" ! "./run" (README ). qemu/supermin/kernel libguestfs libguestfs supermin 5 . supermin 5 . qemu supermin / kernel . "make install" . libguestfs . "localconfigure" : source localenv #export PATH=/tmp/qemu/x86_64-softmmu:$PATH ./configure --prefix /usr "$@" "localconfigure" . "localenv" : #export SUPERMIN=/tmp/supermin/src/supermin #export LIBGUESTFS_HV=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64 #export SUPERMIN_KERNEL=/tmp/linux/arch/x86/boot/bzImage #export SUPERMIN_KERNEL_VERSION=4.XX.0 #export SUPERMIN_MODULES=/tmp/lib/modules/4.XX.0 . "./configure" "./localconfigure" libguestfs . "make install" ! "./run" (README ). libguestfs supermin supermin 5 supermin . supermin 5 << appliance >> (fixed appliance method) appliance . libguestfs supermin "--disable-appliance --disable-daemon" ./configure ./configure ( git tarball). libguestfs "LIBGUESTFS_PATH" appliance "FIXED APPLIANCE" guestfs-internals(1) . appliance : http://libguestfs.org/download/binaries/appliance (Patches) supermin . sVirt Fedora/RHEL: Fedora 18 RHEL 7 . . sVirt SELinux appliance (hardened) (escape) libguestfs ( libguestfs sVirt ). sVirt libvirt .. ( . ) libguestfs . SELinux Fedora . Fedora 18+ SELinux - . : ./configure --with-default-backend=libvirt # libguestfs >= 1.22 ./configure --with-default-attach-method=libvirt # libguestfs <= 1.20 make SELinux Enforcing sVirt . libguestfs sVirt . : virt-rescue(1) libvirt ( sVirt) qemu . virt-rescue sVirt . libvirtd ( /etc/libvirt/libvirtd.log ) libvirtd "Setting SELinux context on ..." sVirt . sVirt AppArmor . libvirt AppArmor . libguestfs ! : 1. libguestfs . XFS XFS . 2. (Language bindings) . ( C) . 3. . libguestfs >= 1.26 appliance ( ) XFS "libguestfs-xfs" . libguestfs ..SS " Fedora >= 18 RHEL >= 7" Fedora >= 18 RHEL >= 7 libguestfs libvirt appliance . ( upstream) libguestfs qemu : | libguestfs | | direct backend | libvirt backend | v v | qemu | | libvirtd | v | qemu | upstream Fedora 18+ non-Fedora RHEL 7+ non-RHEL libvirt SELinux/sVirt ( ) . . libvirt : export LIBGUESTFS_BACKEND=direct libguestfs virt direct . appliance / libguestfs Fedora RHEL . libguestfs (root) : mkdir -p /usr/local/lib/guestfs/appliance libguestfs-make-fixed-appliance /usr/local/lib/guestfs/appliance ls -l /usr/local/lib/guestfs/appliance libguestfs virt : export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance . appliance ( x86-64) libvirt appliance NFS ( direct NFS ). libguestfs Squid . Squid . Squid : https://fedoraproject.org/wiki/Extras/MockTricks#Using_Squid_to_Speed_Up_Mock_package_downloads Squid $http_proxy $ftp_proxy . Squid appliance . libguestfs (Debian) (Hilko Bengen) "approx" (http://packages.debian.org/approx). approx(8) . LIBGUESTFS (SPEED, DISK SPACE USED BY LIBGUESTFS) : : guestfs-performance(1). . ( sparse raw qcow2) . non-sparse raw qcow2 "preallocation=metadata". Libguestfs ! libguestfs appliance : /var/tmp/.guestfs- "TMPDIR" $TMPDIR/.guestfs- . libguestfs . virt-sparsify virt-sparsify(1) raw raw sparse . (sparseness) "du -sh". : $ ls -lh test1.img -rw-rw-r--. 1 rjones rjones 100M Aug 8 08:08 test1.img $ du -sh test1.img 3.6M test1.img ( 100M 3.6M ) --convert (non-sparse) : virt-sparsify --convert qcow2 disk.raw disk.qcow2 -- . . . virt-resize (in-place) : ( ) LVM ( LV ). . "qemu-img create" + "virt-resize" qemu . . virt-sparsify (in-place) libguestfs . (libguestfs >= 1.26) virt-sparsify . : virt-sparsify --in-place disk.img "IN-PLACE SPARSIFICATION" virt-sparsify(1) . (PROBLEMS OPENING DISK IMAGES) libvirt . libvirt . : guestfish -c qemu://remote/system -d Guest (export) . NBD : remote$ qemu-nbd -t -p 10809 guest.img local$ guestfish -a nbd://remote:10809 -i ssh ( qemu ) NFS iSCSI . "REMOTE STORAGE" guestfs(3) . / HTTP / REST / API . ( glance OpenStack .) nbdkit (https://github.com/libguestfs/nbdkit) . NBD . Libguestfs NBD : guestfish -a nbd://remote nbdkit / . API API . VMDK: "uses a vmdk feature which is not supported by this qemu version: VMDK version 3" Qemu ( libguestfs) VMDK . . qemu VMDK : 1. ESX somename-flat.vmdk . (raw) . qemu libguestfs HTTPS ssh . "REMOTE STORAGE" guestfs(3) . 2. vdiskmanager VMware (raw) . 3. nbdkit VDDK (live export) NBD . VMDK . UFS ( BSD) . UFS (self-identifying) . UFS libguestfs . "ufstype" . https://www.kernel.org/doc/Documentation/filesystems/ufs.txt . Windows ReFS Windows ReFS ZFS/Btrfs . libguestfs . . ASCII VFAT . : o ASCII ( ) . VFAT . o VFAT . / (GNU/Linux) . VFAT UTF-16 . . UTF-8 (locales) UTF-8 ( libc ). . : "iocharset" ( libguestfs ) "utf8". VFAT "utf8" . guestfish : > mount-options utf8 /dev/sda1 / guestfish: guestfish [...] -m /dev/sda1:/:utf8 API: guestfs_mount_options (g, "utf8", "/dev/sda1", "/"); UTF-8 . : o "utf8" . . o "iocharset" "utf8" . ..SS " ASCII ISO9660 (_) ." mkisofs genisoimage . Joliet / Rock Ridge . libguestfs (mount) . (Windows) NTFS . : mount: unknown filesystem type 'ntfs' Red Hat Enterprise Linux CentOS < 7.2 libguestfs-winsupport . RHEL >= 7.2 "libguestfs-winsupport" RHEL . "mount: unsupported filesystem type" NTFS RHEL >= 7.2 RHEL 7.2 "libguestfs-winsupport" RHEL . virt-v2v(1) . guestfish(1) guestmount(1) NTFS : mount: unsupported filesystem type RHEL . "CLOSED -> WONTFIX" . libguestfs Red Hat . RHEL 7. XFS . RHEL 7 XFS libguestfs "libguestfs-xfs" . LIBGUESTFS (USING LIBGUESTFS IN YOUR OWN PROGRAMS) API API : "API OVERVIEW" guestfs(3). API C API API : C guestfs_ln_sf (g, target, linkname); Python g.ln_sf (target, linkname); OCaml g#ln_sf target linkname; Perl $g->ln_sf (target, linkname); Shell (guestfish) ln-sf target linkname PHP guestfs_ln_sf ($g, $target, $linkname); API (bindings) : "USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES" guestfs(3). libguestfs / / . - libguestfs . "COPYING.LIB" ( LGPLv2+ ) "COPYING" ( GPLv2+ ) . LIBGUESTFS (DEBUGGING LIBGUESTFS) ! libguestfs "guestfs@lists.libguestfs.org" : libguestfs-test-tool "libguestfs" @ "redhat.com" : 1. 2. () 3. 4. . . export LIBGUESTFS_DEBUG=1 export LIBGUESTFS_TRACE=1 5. libguestfs libguestfs ( "yum install" ) . libguestfs ( virt-customize virt-df) "LIBGUESTFS_*" libguestfs . "LIBGUESTFS_TRACE" 1 libguestfs / API guestfish . "LIBGUESTFS_DEBUG" 1 . appliance libguestfs . : export LIBGUESTFS_TRACE=1 export LIBGUESTFS_DEBUG=1 csh/tcsh : setenv LIBGUESTFS_TRACE 1 setenv LIBGUESTFS_DEBUG 1 : "ENVIRONMENT VARIABLES" guestfs(3)..SS " guestfish " . guestfish -x ( ) -v ( ) . : guestfish(1). API "guestfs_set_trace" guestfs(3) / "guestfs_set_verbose" guestfs(3) . (handle) guestfs launch. API (event API) . : "SETTING CALLBACKS TO HANDLE EVENTS" guestfs(3) examples/debug-logging.c libguestfs. . : guestfs-internals(1). libguestfs run/launch . . libguestfs-test-tool(1) . libvirt libvirt libvirt /etc/libvirt/libvirtd.conf . (non-root) . ~/.config/libvirt/libvirtd.conf : log_level=1 log_outputs="1:file:/tmp/libvirtd.log" libvirtd () (kill ) libguestfs libvirtd /tmp/libvirtd.log . . supermin : export SUPERMIN_KERNEL_VERSION=4.8.0-1.fc25.x86_64 export SUPERMIN_KERNEL=/boot/vmlinuz-$SUPERMIN_KERNEL_VERSION export SUPERMIN_MODULES=/lib/modules/$SUPERMIN_KERNEL_VERSION rm -rf /var/tmp/.guestfs-* libguestfs-test-tool qemu qemu . qemu : export LIBGUESTFS_HV=/path/to/qemu-system-x86_64 libguestfs-test-tool / LIBGUESTFS (DESIGN/INTERNALS OF LIBGUESTFS) : guestfs-internals(1). FUSE / guestmount(1) (mount) . FUSE . API libguestfs . libguestfs API (logical volumes) . : "mkdir /fs/hda1" ( "echo 100M > /fs/hda1/.size") API API . . FUSE FUSE . guestmount libguestfs ( ) . . API libguestfs (streaming) "guestfs_download" "guestfs_tar_out" . GVFS FUSE . GVFS POSIX/FUSE . FTP GVFS FTP API libguestfs . FTP GVFS libguestfs . "--ro" (read-only) libguestfs (overlay) . ( "guestfish" ) . : ( IDE IDE libguestfs ). . "mount -o ro" . / (dirty) . . . libguestfs ( "tests/qemu"). . "--ro" ! "--ro" "-a" "-d". guestfish "add" - ( "readonly:true" ). "guestfish --ro" . : https://www.redhat.com/archives/libguestfs/2010-August/msg00024.html . fsck "guestfish --ro" : guestfish --ro -a /dev/vg/my_root_fs run : fsck /dev/sda qemu (point-in-time) . qemu fsck . fsck ( !) . . LVM2 . btrfs/ZFS btrfs/ZFS fsck . libguestfs -- /sbin/fsck . libguestfs libguestfs ..SS " guestfish virt-rescue " : $ guestfish --ro -a guest.img > run > fsck /dev/sda1 $ virt-rescue --ro guest.img > /sbin/fsck /dev/sda1 guestfish --options ( virt-rescue(1) ). guestfish(1) API guestfs(3) . . . guestfish ( API libguestfs) . virt-rescue(1) libguestfs VM . (ad-hoc) . libguestfs << >> (backdoor) . virt-rescue : > debug sh "cmd arg1 arg2 ..." . . API libguestfs . "guestfish -i" virt-cat VM virt-df "no root device found in this operating system image" . API guestfs(3) << >> . (mount) : / (/dev/sda2) | /boot (/dev/sda1) | /home (/dev/vg_external/Homes) | /usr (/dev/vg_os/lv_usr) | /var (/dev/vg_os/lv_var) ( Windows). API << >> . (inspect) : "INSPECTION" guestfs(3) . ( virt-cat(1)) VM : virt-cat fedora.img /var/log/messages virt-cat /var virt-cat . ( virt-cat(1) virt-edit(1) virt-ls(1)) VM . virt-df(1) virt-filesystems(1) << >> API libguestfs . guestfish(1) . -a -m guestfish . API . -i libguestfs . "no root device found in this operating system image" . . virt-cat . "debug*" "internal-*" API . "debug*" ( "guestfs_debug*") "guestfs_debug" guestfs(3) libguestfs . API libguestfs . "internal-*" ( "guestfs_internal_*") libguestfs . . API ..SH " (DEVELOPERS)" libguestfs https://lists.libguestfs.org . . pull request github - . () () pull request github merge commit . (https://lists.libguestfs.org). libguestfs . ( <> ) "RFE: " (Summary) . libguestfs commit github . ACK . ACK push : https://www.redhat.com/archives/libguestfs/2012-January/msg00023.html libguestfs . Git libguestfs . Github . . (MISCELLANEOUS QUESTIONS) libguestfs libguestfs . Libguestfs : | monitoring program using libguestfs | v | live VM | | libguestfs appliance | | kernel (1)| | appliance kernel (2) | v v (r/o connection) | disk image | ( "readonly" ). libguestfs appliance (2) disk image : i. VM (1) disk image . ii. libguestfs appliance (2) disk image VM (1) . disk image libguestfs appliance . API "guestfs_shutdown" "guestfs_launch" ( : guestfs-performance(3)). appliance : o "guestfs_drop_caches (g, 3)". libguestfs appliance (2) disk image . qemu . libguestfs "cache=none" () . : https://rwmj.wordpress.com/2013/09/02/new-in-libguestfs-allow-cache-mode-to-be-selected o virt-bmap . o agent . ( ) . appliance . ( (consistent snapshots) libguestfs .) (SEE ALSO) guestfish(1), guestfs(3), http://libguestfs.org (AUTHORS) Richard W.M. Jones ("rjones at redhat dot com") (COPYRIGHT) Copyright (C) 2012-2025 Red Hat Inc. (LICENSE) (GNU Lesser General Public License) ( ) . . GNU Lesser General Public License . GNU Lesser General Public License : Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.SH " (BUGS)" libguestfs : https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools libguestfs : https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools : o libguestfs. o libguestfs ( ). o . o libguestfs-test-tool(1) . libguestfs-1.60.1 2026-07-14 guestfs-faq(1)