X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=febootstrap.pod;h=6620976bf872531441074d5e8d901001e7634dc6;hb=cae4aad47dfa49a541a5df463ce35c05e4678de4;hp=dfc93fc52930588c37ef2533b765b16e1f3e9822;hpb=b5e1aa25a0755d9175e21371365879c2b6585560;p=febootstrap.git diff --git a/febootstrap.pod b/febootstrap.pod index dfc93fc..6620976 100644 --- a/febootstrap.pod +++ b/febootstrap.pod @@ -1,179 +1,296 @@ +=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 + +=over 4 -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. +=item B<--help> -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. +Display brief command line usage, and exit. -For more advanced needs, take a look at L, C -and I's C. +=item B<--exclude REGEXP> -The normal output is a root directory located at I and -a fakeroot logfile at C/fakeroot.log>. +After doing dependency resolution, exclude packages which match the +regular expression. -=head1 OPTIONS +This option is only used with I<--names>, and it can be given multiple +times on the command line. -=over 4 +=item B<--names> -=item B<-i package> +Provide a list of package names, instead of providing packages +directly. In this mode febootstrap may require network access. See +L above. -=item B<--install=package> +=item B<--no-warnings> -=item B<-g "group"> +Don't print warnings about packaging problems. -=item B<--groupinstall="group"> +=item B<-o outputdir> -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. +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. -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. +=item B<-v> -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<--verbose> -=item B<--no-clean> +Enable verbose messages. -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. +=item B<-V> -=back +=item B<--version> + +Print the package name and version number, and exit. -=head1 REPOSITORIES +=item B<--yum-config CONFIGFILE> -You can list available repositories by visiting this URL: +(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. -L +=back -(If necessary replace C with your architecture, but it seems -unlikely that this list will change based on architecture). +=head1 SUPERMIN APPLIANCES -=head1 FAKEROOT LOGFILE +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. -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>. +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. -You can use the fakeroot logfile in a number of ways: +Therefore the supermin appliance normally consists of at least two +control files: =over 4 -=item * +=item B -Run +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. - fakeroot -i fakeroot.log command +Paths can contain wildcards, which are expanded when the appliance +is created, eg: -in order to run a command with the faked file permissions. If the -command will make updates, then do: + /etc/yum.repos.d/*.repo - fakeroot -i fakeroot.log -s fakeroot.log command +would copy all of the C<*.repo> files into the appliance. -=item * +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). -Generate an initramfs (compressed cpio) file containing the correct -permissions using the tool C. +=item B -=item * +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. -Apply the permissions to the target directory using the forthcoming -tool C (requires root). +Note that unlike C, paths and directories in the base image +don't need to have any relationship to the host filesystem. =back -=head1 COMPARISON TO debootstrap +=head2 RECONSTRUCTING THE APPLIANCE -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. +The separate tool L is used to +reconstruct an appliance from the hostfiles and base image files. -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 program in fact iterates recursively over the files and +directories passed to it. A common layout is: -=head1 OTHER RESTRICTIONS AND BUGS + supermin.d/ + supermin.d/base.img + supermin.d/extra.img + supermin.d/hostfiles -Some C<%post> scripts do not run correctly. The most common case is -C. 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: +and then invoking febootstrap-supermin-helper with just the +C directory path as an argument. - /sbin/ldconfig: Can't create temporary cache file /etc/ld.so.cache~: Permission denied +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. -This error is mostly harmless. Just run C the first -time you boot into the newly created Fedora system. +=head3 DIRECTORIES BEFORE FILES -Another error you will see is with C -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. +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: -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. + /usr + /usr/sbin + /usr/sbin/serviced -=head1 HOME PAGE +It is fine to list the same directory name multiple times. -L +=head3 LEXICOGRAPHICAL ORDER -=head1 SEE ALSO +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 -L, -L, -L, -L, -L, -L. +Notice how we instruct cpio to create intermediate directories. -=head1 ALTERNATIVES +=head2 MINIMIZING THE SUPERMIN APPLIANCE -L, -L, -L, -L, -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. + +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. + +=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 -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-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