1FEBOOTSTRAP(8) Virtualization Support FEBOOTSTRAP(8)
2
6 febootstrap - Bootstrapping tool for creating supermin appliances
7
9 febootstrap [-o OUTPUTDIR] --names LIST OF PKGS ...
10 febootstrap [-o OUTPUTDIR] PKG FILE NAMES ...
11
13 febootstrap is a tool for building supermin appliances. These are tiny
14 appliances (similar to virtual machines), usually around 100KB in size,
15 which get fully instantiated on-the-fly in a fraction of a second when
16 you need to boot one of them.
17 Originally "fe" in febootstrap stood for "Fedora", but this tool is now
19 distro-independent and can build supermin appliances for several
20 popular Linux distros, and adding support for others is reasonably
21 easy.
22 Note that this manual page documents febootstrap 3.x which is a
24 complete rewrite and quite different from version 2.x. If you are
25 looking for the febootstrap 2.x tools, then this is not the right
26 place.
27 BASIC OPERATION
29 There are two modes for using febootstrap. With the --names parameter,
30 febootstrap takes a list of package names and creates a supermin
31 appliance containing those packages and all dependencies that those
32 packages require. In this mode febootstrap usually needs network
33 access because it may need to consult package repositories in order to
34 work out dependencies and download packages.
35 Without --names, febootstrap takes a list of packages (ie. filenames
37 of locally available packages). This package set must be complete and
38 consistent with no dependencies outside the set of packages you
39 provide. In this mode febootstrap does not require any network access.
40 It works by looking at the package files themselves.
41 By "package" we mean the RPM, DEB, (etc.) package. A package name
43 might be the fully qualified name (eg. "coreutils-8.5-7.fc14.x86_64")
44 or some abbreviation (eg. "coreutils"). The precise format of the name
45 and what abbreviations are allowed depends on the package manager.
46 The supermin appliance that febootstrap writes consists of two files
48 called "hostfiles" and "base.img" (see "SUPERMIN APPLIANCES" below).
49 By default these are written to the current directory. If you specify
50 the -o OUTPUTDIR option then these files are written to the named
51 directory instead (traditionally this directory is named "supermin.d"
52 but you can call it whatever you want).
53 In all cases febootstrap can only build a supermin appliance which is
55 identical in distro, version and architecture to the host. It does not
56 do cross-builds.
57
59 --help
60 Display brief command line usage, and exit.
61 --exclude REGEXP
63 After doing dependency resolution, exclude packages which match the
64 regular expression.
65 This option is only used with --names, and it can be given multiple
67 times on the command line.
68 --names
70 Provide a list of package names, instead of providing packages
71 directly. In this mode febootstrap may require network access.
72 See "BASIC OPERATION" above.
73 --no-warnings
75 Don't print warnings about packaging problems.
76 -o outputdir
78 Select the output directory where the two supermin appliance files
79 are written ("hostfiles" and "base.img"). The default directory is
80 the current directory. Note that if this files exist already in
81 the output directory then they will be overwritten.
82 -v
84 --verbose
85 Enable verbose messages.
86 -V
88 --version
89 Print the package name and version number, and exit.
90 --yum-config CONFIGFILE
92 (Yum/RPM package handler only). Use an alternate configuration
93 file instead of "/etc/yum.conf". If you also want to specify
94 alternate repositories then you can put them in this file directly
95 or add a "reposdir" option to this file. For more information on
96 the file format see yum.conf(5).
97
99 Supermin appliances consist of just enough information to be able to
100 build an appliance containing the same operating system (Linux version,
101 distro, release etc) as the host OS. Since the host and appliance
102 share many common files such as "/bin/bash" and "/lib/libc.so" there is
103 no reason to ship these files in the appliance. They can simply be
104 read from the host on demand when the appliance is launched. Therefore
105 to save space we just store the names of the host files that we want.
106 There are some files which cannot just be copied from the host in this
108 way. These include configuration files which the host admin might have
109 edited. So along with the list of host files, we also store a skeleton
110 base image which contains these files and the outline directory
111 structure.
112 Therefore the supermin appliance normally consists of at least two
114 control files:
115 hostfiles
117 The list of files that are to be copied from the host. This is a
118 plain text file with one pathname per line. Directories are
119 included in this file.
120 Paths can contain wildcards, which are expanded when the appliance
122 is created, eg:
123 /etc/yum.repos.d/*.repo
125 would copy all of the "*.repo" files into the appliance.
127 Each pathname in the file should start with a "/" character. (In
129 older versions of febootstrap, paths started with "./" and were
130 relative to the root directory, but you should not do that in new
131 files).
132 base.img
134 This uncompressed cpio file contains the skeleton filesystem.
135 Mostly it contains directories and a few configuration files.
136 All paths in the cpio file should be relative to the root directory
138 of the appliance.
139 Note that unlike "hostfiles", paths and directories in the base
141 image don't need to have any relationship to the host filesystem.
142 RECONSTRUCTING THE APPLIANCE
144 The separate tool febootstrap-supermin-helper(8) is used to reconstruct
145 an appliance from the hostfiles and base image files.
146 This program in fact iterates recursively over the files and
148 directories passed to it. A common layout is:
149 supermin.d/
151 supermin.d/base.img
152 supermin.d/extra.img
153 supermin.d/hostfiles
154 and then invoking febootstrap-supermin-helper with just the
156 "supermin.d" directory path as an argument.
157 In this way extra files can be added to the appliance just by creating
159 another cpio file ("extra.img" in the example above) and dropping it
160 into the directory. When the appliance is constructed, the extra files
161 will appear in the appliance.
162 DIRECTORIES BEFORE FILES
164 In order for febootstrap-supermin-helper to run quickly, it does not
166 know how to create directories automatically. Inside hostfiles and the
167 cpio files, directories must be specified before any files that they
168 contain. For example:
169 /usr
171 /usr/sbin
172 /usr/sbin/serviced
173 It is fine to list the same directory name multiple times.
175 LEXICOGRAPHICAL ORDER
177 febootstrap-supermin-helper visits the supermin control files in
179 lexicographical order. Thus in the example above, in the order
180 "base.img" -> "extra.img" -> "hostfiles".
181 This has an important effect: files contained in later cpio files
183 overwrite earlier files, and directories do not need to be specified if
184 they have already been created in earlier control files.
185 EXAMPLE OF CREATING EXTRA CPIO FILE
187 You can create a file like "extra.img" very easily using a shell
189 snippet similar to this one:
190 cd $tmpdir
192 mkdir -p usr/sbin
193 cp /path/to/serviced usr/sbin/
194 echo -e "usr\nusr/sbin\nusr/sbin/serviced" |
195 cpio --quiet -o -H newc > extra.img
196 rm -rf usr
197 Notice how we instruct cpio to create intermediate directories.
199 MINIMIZING THE SUPERMIN APPLIANCE
201 You may want to "minimize" the supermin appliance in order to save time
202 and space when it is instantiated. Typically you might want to remove
203 documentation, info files, man pages and locales. We used to provide a
204 separate tool called "febootstrap-minimize" for this purpose, but it is
205 no longer provided. Instead you can post-process "hostfiles" yourself
206 to remove any files or directories that you don't want (by removing
207 lines from the file). Be careful what you remove because files may be
208 necessary for correct operation of the appliance.
209 For example:
211 < supermin.d/hostfiles \
213 grep -v '^/usr/share/man/' |
214 grep -v '^/usr/share/doc/' |
215 grep -v '^/usr/share/info/' > supermin.d/hostfiles-t
216 mv supermin.d/hostfiles-t supermin.d/hostfiles
217 KERNEL AND KERNEL MODULES
219 Usually the kernel and kernel modules are not included in the supermin
220 appliance. When the appliance is instantiated, the kernel modules from
221 the host kernel are copied in, and it is booted using the host kernel.
222 febootstrap-supermin-helper is able to choose the best host kernel
223 available to boot the appliance.
224 BOOTING AND CACHING THE SUPERMIN APPLIANCE
226 For fastest boot times you should cache the output of febootstrap-
227 supermin-helper. See the libguestfs source file "src/appliance.c" for
228 an example of how this is done.
229 ENFORCING AVAILABILITY OF HOSTFILES
231 febootstrap-supermin-helper builds the appliance by copying in host
232 files as listed in "hostfiles". For this to work those host files must
233 be available. We usually enforce this by adding requirements (eg. RPM
234 "Requires:" lines) on the package that uses the supermin appliance, so
235 that package cannot be installed without pulling in the dependent
236 packages and thus making sure the host files are available.
237
239 febootstrap-supermin-helper(8),
240 <http://people.redhat.com/~rjones/febootstrap/>, guestfs(3),
241 <http://libguestfs.org/>.
242
244 · Richard W.M. Jones <http://people.redhat.com/~rjones/>
245 · Matthew Booth mbooth@redhat.com
247
249 Copyright (C) 2009-2010 Red Hat Inc.
250 This program is free software; you can redistribute it and/or modify it
252 under the terms of the GNU General Public License as published by the
253 Free Software Foundation; either version 2 of the License, or (at your
254 option) any later version.
255 This program is distributed in the hope that it will be useful, but
257 WITHOUT ANY WARRANTY; without even the implied warranty of
258 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
259 General Public License for more details.
260 You should have received a copy of the GNU General Public License along
262 with this program; if not, write to the Free Software Foundation, Inc.,
263 675 Mass Ave, Cambridge, MA 02139, USA.
264febootstrap-3.3 2010-12-07 FEBOOTSTRAP(8)