guestfs-faq (1) - Linux Manuals

vs. kpartx

"guestfish -a nbd://remote"
 guestfish --version

"#libguestfs"
 setsebool -P virt_use_execmem=on

 libguestfs-test-tool

 sudo update-guestfs-appliance

"qemu.qemu"
 export LIBGUESTFS_BACKEND=direct

"user"
 supermin: mounting new root on /root
 supermin: chroot
 execl: /init: Permission denied
 supermin: debug: listing directory /
 [...followed by a lot of debug output...]

"hostfiles"
 ldd /bin/bash

"hostfiles"
 yum install '*guestf*'

"libguestfs-winsupport"
 sudo update-guestfs-appliance

 sudo chmod 0644 /boot/vmlinuz*

"kvm"
 sudo usermod -a -G kvm yourlogin

 sudo chmod 0644 /boot/vmlinuz*

 sudo update-guestfs-appliance

 sudo chmod 0644 /boot/vmlinuz*

 emerge libguestfs

"make install"
"./run"
"make install"
"localconfigure"
 source localenv
 #export PATH=/tmp/qemu/x86_64-softmmu:$PATH
 ./autogen.sh --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

"./localconfigure"
"./configure"
"make install"
"./run"
"--disable-appliance --disable-daemon"
"LIBGUESTFS_PATH"
 ./configure --with-default-backend=libvirt       # libguestfs >= 1.22
 ./configure --with-default-attach-method=libvirt # libguestfs <= 1.20
 make

"libguestfs-xfs"
 ┌──────────────────────────────────┐
 │ libguestfs                       │
 ├────────────────┬─────────────────┤
 │ direct backend │ libvirt backend │
 └────────────────┴─────────────────┘
        ↓                  ↓
    ┌───────┐         ┌──────────┐
    │ qemu  │         │ libvirtd │
    └───────┘         └──────────┘
                           ↓
                       ┌───────┐
                       │ qemu  │
                       └───────┘
 
    upstream          Fedora 18+
    non-Fedora         RHEL 7+
    non-RHEL

 export LIBGUESTFS_BACKEND=direct

 mkdir -p /usr/local/lib/guestfs/appliance
 libguestfs-make-fixed-appliance /usr/local/lib/guestfs/appliance
 ls -l /usr/local/lib/guestfs/appliance

 export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance

$http_proxy
$ftp_proxy
"preallocation=metadata"
 /var/tmp/.guestfs-<UID>

"TMPDIR"
"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

 virt-sparsify --convert qcow2 disk.raw disk.qcow2

"qemu-img create"
"virt-resize"
 virt-sparsify --in-place disk.img

 guestfish -c qemu://remote/system -d Guest

 remote$ qemu-nbd -t -p 10809 guest.img
  local$ guestfish -a nbd://remote:10809 -i

 guestfish -a nbd://remote

"ufstype"
"iocharset"
"utf8"
"utf8"
 ><fs> mount-options utf8 /dev/sda1 /

 guestfish [...] -m /dev/sda1:/:utf8

 guestfs_mount_options (g, "utf8", "/dev/sda1", "/");

"utf8"
"iocharset"
"utf8"
 mount: unknown filesystem type 'ntfs'

"libguestfs-winsupport"
"libguestfs-winsupport"
 mount: unsupported filesystem type

"CLOSED -> WONTFIX"
"libguestfs-xfs"
                  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);

"COPYING.LIB"
"COPYING"
"libguestfs"
"redhat.com"
 libguestfs-test-tool

"libguestfs"
"redhat.com"
 export LIBGUESTFS_DEBUG=1
 export LIBGUESTFS_TRACE=1

"yum install"
"LIBGUESTFS_*"
 export LIBGUESTFS_TRACE=1
 export LIBGUESTFS_DEBUG=1

 setenv LIBGUESTFS_TRACE 1
 setenv LIBGUESTFS_DEBUG 1

 log_level=1
 log_outputs="1:file:/tmp/libvirtd.log"

 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

 export LIBGUESTFS_HV=/path/to/qemu-system-x86_64
 libguestfs-test-tool

"mkdir /fs/hda1"
"echo 100M >
/fs/hda1/.size"
"guestfs_download"
"guestfs_tar_out"
"guestfish"
"mount -o ro"
"tests/qemu"
"--ro"
"-a"
"-d"
"add"
"readonly:true"
 guestfish --ro -a /dev/vg/my_root_fs run : fsck /dev/sda

 $ guestfish --ro -a guest.img
 ><fs> run
 ><fs> fsck /dev/sda1

 $ virt-rescue --ro guest.img
 ><rescue> /sbin/fsck /dev/sda1

 ><fs> debug sh "cmd arg1 arg2 ..."

 /          (/dev/sda2)
 │
 ├── /boot  (/dev/sda1)
 │
 ├── /home  (/dev/vg_external/Homes)
 │
 ├── /usr   (/dev/vg_os/lv_usr)
 │
 └── /var   (/dev/vg_os/lv_var)

 virt-cat fedora.img /var/log/messages

