X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=45f63297d6b3cff8b17d4db8e7ee2312dbe8ffbc;hp=6ccecedb0844866899af4df7ec28e4daa80c6d54;hb=5d93d70b4d36b2337104b3dbca07722fa4d47ff5;hpb=9420eaf44ec4067c3740b91b0be0fede08a0c515 diff --git a/src/guestfs.pod b/src/guestfs.pod index 6cceced..45f6329 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. @@ -313,21 +313,36 @@ in the table below. =item B to B -Use L to copy a single file, or -L to copy directories recursively. +Use L to copy a single file, or L to copy +directories recursively. -=item B to B +To copy part of a file (offset and size) use +L. -Use L which efficiently uses L -to copy between files and devices in the guest. +=item B to B + +=item B to B + +=item B to B + +Use L, L, +or L. Example: duplicate the contents of an LV: - guestfs_dd (g, "/dev/VG/Original", "/dev/VG/Copy"); + guestfs_copy_device_to_device (g, + "/dev/VG/Original", "/dev/VG/Copy", + /* -1 marks the end of the list of optional parameters */ + -1); The destination (C) must be at least as large as the -source (C). To copy less than the whole -source device, use L. +source (C). To copy less than the whole source +device, use the optional C parameter: + + guestfs_copy_device_to_device (g, + "/dev/VG/Original", "/dev/VG/Copy", + GUESTFS_COPY_DEVICE_TO_DEVICE_SIZE, 10000, + -1); =item B to B @@ -719,6 +734,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. @@ -798,6 +817,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 +970,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 @@ -2135,6 +2180,77 @@ 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. +=head1 SYSTEMTAP + +The libguestfs C library can be probed using systemtap or DTrace. +This is true of any library, not just libguestfs. However libguestfs +also contains static markers to help in probing internal operations. + +You can list all the static markers by doing: + + stap -l 'process("/usr/lib*/libguestfs.so.0") + .provider("guestfs").mark("*")' + +B These static markers are I part of the stable API and +may change in future versions. + +=head2 SYSTEMTAP SCRIPT EXAMPLE + +This script contains examples of displaying both the static markers +and some ordinary C entry points: + + global last; + + function display_time () { + now = gettimeofday_us (); + delta = 0; + if (last > 0) + delta = now - last; + last = now; + + printf ("%d (+%d):", now, delta); + } + + probe begin { + last = 0; + printf ("ready\n"); + } + + /* Display all calls to static markers. */ + probe process("/usr/lib*/libguestfs.so.0") + .provider("guestfs").mark("*") ? { + display_time(); + printf ("\t%s %s\n", $$name, $$parms); + } + + /* Display all calls to guestfs_mkfs* functions. */ + probe process("/usr/lib*/libguestfs.so.0") + .function("guestfs_mkfs*") ? { + display_time(); + printf ("\t%s %s\n", probefunc(), $$parms); + } + +The script above can be saved to C and run using the +L program. Note that you either have to be root, or you have +to add yourself to several special stap groups. Consult the systemtap +documentation for more information. + + # stap /tmp/test.stap + ready + +In another terminal, run a guestfish command such as this: + + guestfish -N fs + +In the first terminal, stap trace output similar to this is shown: + + 1318248056692655 (+0): launch_start + 1318248056692850 (+195): launch_build_appliance_start + 1318248056818285 (+125435): launch_build_appliance_end + 1318248056838059 (+19774): launch_run_qemu + 1318248061071167 (+4233108): launch_end + 1318248061280324 (+209157): guestfs_mkfs g=0x1024ab0 fstype=0x46116f device=0x1024e60 + =begin html @@ -2243,6 +2359,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 @@ -2590,7 +2799,7 @@ Packagers can run only certain tests by setting for example: TEST_ONLY="vfs_type zerofree" -See C for more details of how these environment +See C for more details of how these environment variables work. =head2 DEBUGGING NEW API ACTIONS @@ -2700,23 +2909,23 @@ the programmers. =over 4 -=item C +=item C -The libguestfs appliance, build scripts and so on. +L command and documentation. -=item C +=item C -Automated tests of the C API. +The libguestfs appliance, build scripts and so on. =item C The L, L and L commands and documentation. -=item C +=item C -Safety and liveness tests of components that libguestfs depends upon -(not of libguestfs itself). Mainly this is for qemu and the kernel. +Tools for cloning virtual machines. Currently contains +L command and documentation. =item C @@ -2739,6 +2948,11 @@ L command and documentation. C API example code. +=item C + +Extra tests. These are not run by default because they require +special tools or configuration. + =item C L, the command-line shell, and various shell scripts @@ -2790,21 +3004,35 @@ Regression tests. L command and documentation. -=item C +=item C -Source code to the C library. +L command and documentation. -=item C +=item C -Command line tools written in Perl (L and many others). +L command and documentation. + +=item C + +Source code to the C library. =item C Test tool for end users to test if their qemu/kernel combination will work with libguestfs. +=item C + +Tests. + +=item C + +Command line tools written in Perl (L and many others). + =item C +=item C + =item C =item C @@ -3042,6 +3270,7 @@ enough. =head1 SEE ALSO L, +L, L, L, L, @@ -3049,6 +3278,7 @@ L, L, L, L, +L, L, L, L, @@ -3061,14 +3291,19 @@ L, L, L, L, +L, +L, +L, L, L, L, L, +L, L, L, L, L, +L, L. Tools with a similar purpose: