X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=a1831c0d0d23e81b5396b2a50cef0d8c8cb4353c;hp=cfd58c979767814f3e2264624fcabf5e2a8edd14;hb=1bf3941b9ccabef122cc6479004d18ddcb935eef;hpb=477eebc83dcd33d00d34398692692dae6af04f22 diff --git a/src/guestfs.pod b/src/guestfs.pod index cfd58c9..a1831c0 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -99,7 +99,7 @@ this: * disk image. */ guestfs_touch (g, "/hello"); - + /* This is only needed for libguestfs < 1.5.24. Since then * it is done automatically when you close the handle. See * discussion of autosync in this page. @@ -354,7 +354,7 @@ doing: guestfs_download (g, filename, "/dev/stdout"); -and you can write tar output to a pipe C by doing: +and you can write tar output to a file descriptor C by doing: char devfd[64]; snprintf (devfd, sizeof devfd, "/dev/fd/%d", fd); @@ -641,16 +641,15 @@ 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 and L). +Drive letter mappings can be found using inspection +(see L and L) -Replacing backslash characters with forward slash characters is also -outside the scope of libguestfs, but something that you can easily do. +Dealing with separator characters (backslash vs forward slash) is +outside the scope of libguestfs, but usually a simple character +replacement will work. -Where we can help is in resolving the case insensitivity of paths. -For this, call L. +To resolve the case insensitivity of paths, call +L. =head3 ACCESSING THE WINDOWS REGISTRY @@ -729,7 +728,7 @@ and we are looking for help to complete this binding. =item B Full documentation is contained in the Javadoc which is distributed -with libguestfs. +with libguestfs. For examples, see L. =item B @@ -776,6 +775,9 @@ them. =item Autosync / forgetting to sync. +I Autosync is enabled by default for all API users starting +from libguestfs 1.5.24. This section only applies to older versions. + When modifying a filesystem from C or another language, you B unmount all filesystems and call L explicitly before you close the libguestfs handle. You can also call: @@ -794,9 +796,6 @@ 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 @@ -880,29 +879,6 @@ representation. Also consider how it might work in guestfish. =back -=head2 PROTOCOL LIMITS - -Internally libguestfs uses a message-based protocol to pass API calls -and their responses to and from a small "appliance" (see L -for plenty more detail about this). The maximum message size used by -the protocol is slightly less than 4 MB. For some API calls you may -need to be aware of this limit. The API calls which may be affected -are individually documented, with a link back to this section of the -documentation. - -A simple call such as L returns its result (the file -data) in a simple string. Because this string is at some point -internally encoded as a message, the maximum size that it can return -is slightly under 4 MB. If the requested file is larger than this -then you will get an error. - -In order to transfer large files into and out of the guest filesystem, -you need to use particular calls that support this. The sections -L and L document how to do this. - -You might also consider mounting the disk image using our FUSE -filesystem support (L). - =head2 KEYS AND PASSPHRASES Certain libguestfs calls take a parameter that contains sensitive key @@ -932,8 +908,8 @@ architecture for multithreaded programs using libvirt and libguestfs. =head2 PATH -Libguestfs needs a kernel and initrd.img, which it finds by looking -along an internal path. +Libguestfs needs a supermin appliance, 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). @@ -972,6 +948,63 @@ For example: Note that libguestfs also calls qemu with the -help and -version options in order to determine features. +=head2 ATTACHING TO RUNNING DAEMONS + +I This is B and has a tendency to eat +babies. Use with caution. + +I This section explains how to attach to a running daemon +from a low level perspective. For most users, simply using virt tools +such as L with the I<--live> option will "just work". + +=head3 Using guestfs_set_attach_method + +By calling L you can change how the +library connects to the C daemon in L +(read L for some background). + +The normal attach method is C, where a small appliance is +created containing the daemon, and then the library connects to this. + +Setting attach method to C> (where I is the path of +a Unix domain socket) causes L to connect to an +existing daemon over the Unix domain socket. + +The normal use for this is to connect to a running virtual machine +that contains a C daemon, and send commands so you can read +and write files inside the live virtual machine. + +=head3 Using guestfs_add_domain with live flag + +L provides some help for getting the +correct attach method. If you pass the C option to this +function, then (if the virtual machine is running) it will +examine the libvirt XML looking for a virtio-serial channel +to connect to: + + + ... + + ... + + + + + ... + + + +L extracts C and sets the attach +method to C. + +Some of the libguestfs tools (including guestfish) support a I<--live> +option which is passed through to L thus allowing +you to attach to and modify live virtual machines. + +The virtual machine needs to have been set up beforehand so that it +has the virtio-serial channel and so that guestfsd is running inside +it. + =head2 ABI GUARANTEE We guarantee the libguestfs ABI (binary interface), for public, @@ -1252,7 +1285,7 @@ Create a handle by calling L. Call L to free the handle and release all resources used. For information on using multiple handles and threads, see the section -L below. +L above. =head2 guestfs_create @@ -1260,15 +1293,16 @@ L below. Create a connection handle. -You have to call L (or one of the equivalent -calls) on the handle at least once. +On success this returns a non-NULL pointer to a handle. On error it +returns NULL. -This function returns a non-NULL pointer to a handle on success or -NULL on error. +You have to "configure" the handle after creating it. This includes +calling L (or one of the equivalent calls) on +the handle at least once. After configuring the handle, you have to call L. -You may also want to configure error handling for the handle. See +You may also want to configure error handling for the handle. See the L section below. =head2 guestfs_close @@ -1277,6 +1311,12 @@ L section below. This closes the connection handle and frees up all resources used. +If autosync was set on the handle and the handle was launched, then +this implicitly calls various functions to unmount filesystems and +sync the disk. See L for more details. + +If a close callback was set on the handle, then it is called. + =head1 ERROR HANDLING API functions can return errors. For example, almost all functions @@ -1304,8 +1344,6 @@ been printed to C before the program exits. For other programs the caller will almost certainly want to install an alternate error handler or do error handling in-line like this: - g = guestfs_create (); - /* This disables the default behaviour of printing errors on stderr. */ guestfs_set_error_handler (g, NULL, NULL); @@ -1314,9 +1352,12 @@ alternate error handler or do error handling in-line like this: /* Examine the error message and print it etc. */ char *msg = guestfs_last_error (g); int errnum = guestfs_last_errno (g); - fprintf (stderr, "%s\n", msg); + fprintf (stderr, "%s", msg); + if (errnum != 0) + fprintf (stderr, ": %s", strerror (errnum)); + fprintf (stderr, "\n"); /* ... */ - } + } Out of memory errors are handled differently. The default action is to call L. If this is undesirable, then you can set a @@ -1626,82 +1667,72 @@ For guestfish, see L. =head2 SETTING CALLBACKS TO HANDLE EVENTS -The child process generates events in some situations. Current events -include: receiving a log message, the child process exits. +B This section documents the generic event mechanism introduced +in libguestfs 1.10, which you should use in new code if possible. The +old functions C, +C, +C, C and +C are no longer documented in this +manual page. Because of the ABI guarantee, the old functions continue +to work. + +Handles generate events when certain things happen, such as log +messages being generated, progress messages during long-running +operations, or the handle being closed. The API calls described below +let you register a callback to be called when events happen. You can +register multiple callbacks (for the same, different or overlapping +sets of events), and individually remove callbacks. If callbacks are +not removed, then they remain in force until the handle is closed. + +In the current implementation, events are only generated +synchronously: that means that events (and hence callbacks) can only +happen while you are in the middle of making another libguestfs call. +The callback is called in the same thread. + +Events may contain a payload, usually nothing (void), an array of 64 +bit unsigned integers, or a message buffer. Payloads are discussed +later on. + +=head3 CLASSES OF EVENTS -Use the C functions to set a callback for -different types of events. - -Only I can be registered for each handle. -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 guestfs_set_log_message_callback - - typedef void (*guestfs_log_message_cb) (guestfs_h *g, void *opaque, - char *buf, int len); - void guestfs_set_log_message_callback (guestfs_h *g, - guestfs_log_message_cb cb, - void *opaque); - -The callback function C will be called whenever qemu or the guest -writes anything to the console. - -Use this function to capture kernel messages and similar. - -Normally there is no log message handler, and log messages are just -discarded. - -=head2 guestfs_set_subprocess_quit_callback +=over 4 - typedef void (*guestfs_subprocess_quit_cb) (guestfs_h *g, void *opaque); - void guestfs_set_subprocess_quit_callback (guestfs_h *g, - guestfs_subprocess_quit_cb cb, - void *opaque); +=item GUESTFS_EVENT_CLOSE +(payload type: void) -The callback function C will be called when the child process -quits, either asynchronously or if killed by -L. (This corresponds to a transition from -any state to the CONFIG state). +The callback function will be called while the handle is being closed +(synchronously from L). -=head2 guestfs_set_launch_done_callback +Note that libguestfs installs an L handler to try to clean +up handles that are open when the program exits. This means that this +callback might be called indirectly from L, which can cause +unexpected problems in higher-level 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). - typedef void (*guestfs_launch_done_cb) (guestfs_h *g, void *opaque); - void guestfs_set_launch_done_callback (guestfs_h *g, - guestfs_launch_done_cb cb, - void *opaque); +If no callback is registered: the handle is closed without any +callback being invoked. -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). +=item GUESTFS_EVENT_SUBPROCESS_QUIT +(payload type: void) -=head2 guestfs_set_close_callback +The callback function will be called when the child process quits, +either asynchronously or if killed by L. +(This corresponds to a transition from any state to the CONFIG state). - typedef void (*guestfs_close_cb) (guestfs_h *g, void *opaque); - void guestfs_set_close_callback (guestfs_h *g, - guestfs_close_cb cb, - void *opaque); +If no callback is registered: the event is ignored. -The callback function C will be called while the handle -is being closed (synchronously from L). +=item GUESTFS_EVENT_LAUNCH_DONE +(payload type: void) -Note that libguestfs installs an L handler to try to -clean up handles that are open when the program exits. This -means that this callback might be called indirectly from -L, which can cause unexpected problems in higher-level -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). +The callback function 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). -=head2 guestfs_set_progress_callback +If no callback is registered: the event is ignored. - 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); +=item GUESTFS_EVENT_PROGRESS +(payload type: array of 4 x uint64_t) Some long-running operations can generate progress messages. If this callback is registered, then it will be called each time a @@ -1709,7 +1740,9 @@ 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 callback receives in the payload four unsigned 64 bit numbers +which are (in order): C, C, C, 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 @@ -1731,24 +1764,237 @@ indicator which shows the ratio of C:C. =item * If any progress notification is sent during a call, then a final -progress notification is always sent when C = C. +progress notification is always sent when C = C +(I the call fails with an error). 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. +=item * + +For some calls we are unable to estimate the progress of the call, but +we can still generate progress messages to indicate activity. This is +known as "pulse mode", and is directly supported by certain progress +bar implementations (eg. GtkProgressBar). + +For these calls, zero or more progress messages are generated with +C and C, followed by a final message with +C. + +As noted above, if the call fails with an error then the final message +may not be generated. + =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. +The callback also receives the procedure number (C) and +serial number (C) 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. + +If no callback is registered: progress messages are discarded. + +=item GUESTFS_EVENT_APPLIANCE +(payload type: message buffer) + +The callback function is called whenever a log message is generated by +qemu, the appliance kernel, guestfsd (daemon), or utility programs. + +If the verbose flag (L) is set before launch +(L) then additional debug messages are generated. + +If no callback is registered: the messages are discarded unless the +verbose flag is set in which case they are sent to stderr. You can +override the printing of verbose messages to stderr by setting up a +callback. + +=item GUESTFS_EVENT_LIBRARY +(payload type: message buffer) + +The callback function is called whenever a log message is generated by +the library part of libguestfs. + +If the verbose flag (L) is set then additional +debug messages are generated. + +If no callback is registered: the messages are discarded unless the +verbose flag is set in which case they are sent to stderr. You can +override the printing of verbose messages to stderr by setting up a +callback. + +=item GUESTFS_EVENT_TRACE +(payload type: message buffer) + +The callback function is called whenever a trace message is generated. +This only applies if the trace flag (L) is set. + +If no callback is registered: the messages are sent to stderr. You +can override the printing of trace messages to stderr by setting up a +callback. + +=back + +=head3 guestfs_set_event_callback + + int guestfs_set_event_callback (guestfs_h *g, + guestfs_event_callback cb, + uint64_t event_bitmask, + int flags, + void *opaque); + +This function registers a callback (C) for all event classes +in the C. + +For example, to register for all log message events, you could call +this function with the bitmask +C. To register a +single callback for all possible classes of events, use +C. + +C should always be passed as 0. + +C is an opaque pointer which is passed to the callback. You +can use it for any purpose. + +The return value is the event handle (an integer) which you can use to +delete the callback (see below). + +If there is an error, this function returns C<-1>, and sets the error +in the handle in the usual way (see L etc.) + +Callbacks remain in effect until they are deleted, or until the handle +is closed. + +In the case where multiple callbacks are registered for a particular +event class, all of the callbacks are called. The order in which +multiple callbacks are called is not defined. + +=head3 guestfs_delete_event_callback + + void guestfs_delete_event_callback (guestfs_h *g, int event_handle); + +Delete a callback that was previously registered. C +should be the integer that was returned by a previous call to +C on the same handle. + +=head3 guestfs_event_callback + + typedef void (*guestfs_event_callback) ( + guestfs_h *g, + void *opaque, + uint64_t event, + int event_handle, + int flags, + const char *buf, size_t buf_len, + const uint64_t *array, size_t array_len); + +This is the type of the event callback function that you have to +provide. + +The basic parameters are: the handle (C), the opaque user pointer +(C), the event class (eg. C), the +event handle, and C which in the current API you should ignore. + +The remaining parameters contain the event payload (if any). Each +event may contain a payload, which usually relates to the event class, +but for future proofing your code should be written to handle any +payload for any event class. + +C and C contain a message buffer (if C, +then there is no message buffer). Note that this message buffer can +contain arbitrary 8 bit data, including NUL bytes. + +C and C is an array of 64 bit unsigned integers. At +the moment this is only used for progress messages. + +=head3 EXAMPLE: CAPTURING LOG MESSAGES + +One motivation for the generic event API was to allow GUI programs to +capture debug and other messages. In libguestfs E 1.8 these were +sent unconditionally to C. + +Events associated with log messages are: C, +C and C. (Note that +error messages are not events; you must capture error messages +separately). + +Programs have to set up a callback to capture the classes of events of +interest: + + int eh = + guestfs_set_event_callback + (g, message_callback, + GUESTFS_EVENT_LIBRARY|GUESTFS_EVENT_APPLIANCE| + GUESTFS_EVENT_TRACE, + 0, NULL) == -1) + if (eh == -1) { + // handle error in the usual way + } + +The callback can then direct messages to the appropriate place. In +this example, messages are directed to syslog: + + static void + message_callback ( + guestfs_h *g, + void *opaque, + uint64_t event, + int event_handle, + int flags, + const char *buf, size_t buf_len, + const uint64_t *array, size_t array_len) + { + const int priority = LOG_USER|LOG_INFO; + if (buf_len > 0) + syslog (priority, "event 0x%lx: %s", event, buf); + } + +=head1 CANCELLING LONG TRANSFERS + +Some operations can be cancelled by the caller while they are in +progress. Currently only operations that involve uploading or +downloading data can be cancelled (technically: operations that have +C or C parameters in the generator). + +=head2 guestfs_user_cancel + + void guestfs_user_cancel (guestfs_h *g); + +C cancels the current upload or download +operation. + +Unlike most other libguestfs calls, this function is signal safe and +thread safe. You can call it from a signal handler or from another +thread, without needing to do any locking. + +The transfer that was in progress (if there is one) will stop shortly +afterwards, and will return an error. The errno (see +L) is set to C, so you can test for this +to find out if the operation was cancelled or failed because of +another error. + +No cleanup is performed: for example, if a file was being uploaded +then after cancellation there may be a partially uploaded file. It is +the caller's responsibility to clean up if necessary. + +There are two common places that you might call C. + +In an interactive text-based program, you might call it from a +C signal handler so that pressing C<^C> cancels the current +operation. (You also need to call L so that +child processes don't receive the C<^C> signal). + +In a graphical program, when the main thread is displaying a progress +bar with a cancel button, wire up the cancel button to call this +function. =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. +fetch them by name, and walk over them, 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: @@ -1756,12 +2002,13 @@ To attach a named piece of data, use the following call: 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. +same key 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. +You can use any C you want, but your key should I start with +an underscore character. Keys beginning with an underscore character +are reserved for internal libguestfs purposes (eg. for implementing +language bindings). It is recommended that you prefix the key with +some unique string to avoid collisions with other users. To retrieve the pointer, use: @@ -1776,11 +2023,102 @@ 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). +set up a close callback to do it (see L). + +To walk over all entries, use these two functions: + + void *guestfs_first_private (guestfs_h *g, const char **key_rtn); + + void *guestfs_next_private (guestfs_h *g, const char **key_rtn); -The private data area is implemented using a hash table, and should be -reasonably efficient for moderate numbers of keys. +C returns the first key, pointer pair ("first" +does not have any particular meaning -- keys are not returned in any +defined order). A pointer to the key is returned in C<*key_rtn> and +the corresponding data pointer is returned from the function. C +is returned if there are no keys stored in the handle. + +C returns the next key, pointer pair. The +return value of this function is also C is there are no further +entries to return. + +Notes about walking over entries: + +=over 4 + +=item * + +You must not call C while walking over the +entries. + +=item * + +The handle maintains an internal iterator which is reset when you call +C. This internal iterator is invalidated when +you call C. + +=item * + +If you have set the data pointer associated with a key to C, ie: + + guestfs_set_private (g, key, NULL); + +then that C is not returned when walking. + +=item * + +C<*key_rtn> is only valid until the next call to +C, C or +C. + +=back + +The following example code shows how to print all keys and data +pointers that are associated with the handle C: + + const char *key; + void *data = guestfs_first_private (g, &key); + while (data != NULL) + { + printf ("key = %s, data = %p\n", key, data); + data = guestfs_next_private (g, &key); + } + +More commonly you are only interested in keys that begin with an +application-specific prefix C. Modify the loop like so: + + const char *key; + void *data = guestfs_first_private (g, &key); + while (data != NULL) + { + if (strncmp (key, "foo_", strlen ("foo_")) == 0) + printf ("key = %s, data = %p\n", key, data); + data = guestfs_next_private (g, &key); + } + +If you need to modify keys while walking, then you have to jump back +to the beginning of the loop. For example, to delete all keys +prefixed with C: + + const char *key; + void *data; + again: + data = guestfs_first_private (g, &key); + while (data != NULL) + { + if (strncmp (key, "foo_", strlen ("foo_")) == 0) + { + guestfs_set_private (g, key, NULL); + /* note that 'key' pointer is now invalid, and so is + the internal iterator */ + goto again; + } + data = guestfs_next_private (g, &key); + } + +Note that the above loop is guaranteed to terminate because the keys +are being deleted, but other manipulations of keys within the loop +might not terminate unless you also maintain an indication of which +keys have been visited. =begin html @@ -2043,8 +2381,8 @@ 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. +L) 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 @@ -2360,6 +2698,11 @@ Automated tests of the C API. The L, L and L commands and documentation. +=item C + +Safety and liveness tests of components that libguestfs depends upon +(not of libguestfs itself). Mainly this is for qemu and the kernel. + =item C Outside contributions, experimental parts. @@ -2373,6 +2716,10 @@ actions. L command and documentation. +=item C + +L command and documentation. + =item C C API example code. @@ -2461,10 +2808,175 @@ Language bindings. =back +=head2 MAKING A STABLE RELEASE + +When we make a stable release, there are several steps documented +here. See L for general information +about the stable branch policy. + +=over 4 + +=item * + +Check C works on at least Fedora, Debian and +Ubuntu. + +=item * + +Finalize RELEASE-NOTES. + +=item * + +Update ROADMAP. + +=item * + +Run C. + +=item * + +Push and pull from Transifex. + +Run: + + tx push -s + +to push the latest POT files to Transifex. Then run: + + ./tx-pull.sh + +which is a wrapper to pull the latest translated C<*.po> files. + +=item * + +Create new stable and development directories under +L. + +=item * + +Create the branch in git: + + git tag -a 1.XX.0 -m "Version 1.XX.0 (stable)" + git tag -a 1.YY.0 -m "Version 1.YY.0 (development)" + git branch stable-1.XX + git push origin tag 1.XX.0 1.YY.0 stable-1.XX + +=back + +=head1 LIMITS + +=head2 PROTOCOL LIMITS + +Internally libguestfs uses a message-based protocol to pass API calls +and their responses to and from a small "appliance" (see L +for plenty more detail about this). The maximum message size used by +the protocol is slightly less than 4 MB. For some API calls you may +need to be aware of this limit. The API calls which may be affected +are individually documented, with a link back to this section of the +documentation. + +A simple call such as L returns its result (the file +data) in a simple string. Because this string is at some point +internally encoded as a message, the maximum size that it can return +is slightly under 4 MB. If the requested file is larger than this +then you will get an error. + +In order to transfer large files into and out of the guest filesystem, +you need to use particular calls that support this. The sections +L and L document how to do this. + +You might also consider mounting the disk image using our FUSE +filesystem support (L). + +=head2 MAXIMUM NUMBER OF DISKS + +When using virtio disks (the default) the current limit is B<25> +disks. + +Virtio itself consumes 1 virtual PCI slot per disk, and PCI is limited +to 31 slots. However febootstrap only understands disks with names +C through C (26 letters) and it reserves one disk +for its own purposes. + +We are working to substantially raise this limit in future versions +but it requires complex changes to qemu. + +In future versions of libguestfs it should also be possible to "hot +plug" disks (add and remove disks after calling L). +This also requires changes to qemu. + +=head2 MAXIMUM NUMBER OF PARTITIONS PER DISK + +Virtio limits the maximum number of partitions per disk to B<15>. + +This is because it reserves 4 bits for the minor device number (thus +C, and C through C). + +If you attach a disk with more than 15 partitions, the extra +partitions are ignored by libguestfs. + +=head2 MAXIMUM SIZE OF A DISK + +Probably the limit is between 2**63-1 and 2**64-1 bytes. + +We have tested block devices up to 1 exabyte (2**60 or +1,152,921,504,606,846,976 bytes) using sparse files backed by an XFS +host filesystem. + +Although libguestfs probably does not impose any limit, the underlying +host storage will. If you store disk images on a host ext4 +filesystem, then the maximum size will be limited by the maximum ext4 +file size (currently 16 TB). If you store disk images as host logical +volumes then you are limited by the maximum size of an LV. + +For the hugest disk image files, we recommend using XFS on the host +for storage. + +=head2 MAXIMUM SIZE OF A PARTITION + +The MBR (ie. classic MS-DOS) partitioning scheme uses 32 bit sector +numbers. Assuming a 512 byte sector size, this means that MBR cannot +address a partition located beyond 2 TB on the disk. + +It is recommended that you use GPT partitions on disks which are +larger than this size. GPT uses 64 bit sector numbers and so can +address partitions which are theoretically larger than the largest +disk we could support. + +=head2 MAXIMUM SIZE OF A FILESYSTEM, FILES, DIRECTORIES + +This depends on the filesystem type. libguestfs itself does not +impose any known limit. Consult Wikipedia or the filesystem +documentation to find out what these limits are. + +=head2 MAXIMUM UPLOAD AND DOWNLOAD + +The API functions L, L, +L, L and the like allow unlimited +sized uploads and downloads. + +=head2 INSPECTION LIMITS + +The inspection code has several arbitrary limits on things like the +size of Windows Registry hive it will read, and the length of product +name. These are intended to stop a malicious guest from consuming +arbitrary amounts of memory and disk space on the host, and should not +be reached in practice. See the source code for more information. + =head1 ENVIRONMENT VARIABLES =over 4 +=item FEBOOTSTRAP_KERNEL + +=item FEBOOTSTRAP_MODULES + +These two environment variables allow the kernel that libguestfs uses +in the appliance to be selected. If C<$FEBOOTSTRAP_KERNEL> is not +set, then the most recent host kernel is chosen. For more information +about kernel selection, see L. This +feature is only available in febootstrap E 3.8. + =item LIBGUESTFS_APPEND Pass additional options to the guest kernel. @@ -2483,8 +2995,8 @@ example: =item LIBGUESTFS_PATH -Set the path that libguestfs uses to search for kernel and initrd.img. -See the discussion of paths in section PATH above. +Set the path that libguestfs uses to search for a supermin appliance. +See the discussion of paths in section L above. =item LIBGUESTFS_QEMU @@ -2515,7 +3027,9 @@ enough. =head1 SEE ALSO L, +L, L, +L, L, L, L, @@ -2538,6 +3052,7 @@ L, L, L, L, +L, L, L. @@ -2587,7 +3102,7 @@ Richard W.M. Jones (C) =head1 COPYRIGHT -Copyright (C) 2009-2010 Red Hat Inc. +Copyright (C) 2009-2011 Red Hat Inc. L This library is free software; you can redistribute it and/or