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