guestfs_mount (g, "/dev/sda1", "/");
guestfs_touch (g, "/hello");
guestfs_umount (g, "/");
- guestfs_sync (g);
guestfs_close (g);
cc prog.c -o prog -lguestfs
Libguestfs is a large API because it can do many things. For a gentle
introduction, please read the L</API OVERVIEW> section next.
+There are also some example programs in the L<guestfs-examples(3)>
+manual page.
+
=head1 API OVERVIEW
This section provides a gentler overview of the libguestfs API. We
* disk image.
*/
guestfs_touch (g, "/hello");
-
- /* You only need to call guestfs_sync if you have made
- * changes to the guest image. (But if you've made changes
- * then you *must* sync). See also: guestfs_umount and
- * guestfs_umount_all calls.
+
+ /* This is only needed for libguestfs < 1.5.24. Since then
+ * it is done automatically when you close the handle. See
+ * discussion of autosync in this page.
*/
guestfs_sync (g);
functions that return pointers return C<NULL> on error. See section
L</ERROR HANDLING> below for how to handle errors, and consult the
documentation for each function call below to see precisely how they
-return error indications.
+return error indications. See L<guestfs-examples(3)> for fully worked
+examples.
=head2 DISK IMAGES
Before you can read or write files, create directories and so on in a
disk image that contains filesystems, you have to mount those
-filesystems using L</guestfs_mount>. If you already know that a disk
-image contains (for example) one partition with a filesystem on that
-partition, then you can mount it directly:
+filesystems using L</guestfs_mount_options> or L</guestfs_mount_ro>.
+If you already know that a disk image contains (for example) one
+partition with a filesystem on that partition, then you can mount it
+directly:
- guestfs_mount (g, "/dev/sda1", "/");
+ guestfs_mount_options (g, "", "/dev/sda1", "/");
where C</dev/sda1> means literally the first partition (C<1>) of the
first disk image that we added (C</dev/sda>). If the disk contains
-Linux LVM2 logical volumes you could refer to those instead (eg. C</dev/VG/LV>).
+Linux LVM2 logical volumes you could refer to those instead
+(eg. C</dev/VG/LV>). Note that these are libguestfs virtual devices,
+and are nothing to do with host devices.
If you are given a disk image and you don't know what it contains then
you have to find out. Libguestfs can do that too: use
L</guestfs_list_partitions> and L</guestfs_lvs> to list possible
partitions and LVs, and either try mounting each to see what is
mountable, or else examine them with L</guestfs_vfs_type> or
-L</guestfs_file>. Libguestfs also has a set of APIs for inspection of
-disk images (see L</INSPECTION> below). But you might find it easier
-to look at higher level programs built on top of libguestfs, in
+L</guestfs_file>. To list just filesystems, use
+L</guestfs_list_filesystems>.
+
+Libguestfs also has a set of APIs for inspection of unknown disk
+images (see L</INSPECTION> below). But you might find it easier to
+look at higher level programs built on top of libguestfs, in
particular L<virt-inspector(1)>.
-To mount a disk image read-only, use L</guestfs_mount_ro>. There are
+To mount a filesystem read-only, use L</guestfs_mount_ro>. There are
several other variations of the C<guestfs_mount_*> call.
=head2 FILESYSTEM ACCESS AND MODIFICATION
=head2 DOWNLOADING
-Use L</guestfs_cat> to download small, text only files. This call
-is limited to files which are less than 2 MB and which cannot contain
-any ASCII NUL (C<\0>) characters. However it has a very simple
-to use API.
+Use L</guestfs_cat> to download small, text only files. This call is
+limited to files which are less than 2 MB and which cannot contain any
+ASCII NUL (C<\0>) characters. However the API is very simple to use.
L</guestfs_read_file> can be used to read files which contain
arbitrary 8 bit data, since it returns a (pointer, size) pair.
=back
+=head2 UPLOADING AND DOWNLOADING TO PIPES AND FILE DESCRIPTORS
+
+Calls like L</guestfs_upload>, L</guestfs_download>,
+L</guestfs_tar_in>, L</guestfs_tar_out> etc appear to only take
+filenames as arguments, so it appears you can only upload and download
+to files. However many Un*x-like hosts let you use the special device
+files C</dev/stdin>, C</dev/stdout>, C</dev/stderr> and C</dev/fd/N>
+to read and write from stdin, stdout, stderr, and arbitrary file
+descriptor N.
+
+For example, L<virt-cat(1)> writes its output to stdout by
+doing:
+
+ guestfs_download (g, filename, "/dev/stdout");
+
+and you can write tar output to a pipe C<fd> by doing:
+
+ char devfd[64];
+ snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd);
+ guestfs_tar_out (g, "/", devfd);
+
=head2 LISTING FILES
L</guestfs_ll> is just designed for humans to read (mainly when using
For SELinux guests, you may need to enable SELinux and load policy
first. See L</SELINUX> in this manpage.
+=item *
+
+I<Security:> It is not safe to run commands from untrusted, possibly
+malicious guests. These commands may attempt to exploit your program
+by sending unexpected output. They could also try to exploit the
+Linux kernel or qemu provided by the libguestfs appliance. They could
+use the network provided by the libguestfs appliance to bypass
+ordinary network partitions and firewalls. They could use the
+elevated privileges or different SELinux context of your program
+to their advantage.
+
+A secure alternative is to use libguestfs to install a "firstboot"
+script (a script which runs when the guest next boots normally), and
+to have this script run the commands you want in the normal context of
+the running guest, network security and so on. For information about
+other security issues, see L</SECURITY>.
+
=back
The two main API calls to run commands are L</guestfs_command> and
=head2 INSPECTION
Libguestfs has APIs for inspecting an unknown disk image to find out
-if it contains operating systems. (These APIs used to be in a
-separate Perl-only library called L<Sys::Guestfs::Lib(3)> but since
-version 1.5.3 the most frequently used part of this library has been
-rewritten in C and moved into the core code).
+if it contains operating systems, an install CD or a live CD. (These
+APIs used to be in a separate Perl-only library called
+L<Sys::Guestfs::Lib(3)> but since version 1.5.3 the most frequently
+used part of this library has been rewritten in C and moved into the
+core code).
Add all disks belonging to the unknown virtual machine and call
L</guestfs_launch> in the usual way.
calls to C<guestfs_inspect_get_*> return this cached information, but
I<do not> re-read the disks. If you change the content of the guest
disks, you can redo inspection by calling L</guestfs_inspect_os>
-again.
+again. (L</guestfs_inspect_list_applications> works a little
+differently from the other calls and does read the disks. See
+documentation for that function for details).
+
+=head3 INSPECTING INSTALL DISKS
+
+Libguestfs (since 1.9.4) can detect some install disks, install
+CDs, live CDs and more.
+
+Call L</guestfs_inspect_get_format> to return the format of the
+operating system, which currently can be C<installed> (a regular
+operating system) or C<installer> (some sort of install disk).
+
+Further information is available about the operating system that can
+be installed using the regular inspection APIs like
+L</guestfs_inspect_get_product_name>,
+L</guestfs_inspect_get_major_version> etc.
+
+Some additional information specific to installer disks is also
+available from the L</guestfs_inspect_is_live>,
+L</guestfs_inspect_is_netinst> and L</guestfs_inspect_is_multipart>
+calls.
=head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS
Libguestfs can mount NTFS partitions. It does this using the
L<http://www.ntfs-3g.org/> driver.
+=head3 DRIVE LETTERS AND PATHS
+
DOS and Windows still use drive letters, and the filesystems are
always treated as case insensitive by Windows itself, and therefore
you might find a Windows configuration file referring to a path like
Where we can help is in resolving the case insensitivity of paths.
For this, call L</guestfs_case_sensitive_path>.
+=head3 ACCESSING THE WINDOWS REGISTRY
+
Libguestfs also provides some help for decoding Windows Registry
"hive" files, through the library C<hivex> which is part of the
libguestfs project although ships as a separate tarball. You have to
L<hivexsh(1)>, L<hivexregedit(1)> and L<virt-win-reg(1)> for more help
on this issue.
+=head3 SYMLINKS ON NTFS-3G FILESYSTEMS
+
+Ntfs-3g tries to rewrite "Junction Points" and NTFS "symbolic links"
+to provide something which looks like a Linux symlink. The way it
+tries to do the rewriting is described here:
+
+L<http://www.tuxera.com/community/ntfs-3g-advanced/junction-points-and-symbolic-links/>
+
+The essential problem is that ntfs-3g simply does not have enough
+information to do a correct job. NTFS links can contain drive letters
+and references to external device GUIDs that ntfs-3g has no way of
+resolving. It is almost certainly the case that libguestfs callers
+should ignore what ntfs-3g does (ie. don't use L</guestfs_readlink> on
+NTFS volumes).
+
+Instead if you encounter a symbolic link on an ntfs-3g filesystem, use
+L</guestfs_lgetxattr> to read the C<system.ntfs_reparse_data> extended
+attribute, and read the raw reparse data from that (you can find the
+format documented in various places around the web).
+
+=head3 EXTENDED ATTRIBUTES ON NTFS-3G FILESYSTEMS
+
+There are other useful extended attributes that can be read from
+ntfs-3g filesystems (using L</guestfs_getxattr>). See:
+
+L<http://www.tuxera.com/community/ntfs-3g-advanced/extended-attributes/>
+
=head2 USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES
Although we don't want to discourage you from using the C API, we will
mention here that the same API is also available in other languages.
The API is broadly identical in all supported languages. This means
-that the C call C<guestfs_mount(g,path)> is
-C<$g-E<gt>mount($path)> in Perl, C<g.mount(path)> in Python,
-and C<Guestfs.mount g path> in OCaml. In other words, a
+that the C call C<guestfs_add_drive_ro(g,file)> is
+C<$g-E<gt>add_drive_ro($file)> in Perl, C<g.add_drive_ro(file)> in Python,
+and C<g#add_drive_ro file> in OCaml. In other words, a
straightforward, predictable isomorphism between each language.
Error messages are automatically transformed
=item B<OCaml>
-For documentation see the file C<guestfs.mli>.
+See L<guestfs-ocaml(3)>.
=item B<Perl>
-For documentation see L<Sys::Guestfs(3)>.
+See L<guestfs-perl(3)> and L<Sys::Guestfs(3)>.
=item B<PHP>
=item B<Python>
-For documentation do:
-
- $ python
- >>> import guestfs
- >>> help (guestfs)
+See L<guestfs-python(3)>.
=item B<Ruby>
-Use the Guestfs module. There is no Ruby-specific documentation, but
-you can find examples written in Ruby in the libguestfs source.
+See L<guestfs-ruby(3)>.
=item B<shell scripts>
-For documentation see L<guestfish(1)>.
+See L<guestfish(1)>.
=back
dirty guestfish scripts that forget to sync will work just fine, which
can make this very puzzling if you are trying to debug a problem.
+Update: Autosync is enabled by default for all API users starting from
+libguestfs 1.5.24.
+
=item Mount option C<-o sync> should not be the default.
If you use L</guestfs_mount>, then C<-o sync,noatime> are added
This could be fixed in the generator by specially marking parameters
and return values which take bytes or other units.
-=item Library should return errno with error messages.
-
-It would be a nice-to-have to be able to get the original value of
-'errno' from inside the appliance along error paths (where set).
-Currently L<guestmount(1)> goes through hoops to try to reverse the
-error message string into an errno, see the function error() in
-fuse/guestmount.c.
-
-In libguestfs 1.5.4, the protocol was changed so that the
-Linux errno is sent back from the daemon.
-
=item Ambiguity between devices and paths
There is a subtle ambiguity in the API between a device name
this is a concern, scrub the swap partition or don't use libguestfs on
encrypted devices.
-=head1 CONNECTION MANAGEMENT
+=head2 MULTIPLE HANDLES AND MULTIPLE THREADS
-=head2 guestfs_h *
+All high-level libguestfs actions are synchronous. If you want
+to use libguestfs asynchronously then you must create a thread.
-C<guestfs_h> is the opaque type representing a connection handle.
-Create a handle by calling L</guestfs_create>. Call L</guestfs_close>
-to free the handle and release all resources used.
+Only use the handle from a single thread. Either use the handle
+exclusively from one thread, or provide your own mutex so that two
+threads cannot issue calls on the same handle at the same time.
-For information on using multiple handles and threads, see the section
-L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
+See the graphical program guestfs-browser for one possible
+architecture for multithreaded programs using libvirt and libguestfs.
-=head2 guestfs_create
+=head2 PATH
- guestfs_h *guestfs_create (void);
+Libguestfs needs a kernel and initrd.img, which it finds by looking
+along an internal path.
-Create a connection handle.
+By default it looks for these in the directory C<$libdir/guestfs>
+(eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).
-You have to call L</guestfs_add_drive_opts> (or one of the equivalent
-calls) on the handle at least once.
+Use L</guestfs_set_path> or set the environment variable
+L</LIBGUESTFS_PATH> to change the directories that libguestfs will
+search in. The value is a colon-separated list of paths. The current
+directory is I<not> searched unless the path contains an empty element
+or C<.>. For example C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would
+search the current directory and then C</usr/lib/guestfs>.
-This function returns a non-NULL pointer to a handle on success or
-NULL on error.
+=head2 QEMU WRAPPERS
-After configuring the handle, you have to call L</guestfs_launch>.
+If you want to compile your own qemu, run qemu from a non-standard
+location, or pass extra arguments to qemu, then you can write a
+shell-script wrapper around qemu.
-You may also want to configure error handling for the handle. See
-L</ERROR HANDLING> section below.
+There is one important rule to remember: you I<must C<exec qemu>> as
+the last command in the shell script (so that qemu replaces the shell
+and becomes the direct child of the libguestfs-using program). If you
+don't do this, then the qemu process won't be cleaned up correctly.
-=head2 guestfs_close
+Here is an example of a wrapper, where I have built my own copy of
+qemu from source:
- void guestfs_close (guestfs_h *g);
+ #!/bin/sh -
+ qemudir=/home/rjones/d/qemu
+ exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
-This closes the connection handle and frees up all resources used.
+Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>,
+and then use it by setting the LIBGUESTFS_QEMU environment variable.
+For example:
-=head1 ERROR HANDLING
+ LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish
-The convention in all functions that return C<int> is that they return
-C<-1> to indicate an error. You can get additional information on
-errors by calling L</guestfs_last_error> and/or by setting up an error
-handler with L</guestfs_set_error_handler>.
+Note that libguestfs also calls qemu with the -help and -version
+options in order to determine features.
-The default error handler prints the information string to C<stderr>.
+=head2 ATTACHING TO RUNNING DAEMONS
-Out of memory errors are handled differently. The default action is
-to call L<abort(3)>. If this is undesirable, then you can set a
-handler using L</guestfs_set_out_of_memory_handler>.
+I<Note (1):> This is B<highly experimental> and has a tendency to eat
+babies. Use with caution.
-=head2 guestfs_last_error
+I<Note (2):> This section explains how to attach to a running daemon
+from a low level perspective. For most users, simply using virt tools
+such as L<guestfish(1)> with the I<--live> option will "just work".
- const char *guestfs_last_error (guestfs_h *g);
+=head3 Using guestfs_set_attach_method
-This returns the last error message that happened on C<g>. If
-there has not been an error since the handle was created, then this
-returns C<NULL>.
+By calling L</guestfs_set_attach_method> you can change how the
+library connects to the C<guestfsd> daemon in L</guestfs_launch>
+(read L</ARCHITECTURE> for some background).
-The lifetime of the returned string is until the next error occurs, or
-L</guestfs_close> is called.
+The normal attach method is C<appliance>, where a small appliance is
+created containing the daemon, and then the library connects to this.
-The error string is not localized (ie. is always in English), because
-this makes searching for error messages in search engines give the
-largest number of results.
+Setting attach method to C<unix:I<path>> (where I<path> is the path of
+a Unix domain socket) causes L</guestfs_launch> to connect to an
+existing daemon over the Unix domain socket.
-=head2 guestfs_set_error_handler
+The normal use for this is to connect to a running virtual machine
+that contains a C<guestfsd> daemon, and send commands so you can read
+and write files inside the live virtual machine.
- typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
- void *opaque,
- const char *msg);
- void guestfs_set_error_handler (guestfs_h *g,
- guestfs_error_handler_cb cb,
- void *opaque);
+=head3 Using guestfs_add_domain with live flag
-The callback C<cb> will be called if there is an error. The
-parameters passed to the callback are an opaque data pointer and the
-error message string.
+L</guestfs_add_domain> provides some help for getting the
+correct attach method. If you pass the C<live> option to this
+function, then (if the virtual machine is running) it will
+examine the libvirt XML looking for a virtio-serial channel
+to connect to:
-Note that the message string C<msg> is freed as soon as the callback
-function returns, so if you want to stash it somewhere you must make
-your own copy.
+ <domain>
+ ...
+ <devices>
+ ...
+ <channel type='unix'>
+ <source mode='bind' path='/path/to/socket'/>
+ <target type='virtio' name='org.libguestfs.channel.0'/>
+ </channel>
+ ...
+ </devices>
+ </domain>
+
+L</guestfs_add_domain> extracts C</path/to/socket> and sets the attach
+method to C<unix:/path/to/socket>.
+
+Some of the libguestfs tools (including guestfish) support a I<--live>
+option which is passed through to L</guestfs_add_domain> thus allowing
+you to attach to and modify live virtual machines.
+
+The virtual machine needs to have been set up beforehand so that it
+has the virtio-serial channel and so that guestfsd is running inside
+it.
-The default handler prints messages on C<stderr>.
+=head2 ABI GUARANTEE
-If you set C<cb> to C<NULL> then I<no> handler is called.
+We guarantee the libguestfs ABI (binary interface), for public,
+high-level actions as outlined in this section. Although we will
+deprecate some actions, for example if they get replaced by newer
+calls, we will keep the old actions forever. This allows you the
+developer to program in confidence against the libguestfs API.
-=head2 guestfs_get_error_handler
+=head2 BLOCK DEVICE NAMING
- guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
- void **opaque_rtn);
+In the kernel there is now quite a profusion of schemata for naming
+block devices (in this context, by I<block device> I mean a physical
+or virtual hard drive). The original Linux IDE driver used names
+starting with C</dev/hd*>. SCSI devices have historically used a
+different naming scheme, C</dev/sd*>. When the Linux kernel I<libata>
+driver became a popular replacement for the old IDE driver
+(particularly for SATA devices) those devices also used the
+C</dev/sd*> scheme. Additionally we now have virtual machines with
+paravirtualized drivers. This has created several different naming
+systems, such as C</dev/vd*> for virtio disks and C</dev/xvd*> for Xen
+PV disks.
-Returns the current error handler callback.
+As discussed above, libguestfs uses a qemu appliance running an
+embedded Linux kernel to access block devices. We can run a variety
+of appliances based on a variety of Linux kernels.
-=head2 guestfs_set_out_of_memory_handler
+This causes a problem for libguestfs because many API calls use device
+or partition names. Working scripts and the recipe (example) scripts
+that we make available over the internet could fail if the naming
+scheme changes.
- typedef void (*guestfs_abort_cb) (void);
- int guestfs_set_out_of_memory_handler (guestfs_h *g,
- guestfs_abort_cb);
+Therefore libguestfs defines C</dev/sd*> as the I<standard naming
+scheme>. Internally C</dev/sd*> names are translated, if necessary,
+to other names as required. For example, under RHEL 5 which uses the
+C</dev/hd*> scheme, any device parameter C</dev/sda2> is translated to
+C</dev/hda2> transparently.
-The callback C<cb> will be called if there is an out of memory
-situation. I<Note this callback must not return>.
+Note that this I<only> applies to parameters. The
+L</guestfs_list_devices>, L</guestfs_list_partitions> and similar calls
+return the true names of the devices and partitions as known to the
+appliance.
-The default is to call L<abort(3)>.
+=head3 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION
-You cannot set C<cb> to C<NULL>. You can't ignore out of memory
-situations.
+Usually this translation is transparent. However in some (very rare)
+cases you may need to know the exact algorithm. Such cases include
+where you use L</guestfs_config> to add a mixture of virtio and IDE
+devices to the qemu-based appliance, so have a mixture of C</dev/sd*>
+and C</dev/vd*> devices.
-=head2 guestfs_get_out_of_memory_handler
+The algorithm is applied only to I<parameters> which are known to be
+either device or partition names. Return values from functions such
+as L</guestfs_list_devices> are never changed.
- guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
+=over 4
-This returns the current out of memory handler.
+=item *
-=head1 PATH
+Is the string a parameter which is a device or partition name?
-Libguestfs needs a kernel and initrd.img, which it finds by looking
-along an internal path.
+=item *
-By default it looks for these in the directory C<$libdir/guestfs>
-(eg. C</usr/local/lib/guestfs> or C</usr/lib64/guestfs>).
+Does the string begin with C</dev/sd>?
-Use L</guestfs_set_path> or set the environment variable
-L</LIBGUESTFS_PATH> to change the directories that libguestfs will
-search in. The value is a colon-separated list of paths. The current
-directory is I<not> searched unless the path contains an empty element
-or C<.>. For example C<LIBGUESTFS_PATH=:/usr/lib/guestfs> would
-search the current directory and then C</usr/lib/guestfs>.
+=item *
-=head1 HIGH-LEVEL API ACTIONS
+Does the named device exist? If so, we use that device.
+However if I<not> then we continue with this algorithm.
-=head2 ABI GUARANTEE
+=item *
-We guarantee the libguestfs ABI (binary interface), for public,
-high-level actions as outlined in this section. Although we will
-deprecate some actions, for example if they get replaced by newer
-calls, we will keep the old actions forever. This allows you the
-developer to program in confidence against the libguestfs API.
+Replace initial C</dev/sd> string with C</dev/hd>.
-@ACTIONS@
+For example, change C</dev/sda2> to C</dev/hda2>.
-=head1 STRUCTURES
+If that named device exists, use it. If not, continue.
-@STRUCTS@
+=item *
-=head1 AVAILABILITY
+Replace initial C</dev/sd> string with C</dev/vd>.
-=head2 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
+If that named device exists, use it. If not, return an error.
-Using L</guestfs_available> you can test availability of
-the following groups of functions. This test queries the
-appliance to see if the appliance you are currently using
-supports the functionality.
+=back
-@AVAILABILITY@
+=head3 PORTABILITY CONCERNS WITH BLOCK DEVICE NAMING
-=head2 GUESTFISH supported COMMAND
+Although the standard naming scheme and automatic translation is
+useful for simple programs and guestfish scripts, for larger programs
+it is best not to rely on this mechanism.
-In L<guestfish(3)> there is a handy interactive command
-C<supported> which prints out the available groups and
-whether they are supported by this build of libguestfs.
-Note however that you have to do C<run> first.
+Where possible for maximum future portability programs using
+libguestfs should use these future-proof techniques:
-=head2 SINGLE CALLS AT COMPILE TIME
+=over 4
-Since version 1.5.8, C<E<lt>guestfs.hE<gt>> defines symbols
-for each C API function, such as:
+=item *
- #define LIBGUESTFS_HAVE_DD 1
+Use L</guestfs_list_devices> or L</guestfs_list_partitions> to list
+actual device names, and then use those names directly.
-if L</guestfs_dd> is available.
+Since those device names exist by definition, they will never be
+translated.
-Before version 1.5.8, if you needed to test whether a single
-libguestfs function is available at compile time, we recommended using
-build tools such as autoconf or cmake. For example in autotools you
-could use:
+=item *
- AC_CHECK_LIB([guestfs],[guestfs_create])
- AC_CHECK_FUNCS([guestfs_dd])
+Use higher level ways to identify filesystems, such as LVM names,
+UUIDs and filesystem labels.
-which would result in C<HAVE_GUESTFS_DD> being either defined
-or not defined in your program.
+=back
-=head2 SINGLE CALLS AT RUN TIME
+=head1 SECURITY
-Testing at compile time doesn't guarantee that a function really
-exists in the library. The reason is that you might be dynamically
-linked against a previous I<libguestfs.so> (dynamic library)
-which doesn't have the call. This situation unfortunately results
-in a segmentation fault, which is a shortcoming of the C dynamic
-linking system itself.
+This section discusses security implications of using libguestfs,
+particularly with untrusted or malicious guests or disk images.
+
+=head2 GENERAL SECURITY CONSIDERATIONS
+
+Be careful with any files or data that you download from a guest (by
+"download" we mean not just the L</guestfs_download> command but any
+command that reads files, filenames, directories or anything else from
+a disk image). An attacker could manipulate the data to fool your
+program into doing the wrong thing. Consider cases such as:
+
+=over 4
+
+=item *
+
+the data (file etc) not being present
+
+=item *
+
+being present but empty
+
+=item *
+
+being much larger than normal
+
+=item *
+
+containing arbitrary 8 bit data
+
+=item *
+
+being in an unexpected character encoding
+
+=item *
+
+containing homoglyphs.
+
+=back
+
+=head2 SECURITY OF MOUNTING FILESYSTEMS
+
+When you mount a filesystem under Linux, mistakes in the kernel
+filesystem (VFS) module can sometimes be escalated into exploits by
+deliberately creating a malicious, malformed filesystem. These
+exploits are very severe for two reasons. Firstly there are very many
+filesystem drivers in the kernel, and many of them are infrequently
+used and not much developer attention has been paid to the code.
+Linux userspace helps potential crackers by detecting the filesystem
+type and automatically choosing the right VFS driver, even if that
+filesystem type is obscure or unexpected for the administrator.
+Secondly, a kernel-level exploit is like a local root exploit (worse
+in some ways), giving immediate and total access to the system right
+down to the hardware level.
+
+That explains why you should never mount a filesystem from an
+untrusted guest on your host kernel. How about libguestfs? We run a
+Linux kernel inside a qemu virtual machine, usually running as a
+non-root user. The attacker would need to write a filesystem which
+first exploited the kernel, and then exploited either qemu
+virtualization (eg. a faulty qemu driver) or the libguestfs protocol,
+and finally to be as serious as the host kernel exploit it would need
+to escalate its privileges to root. This multi-step escalation,
+performed by a static piece of data, is thought to be extremely hard
+to do, although we never say 'never' about security issues.
+
+In any case callers can reduce the attack surface by forcing the
+filesystem type when mounting (use L</guestfs_mount_vfs>).
+
+=head2 PROTOCOL SECURITY
+
+The protocol is designed to be secure, being based on RFC 4506 (XDR)
+with a defined upper message size. However a program that uses
+libguestfs must also take care - for example you can write a program
+that downloads a binary from a disk image and executes it locally, and
+no amount of protocol security will save you from the consequences.
+
+=head2 INSPECTION SECURITY
+
+Parts of the inspection API (see L</INSPECTION>) return untrusted
+strings directly from the guest, and these could contain any 8 bit
+data. Callers should be careful to escape these before printing them
+to a structured file (for example, use HTML escaping if creating a web
+page).
+
+Guest configuration may be altered in unusual ways by the
+administrator of the virtual machine, and may not reflect reality
+(particularly for untrusted or actively malicious guests). For
+example we parse the hostname from configuration files like
+C</etc/sysconfig/network> that we find in the guest, but the guest
+administrator can easily manipulate these files to provide the wrong
+hostname.
+
+The inspection API parses guest configuration using two external
+libraries: Augeas (Linux configuration) and hivex (Windows Registry).
+Both are designed to be robust in the face of malicious data, although
+denial of service attacks are still possible, for example with
+oversized configuration files.
+
+=head2 RUNNING UNTRUSTED GUEST COMMANDS
+
+Be very cautious about running commands from the guest. By running a
+command in the guest, you are giving CPU time to a binary that you do
+not control, under the same user account as the library, albeit
+wrapped in qemu virtualization. More information and alternatives can
+be found in the section L</RUNNING COMMANDS>.
+
+=head2 CVE-2010-3851
+
+https://bugzilla.redhat.com/642934
+
+This security bug concerns the automatic disk format detection that
+qemu does on disk images.
+
+A raw disk image is just the raw bytes, there is no header. Other
+disk images like qcow2 contain a special header. Qemu deals with this
+by looking for one of the known headers, and if none is found then
+assuming the disk image must be raw.
+
+This allows a guest which has been given a raw disk image to write
+some other header. At next boot (or when the disk image is accessed
+by libguestfs) qemu would do autodetection and think the disk image
+format was, say, qcow2 based on the header written by the guest.
+
+This in itself would not be a problem, but qcow2 offers many features,
+one of which is to allow a disk image to refer to another image
+(called the "backing disk"). It does this by placing the path to the
+backing disk into the qcow2 header. This path is not validated and
+could point to any host file (eg. "/etc/passwd"). The backing disk is
+then exposed through "holes" in the qcow2 disk image, which of course
+is completely under the control of the attacker.
+
+In libguestfs this is rather hard to exploit except under two
+circumstances:
+
+=over 4
+
+=item 1.
+
+You have enabled the network or have opened the disk in write mode.
+
+=item 2.
+
+You are also running untrusted code from the guest (see
+L</RUNNING COMMANDS>).
+
+=back
+
+The way to avoid this is to specify the expected disk format when
+adding disks (the optional C<format> option to
+L</guestfs_add_drive_opts>). You should always do this if the disk is
+raw format, and it's a good idea for other cases too.
+
+For disks added from libvirt using calls like L</guestfs_add_domain>,
+the format is fetched from libvirt and passed through.
+
+For libguestfs tools, use the I<--format> command line parameter as
+appropriate.
+
+=head1 CONNECTION MANAGEMENT
+
+=head2 guestfs_h *
+
+C<guestfs_h> is the opaque type representing a connection handle.
+Create a handle by calling L</guestfs_create>. Call L</guestfs_close>
+to free the handle and release all resources used.
+
+For information on using multiple handles and threads, see the section
+L</MULTIPLE HANDLES AND MULTIPLE THREADS> below.
+
+=head2 guestfs_create
+
+ guestfs_h *guestfs_create (void);
+
+Create a connection handle.
+
+You have to call L</guestfs_add_drive_opts> (or one of the equivalent
+calls) on the handle at least once.
+
+This function returns a non-NULL pointer to a handle on success or
+NULL on error.
+
+After configuring the handle, you have to call L</guestfs_launch>.
+
+You may also want to configure error handling for the handle. See
+L</ERROR HANDLING> section below.
+
+=head2 guestfs_close
+
+ void guestfs_close (guestfs_h *g);
+
+This closes the connection handle and frees up all resources used.
+
+=head1 ERROR HANDLING
+
+API functions can return errors. For example, almost all functions
+that return C<int> will return C<-1> to indicate an error.
+
+Additional information is available for errors: an error message
+string and optionally an error number (errno) if the thing that failed
+was a system call.
+
+You can get at the additional information about the last error on the
+handle by calling L</guestfs_last_error>, L</guestfs_last_errno>,
+and/or by setting up an error handler with
+L</guestfs_set_error_handler>.
+
+When the handle is created, a default error handler is installed which
+prints the error message string to C<stderr>. For small short-running
+command line programs it is sufficient to do:
+
+ if (guestfs_launch (g) == -1)
+ exit (EXIT_FAILURE);
+
+since the default error handler will ensure that an error message has
+been printed to C<stderr> before the program exits.
+
+For other programs the caller will almost certainly want to install an
+alternate error handler or do error handling in-line like this:
+
+ g = guestfs_create ();
+
+ /* This disables the default behaviour of printing errors
+ on stderr. */
+ guestfs_set_error_handler (g, NULL, NULL);
+
+ if (guestfs_launch (g) == -1) {
+ /* Examine the error message and print it etc. */
+ char *msg = guestfs_last_error (g);
+ int errnum = guestfs_last_errno (g);
+ fprintf (stderr, "%s\n", msg);
+ /* ... */
+ }
+
+Out of memory errors are handled differently. The default action is
+to call L<abort(3)>. If this is undesirable, then you can set a
+handler using L</guestfs_set_out_of_memory_handler>.
+
+L</guestfs_create> returns C<NULL> if the handle cannot be created,
+and because there is no handle if this happens there is no way to get
+additional error information. However L</guestfs_create> is supposed
+to be a lightweight operation which can only fail because of
+insufficient memory (it returns NULL in this case).
+
+=head2 guestfs_last_error
+
+ const char *guestfs_last_error (guestfs_h *g);
+
+This returns the last error message that happened on C<g>. If
+there has not been an error since the handle was created, then this
+returns C<NULL>.
+
+The lifetime of the returned string is until the next error occurs, or
+L</guestfs_close> is called.
+
+=head2 guestfs_last_errno
+
+ int guestfs_last_errno (guestfs_h *g);
+
+This returns the last error number (errno) that happened on C<g>.
+
+If successful, an errno integer not equal to zero is returned.
+
+If no error, this returns 0. This call can return 0 in three
+situations:
+
+=over 4
+
+=item 1.
+
+There has not been any error on the handle.
+
+=item 2.
+
+There has been an error but the errno was meaningless. This
+corresponds to the case where the error did not come from a
+failed system call, but for some other reason.
+
+=item 3.
+
+There was an error from a failed system call, but for some
+reason the errno was not captured and returned. This usually
+indicates a bug in libguestfs.
+
+=back
+
+Libguestfs tries to convert the errno from inside the applicance into
+a corresponding errno for the caller (not entirely trivial: the
+appliance might be running a completely different operating system
+from the library and error numbers are not standardized across
+Un*xen). If this could not be done, then the error is translated to
+C<EINVAL>. In practice this should only happen in very rare
+circumstances.
+
+=head2 guestfs_set_error_handler
+
+ typedef void (*guestfs_error_handler_cb) (guestfs_h *g,
+ void *opaque,
+ const char *msg);
+ void guestfs_set_error_handler (guestfs_h *g,
+ guestfs_error_handler_cb cb,
+ void *opaque);
+
+The callback C<cb> will be called if there is an error. The
+parameters passed to the callback are an opaque data pointer and the
+error message string.
+
+C<errno> is not passed to the callback. To get that the callback must
+call L</guestfs_last_errno>.
+
+Note that the message string C<msg> is freed as soon as the callback
+function returns, so if you want to stash it somewhere you must make
+your own copy.
+
+The default handler prints messages on C<stderr>.
+
+If you set C<cb> to C<NULL> then I<no> handler is called.
+
+=head2 guestfs_get_error_handler
+
+ guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g,
+ void **opaque_rtn);
+
+Returns the current error handler callback.
+
+=head2 guestfs_set_out_of_memory_handler
+
+ typedef void (*guestfs_abort_cb) (void);
+ int guestfs_set_out_of_memory_handler (guestfs_h *g,
+ guestfs_abort_cb);
+
+The callback C<cb> will be called if there is an out of memory
+situation. I<Note this callback must not return>.
+
+The default is to call L<abort(3)>.
+
+You cannot set C<cb> to C<NULL>. You can't ignore out of memory
+situations.
+
+=head2 guestfs_get_out_of_memory_handler
+
+ guestfs_abort_fn guestfs_get_out_of_memory_handler (guestfs_h *g);
+
+This returns the current out of memory handler.
+
+=head1 API CALLS
+
+@ACTIONS@
+
+=head1 STRUCTURES
+
+@STRUCTS@
+
+=head1 AVAILABILITY
+
+=head2 GROUPS OF FUNCTIONALITY IN THE APPLIANCE
+
+Using L</guestfs_available> you can test availability of
+the following groups of functions. This test queries the
+appliance to see if the appliance you are currently using
+supports the functionality.
+
+@AVAILABILITY@
+
+=head2 GUESTFISH supported COMMAND
+
+In L<guestfish(3)> there is a handy interactive command
+C<supported> which prints out the available groups and
+whether they are supported by this build of libguestfs.
+Note however that you have to do C<run> first.
+
+=head2 SINGLE CALLS AT COMPILE TIME
+
+Since version 1.5.8, C<E<lt>guestfs.hE<gt>> defines symbols
+for each C API function, such as:
+
+ #define LIBGUESTFS_HAVE_DD 1
+
+if L</guestfs_dd> is available.
+
+Before version 1.5.8, if you needed to test whether a single
+libguestfs function is available at compile time, we recommended using
+build tools such as autoconf or cmake. For example in autotools you
+could use:
+
+ AC_CHECK_LIB([guestfs],[guestfs_create])
+ AC_CHECK_FUNCS([guestfs_dd])
+
+which would result in C<HAVE_GUESTFS_DD> being either defined
+or not defined in your program.
+
+=head2 SINGLE CALLS AT RUN TIME
+
+Testing at compile time doesn't guarantee that a function really
+exists in the library. The reason is that you might be dynamically
+linked against a previous I<libguestfs.so> (dynamic library)
+which doesn't have the call. This situation unfortunately results
+in a segmentation fault, which is a shortcoming of the C dynamic
+linking system itself.
You can use L<dlopen(3)> to test if a function is available
at run time, as in this example program (note that you still
For guestfish, see L<guestfish(1)/OPTIONAL ARGUMENTS>.
-=begin html
-
-<!-- old anchor for the next section -->
-<a name="state_machine_and_low_level_event_api"/>
-
-=end html
-
-=head1 ARCHITECTURE
-
-Internally, libguestfs is implemented by running an appliance (a
-special type of small virtual machine) using L<qemu(1)>. Qemu runs as
-a child process of the main program.
-
- ___________________
- / \
- | main program |
- | |
- | | child process / appliance
- | | __________________________
- | | / qemu \
- +-------------------+ RPC | +-----------------+ |
- | libguestfs <--------------------> guestfsd | |
- | | | +-----------------+ |
- \___________________/ | | Linux kernel | |
- | +--^--------------+ |
- \_________|________________/
- |
- _______v______
- / \
- | Device or |
- | disk image |
- \______________/
-
-The library, linked to the main program, creates the child process and
-hence the appliance in the L</guestfs_launch> function.
-
-Inside the appliance is a Linux kernel and a complete stack of
-userspace tools (such as LVM and ext2 programs) and a small
-controlling daemon called L</guestfsd>. The library talks to
-L</guestfsd> using remote procedure calls (RPC). There is a mostly
-one-to-one correspondence between libguestfs API calls and RPC calls
-to the daemon. Lastly the disk image(s) are attached to the qemu
-process which translates device access by the appliance's Linux kernel
-into accesses to the image.
-
-A common misunderstanding is that the appliance "is" the virtual
-machine. Although the disk image you are attached to might also be
-used by some virtual machine, libguestfs doesn't know or care about
-this. (But you will care if both libguestfs's qemu process and your
-virtual machine are trying to update the disk image at the same time,
-since these usually results in massive disk corruption).
-
-=head1 STATE MACHINE
-
-libguestfs uses a state machine to model the child process:
-
- |
- guestfs_create
- |
- |
- ____V_____
- / \
- | CONFIG |
- \__________/
- ^ ^ ^ \
- / | \ \ guestfs_launch
- / | _\__V______
- / | / \
- / | | LAUNCHING |
- / | \___________/
- / | /
- / | guestfs_launch
- / | /
- ______ / __|____V
- / \ ------> / \
- | BUSY | | READY |
- \______/ <------ \________/
-
-The normal transitions are (1) CONFIG (when the handle is created, but
-there is no child process), (2) LAUNCHING (when the child process is
-booting up), (3) alternating between READY and BUSY as commands are
-issued to, and carried out by, the child process.
-
-The guest may be killed by L</guestfs_kill_subprocess>, or may die
-asynchronously at any time (eg. due to some internal error), and that
-causes the state to transition back to CONFIG.
-
-Configuration commands for qemu such as L</guestfs_add_drive> can only
-be issued when in the CONFIG state.
-
-The API offers one call that goes from CONFIG through LAUNCHING to
-READY. L</guestfs_launch> blocks until the child process is READY to
-accept commands (or until some failure or timeout).
-L</guestfs_launch> internally moves the state from CONFIG to LAUNCHING
-while it is running.
-
-API actions such as L</guestfs_mount> can only be issued when in the
-READY state. These API calls block waiting for the command to be
-carried out (ie. the state to transition to BUSY and then back to
-READY). There are no non-blocking versions, and no way to issue more
-than one command per handle at the same time.
-
-Finally, the child process sends asynchronous messages back to the
-main program, such as kernel log messages. You can register a
-callback to receive these messages.
-
=head2 SETTING CALLBACKS TO HANDLE EVENTS
The child process generates events in some situations. Current events
=head1 PRIVATE DATA AREA
You can attach named pieces of private data to the libguestfs handle,
-and fetch them by name for the lifetime of the handle. This is called
-the private data area and is only available from the C API.
+fetch them by name, and walk over them, for the lifetime of the
+handle. This is called the private data area and is only available
+from the C API.
To attach a named piece of data, use the following call:
set up a close callback to do it (see L</guestfs_set_close_callback>,
and note that only one callback can be registered for a handle).
-The private data area is implemented using a hash table, and should be
-reasonably efficient for moderate numbers of keys.
+To walk over all entries, use these two functions:
-=head1 BLOCK DEVICE NAMING
+ void *guestfs_first_private (guestfs_h *g, const char **key_rtn);
-In the kernel there is now quite a profusion of schemata for naming
-block devices (in this context, by I<block device> I mean a physical
-or virtual hard drive). The original Linux IDE driver used names
-starting with C</dev/hd*>. SCSI devices have historically used a
-different naming scheme, C</dev/sd*>. When the Linux kernel I<libata>
-driver became a popular replacement for the old IDE driver
-(particularly for SATA devices) those devices also used the
-C</dev/sd*> scheme. Additionally we now have virtual machines with
-paravirtualized drivers. This has created several different naming
-systems, such as C</dev/vd*> for virtio disks and C</dev/xvd*> for Xen
-PV disks.
+ void *guestfs_next_private (guestfs_h *g, const char **key_rtn);
-As discussed above, libguestfs uses a qemu appliance running an
-embedded Linux kernel to access block devices. We can run a variety
-of appliances based on a variety of Linux kernels.
+C<guestfs_first_private> returns the first key, pointer pair ("first"
+does not have any particular meaning -- keys are not returned in any
+defined order). A pointer to the key is returned in C<*key_rtn> and
+the corresponding data pointer is returned from the function. C<NULL>
+is returned if there are no keys stored in the handle.
-This causes a problem for libguestfs because many API calls use device
-or partition names. Working scripts and the recipe (example) scripts
-that we make available over the internet could fail if the naming
-scheme changes.
+C<guestfs_next_private> returns the next key, pointer pair. The
+return value of this function is also C<NULL> is there are no further
+entries to return.
-Therefore libguestfs defines C</dev/sd*> as the I<standard naming
-scheme>. Internally C</dev/sd*> names are translated, if necessary,
-to other names as required. For example, under RHEL 5 which uses the
-C</dev/hd*> scheme, any device parameter C</dev/sda2> is translated to
-C</dev/hda2> transparently.
+Notes about walking over entries:
-Note that this I<only> applies to parameters. The
-L</guestfs_list_devices>, L</guestfs_list_partitions> and similar calls
-return the true names of the devices and partitions as known to the
-appliance.
+=over 4
-=head2 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION
+=item *
-Usually this translation is transparent. However in some (very rare)
-cases you may need to know the exact algorithm. Such cases include
-where you use L</guestfs_config> to add a mixture of virtio and IDE
-devices to the qemu-based appliance, so have a mixture of C</dev/sd*>
-and C</dev/vd*> devices.
+You must not call C<guestfs_set_private> while walking over the
+entries.
-The algorithm is applied only to I<parameters> which are known to be
-either device or partition names. Return values from functions such
-as L</guestfs_list_devices> are never changed.
+=item *
-=over 4
+The handle maintains an internal iterator which is reset when you call
+C<guestfs_first_private>. This internal iterator is invalidated when
+you call C<guestfs_set_private>.
=item *
-Is the string a parameter which is a device or partition name?
+If you have set the data pointer associated with a key to C<NULL>, ie:
-=item *
+ guestfs_set_private (g, key, NULL);
-Does the string begin with C</dev/sd>?
+then that C<key> is not returned when walking.
=item *
-Does the named device exist? If so, we use that device.
-However if I<not> then we continue with this algorithm.
+C<*key_rtn> is only valid until the next call to
+C<guestfs_first_private>, C<guestfs_next_private> or
+C<guestfs_set_private>.
-=item *
+=back
-Replace initial C</dev/sd> string with C</dev/hd>.
+The following example code shows how to print all keys and data
+pointers that are associated with the handle C<g>:
-For example, change C</dev/sda2> to C</dev/hda2>.
+ const char *key;
+ void *data = guestfs_first_private (g, &key);
+ while (data != NULL)
+ {
+ printf ("key = %s, data = %p\n", key, data);
+ data = guestfs_next_private (g, &key);
+ }
-If that named device exists, use it. If not, continue.
+More commonly you are only interested in keys that begin with an
+application-specific prefix C<foo_>. Modify the loop like so:
-=item *
+ const char *key;
+ void *data = guestfs_first_private (g, &key);
+ while (data != NULL)
+ {
+ if (strncmp (key, "foo_", strlen ("foo_")) == 0)
+ printf ("key = %s, data = %p\n", key, data);
+ data = guestfs_next_private (g, &key);
+ }
-Replace initial C</dev/sd> string with C</dev/vd>.
+If you need to modify keys while walking, then you have to jump back
+to the beginning of the loop. For example, to delete all keys
+prefixed with C<foo_>:
+
+ const char *key;
+ void *data;
+ again:
+ data = guestfs_first_private (g, &key);
+ while (data != NULL)
+ {
+ if (strncmp (key, "foo_", strlen ("foo_")) == 0)
+ {
+ guestfs_set_private (g, key, NULL);
+ /* note that 'key' pointer is now invalid, and so is
+ the internal iterator */
+ goto again;
+ }
+ data = guestfs_next_private (g, &key);
+ }
+
+Note that the above loop is guaranteed to terminate because the keys
+are being deleted, but other manipulations of keys within the loop
+might not terminate unless you also maintain an indication of which
+keys have been visited.
+
+=begin html
+
+<!-- old anchor for the next section -->
+<a name="state_machine_and_low_level_event_api"/>
+
+=end html
+
+=head1 ARCHITECTURE
+
+Internally, libguestfs is implemented by running an appliance (a
+special type of small virtual machine) using L<qemu(1)>. Qemu runs as
+a child process of the main program.
+
+ ___________________
+ / \
+ | main program |
+ | |
+ | | child process / appliance
+ | | __________________________
+ | | / qemu \
+ +-------------------+ RPC | +-----------------+ |
+ | libguestfs <--------------------> guestfsd | |
+ | | | +-----------------+ |
+ \___________________/ | | Linux kernel | |
+ | +--^--------------+ |
+ \_________|________________/
+ |
+ _______v______
+ / \
+ | Device or |
+ | disk image |
+ \______________/
-If that named device exists, use it. If not, return an error.
+The library, linked to the main program, creates the child process and
+hence the appliance in the L</guestfs_launch> function.
-=back
+Inside the appliance is a Linux kernel and a complete stack of
+userspace tools (such as LVM and ext2 programs) and a small
+controlling daemon called L</guestfsd>. The library talks to
+L</guestfsd> using remote procedure calls (RPC). There is a mostly
+one-to-one correspondence between libguestfs API calls and RPC calls
+to the daemon. Lastly the disk image(s) are attached to the qemu
+process which translates device access by the appliance's Linux kernel
+into accesses to the image.
-=head2 PORTABILITY CONCERNS
+A common misunderstanding is that the appliance "is" the virtual
+machine. Although the disk image you are attached to might also be
+used by some virtual machine, libguestfs doesn't know or care about
+this. (But you will care if both libguestfs's qemu process and your
+virtual machine are trying to update the disk image at the same time,
+since these usually results in massive disk corruption).
-Although the standard naming scheme and automatic translation is
-useful for simple programs and guestfish scripts, for larger programs
-it is best not to rely on this mechanism.
+=head1 STATE MACHINE
-Where possible for maximum future portability programs using
-libguestfs should use these future-proof techniques:
+libguestfs uses a state machine to model the child process:
-=over 4
+ |
+ guestfs_create
+ |
+ |
+ ____V_____
+ / \
+ | CONFIG |
+ \__________/
+ ^ ^ ^ \
+ / | \ \ guestfs_launch
+ / | _\__V______
+ / | / \
+ / | | LAUNCHING |
+ / | \___________/
+ / | /
+ / | guestfs_launch
+ / | /
+ ______ / __|____V
+ / \ ------> / \
+ | BUSY | | READY |
+ \______/ <------ \________/
-=item *
+The normal transitions are (1) CONFIG (when the handle is created, but
+there is no child process), (2) LAUNCHING (when the child process is
+booting up), (3) alternating between READY and BUSY as commands are
+issued to, and carried out by, the child process.
-Use L</guestfs_list_devices> or L</guestfs_list_partitions> to list
-actual device names, and then use those names directly.
+The guest may be killed by L</guestfs_kill_subprocess>, or may die
+asynchronously at any time (eg. due to some internal error), and that
+causes the state to transition back to CONFIG.
-Since those device names exist by definition, they will never be
-translated.
+Configuration commands for qemu such as L</guestfs_add_drive> can only
+be issued when in the CONFIG state.
-=item *
+The API offers one call that goes from CONFIG through LAUNCHING to
+READY. L</guestfs_launch> blocks until the child process is READY to
+accept commands (or until some failure or timeout).
+L</guestfs_launch> internally moves the state from CONFIG to LAUNCHING
+while it is running.
-Use higher level ways to identify filesystems, such as LVM names,
-UUIDs and filesystem labels.
+API actions such as L</guestfs_mount> can only be issued when in the
+READY state. These API calls block waiting for the command to be
+carried out (ie. the state to transition to BUSY and then back to
+READY). There are no non-blocking versions, and no way to issue more
+than one command per handle at the same time.
-=back
+Finally, the child process sends asynchronous messages back to the
+main program, such as kernel log messages. You can register a
+callback to receive these messages.
=head1 INTERNALS
how the receiver knows what type of args structure to expect, or none
at all.
+For functions that take optional arguments, the optional arguments are
+encoded in the C<guestfs_I<foo>_args> structure in the same way as
+ordinary arguments. A bitmask in the header indicates which optional
+arguments are meaningful. The bitmask is also checked to see if it
+contains bits set which the daemon does not know about (eg. if more
+optional arguments were added in a later version of the library), and
+this causes the call to be rejected.
+
The reply message for ordinary functions is:
total length (header + ret,
(see C<daemon/proto.c:notify_progress>). Not all calls generate
progress messages.
-=head1 MULTIPLE HANDLES AND MULTIPLE THREADS
-
-All high-level libguestfs actions are synchronous. If you want
-to use libguestfs asynchronously then you must create a thread.
-
-Only use the handle from a single thread. Either use the handle
-exclusively from one thread, or provide your own mutex so that two
-threads cannot issue calls on the same handle at the same time.
-
-See the graphical program guestfs-browser for one possible
-architecture for multithreaded programs using libvirt and libguestfs.
-
-=head1 QEMU WRAPPERS
-
-If you want to compile your own qemu, run qemu from a non-standard
-location, or pass extra arguments to qemu, then you can write a
-shell-script wrapper around qemu.
-
-There is one important rule to remember: you I<must C<exec qemu>> as
-the last command in the shell script (so that qemu replaces the shell
-and becomes the direct child of the libguestfs-using program). If you
-don't do this, then the qemu process won't be cleaned up correctly.
-
-Here is an example of a wrapper, where I have built my own copy of
-qemu from source:
-
- #!/bin/sh -
- qemudir=/home/rjones/d/qemu
- exec $qemudir/x86_64-softmmu/qemu-system-x86_64 -L $qemudir/pc-bios "$@"
-
-Save this script as C</tmp/qemu.wrapper> (or wherever), C<chmod +x>,
-and then use it by setting the LIBGUESTFS_QEMU environment variable.
-For example:
-
- LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish
-
-Note that libguestfs also calls qemu with the -help and -version
-options in order to determine features.
-
=head1 LIBGUESTFS VERSION NUMBERS
Since April 2010, libguestfs has started to make separate development
backporting fixes from development, that branch will stabilize over
time.
+=head1 EXTENDING LIBGUESTFS
+
+=head2 ADDING A NEW API ACTION
+
+Large amounts of boilerplate code in libguestfs (RPC, bindings,
+documentation) are generated, and this makes it easy to extend the
+libguestfs API.
+
+To add a new API action there are two changes:
+
+=over 4
+
+=item 1.
+
+You need to add a description of the call (name, parameters, return
+type, tests, documentation) to C<generator/generator_actions.ml>.
+
+There are two sorts of API action, depending on whether the call goes
+through to the daemon in the appliance, or is serviced entirely by the
+library (see L</ARCHITECTURE> above). L</guestfs_sync> is an example
+of the former, since the sync is done in the appliance.
+L</guestfs_set_trace> is an example of the latter, since a trace flag
+is maintained in the handle and all tracing is done on the library
+side.
+
+Most new actions are of the first type, and get added to the
+C<daemon_functions> list. Each function has a unique procedure number
+used in the RPC protocol which is assigned to that action when we
+publish libguestfs and cannot be reused. Take the latest procedure
+number and increment it.
+
+For library-only actions of the second type, add to the
+C<non_daemon_functions> list. Since these functions are serviced by
+the library and do not travel over the RPC mechanism to the daemon,
+these functions do not need a procedure number, and so the procedure
+number is set to C<-1>.
+
+=item 2.
+
+Implement the action (in C):
+
+For daemon actions, implement the function C<do_E<lt>nameE<gt>> in the
+C<daemon/> directory.
+
+For library actions, implement the function C<guestfs__E<lt>nameE<gt>>
+(note: double underscore) in the C<src/> directory.
+
+In either case, use another function as an example of what to do.
+
+=back
+
+After making these changes, use C<make> to compile.
+
+Note that you don't need to implement the RPC, language bindings,
+manual pages or anything else. It's all automatically generated from
+the OCaml description.
+
+=head2 ADDING TESTS FOR AN API ACTION
+
+You can supply zero or as many tests as you want per API call. The
+tests can either be added as part of the API description
+(C<generator/generator_actions.ml>), or in some rarer cases you may
+want to drop a script into C<regressions/>. Note that adding a script
+to C<regressions/> is slower, so if possible use the first method.
+
+The following describes the test environment used when you add an API
+test in C<generator_actions.ml>.
+
+The test environment has 4 block devices:
+
+=over 4
+
+=item C</dev/sda> 500MB
+
+General block device for testing.
+
+=item C</dev/sdb> 50MB
+
+C</dev/sdb1> is an ext2 filesystem used for testing
+filesystem write operations.
+
+=item C</dev/sdc> 10MB
+
+Used in a few tests where two block devices are needed.
+
+=item C</dev/sdd>
+
+ISO with fixed content (see C<images/test.iso>).
+
+=back
+
+To be able to run the tests in a reasonable amount of time, the
+libguestfs appliance and block devices are reused between tests. So
+don't try testing L</guestfs_kill_subprocess> :-x
+
+Each test starts with an initial scenario, selected using one of the
+C<Init*> expressions, described in C<generator/generator_types.ml>.
+These initialize the disks mentioned above in a particular way as
+documented in C<generator_types.ml>. You should not assume anything
+about the previous contents of other disks that are not initialized.
+
+You can add a prerequisite clause to any individual test. This is a
+run-time check, which, if it fails, causes the test to be skipped.
+Useful if testing a command which might not work on all variations of
+libguestfs builds. A test that has prerequisite of C<Always> means to
+run unconditionally.
+
+In addition, packagers can skip individual tests by setting
+environment variables before running C<make check>.
+
+ SKIP_TEST_<CMD>_<NUM>=1
+
+eg: C<SKIP_TEST_COMMAND_3=1> skips test #3 of L</guestfs_command>.
+
+or:
+
+ SKIP_TEST_<CMD>=1
+
+eg: C<SKIP_TEST_ZEROFREE=1> skips all L</guestfs_zerofree> tests.
+
+Packagers can run only certain tests by setting for example:
+
+ TEST_ONLY="vfs_type zerofree"
+
+See C<capitests/tests.c> for more details of how these environment
+variables work.
+
+=head2 DEBUGGING NEW API ACTIONS
+
+Test new actions work before submitting them.
+
+You can use guestfish to try out new commands.
+
+Debugging the daemon is a problem because it runs inside a minimal
+environment. However you can fprintf messages in the daemon to
+stderr, and they will show up if you use C<guestfish -v>.
+
+=head2 FORMATTING CODE AND OTHER CONVENTIONS
+
+Our C source code generally adheres to some basic code-formatting
+conventions. The existing code base is not totally consistent on this
+front, but we do prefer that contributed code be formatted similarly.
+In short, use spaces-not-TABs for indentation, use 2 spaces for each
+indentation level, and other than that, follow the K&R style.
+
+If you use Emacs, add the following to one of one of your start-up files
+(e.g., ~/.emacs), to help ensure that you get indentation right:
+
+ ;;; In libguestfs, indent with spaces everywhere (not TABs).
+ ;;; Exceptions: Makefile and ChangeLog modes.
+ (add-hook 'find-file-hook
+ '(lambda () (if (and buffer-file-name
+ (string-match "/libguestfs\\>"
+ (buffer-file-name))
+ (not (string-equal mode-name "Change Log"))
+ (not (string-equal mode-name "Makefile")))
+ (setq indent-tabs-mode nil))))
+
+ ;;; When editing C sources in libguestfs, use this style.
+ (defun libguestfs-c-mode ()
+ "C mode with adjusted defaults for use with libguestfs."
+ (interactive)
+ (c-set-style "K&R")
+ (setq c-indent-level 2)
+ (setq c-basic-offset 2))
+ (add-hook 'c-mode-hook
+ '(lambda () (if (string-match "/libguestfs\\>"
+ (buffer-file-name))
+ (libguestfs-c-mode))))
+
+Enable warnings when compiling (and fix any problems this
+finds):
+
+ ./configure --enable-gcc-warnings
+
+Useful targets are:
+
+ make syntax-check # checks the syntax of the C code
+ make check # runs the test suite
+
+=head2 DAEMON CUSTOM PRINTF FORMATTERS
+
+In the daemon code we have created custom printf formatters C<%Q> and
+C<%R>, which are used to do shell quoting.
+
+=over 4
+
+=item %Q
+
+Simple shell quoted string. Any spaces or other shell characters are
+escaped for you.
+
+=item %R
+
+Same as C<%Q> except the string is treated as a path which is prefixed
+by the sysroot.
+
+=back
+
+For example:
+
+ asprintf (&cmd, "cat %R", path);
+
+would produce C<cat /sysroot/some\ path\ with\ spaces>
+
+I<Note:> Do I<not> use these when you are passing parameters to the
+C<command{,r,v,rv}()> functions. These parameters do NOT need to be
+quoted because they are not passed via the shell (instead, straight to
+exec). You probably want to use the C<sysroot_path()> function
+however.
+
+=head2 SUBMITTING YOUR NEW API ACTIONS
+
+Submit patches to the mailing list:
+L<http://www.redhat.com/mailman/listinfo/libguestfs>
+and CC to L<rjones@redhat.com>.
+
+=head2 INTERNATIONALIZATION (I18N) SUPPORT
+
+We support i18n (gettext anyhow) in the library.
+
+However many messages come from the daemon, and we don't translate
+those at the moment. One reason is that the appliance generally has
+all locale files removed from it, because they take up a lot of space.
+So we'd have to readd some of those, as well as copying our PO files
+into the appliance.
+
+Debugging messages are never translated, since they are intended for
+the programmers.
+
+=head2 SOURCE CODE SUBDIRECTORIES
+
+=over 4
+
+=item C<appliance>
+
+The libguestfs appliance, build scripts and so on.
+
+=item C<capitests>
+
+Automated tests of the C API.
+
+=item C<cat>
+
+The L<virt-cat(1)>, L<virt-filesystems(1)> and L<virt-ls(1)> commands
+and documentation.
+
+=item C<contrib>
+
+Outside contributions, experimental parts.
+
+=item C<daemon>
+
+The daemon that runs inside the libguestfs appliance and carries out
+actions.
+
+=item C<df>
+
+L<virt-df(1)> command and documentation.
+
+=item C<examples>
+
+C API example code.
+
+=item C<fish>
+
+L<guestfish(1)>, the command-line shell, and various shell scripts
+built on top such as L<virt-copy-in(1)>, L<virt-copy-out(1)>,
+L<virt-tar-in(1)>, L<virt-tar-out(1)>.
+
+=item C<fuse>
+
+L<guestmount(1)>, FUSE (userspace filesystem) built on top of libguestfs.
+
+=item C<generator>
+
+The crucially important generator, used to automatically generate
+large amounts of boilerplate C code for things like RPC and bindings.
+
+=item C<images>
+
+Files used by the test suite.
+
+Some "phony" guest images which we test against.
+
+=item C<inspector>
+
+L<virt-inspector(1)>, the virtual machine image inspector.
+
+=item C<logo>
+
+Logo used on the website. The fish is called Arthur by the way.
+
+=item C<m4>
+
+M4 macros used by autoconf.
+
+=item C<po>
+
+Translations of simple gettext strings.
+
+=item C<po-docs>
+
+The build infrastructure and PO files for translations of manpages and
+POD files. Eventually this will be combined with the C<po> directory,
+but that is rather complicated.
+
+=item C<regressions>
+
+Regression tests.
+
+=item C<rescue>
+
+L<virt-rescue(1)> command and documentation.
+
+=item C<src>
+
+Source code to the C library.
+
+=item C<tools>
+
+Command line tools written in Perl (L<virt-resize(1)> and many others).
+
+=item C<test-tool>
+
+Test tool for end users to test if their qemu/kernel combination
+will work with libguestfs.
+
+=item C<csharp>
+
+=item C<haskell>
+
+=item C<java>
+
+=item C<ocaml>
+
+=item C<php>
+
+=item C<perl>
+
+=item C<python>
+
+=item C<ruby>
+
+Language bindings.
+
+=back
+
=head1 ENVIRONMENT VARIABLES
=over 4
=item TMPDIR
-Location of temporary directory, defaults to C</tmp>.
+Location of temporary directory, defaults to C</tmp> except for the
+cached supermin appliance which defaults to C</var/tmp>.
If libguestfs was compiled to use the supermin appliance then the
real appliance is cached in this directory, shared between all
handles belonging to the same EUID. You can use C<$TMPDIR> to
-configure another directory to use in case C</tmp> is not large
+configure another directory to use in case C</var/tmp> is not large
enough.
=back
=head1 SEE ALSO
+L<guestfs-examples(3)>,
+L<guestfs-ocaml(3)>,
+L<guestfs-python(3)>,
+L<guestfs-ruby(3)>,
L<guestfish(1)>,
L<guestmount(1)>,
L<virt-cat(1)>,
+L<virt-copy-in(1)>,
+L<virt-copy-out(1)>,
L<virt-df(1)>,
L<virt-edit(1)>,
+L<virt-filesystems(1)>,
L<virt-inspector(1)>,
L<virt-list-filesystems(1)>,
L<virt-list-partitions(1)>,
L<virt-make-fs(1)>,
L<virt-rescue(1)>,
L<virt-tar(1)>,
+L<virt-tar-in(1)>,
+L<virt-tar-out(1)>,
L<virt-win-reg(1)>,
L<qemu(1)>,
L<febootstrap(1)>,
git.annexia.org / libguestfs.git / blobdiff