5 febootstrap - Bootstrapping tool for creating supermin appliances
9 febootstrap [-o OUTPUTDIR] --names LIST OF PKGS ...
10 febootstrap [-o OUTPUTDIR] PKG FILE NAMES ...
14 febootstrap is a tool for building supermin appliances. These are
15 tiny appliances (similar to virtual machines), usually around 100KB in
16 size, which get fully instantiated on-the-fly in a fraction of a
17 second when you need to boot one of them.
19 Originally "fe" in febootstrap stood for "Fedora", but this tool is
20 now distro-independent and can build supermin appliances for several
21 popular Linux distros, and adding support for others is reasonably
24 Note that this manual page documents febootstrap 3.x which is a
25 complete rewrite and quite different from version 2.x. If you are
26 looking for the febootstrap 2.x tools, then this is not the right
29 =head2 BASIC OPERATION
31 There are two modes for using febootstrap. With the I<--names>
32 parameter, febootstrap takes a list of package names and creates a
33 supermin appliance containing those packages and all dependencies that
34 those packages require. In this mode febootstrap usually needs
35 network access because it may need to consult package repositories in
36 order to work out dependencies and download packages.
38 Without I<--names>, febootstrap takes a list of packages (ie.
39 filenames of locally available packages). This package set must be
40 complete and consistent with no dependencies outside the set of
41 packages you provide. In this mode febootstrap does not require any
42 network access. It works by looking at the package files themselves.
44 By "package" we mean the RPM, DEB, (etc.) package. A package name
45 might be the fully qualified name (eg. C<coreutils-8.5-7.fc14.x86_64>)
46 or some abbreviation (eg. C<coreutils>). The precise format of the
47 name and what abbreviations are allowed depends on the package
50 The supermin appliance that febootstrap writes consists of two files
51 called C<hostfiles> and C<base.img> (see L</SUPERMIN APPLIANCES>
52 below). By default these are written to the current directory. If
53 you specify the I<-o OUTPUTDIR> option then these files are written to
54 the named directory instead (traditionally this directory is named
55 C<supermin.d> but you can call it whatever you want).
57 In all cases febootstrap can only build a supermin appliance which is
58 identical in distro, version and architecture to the host. It does
59 I<not> do cross-builds.
67 Display brief command line usage, and exit.
69 =item B<--exclude REGEXP>
71 After doing dependency resolution, exclude packages which match the
74 This option is only used with I<--names>, and it can be given multiple
75 times on the command line.
79 Provide a list of package names, instead of providing packages
80 directly. In this mode febootstrap may require network access. See
81 L</BASIC OPERATION> above.
83 =item B<--no-warnings>
85 Don't print warnings about packaging problems.
89 Select the output directory where the two supermin appliance files are
90 written (C<hostfiles> and C<base.img>). The default directory is the
91 current directory. Note that if this files exist already in the
92 output directory then they will be overwritten.
98 Enable verbose messages.
104 Print the package name and version number, and exit.
106 =item B<--yum-config CONFIGFILE>
108 (Yum/RPM package handler only). Use an alternate configuration file
109 instead of C</etc/yum.conf>. If you also want to specify alternate
110 repositories then you can put them in this file directly or add a
111 C<reposdir> option to this file. For more information on the file
112 format see L<yum.conf(5)>.
116 =head1 SUPERMIN APPLIANCES
118 Supermin appliances consist of just enough information to be able to
119 build an appliance containing the same operating system (Linux
120 version, distro, release etc) as the host OS. Since the host and
121 appliance share many common files such as C</bin/bash> and
122 C</lib/libc.so> there is no reason to ship these files in the
123 appliance. They can simply be read from the host on demand when the
124 appliance is launched. Therefore to save space we just store the
125 names of the host files that we want.
127 There are some files which cannot just be copied from the host in this
128 way. These include configuration files which the host admin might
129 have edited. So along with the list of host files, we also store a
130 skeleton base image which contains these files and the outline
133 Therefore the supermin appliance normally consists of at least two
140 The list of files that are to be copied from the host. This is a
141 plain text file with one pathname per line. Directories are included
144 Paths can contain wildcards, which are expanded when the appliance
147 /etc/yum.repos.d/*.repo
149 would copy all of the C<*.repo> files into the appliance.
151 Each pathname in the file should start with a C</> character. (In
152 older versions of febootstrap, paths started with C<./> and were
153 relative to the root directory, but you should not do that in new
158 This uncompressed cpio file contains the skeleton filesystem. Mostly
159 it contains directories and a few configuration files.
161 All paths in the cpio file should be relative to the root directory of
164 Note that unlike C<hostfiles>, paths and directories in the base image
165 don't need to have any relationship to the host filesystem.
169 =head2 RECONSTRUCTING THE APPLIANCE
171 The separate tool L<febootstrap-supermin-helper(8)> is used to
172 reconstruct an appliance from the hostfiles and base image files.
174 This program in fact iterates recursively over the files and
175 directories passed to it. A common layout is:
182 and then invoking febootstrap-supermin-helper with just the
183 C<supermin.d> directory path as an argument.
185 In this way extra files can be added to the appliance just by creating
186 another cpio file (C<extra.img> in the example above) and dropping it
187 into the directory. When the appliance is constructed, the extra
188 files will appear in the appliance.
190 =head3 DIRECTORIES BEFORE FILES
192 In order for febootstrap-supermin-helper to run quickly, it does not
193 know how to create directories automatically. Inside hostfiles and
194 the cpio files, directories must be specified before any files that
195 they contain. For example:
201 It is fine to list the same directory name multiple times.
203 =head3 LEXICOGRAPHICAL ORDER
205 febootstrap-supermin-helper visits the supermin control files in
206 lexicographical order. Thus in the example above, in the order
207 C<base.img> -E<gt> C<extra.img> -E<gt> C<hostfiles>.
209 This has an important effect: files contained in later cpio files
210 overwrite earlier files, and directories do not need to be specified
211 if they have already been created in earlier control files.
213 =head3 EXAMPLE OF CREATING EXTRA CPIO FILE
215 You can create a file like C<extra.img> very easily using a shell
216 snippet similar to this one:
220 cp /path/to/serviced usr/sbin/
221 echo -e "usr\nusr/sbin\nusr/sbin/serviced" |
222 cpio --quiet -o -H newc > extra.img
225 Notice how we instruct cpio to create intermediate directories.
227 =head2 MINIMIZING THE SUPERMIN APPLIANCE
229 You may want to "minimize" the supermin appliance in order to save
230 time and space when it is instantiated. Typically you might want to
231 remove documentation, info files, man pages and locales. We used to
232 provide a separate tool called C<febootstrap-minimize> for this
233 purpose, but it is no longer provided. Instead you can post-process
234 C<hostfiles> yourself to remove any files or directories that you
235 don't want (by removing lines from the file). Be careful what you
236 remove because files may be necessary for correct operation of the
241 < supermin.d/hostfiles \
242 grep -v '^/usr/share/man/' |
243 grep -v '^/usr/share/doc/' |
244 grep -v '^/usr/share/info/' > supermin.d/hostfiles-t
245 mv supermin.d/hostfiles-t supermin.d/hostfiles
247 =head2 KERNEL AND KERNEL MODULES
249 Usually the kernel and kernel modules are I<not> included in the
250 supermin appliance. When the appliance is instantiated, the kernel
251 modules from the host kernel are copied in, and it is booted using the
254 febootstrap-supermin-helper is able to choose the best host kernel
255 available to boot the appliance. Users can override this by setting
256 environment variables (see L<febootstrap-supermin-helper(8)>).
258 =head2 BOOTING AND CACHING THE SUPERMIN APPLIANCE
260 For fastest boot times you should cache the output of
261 febootstrap-supermin-helper. See the libguestfs source file
262 C<src/appliance.c> for an example of how this is done.
264 =head2 ENFORCING AVAILABILITY OF HOSTFILES
266 febootstrap-supermin-helper builds the appliance by copying in host
267 files as listed in C<hostfiles>. For this to work those host files
268 must be available. We usually enforce this by adding requirements
269 (eg. RPM C<Requires:> lines) on the package that uses the supermin
270 appliance, so that package cannot be installed without pulling in the
271 dependent packages and thus making sure the host files are available.
275 L<febootstrap-supermin-helper(8)>,
276 L<http://people.redhat.com/~rjones/febootstrap/>,
278 L<http://libguestfs.org/>.
286 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
290 Matthew Booth L<mbooth@redhat.com>
296 Copyright (C) 2009-2010 Red Hat Inc.
298 This program is free software; you can redistribute it and/or modify
299 it under the terms of the GNU General Public License as published by
300 the Free Software Foundation; either version 2 of the License, or
301 (at your option) any later version.
303 This program is distributed in the hope that it will be useful,
304 but WITHOUT ANY WARRANTY; without even the implied warranty of
305 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
306 GNU General Public License for more details.
308 You should have received a copy of the GNU General Public License
309 along with this program; if not, write to the Free Software
310 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.