From 1d6f1a9cb0fb1be8467d8e2c0fbda1b7eca70c66 Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Thu, 1 Sep 2011 14:08:50 +0100 Subject: Move febootstrap into src/ subdirectory. Now we have src/ for febootstrap and helper/ for febootstrap-supermin-helper. --- febootstrap.pod | 315 -------------------------------------------------------- 1 file changed, 315 deletions(-) delete mode 100644 febootstrap.pod (limited to 'febootstrap.pod') diff --git a/febootstrap.pod b/febootstrap.pod deleted file mode 100644 index ac97f48..0000000 --- a/febootstrap.pod +++ /dev/null @@ -1,315 +0,0 @@ -=encoding utf8 - -=head1 NAME - -febootstrap - Bootstrapping tool for creating supermin appliances - -=head1 SYNOPSIS - - febootstrap [-o OUTPUTDIR] --names LIST OF PKGS ... - febootstrap [-o OUTPUTDIR] PKG FILE NAMES ... - -=head1 DESCRIPTION - -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) -or some abbreviation (eg. C). 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 and C (see L -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 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 do cross-builds. - -=head1 OPTIONS - -=over 4 - -=item B<--help> - -Display brief command line usage, and exit. - -=item B<--exclude REGEXP> - -After doing dependency resolution, exclude packages which match the -regular expression. - -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 above. - -=item B<--no-warnings> - -Don't print warnings about packaging problems. - -=item B<-o outputdir> - -Select the output directory where the two supermin appliance files are -written (C and C). The default directory is the -current directory. Note that if this files exist already in the -output directory then they will be overwritten. - -=item B<--save-temps> - -Don't remove temporary files and directories on exit. This is useful -for debugging. - -=item B<-v> - -=item B<--verbose> - -Enable verbose messages. - -=item B<-V> - -=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. If you also want to specify alternate -repositories then you can put them in this file directly or add a -C option to this file. For more information on the file -format see L. - -=back - -=head1 SUPERMIN APPLIANCES - -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 and -C 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. - -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. - -Therefore the supermin appliance normally consists of at least two -control files: - -=over 4 - -=item B - -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. - -Paths can contain wildcards, which are expanded when the appliance -is created, eg: - - /etc/yum.repos.d/*.repo - -would copy all of the C<*.repo> files into the appliance. - -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). - -=item B - -This uncompressed cpio file contains the skeleton filesystem. Mostly -it contains directories and a few configuration files. - -All paths in the cpio file should be relative to the root directory of -the appliance. - -Note that unlike C, paths and directories in the base image -don't need to have any relationship to the host filesystem. - -=back - -=head2 RECONSTRUCTING THE APPLIANCE - -The separate tool L is used to -reconstruct an appliance from the hostfiles and base image files. - -This program in fact iterates recursively over the files and -directories passed to it. A common layout is: - - supermin.d/ - supermin.d/base.img - supermin.d/extra.img - supermin.d/hostfiles - -and then invoking febootstrap-supermin-helper with just the -C directory path as an argument. - -In this way extra files can be added to the appliance just by creating -another cpio file (C in the example above) and dropping it -into the directory. When the appliance is constructed, the extra -files will appear in the appliance. - -=head3 DIRECTORIES BEFORE FILES - -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: - - /usr - /usr/sbin - /usr/sbin/serviced - -It is fine to list the same directory name multiple times. - -=head3 LEXICOGRAPHICAL ORDER - -febootstrap-supermin-helper visits the supermin control files in -lexicographical order. Thus in the example above, in the order -C -E C -E C. - -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. - -=head3 EXAMPLE OF CREATING EXTRA CPIO FILE - -You can create a file like C very easily using a shell -snippet similar to this one: - - 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 - -Notice how we instruct cpio to create intermediate directories. - -=head2 MINIMIZING THE SUPERMIN APPLIANCE - -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 for this -purpose, but it is no longer provided. Instead you can post-process -C 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. - -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 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. Users can override this by setting -environment variables (see L). - -=head2 BOOTING AND CACHING THE SUPERMIN APPLIANCE - -For fastest boot times you should cache the output of -febootstrap-supermin-helper. See the libguestfs source file -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. For this to work those host files -must be available. We usually enforce this by adding requirements -(eg. RPM C 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, -L, -L, -L. - -=head1 AUTHORS - -=over 4 - -=item * - -Richard W.M. Jones L - -=item * - -Matthew Booth L - -=back - -=head1 COPYRIGHT - -Copyright (C) 2009-2011 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 -the Free Software Foundation; either version 2 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program; if not, write to the Free Software -Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -- cgit