X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs.pod;h=fdac80a66b76b3030a19c4dd2451161dc74bccd4;hp=9e0d4d3188c1d64ab2d440b459e21eee98d9428f;hb=b1e1ca2f74a921b3f784537d59c617df29ea1d60;hpb=34d2df41626f1ee4172a6d40b06d72d6ed9d6348 diff --git a/guestfs.pod b/guestfs.pod index 9e0d4d3..fdac80a 100644 --- a/guestfs.pod +++ b/guestfs.pod @@ -11,7 +11,6 @@ guestfs - Library for accessing and modifying virtual machine images 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 (handle, "/hello"); guestfs_sync (handle); @@ -56,7 +55,6 @@ functions in the following order: */ guestfs_launch (handle); - guestfs_wait_ready (handle); /* now you can examine what partitions, LVs etc are available * you have to mount / at least @@ -73,12 +71,12 @@ functions in the following order: guestfs_close (handle); -C and all of the actions including C +C and all of the actions including C are blocking calls. You can use the low-level event API to do non-blocking operations instead. All functions that return integers, return C<-1> on error. See -section ERROR HANDLING below for how to handle errors. +section L below for how to handle errors. =head2 guestfs_h * @@ -87,7 +85,7 @@ 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 -MULTIPLE HANDLES AND MULTIPLE THREADS below. +L below. =head2 guestfs_create @@ -100,11 +98,10 @@ 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 and -C. +After configuring the handle, you have to call C. You may also want to configure error handling for the handle. See -ERROR HANDLING section below. +L section below. =head2 guestfs_close @@ -220,29 +217,27 @@ L. =head2 PARTITIONING -To create MBR-style (ie. normal PC) partitions use one of the -C variants. These calls use the external -L command. +In the common case where you want to create a single partition +covering the whole disk, you should use the C +call: -The simplest call is: - - char *lines[] = { ",", NULL }; - guestfs_sfdiskM (g, "/dev/sda", lines); - -This will create a single partition on C called -C covering the whole disk. + const char *parttype = "mbr"; + if (disk_is_larger_than_2TB) + parttype = "gpt"; + guestfs_part_disk (g, "/dev/sda", parttype); In general MBR partitions are both unnecessarily complicated and depend on archaic details, namely the Cylinder-Head-Sector (CHS) -geometry of the disk. C allows you to specify sizes -in megabytes instead of cylinders, which is a small win. +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. +probably don't want to know about. -In future we aim to provide access to libparted. +My advice: make a single partition to cover the whole disk, then use +LVM on top. =head2 UPLOADING @@ -316,6 +311,11 @@ Only supports Linux guests (not Windows, BSD, etc). 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 @@ -337,6 +337,47 @@ directory, plus additional information about each one. C can be used to recursively list files. +=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. + =head1 HIGH-LEVEL API ACTIONS =head2 ABI GUARANTEE @@ -397,7 +438,7 @@ libguestfs uses a state machine to model the child process: / | | LAUNCHING | / | \___________/ / | / - / | guestfs_wait_ready + / | guestfs_launch / | / ______ / __|____V / \ ------> / \ @@ -417,12 +458,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 @@ -440,8 +479,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. @@ -451,39 +489,6 @@ 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 - -XXX This section was documented in previous versions but never -implemented in a way which matched the documentation. For now I have -removed the documentation, pending a working implementation. See also -C in the source. - - -=head2 guestfs_set_send_callback - - typedef void (*guestfs_send_cb) (guestfs_h *g, void *opaque); - void guestfs_set_send_callback (guestfs_h *handle, - guestfs_send_cb cb, - void *opaque); - -The callback function C will be called whenever a message -which is queued for sending, has been sent. - -=head2 guestfs_set_reply_callback - - typedef void (*guestfs_reply_cb) (guestfs_h *g, void *opaque, XDR *xdr); - void guestfs_set_reply_callback (guestfs_h *handle, - 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 that the C that you get in the callback is in C -mode, and you need to consume it before you return from the callback -function (since it gets destroyed after). - =head2 guestfs_set_log_message_callback typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque, @@ -523,116 +528,6 @@ The callback function C will be called when the child process becomes ready first time after it has been launched. (This corresponds to a transition from LAUNCHING to the READY state). -You can use this instead of C to implement a -non-blocking wait for the child process to finish booting up. - -=head2 EVENT MAIN LOOP - -To use the low-level event API and/or to use handles from multiple -threads, you have to provide an event "main loop". You can write your -own, but if you don't want to write one, two types are provided for -you: - -=over 4 - -=item libguestfs-select - -A simple main loop that is implemented using L. - -This is the default main loop for new guestfs handles, unless you -call C after a handle is created. - -=item libguestfs-glib - -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. - -=back - -=head2 MULTIPLE HANDLES AND MULTIPLE THREADS - -The support for multiple handles and multiple threads is modelled -after glib (although doesn't require glib, if you use the select-based -main loop). - -L - -You will need to create one main loop for each thread that wants to -use libguestfs. Each guestfs handle should be confined to one thread. -If you try to pass guestfs handles between threads, you will get -undefined results. - -If you only want to use guestfs handles from one thread in your -program, but your program has other threads doing other things, then -you don't need to do anything special. - -=head2 SINGLE THREAD CASE - -In the single thread case, there is a single select-based main loop -created for you. All guestfs handles will use this main loop to -execute high level API actions. - -=head2 MULTIPLE THREADS CASE - -In the multiple threads case, you will need to create a main loop for -each thread that wants to use libguestfs. - -To create main loops for other threads, use -C or C. - -Then you will need to attach each handle to the thread-specific main -loop by calling: - - handle = guestfs_create (); - guestfs_set_main_loop (handle, main_loop_of_current_thread); - -=head2 guestfs_set_main_loop - - void guestfs_set_main_loop (guestfs_h *handle, - guestfs_main_loop *main_loop); - -Sets the main loop used by high level API actions for this handle. By -default, the select-based main loop is used (see -C). - -You only need to use this in multi-threaded programs, where multiple -threads want to use libguestfs. Create a main loop for each thread, -then call this function. - -You cannot pass guestfs handles between threads. - -=head2 guestfs_get_main_loop - - guestfs_main_loop *guestfs_get_main_loop (guestfs_h *handle); - -Return the main loop used by C. - -=head2 guestfs_get_default_main_loop - - guestfs_main_loop *guestfs_get_default_main_loop (void); - -Return the default select-based main loop. - -=head2 guestfs_create_main_loop - - guestfs_main_loop *guestfs_create_main_loop (void); - -This creates a select-based main loop. You should create one main -loop for each additional thread that needs to use libguestfs. - -=head2 guestfs_free_main_loop - - void guestfs_free_main_loop (guestfs_main_loop *); - -Free the select-based main loop which was previously allocated with -C. - -=head2 WRITING A CUSTOM MAIN LOOP - -This isn't documented. Please see the libguestfs-select and -libguestfs-glib implementations. - =head1 BLOCK DEVICE NAMING In the kernel there is now quite a profusion of schemata for naming @@ -875,7 +770,7 @@ parameters, but with the roles of daemon and library reversed. 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. +and daemon is alive. This is what C waits for. =head1 QEMU WRAPPERS @@ -917,10 +812,6 @@ Pass additional options to the guest kernel. Set C to enable verbose messages. This has the same effect as calling C. -=item LIBGUESTFS_KERNEL - -Override the ordinary selection of appliance kernel. - =item LIBGUESTFS_MEMSIZE Set the memory allocated to the qemu process, in megabytes. For @@ -939,7 +830,12 @@ 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. -See also L above. +See also L above. + +=item LIBGUESTFS_TRACE + +Set C to enable command traces. This +has the same effect as calling C. =item TMPDIR @@ -960,6 +856,13 @@ 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: @@ -986,6 +889,11 @@ That you are testing a recent version. 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