path: root/febootstrap-to-supermin.pod

=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 usually of just two files, but can
contain several files and directories from the list below:

=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.

Note that this file is a cpio file in cpio "newc" format, and is
I<not> compressed (unlike initramfs files which are compressed cpio
files).

=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.*

=item any directory

You can specify a directory which should contain image file(s)
and hostfile(s).

Using a directory is useful either to keep the appliance-related files
together, or to make more complex appliances containing optional bits.

=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-2010 Red Hat Inc.,
L<http://people.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.