+=encoding utf8
+
=head1 NAME
-febootstrap - Bootstrap a basic Fedora system (like Debian debootstrap)
+febootstrap - Bootstrapping tool for creating supermin appliances
=head1 SYNOPSIS
- febootstrap [--options] REPO TARGET [MIRROR]
+ febootstrap [-o OUTPUTDIR] --names LIST OF PKGS ...
+ febootstrap [-o OUTPUTDIR] PKG FILE NAMES ...
-=head1 EXAMPLES
+=head1 DESCRIPTION
- febootstrap fedora-10 /tmp/f10
- febootstrap rawhide /tmp/rawhide
- febootstrap rawhide /tmp/rawhide http://mymirror/rawhide/x86_64/os
- febootstrap --groupinstall="Mail Server" fedora-10 /tmp/mailserver
+febootstrap is a tool for building supermin appliances. These are
+tiny appliances (similar to virtual machines), usually around 100KB in
+size, which get fully instantiated on-the-fly in a fraction of a
+second when you need to boot one of them.
+
+Originally "fe" in febootstrap stood for "Fedora", but this tool is
+now distro-independent and can build supermin appliances for several
+popular Linux distros, and adding support for others is reasonably
+easy.
+
+Note that this manual page documents febootstrap 3.x which is a
+complete rewrite and quite different from version 2.x. If you are
+looking for the febootstrap 2.x tools, then this is not the right
+place.
+
+=head2 BASIC OPERATION
+
+There are two modes for using febootstrap. With the I<--names>
+parameter, febootstrap takes a list of package names and creates a
+supermin appliance containing those packages and all dependencies that
+those packages require. In this mode febootstrap usually needs
+network access because it may need to consult package repositories in
+order to work out dependencies and download packages.
+
+Without I<--names>, febootstrap takes a list of packages (ie.
+filenames of locally available packages). This package set must be
+complete and consistent with no dependencies outside the set of
+packages you provide. In this mode febootstrap does not require any
+network access. It works by looking at the package files themselves.
+
+By "package" we mean the RPM, DEB, (etc.) package. A package name
+might be the fully qualified name (eg. C<coreutils-8.5-7.fc14.x86_64>)
+or some abbreviation (eg. C<coreutils>). The precise format of the
+name and what abbreviations are allowed depends on the package
+manager.
+
+The supermin appliance that febootstrap writes consists of two files
+called C<hostfiles> and C<base.img> (see L</SUPERMIN APPLIANCES>
+below). By default these are written to the current directory. If
+you specify the I<-o OUTPUTDIR> option then these files are written to
+the named directory instead (traditionally this directory is named
+C<supermin.d> but you can call it whatever you want).
+
+In all cases febootstrap can only build a supermin appliance which is
+identical in distro, version and architecture to the host. It does
+I<not> do cross-builds.
-=head1 DESCRIPTION
+=head1 OPTIONS
-febootstrap creates a Fedora root filesystem, based on the Fedora
-version specified by I<REPO> under the directory specified by
-I<TARGET>. Optionally I<MIRROR> can point to a local mirror
-(otherwise the public Fedora mirrors are used). I<REPO> names are
-C<fedora-I<VERSION>> (eg. C<fedora-10>) or C<rawhide>.
+=over 4
-febootstrap does I<not> need to be run as root. If for some reason
-you do run it as root, then it works slightly differently and may have
-side effects such as stopping or starting system daemons.
+=item B<--help>
-For more advanced needs, take a look at L<mock(1)>, C<livecd-creator>
-and I<thincrust.net>'s C<appliance-creator>.
+Display brief command line usage, and exit.
-The normal output is a root directory located at I<TARGET> and
-a fakeroot logfile at C<I<TARGET>/fakeroot.log>.
+=item B<--exclude REGEXP>
-=head1 OPTIONS
+After doing dependency resolution, exclude packages which match the
+regular expression.
-=over 4
+This option is only used with I<--names>, and it can be given multiple
+times on the command line.
+
+=item B<--names>
+
+Provide a list of package names, instead of providing packages
+directly. In this mode febootstrap may require network access. See
+L</BASIC OPERATION> above.
-=item B<-i package>
+=item B<--no-warnings>
-=item B<--install=package>
+Don't print warnings about packaging problems.
-=item B<-g "group">
+=item B<-o outputdir>
-=item B<--groupinstall="group">
+Select the output directory where the two supermin appliance files are
+written (C<hostfiles> and C<base.img>). The default directory is the
+current directory. Note that if this files exist already in the
+output directory then they will be overwritten.
-Specify the package or group to install. To list multiple packages or
-groups, you must give multiple C<-i> or C<-g> options. Group names
-can contain spaces, so use quotes where necessary.
+=item B<-v>
-These are passed directly to C<yum install> or C<yum groupinstall>
-commands, and thus any dependencies are also resolved by yum. You can
-also use shell globs and filenames here, as with ordinary yum.
+=item B<--verbose>
-If no packages or groups are given, then we install the C<Core> group
-which is a small working Fedora installation (but by no means
-minimal). Use C<yum groupinfo Core> to list the packages currently in
-the C<Core> group.
+Enable verbose messages.
-=item B<--no-clean>
+=item B<-V>
-Normally febootstrap will clean up the yum repository
-(C</var/cache/yum> inside the image). This contains the downloaded
-RPMs and metadata. However if you give the C<--no-clean> option, then
-the yum repository is left. This is useful if you want to run further
-yum commands inside the filesystem by hand.
+=item B<--version>
+
+Print the package name and version number, and exit.
+
+=item B<--yum-config CONFIGFILE>
+
+(Yum/RPM package handler only). Use an alternate configuration file
+instead of C</etc/yum.conf>. If you also want to specify alternate
+repositories then you can put them in this file directly or add a
+C<reposdir> option to this file. For more information on the file
+format see L<yum.conf(5)>.
=back
-=head1 REPOSITORIES
+=head1 SUPERMIN APPLIANCES
-You can list available repositories by visiting this URL:
+Supermin appliances consist of just enough information to be able to
+build an appliance containing the same operating system (Linux
+version, distro, release etc) as the host OS. Since the host and
+appliance share many common files such as C</bin/bash> and
+C</lib/libc.so> there is no reason to ship these files in the
+appliance. They can simply be read from the host on demand when the
+appliance is launched. Therefore to save space we just store the
+names of the host files that we want.
-L<http://mirrors.fedoraproject.org/mirrorlist?repo=help&arch=i386>
+There are some files which cannot just be copied from the host in this
+way. These include configuration files which the host admin might
+have edited. So along with the list of host files, we also store a
+skeleton base image which contains these files and the outline
+directory structure.
-(If necessary replace C<i386> with your architecture, but it seems
-unlikely that this list will change based on architecture).
+Therefore the supermin appliance normally consists of at least two
+control files:
-=head1 RUNNING EXTRA COMMANDS IN THE ROOT FILESYSTEM
+=over 4
-If you want to run further commands inside the root filesystem, for
-example additional C<yum> installs, then use C<febootstrap-run>. See
-the L<febootstrap-run(8)> manual page for more details.
+=item B<hostfiles>
-You have to be careful about modifying files in the root filesystem
-directly (without using C<febootstrap-run>). It's easy to confuse
-fakeroot and end up with the wrong permissions on files (see FAKEROOT
-LOGFILE below).
+The list of files that are to be copied from the host. This is a
+plain text file with one pathname per line. Directories are included
+in this file.
-C<febootstrap-run> runs the command inside the root filesystem, which
-means it won't normally have access to files outside the root. You
-can use C<FAKECHROOT_EXCLUDE_PATH> environment variable (see
-L<fakechroot(1)>) or copy files into the root first.
+Paths can contain wildcards, which are expanded when the appliance
+is created, eg:
-=head2 FAKEROOT LOGFILE
+ /etc/yum.repos.d/*.repo
-When febootstrap is run as non-root (the normal case) we use fakeroot
-so that yum thinks it is running as root. Fakeroot keeps track of
-"real" file permissions in a log file which is saved into the target
-directory as C<I<TARGET>/fakeroot.log>.
+would copy all of the C<*.repo> files into the appliance.
-This logfile is indexed by inode number, which makes certain
-operations safe and other operations unsafe. For example, deleting
-files is usually safe. Files should be replaced only by doing:
+Each pathname in the file should start with a C</> character. (In
+older versions of febootstrap, paths started with C<./> and were
+relative to the root directory, but you should not do that in new
+files).
- echo updated-content > old-file
+=item B<base.img>
-(since that preserves the original inode). In most cases it's usually
-safest to use C<febootstrap-run>.
+This uncompressed cpio file contains the skeleton filesystem. Mostly
+it contains directories and a few configuration files.
-You can use the fakeroot logfile in a number of ways:
+All paths in the cpio file should be relative to the root directory of
+the appliance.
-=over 4
+Note that unlike C<hostfiles>, paths and directories in the base image
+don't need to have any relationship to the host filesystem.
-=item *
+=back
-Use L<febootstrap-run(8)> to run a command with the faked file
-permissions.
+=head2 RECONSTRUCTING THE APPLIANCE
-=item *
+The separate tool L<febootstrap-supermin-helper(8)> is used to
+reconstruct an appliance from the hostfiles and base image files.
-Generate an initramfs (compressed cpio) file containing the correct
-permissions using the tool C<febootstrap-to-initramfs>.
+This program in fact iterates recursively over the files and
+directories passed to it. A common layout is:
-=item *
+ supermin.d/
+ supermin.d/base.img
+ supermin.d/extra.img
+ supermin.d/hostfiles
-Apply the permissions to the target directory using the forthcoming
-tool C<febootstrap-fix-root> (requires root).
+and then invoking febootstrap-supermin-helper with just the
+C<supermin.d> directory path as an argument.
-=back
+In this way extra files can be added to the appliance just by creating
+another cpio file (C<extra.img> in the example above) and dropping it
+into the directory. When the appliance is constructed, the extra
+files will appear in the appliance.
-=head1 RUNNING FEBOOTSTRAP AS ROOT
+=head3 DIRECTORIES BEFORE FILES
-There is some rudimentary support for running C<febootstrap> as root.
-However it is not well-tested and generally not recommended.
+In order for febootstrap-supermin-helper to run quickly, it does not
+know how to create directories automatically. Inside hostfiles and
+the cpio files, directories must be specified before any files that
+they contain. For example:
-=head1 COMPARISON TO DEBOOTSTRAP
+ /usr
+ /usr/sbin
+ /usr/sbin/serviced
-febootstrap cannot do cross-architecture installs (C<debootstrap
---foreign>). The reason is that C<%pre> and C<%post> scripts cannot
-run. It may be possible to defer running of scriptlets (which is
-basically how debootstrap works), and patches to do this are welcomed.
+It is fine to list the same directory name multiple times.
-febootstrap cannot do 32-on-64 bit installs. The reason is that
-fakeroot and fakechroot do not load the correct preload library. This
-is really a bug in fakeroot/fakechroot, which we think would be easy
-to fix. (debootstrap deals with this case the same as for
-C<--foreign> installs - see previous point).
+=head3 LEXICOGRAPHICAL ORDER
-=head1 OTHER RESTRICTIONS AND BUGS
+febootstrap-supermin-helper visits the supermin control files in
+lexicographical order. Thus in the example above, in the order
+C<base.img> -E<gt> C<extra.img> -E<gt> C<hostfiles>.
-Some C<%post> scripts do not run correctly. The most common case is
-C</sbin/ldconfig>. Since this binary is statically linked, fakeroot
-and fakechroot's LD_PRELOAD hack does not work, so effectively
-ldconfig tries to update the system cache. You will see the following
-error:
+This has an important effect: files contained in later cpio files
+overwrite earlier files, and directories do not need to be specified
+if they have already been created in earlier control files.
- /sbin/ldconfig: Can't create temporary cache file /etc/ld.so.cache~: Permission denied
+=head3 EXAMPLE OF CREATING EXTRA CPIO FILE
-This error is mostly harmless. Just run C</sbin/ldconfig> the first
-time you boot into the newly created Fedora system.
+You can create a file like C<extra.img> very easily using a shell
+snippet similar to this one:
-Another error you will see is with C</usr/sbin/glibc_post_upgrade>
-which is caused for the same reason - this binary is statically
-linked. We have examined what this binary does, and it is not really
-necessary for installs. If it makes you happier, you can run it the
-first time you boot the new system.
+ cd $tmpdir
+ mkdir -p usr/sbin
+ cp /path/to/serviced usr/sbin/
+ echo -e "usr\nusr/sbin\nusr/sbin/serviced" |
+ cpio --quiet -o -H newc > extra.img
+ rm -rf usr
-febootstrap recreates the repository anew each time, and this causes
-yum to download all the RPMs every time. This is very wasteful, and
-we should provide a way to cache the repository.
+Notice how we instruct cpio to create intermediate directories.
-=head1 HOME PAGE
+=head2 MINIMIZING THE SUPERMIN APPLIANCE
-L<http://et.redhat.com/~rjones/febootstrap>
+You may want to "minimize" the supermin appliance in order to save
+time and space when it is instantiated. Typically you might want to
+remove documentation, info files, man pages and locales. We used to
+provide a separate tool called C<febootstrap-minimize> for this
+purpose, but it is no longer provided. Instead you can post-process
+C<hostfiles> yourself to remove any files or directories that you
+don't want (by removing lines from the file). Be careful what you
+remove because files may be necessary for correct operation of the
+appliance.
-=head1 SEE ALSO
+For example:
+
+ < supermin.d/hostfiles \
+ grep -v '^/usr/share/man/' |
+ grep -v '^/usr/share/doc/' |
+ grep -v '^/usr/share/info/' > supermin.d/hostfiles-t
+ mv supermin.d/hostfiles-t supermin.d/hostfiles
+
+=head2 KERNEL AND KERNEL MODULES
+
+Usually the kernel and kernel modules are I<not> included in the
+supermin appliance. When the appliance is instantiated, the kernel
+modules from the host kernel are copied in, and it is booted using the
+host kernel. febootstrap-supermin-helper is able to choose the best
+host kernel available to boot the appliance.
-L<febootstrap-to-initramfs(8)>,
-L<febootstrap-minimize(8)>,
-L<febootstrap-run(8)>,
-L<fakeroot(1)>,
-L<fakechroot(1)>,
-L<yum(8)>,
-L<rpm(8)>.
+=head2 BOOTING AND CACHING THE SUPERMIN APPLIANCE
-=head1 ALTERNATIVES
+For fastest boot times you should cache the output of
+febootstrap-supermin-helper. See the libguestfs source file
+C<src/appliance.c> for an example of how this is done.
+
+=head2 ENFORCING AVAILABILITY OF HOSTFILES
+
+febootstrap-supermin-helper builds the appliance by copying in host
+files as listed in C<hostfiles>. For this to work those host files
+must be available. We usually enforce this by adding requirements
+(eg. RPM C<Requires:> lines) on the package that uses the supermin
+appliance, so that package cannot be installed without pulling in the
+dependent packages and thus making sure the host files are available.
+
+=head1 SEE ALSO
-L<mock(1)>,
-L<http://fedoraproject.org/wiki/FedoraLiveCD/LiveCDHowTo>,
-L<http://thincrust.net/>,
-L<debootstrap(8)>,
-C<ubuntu-vm-builder>.
+L<febootstrap-supermin-helper(8)>,
+L<http://people.redhat.com/~rjones/febootstrap/>,
+L<guestfs(3)>,
+L<http://libguestfs.org/>.
=head1 AUTHORS
-Richard W.M. Jones <rjones @ redhat . com>
+=over 4
+
+=item *
+
+Richard W.M. Jones L<http://people.redhat.com/~rjones/>
+
+=item *
+
+Matthew Booth L<mbooth@redhat.com>
+
+=back
=head1 COPYRIGHT
-(C) Copyright 2009 Red Hat Inc.,
-L<http://et.redhat.com/~rjones/febootstrap>.
+Copyright (C) 2009-2010 Red Hat Inc.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
git.annexia.org / febootstrap.git / blobdiff