febootstrap-to-supermin.pod

   1 =head1 NAME
   2
   3 febootstrap-to-supermin - Convert febootstrap root to supermin appliance.
   4
   5 =head1 SYNOPSIS
   6
   7  febootstrap-to-supermin DIR supermin.img hostfiles.txt
   8
   9 =head1 DESCRIPTION
  10
  11 I<febootstrap-to-supermin> converts the filesystem created by
  12 L<febootstrap(8)> into a supermin appliance.  The term "supermin
  13 appliance" is described in the documentation below.  First you should
  14 be familiar with L<febootstrap(8)> and L<febootstrap-to-initramfs(8)>.
  15
  16 =head1 PARAMETERS
  17
  18 C<DIR> is the directory created by febootstrap (ie. the output of
  19 febootstrap and the input to this program).
  20
  21 C<supermin.img> is the name of the supermin appliance that this
  22 program creates, and C<hostfiles.txt> is the name of the list of
  23 hostfiles that this program creates.  (ie. the outputs of this
  24 program).
  25
  26 =head1 SUPERMIN APPLIANCE
  27
  28 A supermin appliance is a very specialized, highly minimized
  29 appliance which can be reconstructed on-the-fly at runtime into
  30 an ordinary (initramfs) appliance.
  31
  32 The normal appliance is a self-contained Linux operating system, based
  33 on the Fedora/RHEL/CentOS Linux distro.  So it contains a complete
  34 copy of all the libraries and programs needed, like kernel, libc,
  35 bash, coreutils etc etc.
  36
  37 The supermin appliance removes the kernel and all the executable
  38 libraries and programs from the appliance.  That just leaves a
  39 skeleton of directories, config files and some data files, which is
  40 obviously massively smaller than the normal appliance.  At runtime we
  41 rebuild the appliance on-the-fly from the libraries and programs on
  42 the host (eg. pulling in the real /lib/libc.so, the real /bin/bash
  43 etc.)
  44
  45 Although this process of rebuilding the appliance each time sounds
  46 slow, it turns out to be faster than using a prebuilt appliance.
  47 (Most of the saving comes from not compressing the appliance - it
  48 transpires that decompressing the appliance is the slowest part of the
  49 whole boot sequence).  On my machine, a new appliance can be built in
  50 under a fifth of a second, and the boot time is several seconds
  51 shorter.
  52
  53 The big advantage of the supermin appliance for distributions like
  54 Fedora is that it gets security fixes automatically from the host, so
  55 there is no need to rebuild the whole appliance for a security update
  56 in some underlying library.
  57
  58 There are several I<disadvantages>:
  59
  60 It won't work at all except in very narrow, controlled cases like the
  61 Fedora packaging case.  We control the dependencies of the appliance
  62 RPM tightly to ensure that the required binaries are actually present
  63 on the host.
  64
  65 Furthermore there are certain unlikely changes in the packages on the
  66 host which could break a supermin appliance, eg. an updated library
  67 which depends on an additional data file.
  68
  69 Also supermin appliances are subjected to changes in the host kernel
  70 which might break compatibility with qemu -- these are, of course,
  71 real bugs in any case.
  72
  73 Lastly, supermin appliances really can't be moved between branches of
  74 distributions (eg. built on Fedora 12 and moved to Fedora 10) because
  75 they are not self-contained and they rely on certain libraries being
  76 around.  You shouldn't do this anyway.
  77
  78 Use supermin appliances with caution.
  79
  80 =head2 ANATOMY OF A SUPERMIN APPLIANCE
  81
  82 A supermin appliance consists usually of just two files, but can
  83 contain several files and directories from the list below:
  84
  85 =over 4
  86
  87 =item supermin.img
  88
  89 The image file (conventionally called C<supermin.img>, but you can
  90 call it anything you want) is the skeleton initramfs.  This is like an
  91 initramfs built by L<febootstrap-to-initramfs(8)>, but all libraries
  92 and binaries are removed.
  93
  94 Note that this file is a cpio file in cpio "newc" format, and is
  95 I<not> compressed (unlike initramfs files which are compressed cpio
  96 files).
  97
  98 =item hostfiles.txt
  99
 100 This plain text file contains a list of files that we need to add back
 101 from the host at runtime.  ie. It's the list of libraries and binaries
 102 that we removed when we constructed C<supermin.img>.
 103
 104 This file usually contains wildcards.  This is because we don't
 105 want the file to break on minor updates to libraries, so for example
 106 instead of listing
 107
 108  lib64/libreadline.so.6.1.2
 109
 110 the file contains
 111
 112  lib64/libreadline.so.6.*
 113
 114 =item any directory
 115
 116 You can specify a directory which should contain image file(s)
 117 and hostfile(s).
 118
 119 Using a directory is useful either to keep the appliance-related files
 120 together, or to make more complex appliances containing optional bits.
 121
 122 =back
 123
 124 =head2 RECONSTRUCTING AN INITRAMFS FROM A SUPERMIN APPLIANCE
 125
 126 The program L<febootstrap-supermin-helper(8)> can be used to
 127 reconstruct a full initramfs from C<supermin.img> and C<hostfiles.txt>
 128 (plus, naturally, the required programs and libraries in the host
 129 filesystem).
 130
 131 See that man page for details.
 132
 133 =head2 RESTRICTION: UNREADABLE BINARIES ON THE HOST
 134
 135 Some binaries on the host are not publically readable.  For example:
 136
 137  $ ll /usr/libexec/pt_chown
 138  -rws--x--x 1 root root 28418 2009-09-28 13:42 /usr/libexec/pt_chown
 139  $ ll /usr/bin/chsh
 140  -rws--x--x 1 root root 18072 2009-10-05 16:28 /usr/bin/chsh
 141
 142 These binaries cause a problem when reconstructing the supermin
 143 appliance, because we'd like to copy them into the final appliance,
 144 and usually that process is done as non-root.  Currently the only
 145 solution is that you should remove these problematic binaries from the
 146 appliance.
 147
 148 =head1 EXAMPLE
 149
 150 Create a basic Fedora directory and turn it into a supermin image.
 151
 152 I<NB> You must only build "Rawhide on Rawhide".  If using another
 153 Fedora branch, you must change C<rawhide> below as appropriate, eg to
 154 C<fedora-12>.
 155
 156  $ febootstrap rawhide /tmp/fedora
 157  $ febootstrap-to-supermin /tmp/fedora supermin.img hostfiles.txt
 158
 159 Examine the resulting files:
 160
 161  $ cpio -itv < supermin.img | less
 162  $ less hostfiles.txt
 163
 164 Reconstruct the final kernel and initramfs.
 165
 166 I<NB> The first time you run this, it will be slow because the
 167 required host files are not in cache.  With a "hot cache" it should be
 168 lightning fast.  Run it several times to get representative timings.
 169
 170  $ febootstrap-supermin-helper supermin.img hostfiles.txt \
 171      /tmp/kernel /tmp/initrd
 172
 173 You would boot the final image like this, although in this example it
 174 probably won't work unless you add a C</init> file to the appliance
 175 (see the discussion in L<febootstrap-to-initramfs(8)>).
 176
 177  $ qemu -m 1024 -kernel /tmp/kernel -initrd /tmp/initrd [etc...]
 178
 179 =head1 SEE ALSO
 180
 181 L<febootstrap(8)>,
 182 L<febootstrap-to-initramfs(8)>,
 183 L<febootstrap-supermin-helper(8)>.
 184
 185 =head1 AUTHORS
 186
 187 Richard W.M. Jones <rjones @ redhat . com>
 188
 189 =head1 COPYRIGHT
 190
 191 (C) Copyright 2009-2010 Red Hat Inc.,
 192 L<http://people.redhat.com/~rjones/febootstrap>.
 193
 194 This program is free software; you can redistribute it and/or modify
 195 it under the terms of the GNU General Public License as published by
 196 the Free Software Foundation; either version 2 of the License, or
 197 (at your option) any later version.
 198
 199 This program is distributed in the hope that it will be useful,
 200 but WITHOUT ANY WARRANTY; without even the implied warranty of
 201 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 202 GNU General Public License for more details.
 203
 204 You should have received a copy of the GNU General Public License
 205 along with this program; if not, write to the Free Software
 206 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.