diff options
Diffstat (limited to 'encap/HOWTO')
| -rw-r--r-- | encap/HOWTO | 177 |
1 files changed, 177 insertions, 0 deletions
diff --git a/encap/HOWTO b/encap/HOWTO new file mode 100644 index 000000000..488639c7f --- /dev/null +++ b/encap/HOWTO @@ -0,0 +1,177 @@ += Encap based bootstrap for bcfg2 and complete bcfg2 client toolchain = + +This bootstrap code is a method for getting bcfg2 (as a client), +including all dependencies, up and running on a new platform as +quickly as possible (from source). + +The latest version of this document is always available from: + * http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/encap/README + +For a more general overview of what this is, see: + * http://trac.mcs.anl.gov/projects/bcfg2/wiki/EncapPackages + +You can view this document with glorious Trac Wiki formatting at: + * http://trac.mcs.anl.gov/projects/bcfg2/wiki/EncapHowto + (Although that version may be out of date) + +You can obtain the latest version of the code from bcfg2 svn: + * `svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2/encap` + +Or browse the latest version on the web via: + * http://trac.mcs.anl.gov/projects/bcfg2/browser/trunk/bcfg2/encap + +Using the encap package manager it automatically downloads, builds and +creates encap packages for bcfg2 and dependencies to `/usr/local/encap`, and +installs symbolic links to these packages from `/usr/local` (the usual encap +thing). + +It attempts to be as self contained as possible; everything gets linked to +under `/usr/local/lib/bcfg2`, except for bcfg2 itself and some dependent +software, which is prefixed by `b2-` (`b2-openssl`, `b2-python` etc.). + +To run the bcfg2 server, you also need to install gamin, which +supports a subset of the platforms bcfg2 client will work on, including +GNU/Linux and FreeBSD. + +When using this packaging, `/etc/bcfg2.conf` is instead +`/usr/local/etc/bcfg2.conf`. + +This should be considered an alpha version. Everything compiles and seems to +work, but it has not yet been tested with a working bcfg2 repository. + +== Building and installing everything == + 1. Make sure all of the Prerequisites (see below) are installed. + 1. The build user needs write access to the encap source and build + directories. By default, these are `/usr/local/encap` and + `/usr/local/src`. If you like to live dangerously, you can also just do + the builds as `root`. + 1. Run `make`. This will kick off and background the entire build process. + Make output will be redirected to `make.log`, and package build output + will go to individual log files. + 1. If everything goes well, try running "`bcfg2-repo-validate`". This should + not generate a python traceback :-) + 1. You now have *-encap-*.tar.gz encap packages you can distribute to other + machines. If you don't like the OS name encap uses automatically (esp. + on GNU/Linux these can be too generic), do `make rename OS=somestring`. + +== Prerequisites == + * GNU gcc and GNU g++ + * If you are using the gcc distributed with Solaris/x86 10, you need to + install the gcc bugfix at http://www.openssl.org/~appro/values.c by + running "ksh -f values.c" as root (or openssl will segfault) + * GNU make (make sure "gmake" links to GNU make on non-GNU platforms) + * /usr/local/man should be a directory, not a symbolic link + * epkg (the encap package manager) + * Canonical website is http://www.encap.org/epkg + * Mirror of epkg binaries is available at http://www.dclark.us/mirror/ + * If built from source, first need all recommended libraries from web page + +You will need binaries of the GNU tools. For GNU and BSD based operating +systems, you should be able to get these via the operating system's package +system. For commercial operating systems, these can be obtained from: + + AIX:: + * UCLA's Public Domain Software Library for AIX at + http://aixpdslib.seas.ucla.edu/aixpdslib.html + (These are trivial to convert into encap packages) + * Bull AIX Freeware at http://www.bullfreeware.com/ + + Solaris:: + * Freeware for Solaris at http://www.sunfreeware.com/ + * Community Software for Solaris at http://www.blastwave.org/packages.php + +== Supported Platforms == +Below is a table of platforms that have been successfully bootstrapped using +this code. + +|| OS || Vendor || Version || Arch || GCC || By || With VERSION || +|| AIX || IBM || 5.3 || POWER || 4.1.0 || dc || 0.7/0.8.2 || +|| GNU/Linux || Debian || Sarge || i386 || 3.3.5 || dc || 0.7/0.8.2 || +|| GNU/Linux || Debian || Sid || i386 || 4.1.2 || dc || 0.8/0.8.2 || +|| Solaris || Sun || 10 || Sparc || 3.4.3 || dc || 0.7/0.8.2 || +|| Solaris || Sun || 10 || i386 || 3.4.3 || dc || 0.7/0.8.2 || + +dc: "Daniel Clark" <mailto:dclark@member.fsf.org> + +If you bootstrap a platform not listed above, please add a comment to: + * http://trac.mcs.anl.gov/projects/bcfg2/ticket/74 +so that platform can be added to the list. + +If you modified any of the files in this package to be able to bootstrap the +new platform, please include either diffs or a tarball of your modified +version in a new ticket so your changes can be incorporated into a new +release. + +Any other notes, such as where you got the GNU binaries or any issues people +should be aware of, would also be appreciated. + +You may want to scan all of the bootstrapped binaries and libraries with +`ldd` (or equivalent) to make sure there are no dependencies on libraries +other than those included with the base operating system and the libraries +built as part of the bootstrap process. + +On non-GNU operating systems, libgcc and libstdc++ are a run-time +requirement. These libraries are usually distributed with gcc/g++, so the +bootstrap system attempts to create encap packages containing those +libraries by copying them from the build machine. To test that this worked, +you'll want to either temporarily remove gcc/g++ from the build machine and +make sure everything still works, or install the bcfg2-*.tar.gz encap +packages on a "clean" machine (without a gcc/g++ install) and test on that +machine. + +Note that the doc for the encap profile format is in "man 5 encap_profile". + +== Release Notes == + 0.1:: + * Initial Released Version + * Work needs to be done to minimize size of distribution. In 0.1 + libraries and binaries are not stripped, and there is a lot of + pruning that can be done of individual packages. + + 0.2:: + * Updated bcfg2 to 0.8.2pre7 + * Updated README to point to mcs.anl.gov resources + + 0.3:: + * Updated bcfg2 to 0.8.2pre10 + + 0.4:: + * Versions before this version won't work without manually fixing paths + * Added patches so paths actually exist, specifically: + * bcfg2.conf default location is /usr/local/etc + * epkg/encap paths changed to encap default /usr/local paths + * schema prefix patch (changeset 1953) applied + * default schema prefix changed to /usr/local/lib/bcfg2 + * Added mirror of all packages downloaded by the profiles at + http://www.pobox.com/users/dclark/mirror and made mirror default for + those downloads + * Set up automatic hourly mirror of bcfg2 ftp site *.tar.gz files + * Mirror of other packages is manual (but deps shouldn't change often) + + 0.5:: + * Removed external download of patches as that was not working consistently; + replaced with patches inline the bcfg2 encap profile (.ep file) + * Added GNU patch dependency, both for bcfg2 patches and call from Cfg.py + * Fixed bcfg-repo-validate so it can find xmllint (as b2-xmllint) + + 0.6:: + * Updated bcfg2 to 0.8.2 (released version) + * Removed r1953 patch from bcfg2 profile, since that is included in 0.8.2 + * Added alpha version warning + + 0.7:: + * Added Solaris support + + 0.8:: + * Added python code to fix paths; removed inline patch & GNU patch dependency + * Path change happens as part of install, logged to postinstall.log + * Changed prefix from b2 to b2- to disambiguate from system commands + * Fixes to make man pages easier to access + * Install tools as b2-example-tools-* + * Added some auxiliary tools under tools/ directory + * daemontools - cross-platform alternative to init scripts/cron + * ostiary - simple/secure daemon for kicking off a local script + * epkg Makefile - to build epkg when prebuilt binaries aren't available + +== Documentation Version == +$Id$ |