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