Update README for guestfish support.

Signed-off-by: Martin Schwenke <martin@meltin.net>

1 files changed, 89 insertions, 38 deletions

diff --git a/README b/README
index 1fa7b2b..d42ce5e 100644
--- a/README
+++ b/README
@@ -53,20 +53,28 @@ This section explains how to setup a host machine to run virtual
 clusters generated by autocluster.
 
 
- 1) Install kvm, libvirt, qemu-nbd, nbd-client and expect.
+ 1) Install and configure required software.
+
+ a) Install kvm, libvirt and expect.
 
     Autocluster creates virtual machines that use libvirt to run under
     KVM.  This means that you will need to install both KVM and
-    libvirt on your host machine.  You will also need the qemu-nbd and
-    nbd-client programs, which autocluster uses to loopback-nbd-mount
-    the disk images when configuring each node.  Expect is used by the
-    "waitfor" script and should be available for installation form
-    your distribution.
+    libvirt on your host machine.  Expect is used by the "waitfor"
+    script and should be available for installation form your
+    distribution.
 
     For various distros:
 
     * RHEL/CentOS
 
+      Autocluster should work with the standard RHEL6 qemu-kvm and
+      libvirt packages.  However, RHEL's KVM doesn't support the SCSI
+      emulation, so you will need these settings:
+
+        SYSTEM_DISK_TYPE=ide
+        SHARED_DISK_TYPE=virtio
+        KVM=/usr/libexec/qemu-kvm
+
       For RHEL5/CentOS5, useful packages for both kvm and libvirt used
       to be found here:
 
@@ -75,40 +83,27 @@ clusters generated by autocluster.
       However, since recent versions of RHEL5 ship with KVM, 3rd party
       KVM RPMs for RHEL5 are now scarce.
 
-      RHEL5.4 ships with KVM but it doesn't have the SCSI disk
-      emulation that autocluster uses by default.  There are also
-      problems when autocluster uses virtio on RHEL5.4's KVM.  See the
-      sections below on "iSCSI shared disks" and "Raw IDE system
-      disks".  Also, to use the RHEL5 version of KVM you will need to
-      set
-
-        KVM=/usr/libexec/qemu-kvm
-
-      in your configuration file.
-
-      Unless you can find an RPM for nbd-client then you need to
-      download source from:
- 
-        http://sourceforge.net/projects/nbd/
+      RHEL5.4's KVM also has problems when autocluster uses virtio
+      shared disks, since multipath doesn't notice virtio disks.  This
+      is fixed in RHEL5.6 and in a recent RHEL5.5 update - you should
+      be able to use the settings recommended above for RHEL6.
 
-      and build it.
+      If you're still running RHEL5.4, you have lots of time, you have
+      lots of disk space and you like complexity then see the sections
+      below on "iSCSI shared disks" and "Raw IDE system disks".
 
     * Fedora Core
 
       Useful packages ship with Fedora Core 10 (Cambridge) and later.
-
-      qemu-nbd is in the kvm package.
-
-      nbd-client is in the nbd package.
+      Some of the above notes on RHEL might apply to Fedora Core's
+      KVM.
 
     * Ubuntu
 
       Useful packages ship with Ubuntu 8.10 (Intrepid Ibex) and later.
-
-      qemu-nbd is in the kvm package but is called kvm-nbd, so you
-      need to set the QEMU_NBD configuration variable.
-
-      nbd-client is in the nbd-client package.
+      In recent Ubuntu versions (e.g. 10.10 Maverick Meerkat) the KVM
+      package is called "qemu-kvm".  Older versions have a package
+      called "kvm".
 
     For other distributions you'll have to backport distro sources or
     compile from upstream source as described below.
@@ -121,10 +116,66 @@ clusters generated by autocluster.
 
         http://libvirt.org/
 
-    * As mentioned about, nbd can be found at:
+ b) Install guestfish or qemu-nbd and nbd-client.
+
+    Recent Linux distributions, including RHEL6.0, contain guestfish.
+    Guestfish (see http://libguestfs.org/ - there are binary packages
+    for several distros here) is a CLI for manipulating KVM/QEMU disk
+    images.  Autocluster supports guestfish, so if guestfish is
+    available then you should use it.  It should be more reliable than
+    NBD.
+
+    Guestfish isn't yet the default autocluster method for disk image
+    manipulation.  To use it put this in your configuration file:
+
+      SYSTEM_DISK_ACCESS_METHOD=guestfish
+
+    Note that autocluster's guestfish support is new and was written
+    to work around some bugs in RHEL6.0's version of guestfish... so
+    might not work well with newer, non-buggy versions.  If so, please
+    report bugs!
+
+    If you can't use guestfish then you'll have to use NBD.  For this
+    you will need the qemu-nbd and nbd-client programs, which
+    autocluster uses to loopback-nbd-mount the disk images when
+    configuring each node.
 
+    NBD for various distros:
+
+    * RHEL/CentOS
+
+      qemu-nbd is only available in the old packages from lfarkas.org.
+      Recompiling the RHEL5 kvm package to support NBD is quite
+      straightforward.  RHEL6 doesn't have an NBD kernel module, so is
+      harder to retrofit for NBD support - use guestfish instead.
+
+      Unless you can find an RPM for nbd-client then you need to
+      download source from:
+ 
         http://sourceforge.net/projects/nbd/
 
+      and build it.
+
+    * Fedora Core
+
+      qemu-nbd is in the qemu-kvm or kvm package.
+
+      nbd-client is in the nbd package.
+
+    * Ubuntu
+
+      qemu-nbd is in the qemu-kvm or kvm package.  In older releases
+      it is called kvm-nbd, so you need to set the QEMU_NBD
+      configuration variable.
+
+      nbd-client is in the nbd-client package.
+
+    * As mentioned above, nbd can be found at:
+
+        http://sourceforge.net/projects/nbd/
+
+ c) Environment and libvirt virtual networks
+
     You will need to add the autocluster directory to your PATH.
 
     You will need to configure the right kvm networking setup. The
@@ -241,9 +292,9 @@ all of this as root.
     disk images for your cluster nodes, and any other nodes you have
     configured.  Each disk image is initially created as an "empty"
     copy-on-write image, which is linked to the base image.  Those
-    images are then loopback-nbd-mounted and populated with system
-    configuration files and other potentially useful things (such as
-    scripts).
+    images are then attached to using guestfish or
+    loopback-nbd-mounted, and populated with system configuration
+    files and other potentially useful things (such as scripts).
 
 
 BOOTING A CLUSTER
@@ -461,9 +512,9 @@ iSCSI shared disks
 
 The RHEL5 version of KVM does not support the SCSI block device
 emulation.  Therefore, you can use either virtio or iSCSI shared
-disks.  Unfortunately, at the time of writing, virtio block devices
-are not supported by the version of multipath in RHEL5.  So this
-leaves iSCSI as the only choice.
+disks.  Unfortunately, in RHEL5.4 and early versions of RHEL5.5,
+virtio block devices are not supported by the version of multipath in
+RHEL5.  So this leaves iSCSI as the only choice.
 
 The main configuration options you need for iSCSI disks are: