+=head1 NAME
+
+febootstrap-to-supermin - Convert febootstrap root to supermin appliance.
+
+=head1 SYNOPSIS
+
+ febootstrap-to-supermin DIR supermin.img hostfiles.txt
+
+=head1 DESCRIPTION
+
+I<febootstrap-to-supermin> converts the filesystem created by
+L<febootstrap(8)> into a supermin appliance. The term "supermin
+appliance" is described in the documentation below. First you should
+be familiar with L<febootstrap(8)> and L<febootstrap-to-initramfs(8)>.
+
+=head1 PARAMETERS
+
+C<DIR> is the directory created by febootstrap (ie. the output of
+febootstrap and the input to this program).
+
+C<supermin.img> is the name of the supermin appliance that this
+program creates, and C<hostfiles.txt> is the name of the list of
+hostfiles that this program creates. (ie. the outputs of this
+program).
+
+=head1 SUPERMIN APPLIANCE
+
+A supermin appliance is a very specialized, highly minimized
+appliance which can be reconstructed on-the-fly at runtime into
+an ordinary (initramfs) appliance.
+
+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 directories, 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 a 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 appliance for a security update
+in some underlying library.
+
+There are several I<disadvantages>:
+
+It won't work at all except in very narrow, controlled cases like the
+Fedora packaging case. We control the dependencies of the appliance
+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.
+
+=head2 ANATOMY OF A SUPERMIN APPLIANCE
+
+A supermin appliance consists of two files:
+
+=over 4
+
+=item supermin.img
+
+The image file (conventionally called C<supermin.img>, but you can
+call it anything you want) is the skeleton initramfs. This is like an
+initramfs built by L<febootstrap-to-initramfs(8)>, but all libraries
+and binaries are removed.
+
+=item hostfiles.txt
+
+This plain text file contains a list of files that we need to add back
+from the host at runtime. ie. It's the list of libraries and binaries
+that we removed when we constructed C<supermin.img>.
+
+This file usually contains wildcards. This is because we don't
+want the file to break on minor updates to libraries, so for example
+instead of listing
+
+ lib64/libreadline.so.6.1.2
+
+the file contains
+
+ lib64/libreadline.so.6.*
+
+=back
+
+=head2 RECONSTRUCTING AN INITRAMFS FROM A SUPERMIN APPLIANCE
+
+The program L<febootstrap-supermin-helper(8)> can be used to
+reconstruct a full initramfs from C<supermin.img> and C<hostfiles.txt>
+(plus, naturally, the required programs and libraries in the host
+filesystem).
+
+See that man page for details.
+
+=head2 RESTRICTION: UNREADABLE BINARIES ON THE HOST
+
+Some binaries on the host are not publically readable. For example:
+
+ $ ll /usr/libexec/pt_chown
+ -rws--x--x 1 root root 28418 2009-09-28 13:42 /usr/libexec/pt_chown
+ $ ll /usr/bin/chsh
+ -rws--x--x 1 root root 18072 2009-10-05 16:28 /usr/bin/chsh
+
+These binaries cause a problem when reconstructing the supermin
+appliance, because we'd like to copy them into the final appliance,
+and usually that process is done as non-root. Currently the only
+solution is that you should remove these problematic binaries from the
+appliance.
+
+=head1 EXAMPLE
+
+Create a basic Fedora directory and turn it into a supermin image.
+
+I<NB> You must only build "Rawhide on Rawhide". If using another
+Fedora branch, you must change C<rawhide> below as appropriate, eg to
+C<fedora-12>.
+
+ $ febootstrap rawhide /tmp/fedora
+ $ febootstrap-to-supermin /tmp/fedora supermin.img hostfiles.txt
+
+Examine the resulting files:
+
+ $ cpio -itv < supermin.img | less
+ $ less hostfiles.txt
+
+Reconstruct the final kernel and initramfs.
+
+I<NB> The first time you run this, it will be slow because the
+required host files are not in cache. With a "hot cache" it should be
+lightning fast. Run it several times to get representative timings.
+
+ $ febootstrap-supermin-helper supermin.img hostfiles.txt \
+ /tmp/kernel /tmp/initrd
+
+You would boot the final image like this, although in this example it
+probably won't work unless you add a C</init> file to the appliance
+(see the discussion in L<febootstrap-to-initramfs(8)>).
+
+ $ qemu -m 1024 -kernel /tmp/kernel -initrd /tmp/initrd [etc...]
+
+=head1 SEE ALSO
+
+L<febootstrap(8)>,
+L<febootstrap-to-initramfs(8)>,
+L<febootstrap-supermin-helper(8)>.
+
+=head1 AUTHORS
+
+Richard W.M. Jones <rjones @ redhat . com>
+
+=head1 COPYRIGHT
+
+(C) Copyright 2009 Red Hat Inc.,
+L<http://et.redhat.com/~rjones/febootstrap>.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.