Libguestfs is a library that can be linked with C and C++ management
programs (or management programs written in OCaml, Perl, Python, Ruby,
-Java, Haskell or C#). You can also use it from shell scripts or the
+Java, PHP, Haskell or C#). You can also use it from shell scripts or the
command line.
You don't need to be root to use libguestfs, although obviously you do
you have created through L<posix_fallocate(3)>. Libguestfs lets you
do useful things to all of these.
-You can add a disk read-only using L</guestfs_add_drive_ro>, in which
+The call you should use in modern code for adding drives is
+L</guestfs_add_drive_opts>. To add a disk image, allowing writes, and
+specifying that the format is raw, do:
+
+ guestfs_add_drive_opts (g, filename,
+ GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
+ -1);
+
+You can add a disk read-only using:
+
+ guestfs_add_drive_opts (g, filename,
+ GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
+ GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
+ -1);
+
+or by calling the older function L</guestfs_add_drive_ro>. In either
case libguestfs won't modify the file.
Be extremely cautious if the disk image is in use, eg. if it is being
=head2 RUNNING COMMANDS
-Although libguestfs is a primarily an API for manipulating files
+Although libguestfs is primarily an API for manipulating files
inside guest images, we also provide some limited facilities for
running commands inside guests.
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.
+
=back
The two main API calls to run commands are L</guestfs_command> and
For documentation see L<Sys::Guestfs(3)>.
+=item B<PHP>
+
+For documentation see C<README-PHP> supplied with libguestfs
+sources or in the php-libguestfs package for your distribution.
+
+The PHP binding only works correctly on 64 bit machines.
+
=item B<Python>
For documentation do:
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
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
+(eg. C</dev/sdb2>) and a similar pathname. A file might just happen
+to be called C<sdb2> in the directory C</dev> (consider some non-Unix
+VM image).
+
+In the current API we usually resolve this ambiguity by having two
+separate calls, for example L</guestfs_checksum> and
+L</guestfs_checksum_device>. Some API calls are ambiguous and
+(incorrectly) resolve the problem by detecting if the path supplied
+begins with C</dev/>.
+
+To avoid both the ambiguity and the need to duplicate some calls, we
+could make paths/devices into structured names. One way to do this
+would be to use a notation like grub (C<hd(0,0)>), although nobody
+really likes this aspect of grub. Another way would be to use a
+structured type, equivalent to this OCaml type:
+
+ type path = Path of string | Device of int | Partition of int * int
+
+which would allow you to pass arguments like:
+
+ Path "/foo/bar"
+ Device 1 (* /dev/sdb, or perhaps /dev/sda *)
+ Partition (1, 2) (* /dev/sdb2 (or is it /dev/sda2 or /dev/sdb3?) *)
+ Path "/dev/sdb2" (* not a device *)
+
+As you can see there are still problems to resolve even with this
+representation. Also consider how it might work in guestfish.
+
=back
=head2 PROTOCOL LIMITS
Create a connection handle.
-You have to call L</guestfs_add_drive> on the handle at least once.
+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.
=head2 SINGLE CALLS AT COMPILE TIME
-If you need to test whether a single libguestfs function is
-available at compile time, we recommend using build tools
-such as autoconf or cmake. For example in autotools you could
-use:
+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])
at run time, as in this example program (note that you still
need the compile time check as well):
- #include <config.h>
-
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
main ()
{
- #ifdef HAVE_GUESTFS_DD
+ #ifdef LIBGUESTFS_HAVE_DD
void *dl;
int has_function;
Requires: libguestfs >= 1.0.80
+=head1 CALLS WITH OPTIONAL ARGUMENTS
+
+A recent feature of the API is the introduction of calls which take
+optional arguments. In C these are declared 3 ways. The main way is
+as a call which takes variable arguments (ie. C<...>), as in this
+example:
+
+ int guestfs_add_drive_opts (guestfs_h *g, const char *filename, ...);
+
+Call this with a list of optional arguments, terminated by C<-1>.
+So to call with no optional arguments specified:
+
+ guestfs_add_drive_opts (g, filename, -1);
+
+With a single optional argument:
+
+ guestfs_add_drive_opts (g, filename,
+ GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
+ -1);
+
+With two:
+
+ guestfs_add_drive_opts (g, filename,
+ GUESTFS_ADD_DRIVE_OPTS_FORMAT, "qcow2",
+ GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
+ -1);
+
+and so forth. Don't forget the terminating C<-1> otherwise
+Bad Things will happen!
+
+=head2 USING va_list FOR OPTIONAL ARGUMENTS
+
+The second variant has the same name with the suffix C<_va>, which
+works the same way but takes a C<va_list>. See the C manual for
+details. For the example function, this is declared:
+
+ int guestfs_add_drive_opts_va (guestfs_h *g, const char *filename,
+ va_list args);
+
+=head2 CONSTRUCTING OPTIONAL ARGUMENTS
+
+The third variant is useful where you need to construct these
+calls. You pass in a structure where you fill in the optional
+fields. The structure has a bitmask as the first element which
+you must set to indicate which fields you have filled in. For
+our example function the structure and call are declared:
+
+ struct guestfs_add_drive_opts_argv {
+ uint64_t bitmask;
+ int readonly;
+ const char *format;
+ /* ... */
+ };
+ int guestfs_add_drive_opts_argv (guestfs_h *g, const char *filename,
+ const struct guestfs_add_drive_opts_argv *optargs);
+
+You could call it like this:
+
+ struct guestfs_add_drive_opts_argv optargs = {
+ .bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK |
+ GUESTFS_ADD_DRIVE_OPTS_FORMAT_BITMASK,
+ .readonly = 1,
+ .format = "qcow2"
+ };
+
+ guestfs_add_drive_opts_argv (g, filename, &optargs);
+
+Notes:
+
+=over 4
+
+=item *
+
+The C<_BITMASK> suffix on each option name when specifying the
+bitmask.
+
+=item *
+
+You do not need to fill in all fields of the structure.
+
+=item *
+
+There must be a one-to-one correspondence between fields of the
+structure that are filled in, and bits set in the bitmask.
+
+=back
+
+=head2 OPTIONAL ARGUMENTS IN OTHER LANGUAGES
+
+In other languages, optional arguments are expressed in the
+way that is natural for that language. We refer you to the
+language-specific documentation for more details on that.
+
+For guestfish, see L<guestfish(1)/OPTIONAL ARGUMENTS>.
+
=begin html
<!-- old anchor for the next section -->
Configuration commands for qemu such as L</guestfs_add_drive> can only
be issued when in the CONFIG state.
-The high-level API offers two calls that go 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).
+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.
-High-level API actions such as L</guestfs_mount> can only be issued
-when in the READY state. These high-level API calls block waiting for
-the command to be carried out (ie. the state to transition to BUSY and
-then back to READY). But using the low-level event API, you get
-non-blocking versions. (But you can still only carry out one
-operation per handle at a time - that is a limitation of the
-communications protocol we use).
+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. Mostly these are ignored
-by the high-level API, but using the low-level event API you can
-register to receive these messages.
+main program, such as kernel log messages. You can register a
+callback to receive these messages.
=head2 SETTING CALLBACKS TO HANDLE EVENTS
=head3 INITIAL MESSAGE
-Because the underlying channel (QEmu -net channel) doesn't have any
-sort of connection control, when the daemon launches it sends an
-initial word (C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest
-and daemon is alive. This is what L</guestfs_launch> waits for.
+When the daemon launches it sends an initial word
+(C<GUESTFS_LAUNCH_FLAG>) which indicates that the guest and daemon is
+alive. This is what L</guestfs_launch> waits for.
+
+=head3 PROGRESS NOTIFICATION MESSAGES
+
+The daemon may send progress notification messages at any time. These
+are distinguished by the normal length word being replaced by
+C<GUESTFS_PROGRESS_FLAG>, followed by a fixed size progress message.
+
+The library turns them into progress callbacks (see
+C<guestfs_set_progress_callback>) if there is a callback registered,
+or discards them if not.
+
+The daemon self-limits the frequency of progress messages it sends
+(see C<daemon/proto.c:notify_progress>). Not all calls generate
+progress messages.
=head1 MULTIPLE HANDLES AND MULTIPLE THREADS
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 of temporary directory, defaults to C</tmp>.
-If libguestfs was compiled to use the supermin appliance then each
-handle will require rather a large amount of space in this directory
-for short periods of time (~ 80 MB). You can use C<$TMPDIR> to
+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
enough.
git.annexia.org / libguestfs.git / blobdiff