Generated code for 'glob-expand'.

[libguestfs.git] / README

diff --git a/README b/README
index 299b9c9..3dea215 100644 (file)
--- a/README
+++ b/README
@@ -25,13 +25,19 @@ For discussion please use the fedora-virt mailing list:
   https://www.redhat.com/mailman/listinfo/fedora-virt
 
 
+Home page
+----------------------------------------------------------------------
+
+  http://libguestfs.org/
+
+
 Requirements
 ----------------------------------------------------------------------
 
 - recent QEMU >= 0.10 with vmchannel support
   http://lists.gnu.org/archive/html/qemu-devel/2009-02/msg01042.html
 
-- febootstrap >= 2.0
+- febootstrap >= 2.3
 
 - fakeroot
 
@@ -44,12 +50,15 @@ Requirements
 - (Optional) Augeas (http://augeas.net/)
 
 - perldoc (pod2man, pod2text) to generate the manual pages and
-other documentation.
+  other documentation.
 
 - (Optional) Readline to have nicer command-line editing in guestfish.
 
+- (Optional) 'reged' program from chntpw to decode Windows registry
+  entries (http://home.eunet.no/~pnordahl/ntpasswd/)
+
 - (Optional) OCaml if you want to rebuild the generated files, and
-also to build the OCaml bindings
+  also to build the OCaml bindings
 
 - (Optional) local Fedora mirror
 
@@ -111,10 +120,13 @@ or build from our source RPMs.
 Debian
 ----------------------------------------------------------------------
 
-libguestfs should build and run on Debian.  At the moment we don't
-provide Debian packages, and because of the appliance it's rather
-complicated to provide a package which could be accepted into the
-Debian repositories.  Want to help?  Please contact us.
+libguestfs should build and run on Debian.
+
+febootstrap, yum, rpm, fakeroot, fakechroot are all packaged in
+Debian.
+
+Please see the fedora-virt mailing list for the status of libguestfs
+in Debian.
 
 
 qemu
@@ -159,6 +171,62 @@ On some systems, the chmod will not survive a reboot, and you will
 need to make edits to the udev configuration.
 
 
+Supermin appliance
+----------------------------------------------------------------------
+
+If you configure with --enable-supermin then we will build a supermin
+appliance (supermin = super-minimized).  This is a very specialized
+appliance which is built on-the-fly at runtime (specifically, when you
+call guestfs_launch).
+
+The normal appliance is a self-contained Linux operating system, based
+on the Fedora/RHEL/CentOS Linux distro.  So it contains a complete
+copy of all the libraries and programs needed, like kernel, libc,
+bash, coreutils etc etc.
+
+The supermin appliance removes the kernel and all the executable
+libraries and programs from the appliance.  That just leaves a
+skeleton of config files and some data files, which is obviously
+massively smaller than the normal appliance.  At runtime we rebuild
+the appliance on-the-fly from the libraries and programs on the host
+(eg. pulling in the real /lib/libc.so, the real /bin/bash etc.)
+
+Although this process of rebuilding the appliance each time sounds
+slow, it turns out to be faster than using the prebuilt appliance.
+(Most of the saving comes from not compressing the appliance - it
+transpires that decompressing the appliance is the slowest part of the
+whole boot sequence).  On my machine, a new appliance can be built in
+under a fifth of a second, and the boot time is several seconds
+shorter.
+
+The big advantage of the supermin appliance for distributions like
+Fedora is that it gets security fixes automatically from the host, so
+there is no need to rebuild the whole of libguestfs for a security
+update in some underlying library.
+
+There are several DISADVANTAGES:
+
+It won't work at all except in very narrow, controlled cases like the
+Fedora packaging case.  We control the dependencies of the libguestfs
+RPM tightly to ensure that the required binaries are actually present
+on the host.
+
+Furthermore there are certain unlikely changes in the packages on the
+host which could break a supermin appliance, eg. an updated library
+which depends on an additional data file.
+
+Also supermin appliances are subjected to changes in the host kernel
+which might break compatibility with qemu -- these are, of course,
+real bugs in any case.
+
+Lastly, supermin appliances really can't be moved between branches of
+distributions (eg. built on Fedora 12 and moved to Fedora 10) because
+they are not self-contained and they rely on certain libraries being
+around.  You shouldn't do this anyway.
+
+Use supermin appliances with caution.
+
+
 Notes on cross-architecture support
 ----------------------------------------------------------------------