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> (it is common for users to add
  52 more files).  By default these are written to the current directory.
  53 If you specify the I<-o OUTPUTDIR> option then these files are written
  54 to 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 =head2 MINIMIZING THE SUPERMIN APPLIANCE
  62
  63 You may want to "minimize" the supermin appliance in order to save
  64 time and space when it is instantiated.  Typically you might want to
  65 remove documentation, info files, man pages and locales.  We used to
  66 provide a separate tool called C<febootstrap-minimize> for this
  67 purpose, but it is no longer provided.  Instead you can post-process
  68 C<hostfiles> yourself to remove any files or directories that you
  69 don't want (by removing lines from the file).  Be careful what you
  70 remove because files may be necessary for correct operation of the
  71 appliance.
  72
  73 =head2 KERNEL AND KERNEL MODULES
  74
  75 Usually the kernel and kernel modules are I<not> included in the
  76 supermin appliance.  When the appliance is instantiated, the kernel
  77 modules from the host kernel are copied in, and it is booted using the
  78 host kernel.
  79
  80 =head2 BOOTING AND CACHING THE SUPERMIN APPLIANCE
  81
  82 To instantiate and boot the supermin appliance you need to use the
  83 separate tool L<febootstrap-supermin-helper(8)>.  For fastest boot
  84 times you should cache the output of that tool.  See the libguestfs
  85 source file C<src/appliance.c> for an example of how this is done.
  86
  87 =head2 ENFORCING AVAILABILITY OF HOSTFILES
  88
  89 L<febootstrap-supermin-helper(8)> builds the appliance by copying in
  90 host files as listed in C<hostfiles>.  For this to work those host
  91 files must be available.  We usually enforce this by adding
  92 requirements (eg. RPM C<Requires:> lines) on the package that uses the
  93 supermin appliance, so that package cannot be installed without
  94 pulling in the dependent packages and thus making sure the host files
  95 are available.
  96
  97 =head1 OPTIONS
  98
  99 =over 4
 100
 101 =item B<--help>
 102
 103 Display brief command line usage, and exit.
 104
 105 =item B<--exclude REGEXP>
 106
 107 After doing dependency resolution, exclude packages which match the
 108 regular expression.
 109
 110 This option is only used with I<--names>, and it can be given multiple
 111 times on the command line.
 112
 113 =item B<--names>
 114
 115 Provide a list of package names, instead of providing packages
 116 directly.  In this mode febootstrap may require network access.  See
 117 L</BASIC OPERATION> above.
 118
 119 =item B<--no-warnings>
 120
 121 Don't print warnings about packaging problems.
 122
 123 =item B<-o outputdir>
 124
 125 Select the output directory where the two supermin appliance files are
 126 written (C<hostfiles> and C<base.img>).  The default directory is the
 127 current directory.  Note that if this files exist already in the
 128 output directory then they will be overwritten.
 129
 130 =item B<-v>
 131
 132 =item B<--verbose>
 133
 134 Enable verbose messages.
 135
 136 =item B<-V>
 137
 138 =item B<--version>
 139
 140 Print the package name and version number, and exit.
 141
 142 =back
 143
 144 =head1 SEE ALSO
 145
 146 L<febootstrap-supermin-helper(8)>,
 147 L<http://people.redhat.com/~rjones/febootstrap/>,
 148 L<guestfs(3)>,
 149 L<http://libguestfs.org/>.
 150
 151 =head1 AUTHORS
 152
 153 =over 4
 154
 155 =item *
 156
 157 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 158
 159 =item *
 160
 161 Matthew Booth L<mbooth@redhat.com>
 162
 163 =back
 164
 165 =head1 COPYRIGHT
 166
 167 Copyright (C) 2009-2010 Red Hat Inc.
 168
 169 This program is free software; you can redistribute it and/or modify
 170 it under the terms of the GNU General Public License as published by
 171 the Free Software Foundation; either version 2 of the License, or
 172 (at your option) any later version.
 173
 174 This program is distributed in the hope that it will be useful,
 175 but WITHOUT ANY WARRANTY; without even the implied warranty of
 176 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 177 GNU General Public License for more details.
 178
 179 You should have received a copy of the GNU General Public License
 180 along with this program; if not, write to the Free Software
 181 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.