guestfs-faq(1) Virtualization Support guestfs-faq(1)NAMEguestfs-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 bindings for many common programming languages.
For more information about what libguestfs can do read the introduction
on the home page (http://libguestfs.org).
What are the virt tools?
Virt tools (website: 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.
How does libguestfs compare to other tools?
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
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 PROBLEMS
See also "LIBGUESTFS GOTCHAS" in guestfs(3) for some "gotchas" with
using the libguestfs API.
"Could not allocate dynamic translator buffer"
This obscure error is in fact an SELinux failure. You have to enable
the following SELinux boolean:
setsebool -P virt_use_execmem=on
For more information see
https://bugzilla.redhat.com/show_bug.cgi?id=806106.
"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).
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 X 11
Use:
yum install '*guestf*'
For the latest builds, see:
http://koji.fedoraproject.org/koji/packageinfo?packageID=8391
Red Hat Enterprise Linux
RHEL 5
Use the package from EPEL 5:
https://fedoraproject.org/wiki/EPEL
RHEL 6.2-6.4
It is part of the default install. On RHEL 6 (only) you have
to install "libguestfs-winsupport" to get Windows guest
support.
RHEL 7
It will be part of the default install, and based on libguestfs
1.20 or 1.22. As with RHEL 6 you will need to install
"libguestfs-winsupport" separately to get Windows guest
support.
Debian and Ubuntu
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 a full time Ubuntu maintainer, and the packages
supplied by Canonical (which are outside our control) are
sometimes broken.
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/
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 X 3.14-2 from:
http://packages.ubuntu.com/precise/febootstrap
After installing or updating febootstrap, rebuild the
appliance:
sudo update-guestfs-appliance
You need seabios X 0.6.2-0ubuntu2.1 or X 0.6.2-0ubuntu3 from:
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*
Gentoo
Libguestfs was added to Gentoo in 2012-07. Do:
emerge libguestfs
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 supermin (that is, Fedora,
Red Hat Enterprise Linux X 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 supermin, you will need to use the "fixed appliance
method". See: http://libguestfs.org/download/binaries/appliance/
Patches to port supermin 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]
How can I add support for sVirt?
Note for Fedora/RHEL users: This configuration is the default starting
with Fedora 18 and RHEL 7. If you find any problems, please let us
know or file a bug.
SVirt provides a hardened appliance using SELinux, making it very hard
for a rogue disk image to "escape" from the confinement of libguestfs
and damage the host (it's fair to say that even in standard libguestfs
this would be hard, but sVirt provides an extra layer of protection for
the host and more importantly protects virtual machines on the same
host from each other).
Currently to enable sVirt you will need libvirt X 0.10.2 (1.0 or later
preferred), libguestfs X 1.20, and the SELinux policies from recent
Fedora. If you are not running Fedora 18+, you will need to make
changes to your SELinux policy - contact us on the mailing list.
Once you have the requirements, do:
./configure --with-default-attach-method=libvirt
make
Set SELinux to Enforcing mode, and sVirt should be used automatically.
All, or almost all, features of libguestfs should work under sVirt.
There is one known shortcoming: virt-rescue(1) will not use libvirt
(hence sVirt), but falls back to direct launch of qemu. So you won't
currently get the benefit of sVirt protection when using virt-rescue.
You can check if sVirt is being used by enabling libvirtd logging (see
"/etc/libvirt/libvirtd.log"), killing and restarting libvirtd, and
checking the log files for "Setting SELinux context on ..." messages.
In theory sVirt should support AppArmor, but we have not tried it. It
will almost certainly require patching libvirt and writing an AppArmor
policy.
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.
How can I speed up libguestfs builds (Debian)?
Hilko Bengen suggests using "approx" which is a Debian archive proxy
(http://packages.debian.org/approx). This tool is documented on Debian
in the approx(8) manual page.
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 X 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.
virt-sparsify seems to make the image grow to the full size of the
virtual disk
If the input to virt-sparsify(1) is raw, then the output will be raw
sparse. Make sure you are measuring the output with a tool which
understands sparseness such as "du -sh". It can make a huge
difference:
$ 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
(Compare the apparent size 100M vs the actual size 3.6M)
If all this confuses you, use a non-sparse output format by specifying
the --convert option, eg:
virt-sparsify --convert qcow2 disk.raw disk.qcow2
Why doesn't virt-resize work on the disk image in-place?
Resizing a disk image is very tricky -- especially making sure that you
don't lose data or break the bootloader. The current method
effectively creates a new disk image and copies the data plus
bootloader from the old one. If something goes wrong, you can always
go back to the original.
If we were to make virt-resize work in-place then there would have to
be limitations: for example, you wouldn't be allowed to move existing
partitions (because moving data across the same disk is most likely to
corrupt data in the event of a power failure or crash), and LVM would
be very difficult to support (because of the almost arbitrary mapping
between LV content and underlying disk blocks).
Another method we have considered is to place a snapshot over the
original disk image, so that the original data is untouched and only
differences are recorded in the snapshot. You can do this today using
"qemu-img create" + "virt-resize", but qemu currently isn't smart
enough to recognize when the same block is written back to the snapshot
as already exists in the backing disk, so you will find that this
doesn't save you any space or time.
In summary, this is a hard problem, and what we have now mostly works
so we are reluctant to change it.
Why doesn't virt-sparsify work on the disk image in-place?
Eventually we plan to make virt-sparsify work on disk images in-place,
instead of copying the disk image. However it requires several changes
to both the Linux kernel and qemu which are slowly making their way
upstream (thanks to the tireless efforts of Paolo Bonzini). Then we
will have to modify virt-sparsify to support this. Finally there will
be some integration work required to make sure all the pieces work
together.
Even with this implemented there may be some limitations: For example,
it requires completely different steps (and is probably harder) to
sparsify a disk image that is stored on a SAN LUN, compared to one
which is stored in a local raw image file, so you can expect that
different storage and backing formats will become supported at
different times. Some backing filesystems / formats may never support
sparsification (eg. disk images stored on VFAT, old-style non-thin
LVs).
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 - read the license
that comes with libguestfs, and if you have specific questions 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
How do I debug when using any libguestfs program or tool (eg. virt-v2v
or virt-df)?
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.
Why can I write to the disk, even though I added it read-only?
Why does "--ro" appear to have no effect?
When you add a disk read-only, libguestfs places a writable overlay on
top of the underlying disk. Writes go into this overlay, and are
discarded when the handle is closed (or "guestfish" etc. exits).
There are two reasons for doing it this way: Firstly read-only disks
aren't possible in many cases (eg. IDE simply doesn't support them, so
you couldn't have an IDE-emulated read-only disk, although this is not
common in real libguestfs installations).
Secondly and more importantly, even if read-only disks were possible,
you wouldn't want them. Mounting any filesystem that has a journal,
even "mount -o ro", causes writes to the filesystem because the journal
has to be replayed and metadata updated. If the disk was truly read-
only, you wouldn't be able to mount a dirty filesystem.
To make it usable, we create the overlay as a place to temporarily
store these writes, and then we discard it afterwards. This ensures
that the underlying disk is always untouched.
Note also that there is a regression test for this when building
libguestfs (in "tests/qemu"). This is one reason why it's important
for packagers to run the test suite.
Does "--ro" make all disks read-only?
No! The "--ro" option only affects disks added on the command line,
ie. using "-a" and "-d" options.
In guestfish, if you use the "add" command, then disk is added read-
write (unless you specify the "readonly:true" flag explicitly with the
command).
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
See also the next question.
Why can't I run fsck on a live filesystem using "guestfish --ro"?
This command will usually not work:
guestfish --ro -a /dev/vg/my_root_fs run : fsck /dev/sda
The reason for this is that qemu creates a snapshot over the original
filesystem, but it doesn't create a strict point-in-time snapshot.
Blocks of data on the underlying filesystem are read by qemu at
different times as the fsck operation progresses, with host writes in
between. The result is that fsck sees massive corruption (imaginary,
not real!) and fails.
What you have to do is to create a point-in-time snapshot. If it's a
logical volume, use an LVM2 snapshot. If the filesystem is located
inside something like a btrfs/ZFS file, use a btrfs/ZFS snapshot, and
then run the fsck on the snapshot. In practice you don't need to use
libguestfs for this -- just run "/sbin/fsck" directly.
Creating point-in-time snapshots of host devices and files is outside
the scope of libguestfs, although libguestfs can operate on them once
they are created.
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.
What do these "debug*" and "internal-*" functions do?
There are some functions which are used for debugging and internal
purposes which are not part of the stable API.
The "debug*" (or "guestfs_debug*") functions, primarily "guestfs_debug"
in guestfs(3) and a handful of others, are used for debugging
libguestfs. Although they are not part of the stable API and thus may
change or be removed at any time, some programs may want to call these
while waiting for features to be added to libguestfs.
The "internal-*" (or "guestfs_internal_*") functions are purely to be
used by libguestfs itself. There is no reason for programs to call
them, and programs should not try to use them. Using them will often
cause bad things to happen, as well as not being part of the documented
stable API.
DEVELOPERS
Where do I send patches?
Please send patches to the libguestfs mailing list
https://www.redhat.com/mailman/listinfo/libguestfs. You don't have to
be subscribed, but there will be a delay until your posting is manually
approved.
Please don't use github pull requests - they will be ignored. The
reasons are (a) we want to discuss and dissect patches on the mailing
list, and (b) github pull requests turn into merge commits which we
don't want.
How do I propose a feature?
Large new features that you intend to contribute should be discussed on
the mailing list first
(https://www.redhat.com/mailman/listinfo/libguestfs). This avoids
disappointment and wasted work if we don't think the feature would fit
into the libguestfs project.
If you want to suggest a useful feature but don't want to write the
code, you can file a bug (see "GETTING HELP AND REPORTING BUGS") with
"RFE: " at the beginning of the Summary line.
SEE ALSOguestfish(1), guestfs(3), http://libguestfs.org/.
AUTHORS
Richard W.M. Jones ("rjones at redhat dot com")
COPYRIGHT
Copyright (C) 2012-2013 Red Hat Inc.
LICENSE
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
BUGS
To get a list of bugs against libguestfs, use this link:
https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
To report a new bug against libguestfs, use this link:
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
When reporting a bug, please supply:
· The version of libguestfs.
· Where you got libguestfs (eg. which Linux distro, compiled from
source, etc)
· Describe the bug accurately and give a way to reproduce it.
· Run libguestfs-test-tool(1) and paste the complete, unedited output
into the bug report.
libguestfs-1.20.4 2013-03-12 guestfs-faq(1)
