X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=febootstrap.pod;h=ac97f48cbdaa3d902b2df48bface54cdbb254059;hb=57b3004bde579b986523c43e3a0e6693fd49dd21;hp=a8f73ffceee80f78f9c6684fc302c72406a6e32d;hpb=467d77a9af3dbb1a4bcfbb9c7f97c8e300d6dca0;p=febootstrap.git diff --git a/febootstrap.pod b/febootstrap.pod index a8f73ff..ac97f48 100644 --- a/febootstrap.pod +++ b/febootstrap.pod @@ -1,214 +1,304 @@ +=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) +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 DESCRIPTION +=head1 OPTIONS -febootstrap creates a Fedora root filesystem, based on the Fedora -version specified by I under the directory specified by -I. Optionally I can point to a local mirror -(otherwise the public Fedora mirrors are used). I names are -C> (eg. C) or C. +=over 4 -febootstrap does I 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, C -and I's C. +Display brief command line usage, and exit. -The normal output is a root directory located at I and -a fakeroot logfile at C/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 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 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. -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<--save-temps> -These are passed directly to C or C -commands, and thus any dependencies are also resolved by yum. You can -also use shell globs and filenames here, as with ordinary yum. +Don't remove temporary files and directories on exit. This is useful +for debugging. -If no packages or groups are given, then we install the C group -which is a small working Fedora installation (but by no means -minimal). Use C to list the packages currently in -the C group. +=item B<-v> -=item B<--no-clean> +=item B<--verbose> -Normally febootstrap will clean up the yum repository -(C 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. +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 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 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. -L +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 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 installs, then use C. See -the L manual page for more details. +=item B -You have to be careful about modifying files in the root filesystem -directly (without using C). 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 runs the command inside the root filesystem, which -means it won't normally have access to files outside the root. You -can use C environment variable (see -L) 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/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 -(since that preserves the original inode). +This uncompressed cpio file contains the skeleton filesystem. Mostly +it contains directories and a few configuration files. -Deleting files and then creating new ones (even with a different name) -is usually unsafe, because the new files might reuse inodes claimed by -the old files, and so appear with peculiar permissions -(eg. unreadable, or as a symbolic link). (XXX We need an -C utility to automate installing new files safely -into a filesystem). +All paths in the cpio file should be relative to the root directory of +the appliance. -In most cases it's usually safest to use C. +Note that unlike C, paths and directories in the base image +don't need to have any relationship to the host filesystem. -You can use the fakeroot logfile in a number of ways: +=back -=over 4 +=head2 RECONSTRUCTING THE APPLIANCE -=item * +The separate tool L is used to +reconstruct an appliance from the hostfiles and base image files. -Use L to run a command with the faked file -permissions. +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 -Generate an initramfs (compressed cpio) file containing the correct -permissions using the tool C. +and then invoking febootstrap-supermin-helper with just the +C directory path as an argument. -=item * +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. -Apply the permissions to the target directory using the forthcoming -tool C (requires root). +=head3 DIRECTORIES BEFORE FILES -=back +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 RUNNING FEBOOTSTRAP AS ROOT + /usr + /usr/sbin + /usr/sbin/serviced -There is some rudimentary support for running C as root. -However it is not well-tested and generally not recommended. +It is fine to list the same directory name multiple times. -=head1 COMPARISON TO DEBOOTSTRAP +=head3 LEXICOGRAPHICAL ORDER -febootstrap cannot do cross-architecture installs (C). 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. +febootstrap-supermin-helper visits the supermin control files in +lexicographical order. Thus in the example above, in the order +C -E C -E C. -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). +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. -=head1 OTHER RESTRICTIONS AND BUGS +=head3 EXAMPLE OF CREATING EXTRA CPIO FILE -The following programs are not run during C<%post> scriptlets (because -they are all statically linked, and fakechroot cannot run statically -linked programs). +You can create a file like C very easily using a shell +snippet similar to this one: -=over 4 + 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 -=item C (from many packages) +Notice how we instruct cpio to create intermediate directories. -=item C (from C) +=head2 MINIMIZING THE SUPERMIN APPLIANCE -=item C (from C) +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. -=item C (from C) +For example: -=back + < 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 -If you wish, you can run them the first time you boot into the new -machine. +=head2 KERNEL AND KERNEL MODULES -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. +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. -=head1 HOME PAGE +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). -L +=head2 BOOTING AND CACHING THE SUPERMIN APPLIANCE -=head1 SEE ALSO +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 -L, -L, -L, -L, -L, -L, -L. +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 ALTERNATIVES +=head1 SEE ALSO -L, -L, -L, -L, -C. +L, +L, +L, +L. =head1 AUTHORS -Richard W.M. Jones +=over 4 + +=item * + +Richard W.M. Jones L + +=item * + +Matthew Booth L + +=back =head1 COPYRIGHT -(C) Copyright 2009 Red Hat Inc., -L. +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