X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=guestfs.pod;h=3dad35c40d990acafc37c3d1042d3930e13f7b77;hp=06cc2b3a457198c9c6f519a6c5307c444425d116;hb=215041c7178922341ecbfdb23eb203f2bb8c29c4;hpb=d43dac69483e8ec62e8356d93f761684ce2f5cc8

diff --git a/guestfs.pod b/guestfs.pod
index 06cc2b3..3dad35c 100644
--- a/guestfs.pod
+++ b/guestfs.pod
@@ -205,6 +205,14 @@ search the current directory and then C</usr/lib/guestfs>.
 
 =head1 HIGH-LEVEL API ACTIONS
 
+=head2 ABI GUARANTEE
+
+We guarantee the libguestfs ABI (binary interface), for public,
+high-level actions as outlined in this section.  Although we will
+deprecate some actions, for example if they get replaced by newer
+calls, we will keep the old actions forever.  This allows you the
+developer to program in confidence against libguestfs.
+
 @ACTIONS@
 
 =head1 STRUCTURES
@@ -491,6 +499,109 @@ C<guestfs_create_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
+block devices (in this context, by I<block device> I mean a physical
+or virtual hard drive).  The original Linux IDE driver used names
+starting with C</dev/hd*>.  SCSI devices have historically used a
+different naming scheme, C</dev/sd*>.  When the Linux kernel I<libata>
+driver became a popular replacement for the old IDE driver
+(particularly for SATA devices) those devices also used the
+C</dev/sd*> scheme.  Additionally we now have virtual machines with
+paravirtualized drivers.  This has created several different naming
+systems, such as C</dev/vd*> for virtio disks and C</dev/xvd*> for Xen
+PV disks.
+
+As discussed above, libguestfs uses a qemu appliance running an
+embedded Linux kernel to access block devices.  We can run a variety
+of appliances based on a variety of Linux kernels.
+
+This causes a problem for libguestfs because many API calls use device
+or partition names.  Working scripts and the recipe (example) scripts
+that we make available over the internet could fail if the naming
+scheme changes.
+
+Therefore libguestfs defines C</dev/sd*> as the I<standard naming
+scheme>.  Internally C</dev/sd*> names are translated, if necessary,
+to other names as required.  For example, under RHEL 5 which uses the
+C</dev/hd*> scheme, any device parameter C</dev/sda2> is translated to
+C</dev/hda2> transparently.
+
+Note that this I<only> applies to parameters.  The
+C<guestfs_list_devices>, C<guestfs_list_partitions> and similar calls
+return the true names of the devices and partitions as known to the
+appliance.
+
+=head2 ALGORITHM FOR BLOCK DEVICE NAME TRANSLATION
+
+Usually this translation is transparent.  However in some (very rare)
+cases you may need to know the exact algorithm.  Such cases include
+where you use C<guestfs_config> to add a mixture of virtio and IDE
+devices to the qemu-based appliance, so have a mixture of C</dev/sd*>
+and C</dev/vd*> devices.
+
+The algorithm is applied only to I<parameters> which are known to be
+either device or partition names.  Return values from functions such
+as C<guestfs_list_devices> are never changed.
+
+=over 4
+
+=item *
+
+Is the string a parameter which is a device or partition name?
+
+=item *
+
+Does the string begin with C</dev/sd>?
+
+=item *
+
+Does the named device exist?  If so, we use that device.
+However if I<not> then we continue with this algorithm.
+
+=item *
+
+Replace initial C</dev/sd> string with C</dev/hd>.
+
+For example, change C</dev/sda2> to C</dev/hda2>.
+
+If that named device exists, use it.  If not, continue.
+
+=item *
+
+Replace initial C</dev/sd> string with C</dev/vd>.
+
+If that named device exists, use it.  If not, return an error.
+
+=back
+
+=head2 PORTABILITY CONCERNS
+
+Although the standard naming scheme and automatic translation is
+useful for simple programs and guestfish scripts, for larger programs
+it is best not to rely on this mechanism.
+
+Where possible for maximum future portability programs using
+libguestfs should use these future-proof techniques:
+
+=over 4
+
+=item *
+
+Use C<guestfs_list_devices> or C<guestfs_list_partitions> to list
+actual device names, and then use those names directly.
+
+Since those device names exist by definition, they will never be
+translated.
+
+=item *
+
+Use higher level ways to identify filesystems, such as LVM names,
+UUIDs and filesystem labels.
+
+=back
+
 =head1 INTERNALS
 
 =head2 COMMUNICATION PROTOCOL
@@ -656,6 +767,9 @@ For example:
 
  LIBGUESTFS_QEMU=/tmp/qemu.wrapper guestfish
 
+Note that libguestfs also calls qemu with the -help and -version
+options in order to determine features.
+
 =head1 ENVIRONMENT VARIABLES
 
 =over 4
@@ -678,6 +792,10 @@ used.
 
 See also L<QEMU WRAPPERS> above.
 
+=item LIBGUESTFS_APPEND
+
+Pass additional options to the guest kernel.
+
 =back
 
 =head1 SEE ALSO
@@ -685,7 +803,35 @@ See also L<QEMU WRAPPERS> above.
 L<guestfish(1)>,
 L<qemu(1)>,
 L<febootstrap(1)>,
-L<http://et.redhat.com/~rjones/libguestfs>.
+L<http://libguestfs.org/>.
+
+=head1 BUGS
+
+To get a list of bugs against libguestfs use this link:
+
+L<https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools>
+
+To report a new bug against libguestfs use this link:
+
+L<https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools>
+
+When reporting a bug, please check:
+
+=over 4
+
+=item *
+
+That the bug hasn't been reported already.
+
+=item *
+
+That you are testing a recent version.
+
+=item *
+
+Describe the bug accurately, and give a way to reproduce it.
+
+=back
 
 =head1 AUTHORS
 
@@ -694,7 +840,7 @@ Richard W.M. Jones (C<rjones at redhat dot com>)
 =head1 COPYRIGHT
 
 Copyright (C) 2009 Red Hat Inc.
-L<http://et.redhat.com/~rjones/libguestfs>
+L<http://libguestfs.org/>
 
 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public