summaryrefslogtreecommitdiffstats
path: root/encap/README
blob: 488639c7fc86bc7073b547a54a12014110f7b00e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
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$