X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=db0ab36a8ab0d49b29fcb2f74603b66d3c7c9e8a;hp=7cfd2b29723f7639b368cbd1c23704306cecaf50;hb=fac15924f59a076c903d453d20305e00e1ae258a;hpb=40f2b698ac765128bfcda5f0db893c95d09ae89a diff --git a/src/guestfs.pod b/src/guestfs.pod index 7cfd2b2..db0ab36 100644 --- a/src/guestfs.pod +++ b/src/guestfs.pod @@ -42,8 +42,8 @@ FUSE. Libguestfs is a library that can be linked with C and C++ management programs (or management programs written in OCaml, Perl, Python, Ruby, -Java, PHP, Haskell or C#). You can also use it from shell scripts or the -command line. +Java, PHP, Erlang, Haskell or C#). You can also use it from shell +scripts or the command line. You don't need to be root to use libguestfs, although obviously you do need enough permissions to access the disk images. @@ -719,6 +719,10 @@ used. The C# bindings are highly experimental. Please read the warnings at the top of C. +=item B + +See L. + =item B This is the only language binding that is working but incomplete. @@ -728,7 +732,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 @@ -798,6 +802,9 @@ can make this very puzzling if you are trying to debug a problem. =item Mount option C<-o sync> should not be the default. +I L no longer adds any options starting +from libguestfs 1.13.16. This section only applies to older versions. + If you use L, then C<-o sync,noatime> are added implicitly. However C<-o sync> does not add any reliability benefit, but does have a very large performance impact. @@ -948,6 +955,29 @@ For example: Note that libguestfs also calls qemu with the -help and -version options in order to determine features. +Wrappers can also be used to edit the options passed to qemu. In the +following example, the C<-machine ...> option (C<-machine> and the +following argument) are removed from the command line and replaced +with C<-machine pc,accel=tcg>. The while loop iterates over the +options until it finds the right one to remove, putting the remaining +options into the C array. + + #!/bin/bash - + + i=0 + while [ $# -gt 0 ]; do + case "$1" in + -machine) + shift 2;; + *) + args[i]="$1" + (( i++ )) + shift ;; + esac + done + + exec qemu-kvm -machine pc,accel=tcg "${args[@]}" + =head2 ATTACHING TO RUNNING DAEMONS I This is B and has a tendency to eat @@ -1344,8 +1374,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); @@ -1354,9 +1382,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 @@ -1452,8 +1483,8 @@ 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 *g, - guestfs_abort_cb); + void guestfs_set_out_of_memory_handler (guestfs_h *g, + guestfs_abort_cb); The callback C will be called if there is an out of memory situation. I. @@ -1832,6 +1863,21 @@ 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. +=item GUESTFS_EVENT_ENTER +(payload type: function name) + +The callback function is called whenever a libguestfs function +is entered. + +The payload is a string which contains the name of the function +that we are entering (not including C prefix). + +Note that libguestfs functions can call themselves, so you may +see many events from a single call. A few libguestfs functions +do not generate this event. + +If no callback is registered: the event is ignored. + =back =head3 guestfs_set_event_callback @@ -1949,6 +1995,45 @@ this example, messages are directed to syslog: 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, @@ -2188,6 +2273,99 @@ callback to receive these messages. =head1 INTERNALS +=head2 APPLIANCE BOOT PROCESS + +This process has evolved and continues to evolve. The description +here corresponds only to the current version of libguestfs and is +provided for information only. + +In order to follow the stages involved below, enable libguestfs +debugging (set the environment variable C). + +=over 4 + +=item Create the appliance + +C is invoked to create the kernel, a +small initrd and the appliance. + +The appliance is cached in CUIDE> (or in +another directory if C is set). + +For a complete description of how the appliance is created and cached, +read the L and L man +pages. + +=item Start qemu and boot the kernel + +qemu is invoked to boot the kernel. + +=item Run the initrd + +C builds a small initrd. The initrd is +not the appliance. The purpose of the initrd is to load enough kernel +modules in order that the appliance itself can be mounted and started. + +The initrd is a cpio archive called +CUIDE/initrd>. + +When the initrd has started you will see messages showing that kernel +modules are being loaded, similar to this: + + febootstrap: ext2 mini initrd starting up + febootstrap: mounting /sys + febootstrap: internal insmod libcrc32c.ko + febootstrap: internal insmod crc32c-intel.ko + +=item Find and mount the appliance device + +The appliance is a sparse file containing an ext2 filesystem which +contains a familiar (although reduced in size) Linux operating system. +It would normally be called CUIDE/root>. + +The regular disks being inspected by libguestfs are the first +devices exposed by qemu (eg. as C). + +The last disk added to qemu is the appliance itself (eg. C +if there was only one regular disk). + +Thus the final job of the initrd is to locate the appliance disk, +mount it, and switch root into the appliance, and run C from +the appliance. + +If this works successfully you will see messages such as: + + febootstrap: picked /sys/block/vdb/dev as root device + febootstrap: creating /dev/root as block special 252:16 + febootstrap: mounting new root on /root + febootstrap: chroot + Starting /init script ... + +Note that C indicates that the appliance's +init script is now running. + +=item Initialize the appliance + +The appliance itself now initializes itself. This involves starting +certain processes like C, possibly printing some debug +information, and finally running the daemon (C). + +=item The daemon + +Finally the daemon (C) runs inside the appliance. If it +runs you should see: + + verbose daemon enabled + +The daemon expects to see a named virtio-serial port exposed by qemu +and connected on the other end to the library. + +The daemon connects to this port (and hence to the library) and sends +a four byte message C, which initiates the +communication protocol (see below). + +=back + =head2 COMMUNICATION PROTOCOL Don't rely on using this protocol directly. This section documents @@ -2658,6 +2836,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. @@ -2671,6 +2854,10 @@ actions. L command and documentation. +=item C + +L command and documentation. + =item C C API example code. @@ -2732,7 +2919,7 @@ Source code to the C library. =item C -Command line tools written in Perl (L and many others). +Command line tools written in Perl (L and many others). =item C @@ -2741,6 +2928,8 @@ will work with libguestfs. =item C +=item C + =item C =item C @@ -2759,6 +2948,61 @@ 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 @@ -2819,6 +3063,15 @@ 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 @@ -2854,6 +3107,16 @@ be reached in practice. See the source code for more information. =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. @@ -2904,7 +3167,10 @@ enough. =head1 SEE ALSO L, +L, +L, L, +L, L, L, L, @@ -2921,12 +3187,15 @@ L, L, L, L, +L, +L, L, L, L, L, L, L, +L, L, L.