X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=src%2Fguestfs.pod;h=db0ab36a8ab0d49b29fcb2f74603b66d3c7c9e8a;hp=8cb1b8677cd8fb404e9cfd39f89400e565ccbc0b;hb=fac15924f59a076c903d453d20305e00e1ae258a;hpb=70f44cc0ea0bcdd025ed657461e07f6778be44ba

diff --git a/src/guestfs.pod b/src/guestfs.pod
index 8cb1b86..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<csharp/Libguestfs.cs>.
 
+=item B<Erlang>
+
+See L<guestfs-erlang(3)>.
+
 =item B<Haskell>
 
 This is the only language binding that is working but incomplete.
@@ -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<Update:> L</guestfs_mount> no longer adds any options starting
+from libguestfs 1.13.16.  This section only applies to older versions.
+
 If you use L</guestfs_mount>, 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<args> 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<Note (1):> This is B<highly experimental> and has a tendency to eat
@@ -1833,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<guestfs_> 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
@@ -2228,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<LIBGUESTFS_DEBUG=1>).
+
+=over 4
+
+=item Create the appliance
+
+C<febootstrap-supermin-helper> is invoked to create the kernel, a
+small initrd and the appliance.
+
+The appliance is cached in C</var/tmp/.guestfs-E<lt>UIDE<gt>> (or in
+another directory if C<TMPDIR> is set).
+
+For a complete description of how the appliance is created and cached,
+read the L<febootstrap(8)> and L<febootstrap-supermin-helper(8)> man
+pages.
+
+=item Start qemu and boot the kernel
+
+qemu is invoked to boot the kernel.
+
+=item Run the initrd
+
+C<febootstrap-supermin-helper> 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
+C</var/tmp/.guestfs-E<lt>UIDE<gt>/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 C</var/tmp/.guestfs-E<lt>UIDE<gt>/root>.
+
+The regular disks being inspected by libguestfs are the first
+devices exposed by qemu (eg. as C</dev/vda>).
+
+The last disk added to qemu is the appliance itself (eg. C</dev/vdb>
+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</init> 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<Starting /init script ...> 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<udev>, possibly printing some debug
+information, and finally running the daemon (C<guestfsd>).
+
+=item The daemon
+
+Finally the daemon (C<guestfsd>) 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<GUESTFS_LAUNCH_FLAG>, which initiates the
+communication protocol (see below).
+
+=back
+
 =head2 COMMUNICATION PROTOCOL
 
 Don't rely on using this protocol directly.  This section documents
@@ -2781,7 +2919,7 @@ Source code to the C library.
 
 =item C<tools>
 
-Command line tools written in Perl (L<virt-resize(1)> and many others).
+Command line tools written in Perl (L<virt-win-reg(1)> and many others).
 
 =item C<test-tool>
 
@@ -2790,6 +2928,8 @@ will work with libguestfs.
 
 =item C<csharp>
 
+=item C<erlang>
+
 =item C<haskell>
 
 =item C<java>
@@ -3027,6 +3167,7 @@ enough.
 =head1 SEE ALSO
 
 L<guestfs-examples(3)>,
+L<guestfs-erlang(3)>,
 L<guestfs-java(3)>,
 L<guestfs-ocaml(3)>,
 L<guestfs-perl(3)>,
@@ -3046,6 +3187,8 @@ L<virt-list-partitions(1)>,
 L<virt-ls(1)>,
 L<virt-make-fs(1)>,
 L<virt-rescue(1)>,
+L<virt-resize(1)>,
+L<virt-sparsify(1)>,
 L<virt-tar(1)>,
 L<virt-tar-in(1)>,
 L<virt-tar-out(1)>,