X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=dd06880842bf663709386137ae2e205427b4f15b;hp=97b9282409dc9868a387afbb0090bbca0be9d03b;hb=aae5bebe6878c01803653fae166c58b7217b6100;hpb=b1454e38987473c94f20b10061031f2abe5a69a0 diff --git a/src/guestfs.pod b/src/guestfs.pod index 97b9282..dd06880 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -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 @@ -375,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 @@ -686,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 @@ -736,16 +770,36 @@ 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 Library should return errno with error messages. +=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). -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 goes through hoops to try to reverse the -error message string into an errno, see the function error() in -fuse/guestmount.c. +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. -In libguestfs 1.5.4, the protocol was changed so that the -Linux errno is sent back from the daemon. +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 @@ -804,7 +858,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. @@ -822,10 +877,17 @@ This closes the connection handle and frees up all resources used. =head1 ERROR HANDLING -The convention in all functions that return C is that they return -C<-1> to indicate an error. You can get additional information on -errors by calling L and/or by setting up an error -handler with L. +API functions can return errors. For example, almost all functions +that return C 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, L, +and/or by setting up an error handler with +L. The default error handler prints the information string to C. @@ -848,6 +910,45 @@ 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. +=head2 guestfs_last_errno + + int guestfs_last_errno (guestfs_h *g); + +This returns the last error number (errno) that happened on C. + +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. In practice this should only happen in very rare +circumstances. + =head2 guestfs_set_error_handler typedef void (*guestfs_error_handler_cb) (guestfs_h *g, @@ -861,6 +962,9 @@ The callback C 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 is not passed to the callback. To get that the callback must +call L. + Note that the message string C is freed as soon as the callback function returns, so if you want to stash it somewhere you must make your own copy. @@ -1019,6 +1123,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 @@ -1549,6 +1748,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 @@ -1681,9 +1883,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.