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 --packager-config CONFIGFILE
84 Set the configuration file for the package manager. This allows
85 you to specify alternate software repositories.
86 For ArchLinux, this sets the pacman configuration file (default
88 "/etc/pacman.conf"). See pacman.conf(5).
89 For Yum/RPM distributions, this sets the yum configuration file
91 (default "/etc/yum.conf"). See yum.conf(5).
92 --save-temps
94 Don't remove temporary files and directories on exit. This is
95 useful for debugging.
96 --use-installed
98 If packages are already installed, use the contents (from the local
99 filesystem) instead of downloading them.
100 Note that this can cause malformed appliances if local files have
102 been changed from what was originally in the package. This is
103 particularly a problem for configuration files.
104 However this option is useful in some controlled situations: for
106 example when using febootstrap inside a freshly installed chroot.
107 -v
109 --verbose
110 Enable verbose messages.
111 -V
113 --version
114 Print the package name and version number, and exit.
115 --yum-config CONFIGFILE
117 This is a deprecated alias for --packager-config CONFIGFILE.
118
120 Supermin appliances consist of just enough information to be able to
121 build an appliance containing the same operating system (Linux version,
122 distro, release etc) as the host OS. Since the host and appliance
123 share many common files such as "/bin/bash" and "/lib/libc.so" there is
124 no reason to ship these files in the appliance. They can simply be
125 read from the host on demand when the appliance is launched. Therefore
126 to save space we just store the names of the host files that we want.
127 There are some files which cannot just be copied from the host in this
129 way. These include configuration files which the host admin might have
130 edited. So along with the list of host files, we also store a skeleton
131 base image which contains these files and the outline directory
132 structure.
133 Therefore the supermin appliance normally consists of at least two
135 control files:
136 hostfiles
138 The list of files that are to be copied from the host. This is a
139 plain text file with one pathname per line. Directories are
140 included in this file.
141 Paths can contain wildcards, which are expanded when the appliance
143 is created, eg:
144 /etc/yum.repos.d/*.repo
146 would copy all of the "*.repo" files into the appliance.
148 Each pathname in the file should start with a "/" character. (In
150 older versions of febootstrap, paths started with "./" and were
151 relative to the root directory, but you should not do that in new
152 files).
153 base.img
155 This uncompressed cpio file contains the skeleton filesystem.
156 Mostly it contains directories and a few configuration files.
157 All paths in the cpio file should be relative to the root directory
159 of the appliance.
160 Note that unlike "hostfiles", paths and directories in the base
162 image don't need to have any relationship to the host filesystem.
163 RECONSTRUCTING THE APPLIANCE
165 The separate tool febootstrap-supermin-helper(8) is used to reconstruct
166 an appliance from the hostfiles and base image files.
167 This program in fact iterates recursively over the files and
169 directories passed to it. A common layout is:
170 supermin.d/
172 supermin.d/base.img
173 supermin.d/extra.img
174 supermin.d/hostfiles
175 and then invoking febootstrap-supermin-helper with just the
177 "supermin.d" directory path as an argument.
178 In this way extra files can be added to the appliance just by creating
180 another cpio file ("extra.img" in the example above) and dropping it
181 into the directory. When the appliance is constructed, the extra files
182 will appear in the appliance.
183 DIRECTORIES BEFORE FILES
185 In order for febootstrap-supermin-helper to run quickly, it does not
187 know how to create directories automatically. Inside hostfiles and the
188 cpio files, directories must be specified before any files that they
189 contain. For example:
190 /usr
192 /usr/sbin
193 /usr/sbin/serviced
194 It is fine to list the same directory name multiple times.
196 LEXICOGRAPHICAL ORDER
198 febootstrap-supermin-helper visits the supermin control files in
200 lexicographical order. Thus in the example above, in the order
201 "base.img" -> "extra.img" -> "hostfiles".
202 This has an important effect: files contained in later cpio files
204 overwrite earlier files, and directories do not need to be specified if
205 they have already been created in earlier control files.
206 EXAMPLE OF CREATING EXTRA CPIO FILE
208 You can create a file like "extra.img" very easily using a shell
210 snippet similar to this one:
211 cd $tmpdir
213 mkdir -p usr/sbin
214 cp /path/to/serviced usr/sbin/
215 echo -e "usr\nusr/sbin\nusr/sbin/serviced" |
216 cpio --quiet -o -H newc > extra.img
217 rm -rf usr
218 Notice how we instruct cpio to create intermediate directories.
220 MINIMIZING THE SUPERMIN APPLIANCE
222 You may want to "minimize" the supermin appliance in order to save time
223 and space when it is instantiated. Typically you might want to remove
224 documentation, info files, man pages and locales. We used to provide a
225 separate tool called "febootstrap-minimize" for this purpose, but it is
226 no longer provided. Instead you can post-process "hostfiles" yourself
227 to remove any files or directories that you don't want (by removing
228 lines from the file). Be careful what you remove because files may be
229 necessary for correct operation of the appliance.
230 For example:
232 < supermin.d/hostfiles \
234 grep -v '^/usr/share/man/' |
235 grep -v '^/usr/share/doc/' |
236 grep -v '^/usr/share/info/' > supermin.d/hostfiles-t
237 mv supermin.d/hostfiles-t supermin.d/hostfiles
238 KERNEL AND KERNEL MODULES
240 Usually the kernel and kernel modules are not included in the supermin
241 appliance. When the appliance is instantiated, the kernel modules from
242 the host kernel are copied in, and it is booted using the host kernel.
243 febootstrap-supermin-helper is able to choose the best host kernel
245 available to boot the appliance. Users can override this by setting
246 environment variables (see febootstrap-supermin-helper(8)).
247 BOOTING AND CACHING THE SUPERMIN APPLIANCE
249 For fastest boot times you should cache the output of febootstrap-
250 supermin-helper. See the libguestfs source file "src/appliance.c" for
251 an example of how this is done.
252 ENFORCING AVAILABILITY OF HOSTFILES
254 febootstrap-supermin-helper builds the appliance by copying in host
255 files as listed in "hostfiles". For this to work those host files must
256 be available. We usually enforce this by adding requirements (eg. RPM
257 "Requires:" lines) on the package that uses the supermin appliance, so
258 that package cannot be installed without pulling in the dependent
259 packages and thus making sure the host files are available.
260
262 febootstrap-supermin-helper(8),
263 <http://people.redhat.com/~rjones/febootstrap/>, guestfs(3),
264 <http://libguestfs.org/>.
265
267 · Richard W.M. Jones <http://people.redhat.com/~rjones/>
268 · Matthew Booth mbooth@redhat.com
270
272 Copyright (C) 2009-2011 Red Hat Inc.
273 This program is free software; you can redistribute it and/or modify it
275 under the terms of the GNU General Public License as published by the
276 Free Software Foundation; either version 2 of the License, or (at your
277 option) any later version.
278 This program is distributed in the hope that it will be useful, but
280 WITHOUT ANY WARRANTY; without even the implied warranty of
281 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
282 General Public License for more details.
283 You should have received a copy of the GNU General Public License along
285 with this program; if not, write to the Free Software Foundation, Inc.,
286 675 Mass Ave, Cambridge, MA 02139, USA.
287febootstrap-3.20 2012-12-22 FEBOOTSTRAP(8)