NAME¶
guestfs-faq - libguestfs Frequently Asked Questions (FAQ)
ABOUT LIBGUESTFS¶
What is libguestfs?¶
libguestfs is a way to create, access and modify disk images. You can look
inside disk images, modify the files they contain, create them from scratch,
resize them, and much more. It's especially useful from scripts and programs
and from the command line.
libguestfs is a C library (hence "lib-"), and a set of tools built on
this library, and a set of bindings in many different programming languages.
For more information about what libguestfs can do read the introduction on the
home page (<
http://libguestfs.org>).
Virt tools (website:
http://virt-tools.org <
http://virt-tools.org>) are a
whole set of virtualization management tools aimed at system administrators.
Some of them come from libguestfs, some from libvirt and many others from
other open source projects. So virt tools is a superset of libguestfs. However
libguestfs comes with many important tools. See <
http://libguestfs.org>
for a full list.
Does libguestfs need { libvirt / KVM / Red Hat / Fedora }?¶
No!
libvirt is not a requirement for libguestfs.
libguestfs works with any disk image, including ones created in VMware, KVM,
qemu, VirtualBox, Xen, and many other hypervisors, and ones which you have
created from scratch.
Red Hat sponsors (ie. pays for) development of libguestfs and a huge number of
other open source projects. But you can run libguestfs and the virt tools on
many different Linux distros and Mac OS X. Some virt tools have been ported to
Windows.
- vs. kpartx
- Libguestfs takes a different approach from kpartx. kpartx
needs root, and mounts filesystems on the host kernel (which can be
insecure - see "SECURITY" in guestfs(3)). Libguestfs
isolates your host kernel from guests, is more flexible, scriptable,
supports LVM, doesn't require root, is isolated from other processes, and
cleans up after itself. Libguestfs is more than just file access because
you can use it to create images from scratch.
- vs. vdfuse
- vdfuse is like kpartx but for VirtualBox images. See the
kpartx comparison above. You can use libguestfs on the partition files
exposed by vdfuse, although it's not necessary since libguestfs can access
VirtualBox images directly.
- vs. qemu-nbd
- nbd is like kpartx but for qcow2 images. See the kpartx
comparison above. You can use libguestfs and qemu-nbd together for access
to block devices over the network.
- vs. mounting filesystems in the host
- Mounting guest filesystems in the host is insecure and
should be avoided completely for untrusted guests. Use libguestfs to
provide a layer of protection against filesystem exploits. See also
guestmount(1).
- vs. parted
- Libguestfs supports LVM. Libguestfs uses parted and
provides most parted features through the libguestfs API.
GETTING HELP AND REPORTING BUGS¶
How do I know what version I'm using?¶
The simplest method is:
guestfish --version
Libguestfs development happens along an unstable branch and we periodically
create a stable branch which we backport stable patches to. To find out more,
read "LIBGUESTFS VERSION NUMBERS" in
guestfs(3).
How can I get help? What mailing lists or chat rooms are
available?¶
If you are a Red Hat customer using Red Hat Enterprise Linux, please contact Red
Hat Support: <
http://redhat.com/support>
There is a mailing list, mainly for development, but users are also welcome to
ask questions about libguestfs and the virt tools:
<
https://www.redhat.com/mailman/listinfo/libguestfs>
You can also talk to us on IRC channel "#libguestfs" on FreeNode.
We're not always around, so please stay in the channel after asking your
question and someone will get back to you.
For other virt tools (not ones supplied with libguestfs) there is a general virt
tools mailing list:
https://www.redhat.com/mailman/listinfo/virt-tools-list
<
https://www.redhat.com/mailman/listinfo/virt-tools-list>
How do I report bugs?¶
Please use the following link to enter a bug in Bugzilla:
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
Include as much detail as you can and a way to reproduce the problem.
Include the full output of
libguestfs-test-tool(1).
COMMON ERRORS¶
"child process died unexpectedly"¶
This error indicates that qemu failed or the host kernel could not boot. To get
further information about the failure, you have to run:
libguestfs-test-tool
If, after using this, you still don't understand the failure, contact us (see
previous section).
COMMON PROBLEMS¶
See also "LIBGUESTFS GOTCHAS" in
guestfs(3) for some
"gotchas" with using the libguestfs API.
Non-ASCII characters don't appear on VFAT filesystems.¶
Typical symptoms of this problem:
- •
- You get an error when you create a file where the filename
contains non-ASCII characters, particularly non 8-bit characters from
Asian languages (Chinese, Japanese, etc). The filesystem is VFAT.
- •
- When you list a directory from a VFAT filesystem, filenames
appear as question marks.
This is a design flaw of the GNU/Linux system.
VFAT stores long filenames as UTF-16 characters. When opening or returning
filenames, the Linux kernel has to translate these to some form of 8 bit
string. UTF-8 would be the obvious choice, except for Linux users who persist
in using non-UTF-8 locales (the user's locale is not known to the kernel
because it's a function of libc).
Therefore you have to tell the kernel what translation you want done when you
mount the filesystem. The two methods are the "iocharset" parameter
(which is not relevant to libguestfs) and the "utf8" flag.
So to use a VFAT filesystem you must add the "utf8" flag when
mounting. From guestfish, use:
><fs> mount-options utf8 /dev/sda1 /
or on the guestfish command line:
guestfish [...] -m /dev/sda1:/:utf8
or from the API:
guestfs_mount_options (g, "utf8", "/dev/sda1", "/");
The kernel will then translate filenames to and from UTF-8 strings.
We considered adding this mount option transparently, but unfortunately there
are several problems with doing that:
- •
- On some Linux systems, the "utf8" mount option
doesn't work. We don't precisely understand what systems or why, but this
was reliably reported by one user.
- •
- It would prevent you from using the "iocharset"
parameter because it is incompatible with "utf8". It is probably
not a good idea to use this parameter, but we don't want to prevent
it.
Non-ASCII characters appear as underscore (_) on ISO9660
filesystems.¶
The filesystem was not prepared correctly with mkisofs or genisoimage. Make sure
the filesystem was created using Joliet and/or Rock Ridge extensions.
libguestfs does not require any special mount options to handle the
filesystem.
DOWNLOADING, INSTALLING, COMPILING LIBGUESTFS¶
Where can I get the latest binaries for ...?¶
- Fedora ≥ 11, RHEL ≥ 5.3, EPEL 5
- Use:
yum install '*guestf*'
For the latest builds, see:
<http://koji.fedoraproject.org/koji/packageinfo?packageID=8391>
- Red Hat Enterprise Linux 6
- It is part of the default install. On RHEL 6 (only) you
have to install "libguestfs-winsupport" to get Windows guest
support.
- RHEL 6.3
- Preview packages are available here:
http://people.redhat.com/~rjones/libguestfs-RHEL-6.3-preview/
<http://people.redhat.com/~rjones/libguestfs-RHEL-6.3-preview/>
- Debian Squeeze (6)
- Use Hilko Bengen's backport repository:
<http://people.debian.org/~bengen/libguestfs/>
- Debian Wheezy and later (7+)
- Official Debian packages are available:
<http://packages.debian.org/search?keywords=libguestfs> (thanks
Hilko Bengen).
- Ubuntu
- We don't have an Ubuntu maintainer, and the packages
supplied by Canonical (which are outside our control) are often broken.
Try compiling from source (next section).
Canonical decided to change the permissions on the kernel so that it's not
readable except by root. This is completely stupid, but they won't change
it (<https://bugs.launchpad.net/ubuntu/+source/linux/+bug/759725>).
So every user should do this:
sudo chmod 0644 /boot/vmlinuz*
- Ubuntu 10.04
- See:
http://libguestfs.org/download/binaries/ubuntu1004-packages/
<http://libguestfs.org/download/binaries/ubuntu1004-packages/>
- Ubuntu 12.04
- libguestfs in this version of Ubuntu works, but you need to
update febootstrap and seabios to the latest versions.
You need febootstrap ≥ 3.14-2 from:
<http://packages.ubuntu.com/precise/febootstrap>
You need seabios ≥ 0.6.2-0ubuntu2.1 or ≥ 0.6.2-0ubuntu3 from:
http://packages.ubuntu.com/precise-updates/seabios
<http://packages.ubuntu.com/precise-updates/seabios> or
<http://packages.ubuntu.com/quantal/seabios>
Also you need to do (see above):
sudo chmod 0644 /boot/vmlinuz*
- Other Linux distro
- Compile from source (next section).
- Other non-Linux distro
- You'll have to compile from source, and port it.
How can I compile and install libguestfs from source?¶
If your Linux distro has a working port of febootstrap (that is, Fedora, Red Hat
Enterprise Linux >= 6.3, Debian, Ubuntu and ArchLinux) then you should just
be able to compile from source in the usual way. Download the latest tarball
from <
http://libguestfs.org/download>, unpack it, and start by reading
the README file.
If you
don't have febootstrap, you will need to use the "fixed
appliance method". See:
<
http://libguestfs.org/download/binaries/appliance/>
Patches to port febootstrap to more Linux distros are welcome.
Why do I get an error when I try to rebuild from the source RPMs
supplied by Red Hat / Fedora?¶
Because of the complexity of building the libguestfs appliance, the source RPMs
provided cannot be rebuilt directly using "rpmbuild" or
"mock".
If you use Koji (which is open source software and may be installed locally),
then the SRPMs can be rebuilt in Koji.
<
https://fedoraproject.org/wiki/Koji>
If you don't have or want to use Koji, then you have to give libguestfs access
to the network so it can download the RPMs for building the appliance. You
also need to set an RPM macro to tell libguestfs to use the network. Put the
following line into a file called "$HOME/.rpmmacros":
%libguestfs_buildnet 1
If you are using mock, do:
mock -D '%libguestfs_buildnet 1' [etc]
Libguestfs has a really long list of dependencies!¶
That's because it does a lot of things.
How can I speed up libguestfs builds?¶
By far the most important thing you can do is to install and properly configure
Squid. Note that the default configuration that ships with Squid is rubbish,
so configuring it is not optional.
A very good place to start with Squid configuration is here:
<
https://fedoraproject.org/wiki/Extras/MockTricks#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.
With Squid running and correctly configured, appliance builds should be reduced
to a few minutes.
SPEED, DISK SPACE USED BY LIBGUESTFS¶
Note: Most of the information in this section has moved:
guestfs-performance(1).
Upload or write seem very slow.¶
In libguestfs < 1.13.16, the mount command ("guestfs_mount" in
guestfs(3)) enabled option "-o sync" implicitly. This causes
very poor write performance, and was one of the main gotchas for new
libguestfs users.
For libguestfs < 1.13.16, replace mount with "mount-options",
leaving the first parameter as an empty string.
You can also do this with more recent versions of libguestfs, but if you know
that you are using libguestfs ≥ 1.13.16 then it's safe to use plain
mount.
If the underlying disk is not fully allocated (eg. sparse raw or qcow2) then
writes can be slow because the host operating system has to do costly disk
allocations while you are writing. The solution is to use a fully allocated
format instead, ie. non-sparse raw, or qcow2 with the
"preallocation=metadata" option.
Libguestfs uses too much disk space!¶
libguestfs caches a large-ish appliance in:
/var/tmp/.guestfs-<UID>
If the environment variable "TMPDIR" is defined, then
"$TMPDIR/.guestfs-<UID>" is used instead.
It is safe to delete this directory when you are not using libguestfs.
USING LIBGUESTFS IN YOUR OWN PROGRAMS¶
The API has hundreds of methods, where do I start?¶
We recommend you start by reading the API overview: "API OVERVIEW" in
guestfs(3).
Although the API overview covers the C API, it is still worth reading even if
you are going to use another programming language, because the API is the
same, just with simple logical changes to the names of the calls:
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);
Once you're familiar with the API overview, you should look at this list of
starting points for other language bindings: "USING LIBGUESTFS WITH OTHER
PROGRAMMING LANGUAGES" in
guestfs(3).
Can I use libguestfs in my proprietary / closed source /
commercial program?¶
In general, yes. However this is not legal advice. You should read the license
that comes with libguestfs, and if you have specific questions about your
obligations when distributing libguestfs, contact a lawyer. In the source tree
the license is in the file "COPYING.LIB" (LGPLv2+ for the library
and bindings) and "COPYING" (GPLv2+ for the standalone programs).
DEBUGGING LIBGUESTFS¶
There are two "LIBGUESTFS_*" environment variables you can set in
order to get more information from libguestfs.
- "LIBGUESTFS_TRACE"
- Set this to 1 and libguestfs will print out each command /
API call in a format which is similar to guestfish commands.
- "LIBGUESTFS_DEBUG"
- Set this to 1 in order to enable massive amounts of debug
messages. If you think there is some problem inside the libguestfs
appliance, then you should use this option.
To set these from the shell, do this before running the program:
export LIBGUESTFS_TRACE=1
export LIBGUESTFS_DEBUG=1
For csh/tcsh the equivalent commands would be:
setenv LIBGUESTFS_TRACE 1
setenv LIBGUESTFS_DEBUG 1
For further information, see: "ENVIRONMENT VARIABLES" in
guestfs(3).
How do I debug when using guestfish?¶
You can use the same environment variables above. Alternatively use the
guestfish options -x (to trace commands) or -v (to get the full debug output),
or both.
For further information, see:
guestfish(1).
How do I debug when using the API?¶
Call "guestfs_set_trace" in
guestfs(3) to enable command
traces, and/or "guestfs_set_verbose" in
guestfs(3) to enable
debug messages.
For best results, call these functions as early as possible, just after creating
the guestfs handle if you can, and definitely before calling launch.
How do I capture debug output and put it into my logging
system?¶
Use the event API. For examples, see: "SETTING CALLBACKS TO HANDLE
EVENTS" in
guestfs(3).
Digging deeper into the appliance boot process.¶
Enable debugging and then read this documentation on the appliance boot process:
"INTERNALS" in
guestfs(3).
libguestfs hangs or fails during run/launch.¶
Enable debugging and look at the full output. If you cannot work out what is
going on, file a bug report, including the
complete output of
libguestfs-test-tool(1).
DESIGN/INTERNALS OF LIBGUESTFS¶
Why don't you do everything through the FUSE / filesystem
interface?¶
We offer a command called
guestmount(1) 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 more complicated than the 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, reading a file in
64 KB chunks is inefficient because each chunk would turn into a single round
trip. In the libguestfs API it is much more efficient to download an entire
file or directory through one of the streaming calls like
"guestfs_download" or "guestfs_tar_out".
Why don't you do everything through GVFS?¶
The problems are similar to the problems with FUSE.
GVFS is a better abstraction than POSIX/FUSE. There is an FTP backend for GVFS,
which is encouraging because FTP is conceptually similar to the libguestfs
API. However the GVFS FTP backend makes multiple simultaneous connections in
order to keep interactivity, which we can't easily do with libguestfs.
Can I use "guestfish --ro" as a way to backup my
virtual machines?¶
Usually this is not a good idea. The question is answered in more detail in this
mailing list posting:
https://www.redhat.com/archives/libguestfs/2010-August/msg00024.html
<
https://www.redhat.com/archives/libguestfs/2010-August/msg00024.html>
What's the difference between guestfish and virt-rescue?¶
A lot of people are confused by the two superficially similar tools we provide:
$ guestfish --ro -a guest.img
><fs> run
><fs> fsck /dev/sda1
$ virt-rescue --ro guest.img
><rescue> /sbin/fsck /dev/sda1
And the related question which then arises is why you can't type in full shell
commands with all the --options in guestfish (but you can in
virt-rescue(1)).
guestfish(1) is a program providing structured access to the
guestfs(3) 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(1) 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.
But, libguestfs also has 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.
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?¶
These questions are all related at a fundamental level which may not be
immediately obvious.
At the
guestfs(3) API level, a "disk image" is just a pile of
partitions and filesystems.
In contrast, when the virtual machine boots, it mounts those filesystems into a
consistent hierarchy such as:
/ (/dev/sda2)
|
+-- /boot (/dev/sda1)
|
+-- /home (/dev/vg_external/Homes)
|
+-- /usr (/dev/vg_os/lv_usr)
|
+-- /var (/dev/vg_os/lv_var)
(or drive letters on Windows).
The API first of all sees the disk image at the "pile of filesystems"
level. But it also has a way to inspect the disk image to see if it contains
an operating system, and how the disks are mounted when the operating system
boots: "INSPECTION" in
guestfs(3).
Users expect some tools (like
virt-cat(1)) to work with VM paths:
virt-cat fedora.img /var/log/messages
How does virt-cat know that "/var" is a separate partition? The trick
is that virt-cat performs inspection on the disk image, and uses that to
translate the path correctly.
Some tools (including
virt-cat(1),
virt-edit(1),
virt-ls(1)) use inspection to map VM paths. Other tools, such as
virt-df(1) and
virt-filesystems(1) operate entirely at the raw
"big pile of filesystems" level of the libguestfs API, and don't use
inspection.
guestfish(1) is in an interesting middle ground. If you use the
-a
and
-m command line options, then you have to tell guestfish exactly
how to add disk images and where to mount partitions. This is the raw API
level.
If you use the
-i option, libguestfs performs inspection and mounts the
filesystems for you.
The error "no root device found in this operating system image" is
related to this. It means inspection was unable to locate an operating system
within the disk image you gave it. You might see this from programs like
virt-cat if you try to run them on something which is just a disk image, not a
virtual machine disk image.
SEE ALSO¶
guestfish(1),
guestfs(3), <
http://libguestfs.org/>.
AUTHORS¶
Richard W.M. Jones ("rjones at redhat dot com")
COPYRIGHT¶
Copyright (C) 2012 Red Hat Inc. <
http://libguestfs.org/>
This library is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option) any
later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
details.
You should have received a copy of the GNU Lesser General Public License along
with this library; if not, write to the Free Software Foundation, Inc., 51
Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA