febootstrap.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 febootstrap - Bootstrapping tool for creating supermin appliances
   6
   7 =head1 SYNOPSIS
   8
   9  febootstrap [-o OUTPUTDIR] --names LIST OF PKGS ...
  10  febootstrap [-o OUTPUTDIR] PKG FILE NAMES ...
  11
  12 =head1 DESCRIPTION
  13
  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.
  18
  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
  22 easy.
  23
  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
  27 place.
  28
  29 =head2 BASIC OPERATION
  30
  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.
  37
  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.
  43
  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
  48 manager.
  49
  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).
  56
  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.
  60
  61 =head1 OPTIONS
  62
  63 =over 4
  64
  65 =item B<--help>
  66
  67 Display brief command line usage, and exit.
  68
  69 =item B<--exclude REGEXP>
  70
  71 After doing dependency resolution, exclude packages which match the
  72 regular expression.
  73
  74 This option is only used with I<--names>, and it can be given multiple
  75 times on the command line.
  76
  77 =item B<--names>
  78
  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.
  82
  83 =item B<--no-warnings>
  84
  85 Don't print warnings about packaging problems.
  86
  87 =item B<-o outputdir>
  88
  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.
  93
  94 =item B<--save-temps>
  95
  96 Don't remove temporary files and directories on exit.  This is useful
  97 for debugging.
  98
  99 =item B<-v>
 100
 101 =item B<--verbose>
 102
 103 Enable verbose messages.
 104
 105 =item B<-V>
 106
 107 =item B<--version>
 108
 109 Print the package name and version number, and exit.
 110
 111 =item B<--yum-config CONFIGFILE>
 112
 113 (Yum/RPM package handler only).  Use an alternate configuration file
 114 instead of C</etc/yum.conf>.  If you also want to specify alternate
 115 repositories then you can put them in this file directly or add a
 116 C<reposdir> option to this file.  For more information on the file
 117 format see L<yum.conf(5)>.
 118
 119 =back
 120
 121 =head1 SUPERMIN APPLIANCES
 122
 123 Supermin appliances consist of just enough information to be able to
 124 build an appliance containing the same operating system (Linux
 125 version, distro, release etc) as the host OS.  Since the host and
 126 appliance share many common files such as C</bin/bash> and
 127 C</lib/libc.so> there is no reason to ship these files in the
 128 appliance.  They can simply be read from the host on demand when the
 129 appliance is launched.  Therefore to save space we just store the
 130 names of the host files that we want.
 131
 132 There are some files which cannot just be copied from the host in this
 133 way.  These include configuration files which the host admin might
 134 have edited.  So along with the list of host files, we also store a
 135 skeleton base image which contains these files and the outline
 136 directory structure.
 137
 138 Therefore the supermin appliance normally consists of at least two
 139 control files:
 140
 141 =over 4
 142
 143 =item B<hostfiles>
 144
 145 The list of files that are to be copied from the host.  This is a
 146 plain text file with one pathname per line.  Directories are included
 147 in this file.
 148
 149 Paths can contain wildcards, which are expanded when the appliance
 150 is created, eg:
 151
 152  /etc/yum.repos.d/*.repo
 153
 154 would copy all of the C<*.repo> files into the appliance.
 155
 156 Each pathname in the file should start with a C</> character.  (In
 157 older versions of febootstrap, paths started with C<./> and were
 158 relative to the root directory, but you should not do that in new
 159 files).
 160
 161 =item B<base.img>
 162
 163 This uncompressed cpio file contains the skeleton filesystem.  Mostly
 164 it contains directories and a few configuration files.
 165
 166 All paths in the cpio file should be relative to the root directory of
 167 the appliance.
 168
 169 Note that unlike C<hostfiles>, paths and directories in the base image
 170 don't need to have any relationship to the host filesystem.
 171
 172 =back
 173
 174 =head2 RECONSTRUCTING THE APPLIANCE
 175
 176 The separate tool L<febootstrap-supermin-helper(8)> is used to
 177 reconstruct an appliance from the hostfiles and base image files.
 178
 179 This program in fact iterates recursively over the files and
 180 directories passed to it.  A common layout is:
 181
 182  supermin.d/
 183  supermin.d/base.img
 184  supermin.d/extra.img
 185  supermin.d/hostfiles
 186
 187 and then invoking febootstrap-supermin-helper with just the
 188 C<supermin.d> directory path as an argument.
 189
 190 In this way extra files can be added to the appliance just by creating
 191 another cpio file (C<extra.img> in the example above) and dropping it
 192 into the directory.  When the appliance is constructed, the extra
 193 files will appear in the appliance.
 194
 195 =head3 DIRECTORIES BEFORE FILES
 196
 197 In order for febootstrap-supermin-helper to run quickly, it does not
 198 know how to create directories automatically.  Inside hostfiles and
 199 the cpio files, directories must be specified before any files that
 200 they contain.  For example:
 201
 202  /usr
 203  /usr/sbin
 204  /usr/sbin/serviced
 205
 206 It is fine to list the same directory name multiple times.
 207
 208 =head3 LEXICOGRAPHICAL ORDER
 209
 210 febootstrap-supermin-helper visits the supermin control files in
 211 lexicographical order.  Thus in the example above, in the order
 212 C<base.img> -E<gt> C<extra.img> -E<gt> C<hostfiles>.
 213
 214 This has an important effect: files contained in later cpio files
 215 overwrite earlier files, and directories do not need to be specified
 216 if they have already been created in earlier control files.
 217
 218 =head3 EXAMPLE OF CREATING EXTRA CPIO FILE
 219
 220 You can create a file like C<extra.img> very easily using a shell
 221 snippet similar to this one:
 222
 223  cd $tmpdir
 224  mkdir -p usr/sbin
 225  cp /path/to/serviced usr/sbin/
 226  echo -e "usr\nusr/sbin\nusr/sbin/serviced" |
 227    cpio --quiet -o -H newc > extra.img
 228  rm -rf usr
 229
 230 Notice how we instruct cpio to create intermediate directories.
 231
 232 =head2 MINIMIZING THE SUPERMIN APPLIANCE
 233
 234 You may want to "minimize" the supermin appliance in order to save
 235 time and space when it is instantiated.  Typically you might want to
 236 remove documentation, info files, man pages and locales.  We used to
 237 provide a separate tool called C<febootstrap-minimize> for this
 238 purpose, but it is no longer provided.  Instead you can post-process
 239 C<hostfiles> yourself to remove any files or directories that you
 240 don't want (by removing lines from the file).  Be careful what you
 241 remove because files may be necessary for correct operation of the
 242 appliance.
 243
 244 For example:
 245
 246  < supermin.d/hostfiles \
 247  grep -v '^/usr/share/man/' |
 248  grep -v '^/usr/share/doc/' |
 249  grep -v '^/usr/share/info/' > supermin.d/hostfiles-t
 250  mv supermin.d/hostfiles-t supermin.d/hostfiles
 251
 252 =head2 KERNEL AND KERNEL MODULES
 253
 254 Usually the kernel and kernel modules are I<not> included in the
 255 supermin appliance.  When the appliance is instantiated, the kernel
 256 modules from the host kernel are copied in, and it is booted using the
 257 host kernel.
 258
 259 febootstrap-supermin-helper is able to choose the best host kernel
 260 available to boot the appliance.  Users can override this by setting
 261 environment variables (see L<febootstrap-supermin-helper(8)>).
 262
 263 =head2 BOOTING AND CACHING THE SUPERMIN APPLIANCE
 264
 265 For fastest boot times you should cache the output of
 266 febootstrap-supermin-helper.  See the libguestfs source file
 267 C<src/appliance.c> for an example of how this is done.
 268
 269 =head2 ENFORCING AVAILABILITY OF HOSTFILES
 270
 271 febootstrap-supermin-helper builds the appliance by copying in host
 272 files as listed in C<hostfiles>.  For this to work those host files
 273 must be available.  We usually enforce this by adding requirements
 274 (eg. RPM C<Requires:> lines) on the package that uses the supermin
 275 appliance, so that package cannot be installed without pulling in the
 276 dependent packages and thus making sure the host files are available.
 277
 278 =head1 SEE ALSO
 279
 280 L<febootstrap-supermin-helper(8)>,
 281 L<http://people.redhat.com/~rjones/febootstrap/>,
 282 L<guestfs(3)>,
 283 L<http://libguestfs.org/>.
 284
 285 =head1 AUTHORS
 286
 287 =over 4
 288
 289 =item *
 290
 291 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 292
 293 =item *
 294
 295 Matthew Booth L<mbooth@redhat.com>
 296
 297 =back
 298
 299 =head1 COPYRIGHT
 300
 301 Copyright (C) 2009-2011 Red Hat Inc.
 302
 303 This program is free software; you can redistribute it and/or modify
 304 it under the terms of the GNU General Public License as published by
 305 the Free Software Foundation; either version 2 of the License, or
 306 (at your option) any later version.
 307
 308 This program is distributed in the hope that it will be useful,
 309 but WITHOUT ANY WARRANTY; without even the implied warranty of
 310 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 311 GNU General Public License for more details.
 312
 313 You should have received a copy of the GNU General Public License
 314 along with this program; if not, write to the Free Software
 315 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.