X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=50e9f50b11ba7b60d0c38b53e4ed157b0052bf05;hp=a4d9c5724561aa8058bbfce07e004d2e677e8887;hb=b4618fb060b40ba70f2be28b1b1ad625722a7edf;hpb=90d06e28888d9a492560ca986dca0708f881d173 diff --git a/src/guestfs.pod b/src/guestfs.pod index a4d9c57..50e9f50 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -43,7 +43,7 @@ FUSE. 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 @@ -124,7 +124,22 @@ disk, an actual block device, or simply an empty file of zeroes that you have created through L. Libguestfs lets you do useful things to all of these. -You can add a disk read-only using L, in which +The call you should use in modern code for adding drives is +L. 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. In either case libguestfs won't modify the file. Be extremely cautious if the disk image is in use, eg. if it is being @@ -334,7 +349,7 @@ files. =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. @@ -358,6 +373,11 @@ The command will be running in limited memory. =item * +The network may not be available unless you enable it +(see L). + +=item * + Only supports Linux guests (not Windows, BSD, etc). =item * @@ -370,6 +390,22 @@ an X86 host). For SELinux guests, you may need to enable SELinux and load policy first. See L in this manpage. +=item * + +I 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 and @@ -621,6 +657,13 @@ For documentation see the file C. For documentation see L. +=item B + +For documentation see C 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 For documentation do: @@ -674,6 +717,9 @@ Note that in L autosync is the default. So quick and 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, then C<-o sync,noatime> are added @@ -724,7 +770,7 @@ The error message you get from this is also a little obscure. This could be fixed in the generator by specially marking parameters and return values which take bytes or other units. -=item Protocol should return errno with error messages. +=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). @@ -732,6 +778,40 @@ Currently L 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 +(eg. C) and a similar pathname. A file might just happen +to be called C in the directory C (consider some non-Unix +VM image). + +In the current API we usually resolve this ambiguity by having two +separate calls, for example L and +L. Some API calls are ambiguous and +(incorrectly) resolve the problem by detecting if the path supplied +begins with C. + +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), 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 @@ -789,7 +869,8 @@ L below. Create a connection handle. -You have to call L on the handle at least once. +You have to call L (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. @@ -836,11 +917,11 @@ largest number of results. =head2 guestfs_set_error_handler typedef void (*guestfs_error_handler_cb) (guestfs_h *g, - void *data, + void *opaque, const char *msg); void guestfs_set_error_handler (guestfs_h *g, guestfs_error_handler_cb cb, - void *data); + void *opaque); The callback C will be called if there is an error. The parameters passed to the callback are an opaque data pointer and the @@ -857,7 +938,7 @@ If you set C to C then I handler is called. =head2 guestfs_get_error_handler guestfs_error_handler_cb guestfs_get_error_handler (guestfs_h *g, - void **data_rtn); + void **opaque_rtn); Returns the current error handler callback. @@ -932,10 +1013,17 @@ Note however that you have to do C first. =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, Cguestfs.hE> defines symbols +for each C API function, such as: + + #define LIBGUESTFS_HAVE_DD 1 + +if L 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]) @@ -956,8 +1044,6 @@ You can use L to test if a function is available at run time, as in this example program (note that you still need the compile time check as well): - #include - #include #include #include @@ -966,7 +1052,7 @@ need the compile time check as well): main () { - #ifdef HAVE_GUESTFS_DD + #ifdef LIBGUESTFS_HAVE_DD void *dl; int has_function; @@ -999,6 +1085,101 @@ package versioning: 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. 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. + =begin html @@ -1089,24 +1270,21 @@ causes the state to transition back to CONFIG. Configuration commands for qemu such as L 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 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 blocks until the child process is READY to +accept commands (or until some failure or timeout). L internally moves the state from CONFIG to LAUNCHING while it is running. -High-level API actions such as L 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 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 @@ -1178,6 +1356,94 @@ languages (eg. if your HLL interpreter has already been cleaned up by the time this is called, and if your callback then jumps into some HLL function). +=head2 guestfs_set_progress_callback + + typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque, + int proc_nr, int serial, + uint64_t position, uint64_t total); + void guestfs_set_progress_callback (guestfs_h *g, + guestfs_progress_cb cb, + void *opaque); + +Some long-running operations can generate progress messages. If +this callback is registered, then it will be called each time a +progress message is generated (usually two seconds after the +operation started, and three times per second thereafter until +it completes, although the frequency may change in future versions). + +The callback receives two numbers: C and C. +The units of C are not defined, although for some +operations C may relate in some way to the amount of +data to be transferred (eg. in bytes or megabytes), and +C may be the portion which has been transferred. + +The only defined and stable parts of the API are: + +=over 4 + +=item * + +The callback can display to the user some type of progress bar or +indicator which shows the ratio of C:C. + +=item * + +0 E= C E= C + +=item * + +If any progress notification is sent during a call, then a final +progress notification is always sent when C = C. + +This is to simplify caller code, so callers can easily set the +progress indicator to "100%" at the end of the operation, without +requiring special code to detect this case. + +=back + +The callback also receives the procedure number and serial number of +the call. These are only useful for debugging protocol issues, and +the callback can normally ignore them. The callback may want to +print these numbers in error messages or debugging messages. + +=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. + +To attach a named piece of data, use the following call: + + void guestfs_set_private (guestfs_h *g, const char *key, void *data); + +C is the name to associate with this data, and C is an +arbitrary pointer (which can be C). Any previous item with the +same name is overwritten. + +You can use any C you want, but names beginning with an +underscore character are reserved for internal libguestfs purposes +(for implementing language bindings). It is recommended to prefix the +name with some unique string to avoid collisions with other users. + +To retrieve the pointer, use: + + void *guestfs_get_private (guestfs_h *g, const char *key); + +This function returns C if either no data is found associated +with C, or if the user previously set the C's C +pointer to C. + +Libguestfs does not try to look at or interpret the C pointer in +any way. As far as libguestfs is concerned, it need not be a valid +pointer at all. In particular, libguestfs does I try to free the +data when the handle is closed. If the data must be freed, then the +caller must either free it before calling L or must +set up a close callback to do it (see L, +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. + =head1 BLOCK DEVICE NAMING In the kernel there is now quite a profusion of schemata for naming @@ -1417,10 +1683,23 @@ parameters, but with the roles of daemon and library reversed. =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) which indicates that the guest -and daemon is alive. This is what L waits for. +When the daemon launches it sends an initial word +(C) which indicates that the guest and daemon is +alive. This is what L 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, followed by a fixed size progress message. + +The library turns them into progress callbacks (see +C) if there is a callback registered, +or discards them if not. + +The daemon self-limits the frequency of progress messages it sends +(see C). Not all calls generate +progress messages. =head1 MULTIPLE HANDLES AND MULTIPLE THREADS @@ -1431,6 +1710,9 @@ 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 @@ -1563,9 +1845,9 @@ has the same effect as calling C. Location of temporary directory, defaults to C. -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 is not large enough.