X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs.pod;h=0e7079c231afcb8631d962671ca478fb1f1bc5a3;hp=63bd14c43a0d74a6ac85e7e1a9db8de37bfe8500;hb=540c85a1102c5876265502f8ae287ea697834d20;hpb=5de49dc0d82a86032eb51e2cb9e43813e2480594 diff --git a/guestfs.pod b/guestfs.pod index 63bd14c..0e7079c 100644 --- a/guestfs.pod +++ b/guestfs.pod @@ -6,12 +6,13 @@ guestfs - Library for accessing and modifying virtual machine images =head1 SYNOPSIS - guestfs_h handle = guestfs_create (); + #include + + guestfs_h *handle = guestfs_create (); guestfs_add_drive (handle, "guest.img"); guestfs_launch (handle); - guestfs_wait_ready (handle); guestfs_mount (handle, "/dev/sda1", "/"); - guestfs_touch_file (handle, "/hello"); + guestfs_touch (handle, "/hello"); guestfs_sync (handle); guestfs_close (handle); @@ -32,44 +33,595 @@ schemes, qcow, qcow2, vmdk. Libguestfs provides ways to enumerate guest storage (eg. partitions, LVs, what filesystem is in each LV, etc.). It can also run commands -in the context of the guest. Also you can mount guest filesystems on -the host (requires root privs and NFS). +in the context of the guest. Also you can access filesystems over FTP. Libguestfs is a library that can be linked with C and C++ management -programs (or management programs written in other languages, if people -contribute the language bindings). You can also use it from shell -scripts or the command line. +programs (or management programs written in OCaml, Perl, Python, Ruby, Java +or Haskell). You can also use it from shell scripts or the command line. -=head1 CONNECTION MANAGEMENT +You don't need to be root to use libguestfs, although obviously you do +need enough permissions to access the disk images. + +Libguestfs is a large API because it can do many things. For a gentle +introduction, please read the L section next. + +=head1 API OVERVIEW + +This section provides a gentler overview of the libguestfs API. We +also try to group API calls together, where that may not be obvious +from reading about the individual calls below. + +=head2 HANDLES + +Before you can use libguestfs calls, you have to create a handle. +Then you must add at least one disk image to the handle, followed by +launching the handle, then performing whatever operations you want, +and finally closing the handle. So the general structure of all +libguestfs-using programs looks like this: + + guestfs_h *handle = guestfs_create (); + + /* Call guestfs_add_drive additional times if there are + * multiple disk images. + */ + guestfs_add_drive (handle, "guest.img"); + + /* Most manipulation calls won't work until you've launched + * the handle. You have to do this _after_ adding drives + * and _before_ other commands. + */ + guestfs_launch (handle); + + /* Now you can examine what partitions, LVs etc are available. + */ + char **partitions = guestfs_list_partitions (handle); + char **logvols = guestfs_lvs (handle); + + /* To access a filesystem in the image, you must mount it. + */ + guestfs_mount (handle, "/dev/sda1", "/"); + + /* Now you can perform filesystem actions on the guest + * disk image. + */ + guestfs_touch (handle, "/hello"); + + /* You only need to call guestfs_sync if you have made + * changes to the guest image. + */ + guestfs_sync (handle); + + /* Close the handle. */ + guestfs_close (handle); + +The code above doesn't include any error checking. In real code you +should check return values carefully for errors. In general all +functions that return integers return C<-1> on error, and all +functions that return pointers return C on error. See section +L below for how to handle errors, and consult the +documentation for each function call below to see precisely how they +return error indications. + +=head2 DISK IMAGES + +The image filename (C<"guest.img"> in the example above) could be a +disk image from a virtual machine, a L copy of a physical hard +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 C, in which +case libguestfs won't modify the file. + +Be extremely cautious if the disk image is in use, eg. if it is being +used by a virtual machine. Adding it read-write will almost certainly +cause disk corruption, but adding it read-only is safe. + +You must add at least one disk image, and you may add multiple disk +images. In the API, the disk images are usually referred to as +C (for the first one you added), C (for the second +one you added), etc. + +Once C has been called you cannot add any more images. +You can call C to get a list of the device +names, in the order that you added them. See also L below. + +=head2 MOUNTING + +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 C. 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 (handle, "/dev/sda1", "/"); + +where C means literally the first partition (C<1>) of the +first disk image that we added (C). If the disk contains +Linux LVM2 logical volumes you could refer to those instead (eg. C). + +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 +C and C to list possible +partitions and LVs, and either try mounting each to see what is +mountable, or else examine them with C. But you might +find it easier to look at higher level programs built on top of +libguestfs, in particular L. + +To mount a disk image read-only, use C. There are +several other variations of the C call. + +=head2 FILESYSTEM ACCESS AND MODIFICATION + +The majority of the libguestfs API consists of fairly low-level calls +for accessing and modifying the files, directories, symlinks etc on +mounted filesystems. There are over a hundred such calls which you +can find listed in detail below in this man page, and we don't even +pretend to cover them all in this overview. + +Specify filenames as full paths including the mount point. + +For example, if you mounted a filesystem at C<"/"> and you want to +read the file called C<"etc/passwd"> then you could do: + + char *data = guestfs_cat (handle, "/etc/passwd"); + +This would return C as a newly allocated buffer containing the +full content of that file (with some conditions: see also +L below), or C if there was an error. + +As another example, to create a top-level directory on that filesystem +called C<"var"> you would do: + + guestfs_mkdir (handle, "/var"); + +To create a symlink you could do: + + guestfs_ln_s (handle, "/etc/init.d/portmap", + "/etc/rc3.d/S30portmap"); + +Libguestfs will reject attempts to use relative paths. There is no +concept of a current working directory. Libguestfs can return errors +in many situations: for example if the filesystem isn't writable, or +if a file or directory that you requested doesn't exist. If you are +using the C API (documented here) you have to check for those error +conditions after each call. (Other language bindings turn these +errors into exceptions). + +File writes are affected by the per-handle umask, set by calling +C and defaulting to 022. + +=head2 PARTITIONING + +Libguestfs contains API calls to read, create and modify partition +tables on disk images. + +In the common case where you want to create a single partition +covering the whole disk, you should use the C +call: + + const char *parttype = "mbr"; + if (disk_is_larger_than_2TB) + parttype = "gpt"; + guestfs_part_disk (g, "/dev/sda", parttype); + +Obviously this effectively wipes anything that was on that disk image +before. + +In general MBR partitions are both unnecessarily complicated and +depend on archaic details, namely the Cylinder-Head-Sector (CHS) +geometry of the disk. C can be used to +create more complex arrangements where the relative sizes are +expressed in megabytes instead of cylinders, which is a small win. +C will choose the nearest cylinder to approximate the +requested size. There's a lot of crazy stuff to do with IDE and +virtio disks having different, incompatible CHS geometries, that you +probably don't want to know about. + +My advice: make a single partition to cover the whole disk, then use +LVM on top. + +=head2 LVM2 + +Libguestfs provides access to a large part of the LVM2 API, such as +C and C. It won't make much sense +unless you familiarize yourself with the concepts of physical volumes, +volume groups and logical volumes. + +This author strongly recommends reading the LVM HOWTO, online at +L. + +=head2 DOWNLOADING + +Use C 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. + +C can be used to read files which contain +arbitrary 8 bit data, since it returns a (pointer, size) pair. +However it is still limited to "small" files, less than 2 MB. + +C can be used to download any file, with no +limits on content or size (even files larger than 4 GB). + +To download multiple files, see C and +C. + +=head2 UPLOADING + +It's often the case that you want to write a file or files to the disk +image. + +For small, single files, use C. This call +currently contains a bug which limits the call to plain text files +(not containing ASCII NUL characters). + +To upload a single file, use C. This call has no +limits on file content or size (even files larger than 4 GB). + +To upload multiple files, see C and C. + +However the fastest way to upload I +is to turn them into a squashfs or CD ISO (see L and +L), then attach this using C. If +you add the drive in a predictable way (eg. adding it last after all +other drives) then you can get the device name from +C and mount it directly using +C. Note that squashfs images are sometimes +non-portable between kernel versions, and they don't support labels or +UUIDs. If you want to pre-build an image or you need to mount it +using a label or UUID, use an ISO image instead. + +=head2 LISTING FILES + +C is just designed for humans to read (mainly when using +the L-equivalent command C). + +C is a quick way to get a list of files in a directory +from programs, as a flat list of strings. + +C is a programmatic way to get a list of files in a +directory, plus additional information about each one. It is more +equivalent to using the L call on a local filesystem. + +C can be used to recursively list files. + +=head2 RUNNING COMMANDS + +Although libguestfs is a primarily an API for manipulating files +inside guest images, we also provide some limited facilities for +running commands inside guests. + +There are many limitations to this: + +=over 4 + +=item * + +The kernel version that the command runs under will be different +from what it expects. + +=item * + +If the command needs to communicate with daemons, then most likely +they won't be running. + +=item * + +The command will be running in limited memory. + +=item * + +Only supports Linux guests (not Windows, BSD, etc). + +=item * + +Architecture limitations (eg. won't work for a PPC guest on +an X86 host). + +=item * + +For SELinux guests, you may need to enable SELinux and load policy +first. See L in this manpage. + +=back + +The two main API calls to run commands are C and +C (there are also variations). + +The difference is that C runs commands using the shell, so +any shell globs, redirections, etc will work. + +=head2 CONFIGURATION FILES + +To read and write configuration files in Linux guest filesystems, we +strongly recommend using Augeas. For example, Augeas understands how +to read and write, say, a Linux shadow password file or X.org +configuration file, and so avoids you having to write that code. + +The main Augeas calls are bound through the C APIs. We +don't document Augeas itself here because there is excellent +documentation on the L website. + +If you don't want to use Augeas (you fool!) then try calling +C to get the file as a list of lines which +you can iterate over. + +=head2 SELINUX + +We support SELinux guests. To ensure that labeling happens correctly +in SELinux guests, you need to enable SELinux and load the guest's +policy: + +=over 4 + +=item 1. + +Before launching, do: + + guestfs_set_selinux (g, 1); + +=item 2. + +After mounting the guest's filesystem(s), load the policy. This +is best done by running the L command in the +guest itself: + + guestfs_sh (g, "/usr/sbin/load_policy"); + +(Older versions of C require you to specify the +name of the policy file). + +=item 3. + +Optionally, set the security context for the API. The correct +security context to use can only be known by inspecting the +guest. As an example: + + guestfs_setcon (g, "unconfined_u:unconfined_r:unconfined_t:s0"); + +=back + +This will work for running commands and editing existing files. + +When new files are created, you may need to label them explicitly, +for example by running the external command +C. + +=head2 SPECIAL CONSIDERATIONS FOR WINDOWS GUESTS + +Libguestfs can mount NTFS partitions. It does this using the +L driver. + +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 +C. When the filesystem is mounted in libguestfs, +that directory might be referred to as C. + +Drive letter mappings are outside the scope of libguestfs. You have +to use libguestfs to read the appropriate Windows Registry and +configuration files, to determine yourself how drives are mapped (see +also L). + +Replacing backslash characters with forward slash characters is also +outside the scope of libguestfs, but something that you can easily do. + +Where we can help is in resolving the case insensitivity of paths. +For this, call C. + +Libguestfs also provides some help for decoding Windows Registry +"hive" files, through the library C which is part of +libguestfs. You have to locate and download the hive file(s) +yourself, and then pass them to C functions. See also the +programs L, L and L for more +help on this issue. + +=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 is +C<$handle-Emount($path)> in Perl, C in Python, +and C in OCaml. In other words, a +straightforward, predictable isomorphism between each language. +Error messages are automatically transformed +into exceptions if the language supports it. +We don't try to "object orientify" parts of the API in OO languages, +although contributors are welcome to write higher level APIs above +what we provide in their favourite languages if they wish. +=over 4 + +=item B + +You can use the I header file from C++ programs. The C++ +API is identical to the C API. C++ classes and exceptions are +not implemented. + +=item B + +This is the only language binding that is incomplete. Only calls +which return simple integers have been bound in Haskell, and we are +looking for help to complete this binding. + +=item B + +Full documentation is contained in the Javadoc which is distributed +with libguestfs. + +=item B -=head1 CONFIGURATION MANAGEMENT +For documentation see the file C. +=item B +For documentation see L. +=item B +For documentation do: + $ python + >>> import guestfs + >>> help (guestfs) + +=item B + +Use the Guestfs module. There is no Ruby-specific documentation, but +you can find examples written in Ruby in the libguestfs source. + +=item B + +For documentation see L. + +=back + +=head1 CONNECTION MANAGEMENT -=head1 HIGH-LEVEL API +=head2 guestfs_h * +C is the opaque type representing a connection handle. +Create a handle by calling C. Call C +to free the handle and release all resources used. +For information on using multiple handles and threads, see the section +L below. +=head2 guestfs_create + guestfs_h *guestfs_create (void); +Create a connection handle. +You have to call C 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 C. + +You may also want to configure error handling for the handle. See +L section below. + +=head2 guestfs_close + + void guestfs_close (guestfs_h *handle); + +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 C and/or by setting up an error +handler with C. + +The default error handler prints the information string to C. + +Out of memory errors are handled differently. The default action is +to call L. If this is undesirable, then you can set a +handler using C. + +=head2 guestfs_last_error + + const char *guestfs_last_error (guestfs_h *handle); + +This returns the last error message that happened on C. If +there has not been an error since the handle was created, then this +returns C. + +The lifetime of the returned string is until the next error occurs, or +C is called. + +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_set_error_handler + + typedef void (*guestfs_error_handler_cb) (guestfs_h *handle, + void *data, + const char *msg); + void guestfs_set_error_handler (guestfs_h *handle, + guestfs_error_handler_cb cb, + void *data); + +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. + +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. +The default handler prints messages on C. +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 *handle, + void **data_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 *handle, + guestfs_abort_cb); + +The callback C will be called if there is an out of memory +situation. I. + +The default is to call L. + +You cannot set C to C. 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 *handle); + +This returns the current out of memory handler. + +=head1 PATH + +Libguestfs needs a kernel and initrd.img, which it finds by looking +along an internal path. + +By default it looks for these in the directory C<$libdir/guestfs> +(eg. C or C). + +Use C or set the environment variable +C to change the directories that libguestfs will +search in. The value is a colon-separated list of paths. The current +directory is I searched unless the path contains an empty element +or C<.>. For example C would +search the current directory and then C. + +=head1 HIGH-LEVEL API ACTIONS + +=head2 ABI GUARANTEE + +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 libguestfs. + +@ACTIONS@ + +=head1 STRUCTURES + +@STRUCTS@ =head1 STATE MACHINE AND LOW-LEVEL EVENT API @@ -79,6 +631,23 @@ and most of this discussion won't make sense unless you understand that the complexity is dealing with the (asynchronous) actions of the child process. + child process + ___________________ _________________________ + / \ / \ + | main program | | qemu +-----------------+| + | | | | Linux kernel || + +-------------------+ | +-----------------+| + | libguestfs <-------------->| guestfsd || + | | | +-----------------+| + \___________________/ \_________________________/ + +The diagram above shows libguestfs communicating with the guestfsd +daemon running inside the qemu child process. There are several +points of failure here: qemu can fail to start, the virtual machine +inside qemu can fail to boot, guestfsd can fail to start or not +establish communication, any component can start successfully but fail +asynchronously later, and so on. + =head2 STATE MACHINE libguestfs uses a state machine to model the child process: @@ -98,7 +667,7 @@ libguestfs uses a state machine to model the child process: / | | LAUNCHING | / | \___________/ / | / - / | guestfs_wait_ready + / | guestfs_launch / | / ______ / __|____V / \ ------> / \ @@ -118,12 +687,10 @@ Configuration commands for qemu such as C can only be issued when in the CONFIG state. The high-level API offers two calls that go from CONFIG through -LAUNCHING to READY. C is a non-blocking call that -starts up the child process, immediately moving from CONFIG to -LAUNCHING. C blocks until the child process is -READY to accept commands (or until some failure or timeout). The -low-level event API described below provides a non-blocking way to -replace C. +LAUNCHING to READY. C blocks until the child process +is READY to accept commands (or until some failure or timeout). +C internally moves the state from CONFIG to LAUNCHING +while it is running. High-level API actions such as C can only be issued when in the READY state. These high-level API calls block waiting for @@ -141,8 +708,7 @@ register to receive these messages. =head2 SETTING CALLBACKS TO HANDLE EVENTS The child process generates events in some situations. Current events -include: receiving a reply message after some action, receiving a log -message, the child process exits, &c. +include: receiving a log message, the child process exits. Use the C functions to set a callback for different types of events. @@ -152,52 +718,11 @@ Calling C again overwrites the previous callback of that type. Cancel all callbacks of this type by calling this function with C set to C. -=head2 NON-BLOCKING ACTIONS - -C is the most interesting callback to -play with, since it allows you to perform actions without blocking. - -For example: - - do_it () - { - start_call (); - guestfs_main_loop_run (); /* --> blocks, then calls my_cb */ - } - - start_call () - { - guestfs_set_reply_callback (handle, my_cb, data); - guestfs_nb_[action] (handle, [other parameters ...]); - /* returns immediately */ - } - - my_cb (guestfs_h handle, void *data) - { - retval = guestfs_nb_[action]_r (handle); - /* ... */ - } - -There are C and C functions -corresponding to (very nearly) every C action in the -high-level API. - -=head2 guestfs_set_reply_callback - - void guestfs_set_reply_callback (guestfs_handle h, - guestfs_reply_cb cb, - void *opaque); - -The callback function C will be called whenever a reply is -received from the child process. (This corresponds to a transition -from the BUSY state to the READY state). - -Note (I) that high-level API calls overwrite this -callback. - =head2 guestfs_set_log_message_callback - void guestfs_set_log_message_callback (guestfs_handle h, + typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque, + char *buf, int len); + void guestfs_set_log_message_callback (guestfs_h *handle, guestfs_log_message_cb cb, void *opaque); @@ -211,7 +736,8 @@ discarded. =head2 guestfs_set_subprocess_quit_callback - void guestfs_set_subprocess_quit_callback (guestfs_handle h, + typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque); + void guestfs_set_subprocess_quit_callback (guestfs_h *handle, guestfs_subprocess_quit_cb cb, void *opaque); @@ -220,116 +746,393 @@ quits, either asynchronously or if killed by C. (This corresponds to a transition from any state to the CONFIG state). -=head2 guestfs_set_ready_callback +=head2 guestfs_set_launch_done_callback - void guestfs_set_ready_callback (guestfs_handle h, - guestfs_ready_cb cb, - void *opaque); + typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque); + void guestfs_set_launch_done_callback (guestfs_h *handle, + guestfs_ready_cb cb, + void *opaque); The callback function C will be called when the child process -becomes ready. (This corresponds to a transition from I -LAUNCHING I BUSY to the READY state). +becomes ready first time after it has been launched. (This +corresponds to a transition from LAUNCHING to the READY state). + +=head1 BLOCK DEVICE NAMING + +In the kernel there is now quite a profusion of schemata for naming +block devices (in this context, by I I mean a physical +or virtual hard drive). The original Linux IDE driver used names +starting with C. SCSI devices have historically used a +different naming scheme, C. When the Linux kernel I +driver became a popular replacement for the old IDE driver +(particularly for SATA devices) those devices also used the +C scheme. Additionally we now have virtual machines with +paravirtualized drivers. This has created several different naming +systems, such as C for virtio disks and C for Xen +PV disks. + +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. + +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. + +Therefore libguestfs defines C as the I. Internally C names are translated, if necessary, +to other names as required. For example, under RHEL 5 which uses the +C scheme, any device parameter C is translated to +C transparently. + +Note that this I applies to parameters. The +C, C and similar calls +return the true names of the devices and partitions as known to the +appliance. + +=head2 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION + +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 C to add a mixture of virtio and IDE +devices to the qemu-based appliance, so have a mixture of C +and C devices. + +The algorithm is applied only to I which are known to be +either device or partition names. Return values from functions such +as C are never changed. + +=over 4 + +=item * + +Is the string a parameter which is a device or partition name? + +=item * + +Does the string begin with C? + +=item * -You can use this instead of C to implement a -non-blocking wait for the child process to finish booting up. +Does the named device exist? If so, we use that device. +However if I then we continue with this algorithm. -=head2 EVENT MAIN LOOP +=item * + +Replace initial C string with C. + +For example, change C to C. + +If that named device exists, use it. If not, continue. + +=item * + +Replace initial C string with C. + +If that named device exists, use it. If not, return an error. + +=back -To use the low-level event API, you have to provide an event "main -loop". You can write your own, but if you don't want to write one, -two are provided for you: +=head2 PORTABILITY CONCERNS + +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. + +Where possible for maximum future portability programs using +libguestfs should use these future-proof techniques: =over 4 -=item libguestfs-poll +=item * -A simple main loop that is implemented using L. +Use C or C to list +actual device names, and then use those names directly. -This is the default main loop unless you call C -or C. +Since those device names exist by definition, they will never be +translated. -=item libguestfs-glib +=item * -An implementation which can be used with GLib and GTK+ programs. You -can use this to write graphical (GTK+) programs which use libguestfs -without hanging during long or slow operations. +Use higher level ways to identify filesystems, such as LVM names, +UUIDs and filesystem labels. =back -=head2 guestfs_set_main_loop +=head1 INTERNALS - void guestfs_set_main_loop (guestfs_main_loop *); +=head2 COMMUNICATION PROTOCOL -This call sets the current main loop to the list of callbacks -contained in the C structure. +Don't rely on using this protocol directly. This section documents +how it currently works, but it may change at any time. -Only one main loop implementation can be used by libguestfs, so -calling this replaces the previous one. (So this is something that -has to be done by the main program, but only the main program "knows" -that it is a GTK+ program or whatever). +The protocol used to talk between the library and the daemon running +inside the qemu virtual machine is a simple RPC mechanism built on top +of XDR (RFC 1014, RFC 1832, RFC 4506). -You should call this early in the main program, certainly before -calling C. +The detailed format of structures is in C +(note: this file is automatically generated). -=head2 guestfs_glib_set_main_loop +There are two broad cases, ordinary functions that don't have any +C and C parameters, which are handled with very +simple request/reply messages. Then there are functions that have any +C or C parameters, which use the same request and +reply messages, but they may also be followed by files sent using a +chunked encoding. - void guestfs_glib_set_main_loop (GMainLoop *); +=head3 ORDINARY FUNCTIONS (NO FILEIN/FILEOUT PARAMS) -This helper calls C with the correct callbacks -for integrating with the GLib main loop. +For ordinary functions, the request message is: -The libguestfs-glib main loop is contained in a separate library, so -that libguestfs doesn't depend on the whole of GLib: + total length (header + arguments, + but not including the length word itself) + struct guestfs_message_header (encoded as XDR) + struct guestfs__args (encoded as XDR) - #include - #include +The total length field allows the daemon to allocate a fixed size +buffer into which it slurps the rest of the message. As a result, the +total length is limited to C bytes (currently +4MB), which means the effective size of any request is limited to +somewhere under this size. - main () - { - GMainLoop *loop = - g_main_loop_new (g_main_context_default (), 1); - ... - guestfs_glib_set_main_loop (loop); +Note also that many functions don't take any arguments, in which case +the C_args> is completely omitted. + +The header contains the procedure number (C) which is +how the receiver knows what type of args structure to expect, or none +at all. + +The reply message for ordinary functions is: + + total length (header + ret, + but not including the length word itself) + struct guestfs_message_header (encoded as XDR) + struct guestfs__ret (encoded as XDR) + +As above the C_ret> structure may be completely omitted +for functions that return no formal return values. + +As above the total length of the reply is limited to +C. + +In the case of an error, a flag is set in the header, and the reply +message is slightly changed: + + total length (header + error, + but not including the length word itself) + struct guestfs_message_header (encoded as XDR) + struct guestfs_message_error (encoded as XDR) + +The C structure contains the error message as a +string. + +=head3 FUNCTIONS THAT HAVE FILEIN PARAMETERS + +A C parameter indicates that we transfer a file I the +guest. The normal request message is sent (see above). However this +is followed by a sequence of file chunks. + + total length (header + arguments, + but not including the length word itself, + and not including the chunks) + struct guestfs_message_header (encoded as XDR) + struct guestfs__args (encoded as XDR) + sequence of chunks for FileIn param #0 + sequence of chunks for FileIn param #1 etc. + +The "sequence of chunks" is: + + length of chunk (not including length word itself) + struct guestfs_chunk (encoded as XDR) + length of chunk + struct guestfs_chunk (encoded as XDR) ... - g_main_loop_run (loop); - } + length of chunk + struct guestfs_chunk (with data.data_len == 0) + +The final chunk has the C field set to zero. Additionally a +flag is set in the final chunk to indicate either successful +completion or early cancellation. + +At time of writing there are no functions that have more than one +FileIn parameter. However this is (theoretically) supported, by +sending the sequence of chunks for each FileIn parameter one after +another (from left to right). + +Both the library (sender) I the daemon (receiver) may cancel the +transfer. The library does this by sending a chunk with a special +flag set to indicate cancellation. When the daemon sees this, it +cancels the whole RPC, does I send any reply, and goes back to +reading the next request. + +The daemon may also cancel. It does this by writing a special word +C to the socket. The library listens for this +during the transfer, and if it gets it, it will cancel the transfer +(it sends a cancel chunk). The special word is chosen so that even if +cancellation happens right at the end of the transfer (after the +library has finished writing and has started listening for the reply), +the "spurious" cancel flag will not be confused with the reply +message. + +This protocol allows the transfer of arbitrary sized files (no 32 bit +limit), and also files where the size is not known in advance +(eg. from pipes or sockets). However the chunks are rather small +(C), so that neither the library nor the +daemon need to keep much in memory. + +=head3 FUNCTIONS THAT HAVE FILEOUT PARAMETERS + +The protocol for FileOut parameters is exactly the same as for FileIn +parameters, but with the roles of daemon and library reversed. + + total length (header + ret, + but not including the length word itself, + and not including the chunks) + struct guestfs_message_header (encoded as XDR) + struct guestfs__ret (encoded as XDR) + sequence of chunks for FileOut param #0 + sequence of chunks for FileOut param #1 etc. + +=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 C waits for. + +=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. + +=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> 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 (or wherever), C, +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 ENVIRONMENT VARIABLES + +=over 4 + +=item LIBGUESTFS_APPEND -To use this main loop you must link with C<-lguestfs-glib>. (See also -the GLib and GTK+ documentation). +Pass additional options to the guest kernel. -=head2 guestfs_main_loop_run +=item LIBGUESTFS_DEBUG - void guestfs_main_loop_run (void); +Set C to enable verbose messages. This +has the same effect as calling C. -This calls the main loop. +=item LIBGUESTFS_MEMSIZE -For some types of main loop you may want or prefer to call another -function, eg. C, or the main loop may already be -invoked by another part of your program. In those cases, ignore this -call. +Set the memory allocated to the qemu process, in megabytes. For +example: -=head2 guestfs_main_loop_quit + LIBGUESTFS_MEMSIZE=700 - void guestfs_main_loop_quit (void); +=item LIBGUESTFS_PATH -This instructs the main loop to quit. In other words, -C will return. +Set the path that libguestfs uses to search for kernel and initrd.img. +See the discussion of paths in section PATH above. -For some types of main loop you may want or prefer to call another -function, eg. C. In those cases, ignore this call. +=item LIBGUESTFS_QEMU -=head2 WRITING A CUSTOM MAIN LOOP +Set the default qemu binary that libguestfs uses. If not set, then +the qemu which was found at compile time by the configure script is +used. -This isn't documented. Please see the libguestfs-poll and libguestfs-glib -implementations. +See also L above. + +=item LIBGUESTFS_TRACE + +Set C to enable command traces. This +has the same effect as calling C. + +=item TMPDIR + +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 +configure another directory to use in case C is not large +enough. + +=back =head1 SEE ALSO -L +L, +L, +L, +L. +Tools with a similar purpose: +L, +L, +L, +L, +L. +=head1 BUGS +To get a list of bugs against libguestfs use this link: +L + +To report a new bug against libguestfs use this link: + +L + +When reporting a bug, please check: + +=over 4 + +=item * + +That the bug hasn't been reported already. + +=item * + +That you are testing a recent version. + +=item * + +Describe the bug accurately, and give a way to reproduce it. + +=item * + +Run libguestfs-test-tool and paste the B +output into the bug report. + +=back =head1 AUTHORS @@ -338,7 +1141,7 @@ Richard W.M. Jones (C) =head1 COPYRIGHT Copyright (C) 2009 Red Hat Inc. -L +L This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public