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
178
179
180
181
182
183
184
185
186
187
188
189
|
EncapPackages | '''EncapReadme''' | EncapInstall | EncapHowto
----
= EncapReadme: Encap based bootstrap for bcfg2 and complete bcfg2 toolchain =
This code is a method for getting bcfg2, including all dependencies, up and
running on many platforms as quickly as possible, from source.
== What you get ==
The end result is a self-extracting/self-installing bcfg2 client distribution
that does a complete client install, which includes:
* the epkg encap package manager
* all software on which bcfg2 depends
* bcfg2 itself
* ostiary to kick off bcfg2 client runs remotely
* daemontools to run bcfg2 client as a periodic service with logging
* all with site-specific configuration parameters, set at build time in a
single unified build-time configuration file, site-settings.conf
* optional install-time entry of bcfg2 and ostiary passwords, interactively
or via environment variables
As well as:
* encap packages for software on which the bcfg2 server functionality
depends (glib, gamin, and cheetah)
* encaps of optional documentation packages
== Internet resources ==
For a more general overview, see http://www.bcfg2.org/wiki/EncapPackages
You can obtain the latest version of the code from bcfg2 svn:
* `svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2/encap`
== Operation notes ==
Using the encap package manager this code 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 (but
first install glib, on which gamin depends). You also need to install the
cheetah templating system on the bcfg2 server if you wish to use the bcfg2
templating functionality.
== Important differences from upstream sources ==
* In general, everything is under `/usr/local` instead of `/`
* `/usr/local/etc/bcfg2.conf` is used instead of `/etc/bcfg2.conf`
== Environment variables and Sentinel files ==
Before the initial make/gmake and before the client install, you can set some
environment variables to control some behaviors:
* `DEST="<path>"` - Set where the final build output goes. Default is
`./DIST`
* `REPLACE_CONFIG="yes"` - Unconditionally replace local configuration files
for bcfg2 and ostiary with those included in the distribution. The old
files are saved to <filename>-<date>.
* `LOC_BCFG2_PASSWD="<password>"` , `LOC_OST_PASSWD="<password>"` - Set the
bcfg2 server and ostiaryd daemon passwords, to avoid being interactively
prompted for them.
There are also some "sentinel files" (zero byte files that only indicate
state) that you can create to control the operation of the install. This is
mostly useful so that installs don't clobber local changes / changes made by
bcfg2.
Sentinel file names:
* `.SENTINEL_SITE` - Indicates that the bcfg2 client has been previously
installed.
* `.SENTINEL_BCFG2` - Indicates that the files have been modified by bcfg2
itself. (If you change any of the config files mentioned below via bcfg2,
you'll want to put this sentinel file in the appropriate directory with
bcfg2 as well).
If either of these files exist, the install will not overwrite the existing
config files unless `REPLACE_CONFIG="yes"` is set.
{{{
Directory with sentinel file(s) Covered config files
----------------------------------- --------------------------------------
/usr/local/etc bcfg2.conf , ostiary.conf
/usr/local/etc/default/bcfg2-client env/RUN_INTERVAL_SECONDS , env/OPTIONS
/usr/local/etc/default/bcfg2-server env/OPTIONS
/usr/local/sbin ost-bcfg2.sh
}}}
== About daemontools integration ==
In order to avoid a lot of platform/distribution-specific code, the encap
bcfg2 distribution includes and uses [http://cr.yp.to/daemontools.html
daemontools] (with some common patches) instead of init scripts and cron.
The bcfg2 client (.run) distribution uses daemontools to run ostiary, and to
run the bcfg2 client periodically.
On the server, edit `/usr/local/etc/default/bcfg2-server/env/OPTIONS` to
include the options you want to start up the bcfg2 server with, and then do
{{{
ln -s /usr/local/var/svc.d/bcfg2-server /service/
}}}
to enable the service.
You can use `/command/svstat /service/bcfg2-server` to see the status, and
`/command/svrm /service/bcfg2-server` to remove it.
Logs for all daemontools services are under `/usr/local/var/multilog`.
They use a highly precise time format; to translate into a readable format,
pipe the logs through `/command/tai64nlocal`.
== About ostiary integration ==
In order to enable the remote kickoff of bcfg2 client runs, the bcfg2 client
distribution includes [http://ingles.homeunix.org/software/ost/ ostiary], a
simple, very security-paranoid daemon that runs a script with fixed
arguments based on a password hash it receives.
The following actions are available via ostiary; you can add more by editing
`/usr/local/etc/ostiary.cfg`. The <password> is a value you set during
compile-time or (preferably) .run file install time.
* `<password>-bcfg2-dvqn` : Run `bcfg2-client -d -v -q -n`
* `<password>-bcfg2-dvn` : Run `bcfg2-client -d -v -n`
* `<password>-bcfg2-dvq` : Run `bcfg2-client -d -v -q`
* `<password>-bcfg2-dv` : Run `bcfg2-client -d -v`
* `<password>-bcfg2-vq` : Run `bcfg2-client -v -q`
* `<password>-bcfg2-v` : Run `bcfg2-client -v`
* `<password>-bcfg2-restart` : Restart the bcfg2-client daemontools service
There are plans for the future for a bcfg2 plugin that will set per-machine
passwords after the initial install, however as with cfengine the worst that
someone can do if they find your password is to bring your host into a
cleaner state.
To execute one of these actions, you use the `ostclient` command, i.e.:
{{{ ostclient -a <address> -p <port> }}}
where <address> is the address of the machine you want to run the bcfg2
client on, and <port> is the ostiary port number you set during the INSTALL
procedure. You will then be prompted to `Enter command secret: `, at which
point you will enter one of the above-listed values, such as
`<password>-bcfg2-dvqn` (the command to run and the password are
integrated into the same string).
Logs of bcfg2-client runs kicked off via ostiary are in
`/usr/local/var/multilog/bcfg2-client-ostiary`
== Supported Platforms ==
Below is a table of platforms that have been successfully bootstrapped using
this code.
|| OS || Vendor || Version || Arch || GCC || By || Bcfg2 ||
|| AIX || IBM || 5.2 || POWER || 3.3.2 || dc || 0.8.5 ||
|| AIX || IBM || 5.3 || POWER || 4.1.1 || dc || 0.8.5 ||
|| GNU/Linux || Debian || Sarge || i386 || 3.3.5 || dc || 0.8.5 ||
|| GNU/Linux || Debian || Sid || i386 || 4.1.2 || dc || 0.8.5 ||
|| GNU/Linux || SuSE || SLES8 || i386 || 3.2.2 || dc || 0.8.5 ||
|| GNU/Linux || SuSE || SLES10 || i386 || 4.1.0 || dc || 0.8.5 ||
|| GNU/Linux || Ubuntu || Dapper || i386 || 4.0.3 || dc || 0.8.5 ||
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.
== Encap profile (.ep) documentation ==
Note that the doc for the encap profile format is in
[wiki:EncapManEncapProfile `man 5 encap_profile`].
== Next steps ==
1. Build and install; see [wiki:EncapInstall INSTALL]
1. Set up your server and clients; see [wiki:EncapHowto HOWTO]
== Documentation Version ==
* This is a copy of: $Id$
* Most recent version: http://www.bcfg2.org/browser/trunk/bcfg2/encap/README
|