"no root device found in this operating system image"
"debug*"
"guestfs_debug*"
"internal-*"
"guestfs_internal_*"
"RFE: "
            ┌─────────────────────────────────────┐
            │ monitoring program using libguestfs │
            └─────────────────────────────────────┘
                             ↓
 ┌───────────┐    ┌──────────────────────┐
 │ live VM   │    │ libguestfs appliance │
 ├───────────┤    ├──────────────────────┤
 │ kernel (1)│    │ appliance kernel (2) │
 └───────────┘    └──────────────────────┘
      ↓                      ↓ (r/o connection)
      ┌──────────────────────┐
      |      disk image      |
      └──────────────────────┘

"readonly"
"guestfs_shutdown"
"guestfs_launch"
"guestfs_drop_caches (g, 3)"
"cache=none"
"rjones at redhat dot com"

guestfs-faq (1) - Linux Manuals

guestfs-faq: libguestfs Frequently Asked Questions (FAQ)

NAME

ABOUT LIBGUESTFS

What is libguestfs?

What are the virt tools?

Does libguestfs need { libvirt / KVM / Red Hat / Fedora }?

How does libguestfs compare to other tools?

GETTING HELP AND REPORTING BUGS

How do I know what version I'm using?

How can I get help?

What mailing lists or chat rooms are available?

How do I report bugs?

COMMON PROBLEMS

Could not allocate dynamic translator buffer

child process died unexpectedly

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

Permission denied when running libguestfs as root

execl: /init: Permission denied

DOWNLOADING, INSTALLING, COMPILING LIBGUESTFS

Where can I get the latest binaries for ...?

How can I compile and install libguestfs from source?

How can I compile and install libguestfs if my distro doesn't have new enough qemu/supermin/kernel?

How can I compile and install libguestfs without supermin?

How can I add support for sVirt?

Libguestfs has a really long list of dependencies!

Errors during launch on Fedora ≥ 18, RHEL ≥ 7

How can I switch to a fixed / prebuilt appliance?

How can I speed up libguestfs builds?

SPEED, DISK SPACE USED BY LIBGUESTFS

Upload or write seem very slow.

Libguestfs uses too much disk space!

virt-sparsify seems to make the image grow to the full size of the virtual disk

Why doesn't virt-resize work on the disk image in-place?

Why doesn't virt-sparsify work on the disk image in-place?

PROBLEMS OPENING DISK IMAGES

Remote libvirt guests cannot be opened.

How can I open this strange disk source?

Error opening VMDK disks: uses a vmdk feature which is not supported by this qemu version: VMDK version 3

UFS disks (as used by BSD) cannot be opened.

Windows ReFS

Non-ASCII characters don’t appear on VFAT filesystems.

Non-ASCII characters appear as underscore (_) on ISO9660 filesystems.

Cannot open Windows guests which use NTFS.

mount: unsupported filesystem type with NTFS in RHEL ≥ 7.2

Cannot open or inspect RHEL 7 guests.

Cannot open Linux guests which use XFS.

USING LIBGUESTFS IN YOUR OWN PROGRAMS

The API has hundreds of methods, where do I start?

Can I use libguestfs in my proprietary / closed source / commercial program?

DEBUGGING LIBGUESTFS

Help, it’s not working!

How do I debug when using any libguestfs program or tool (eg. virt-v2v or virt-df)?

How do I debug when using guestfish?

How do I debug when using the API?

How do I capture debug output and put it into my logging system?

Digging deeper into the appliance boot process.

libguestfs hangs or fails during run/launch.

Debugging libvirt

Broken kernel, or trying a different kernel.

Broken qemu, or trying a different qemu.

DESIGN/INTERNALS OF LIBGUESTFS

Why don’t you do everything through the FUSE / filesystem interface?

Why don’t you do everything through GVFS?

Why can I write to the disk, even though I added it read-only?

Why does --ro appear to have no effect?

Does --ro make all disks read-only?

Can I use guestfish --ro as a way to backup my virtual machines?

Why can’t I run fsck on a live filesystem using guestfish --ro?

What’s the difference between guestfish and virt-rescue?

What’s the deal with guestfish -i?

Why does virt-cat only work on a real VM image, but virt-df works on any disk image?

What does no root device found in this operating system image mean?

What do these debug* and internal-* functions do?

DEVELOPERS

Where do I send patches?

How do I propose a feature?

Who can commit to libguestfs git?