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<-v>
  95
  96 =item B<--verbose>
  97
  98 Enable verbose messages.
  99
 100 =item B<-V>
 101
 102 =item B<--version>
 103
 104 Print the package name and version number, and exit.
 105
 106 =item B<--yum-config CONFIGFILE>
 107
 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)>.
 113
 114 =back
 115
 116 =head1 SUPERMIN APPLIANCES
 117
 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.
 126
 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
 131 directory structure.
 132
 133 Therefore the supermin appliance normally consists of at least two
 134 control files:
 135
 136 =over 4
 137
 138 =item B<hostfiles>
 139
 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
 142 in this file.
 143
 144 Paths can contain wildcards, which are expanded when the appliance
 145 is created, eg:
 146
 147  /etc/yum.repos.d/*.repo
 148
 149 would copy all of the C<*.repo> files into the appliance.
 150
 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
 154 files).
 155
 156 =item B<base.img>
 157
 158 This uncompressed cpio file contains the skeleton filesystem.  Mostly
 159 it contains directories and a few configuration files.
 160
 161 All paths in the cpio file should be relative to the root directory of
 162 the appliance.
 163
 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.
 166
 167 =back
 168
 169 =head2 RECONSTRUCTING THE APPLIANCE
 170
 171 The separate tool L<febootstrap-supermin-helper(8)> is used to
 172 reconstruct an appliance from the hostfiles and base image files.
 173
 174 This program in fact iterates recursively over the files and
 175 directories passed to it.  A common layout is:
 176
 177  supermin.d/
 178  supermin.d/base.img
 179  supermin.d/extra.img
 180  supermin.d/hostfiles
 181
 182 and then invoking febootstrap-supermin-helper with just the
 183 C<supermin.d> directory path as an argument.
 184
 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.
 189
 190 =head3 DIRECTORIES BEFORE FILES
 191
 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:
 196
 197  /usr
 198  /usr/sbin
 199  /usr/sbin/serviced
 200
 201 It is fine to list the same directory name multiple times.
 202
 203 =head3 LEXICOGRAPHICAL ORDER
 204
 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>.
 208
 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.
 212
 213 =head3 EXAMPLE OF CREATING EXTRA CPIO FILE
 214
 215 You can create a file like C<extra.img> very easily using a shell
 216 snippet similar to this one:
 217
 218  cd $tmpdir
 219  mkdir -p usr/sbin
 220  cp /path/to/serviced usr/sbin/
 221  echo -e "usr\nusr/sbin\nusr/sbin/serviced" |
 222    cpio --quiet -o -H newc > extra.img
 223  rm -rf usr
 224
 225 Notice how we instruct cpio to create intermediate directories.
 226
 227 =head2 MINIMIZING THE SUPERMIN APPLIANCE
 228
 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
 237 appliance.
 238
 239 For example:
 240
 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
 246
 247 =head2 KERNEL AND KERNEL MODULES
 248
 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
 252 host kernel.  febootstrap-supermin-helper is able to choose the best
 253 host kernel available to boot the appliance.
 254
 255 =head2 BOOTING AND CACHING THE SUPERMIN APPLIANCE
 256
 257 For fastest boot times you should cache the output of
 258 febootstrap-supermin-helper.  See the libguestfs source file
 259 C<src/appliance.c> for an example of how this is done.
 260
 261 =head2 ENFORCING AVAILABILITY OF HOSTFILES
 262
 263 febootstrap-supermin-helper builds the appliance by copying in host
 264 files as listed in C<hostfiles>.  For this to work those host files
 265 must be available.  We usually enforce this by adding requirements
 266 (eg. RPM C<Requires:> lines) on the package that uses the supermin
 267 appliance, so that package cannot be installed without pulling in the
 268 dependent packages and thus making sure the host files are available.
 269
 270 =head1 SEE ALSO
 271
 272 L<febootstrap-supermin-helper(8)>,
 273 L<http://people.redhat.com/~rjones/febootstrap/>,
 274 L<guestfs(3)>,
 275 L<http://libguestfs.org/>.
 276
 277 =head1 AUTHORS
 278
 279 =over 4
 280
 281 =item *
 282
 283 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 284
 285 =item *
 286
 287 Matthew Booth L<mbooth@redhat.com>
 288
 289 =back
 290
 291 =head1 COPYRIGHT
 292
 293 Copyright (C) 2009-2010 Red Hat Inc.
 294
 295 This program is free software; you can redistribute it and/or modify
 296 it under the terms of the GNU General Public License as published by
 297 the Free Software Foundation; either version 2 of the License, or
 298 (at your option) any later version.
 299
 300 This program is distributed in the hope that it will be useful,
 301 but WITHOUT ANY WARRANTY; without even the implied warranty of
 302 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 303 GNU General Public License for more details.
 304
 305 You should have received a copy of the GNU General Public License
 306 along with this program; if not, write to the Free Software
 307 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.