libguestfs Frequently Asked Questions (FAQ)

<<< Back to the libguestfs home page

• Where can I get the latest binaries for ...?
• libguestfs is too slow to start!
• libguestfs uses too much disk space!
• libguestfs uses too much memory!
• libguestfs hangs or fails in the run / launch / wait_ready commands
• How do I package libguestfs for distro X?
• Do you use virtio in the appliance?
• The API has hundreds of methods, where do I start?
• Why don't you do everything through the FUSE / filesystem interface?
• Is there a binding for Python or (insert other language here)?
• What's the difference between guestfish and virt-rescue?
• Why can't I type full shell commands in guestfish?
• libguestfs has a really long list of dependencies!
• How do I speed up libguestfs builds?

chmod o+rw /dev/kvm

libguestfs works by booting an appliance (like a mini-operating system), and this does take some time. Usually around 15 seconds on a reasonable machine with KVM enabled.

If you find yourself restarting guestfish over and over again, you may find it better to use the remote control feature of guestfish to avoid the start-up costs.

If your distro packager enabled the so-called supermin appliance variant of libguestfs, then libguestfs will use quite a lot of disk space from /tmp for each libguestfs handle. Probably around 70MB-100MB per handle. (It's only used temporarily).

This is unavoidable, but you can place the temporary files somewhere else by setting the TMPDIR environment variable. (Since libguestfs 1.0.63, see this bug).

Nevertheless you can change the amount of memory allocated to the appliance by setting the LIBGUESTFS_MEMSIZE environment variable. Be careful about setting this too small.

export LIBGUESTFS_DEBUG=1

$ guestfish -v

$ libguestfs-test-tool

Usually these problems are caused by the combination of host, qemu and appliance kernel, and are nothing to do with libguestfs. There are various ways you can try to work around these problems, which come down to trying different host, qemu and appliance combinations. Use LIBGUESTFS_QEMU to select other versions of qemu.

To understand the answer, you need to read about the architecture of libguestfs.

Specifically we include an appliance (like a mini-operating system) with libguestfs when it is packaged for Fedora and Debian. And on Fedora and Debian, this appliance gets built on the fly when the libguestfs package itself is built. The two tools we use for this are febootstrap (for Fedora builds) and debootstrap (for Debian builds).

It may not be obvious, but the Fedora libguestfs package ships with a Fedora-based appliance. And the Debian libguestfs package ships with a Debian-based appliance. (For the Ubuntu case, just subtitute "Ubuntu" for "Debian" in the preceeding discussion).

To build for another distro, you need to solve the problem of building the appliance. There are three choices:

1. Your distro has some equivalent bootstrapping tool. You will need to port libguestfs to use your bootstrapping tool. This is how the Debian port was done originally, and is definitely the best, highest quality way to port libguestfs to a new distro.
2. You have debootstrap or febootstrap already for your distro. libguestfs will probably just work with only minimal changes. However you will be shipping a Fedora/Debian appliance along with the libguestfs package. This may or may not be a problem for you and/or your distro.
3. Take the binary appliance blobs built on a Fedora or Debian system and use those. Check the licenses of all the software in the appliance carefully.

If you see a serious performance regression (only for certain operations) when using the virtio block driver then you can try switching to using the IDE (libata) driver for:

./configure --with-drive-if=ide

Note that you will still be able to use names like /dev/sda even with the virtio driver enabled. See the section on block device naming in the manpage.

We recommend you start with the API overview.

Now although this overview covers the C API, it's still worth reading, because all the other languages use the same API, with simple logical changes to the names of the calls:

Once you're familiar with the API overview, you should look at this list of starting points for other language bindings.

We offer a command called guestmount which lets you mount guest filesystems on the host. This is implemented as a FUSE module. Why don't we just implement the whole of libguestfs using this mechanism, instead of having the large and rather complicated API?

The reasons are twofold. Firstly, libguestfs offers API calls for doing things like creating and deleting partitions and logical volumes, which don't fit into a filesystem model very easily. Or rather, you could fit them in: for example, creating a partition could be mapped to mkdir /fs/hda1 but then you'd have to specify some method to choose the size of the partition (maybe echo 100M > /fs/hda1/.size), and the partition type, start and end sectors etc., but once you've done that the filesystem-based API starts to look as complicated or more than the straightforward call-based API we currently have.

The second reason is for efficiency. FUSE itself is reasonably efficient, but it does make lots of small, independent calls into the FUSE module. In guestmount these have to be translated into messages to the libguestfs appliance which has a big overhead (in time and round trips). For example, listing a directory can involve hundreds of round trips (although we try to be as clever as possible by prefetching anticipated data). Making a single libguestfs API call is always more efficient.

We have language bindings for many common programming languages. A full list is on the front page and this link describes how to get started in each language.

One thing you should note about libguestfs is that we prefer to autogenerate as much boilerplate code as possible, and that includes language bindings. Therefore if you wish to add a new programming language to the mix (which is something we welcome) it's best to get that language added to the generator.

Which language did we use to write the generator? OCaml, which is a modern take on ML, a language which has been around since 1974 and was originally designed in order to write compilers, and therefore is very suitable for writing code generation. So you'll need to learn a very little bit of OCaml in order to add your code to the generator.

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

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

guestfish is a program providing structured access to the guestfs API. It happens to be a nice interactive shell too, but its primary purpose is structured access from shell scripts. Think of it more like a language binding, like Python and other bindings, but for shell. The key differentiating factor of guestfish (and the libguestfs API in general) is the ability to automate changes.

virt-rescue is a free-for-all freeform way to boot the libguestfs appliance and make arbitrary changes to your VM. It's not structured, you can't automate it, but for making quick ad-hoc fixes to your guests, it can be quite useful.

See the question above.

But, if libguestfs was configured (at build time) with:

./configure --enable-debug-command

(which is true for all Fedora builds) then there is a "backdoor" into the appliance allowing you to send arbitrary shell commands. It's not as flexible as virt-rescue, because you can't interact with the shell commands, but here it is anyway:

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

Note that you should not rely on this. It could be removed or changed in future. If your program needs some operation, please add it to the libguestfs API instead.

If you're on Fedora and want to build libguestfs from source, a good place to start is to look at all of the BuildRequires lines in the libguestfs spec file. Once you've installed all of those packages, you should be good.

A very good place to start with Squid configuration is here: Using Squid to Speed Up Mock package downloads.

Make sure Squid is running, and that the environment variables $http_proxy and $ftp_proxy are pointing to it.

I have a file /etc/profile.d/local.sh that contains:

export http_proxy=http://192.168.2.1:3128/
export ftp_proxy=$http_proxy

where 192.168.2.1:3128 is the address and port number of my Squid proxy.

With that, the appliance building step should be reduced to a few minutes.

$Id: FAQ.html,v 1.11 2010/02/19 17:01:19 rjones Exp $