summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDaniel Joseph Barnhart Clark <dclark@pobox.com>2006-09-04 13:30:26 +0000
committerDaniel Joseph Barnhart Clark <dclark@pobox.com>2006-09-04 13:30:26 +0000
commit2b89d1f041c6f46c52dac18c0f8107c3596c38a4 (patch)
tree10d63b47751eafe83c1caff780bcb4c3522ec7de
parentd2127cb280720aed2e01a5ab4981322043800614 (diff)
downloadbcfg2-2b89d1f041c6f46c52dac18c0f8107c3596c38a4.tar.gz
bcfg2-2b89d1f041c6f46c52dac18c0f8107c3596c38a4.tar.bz2
bcfg2-2b89d1f041c6f46c52dac18c0f8107c3596c38a4.zip
EncapPackages: Final README for 0.8.3
git-svn-id: https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2@2176 ce84e21b-d406-0410-9b95-82705330c041
-rw-r--r--encap/README139
-rw-r--r--encap/TODO24
2 files changed, 121 insertions, 42 deletions
diff --git a/encap/README b/encap/README
index 46cff66c3..82e81abbd 100644
--- a/encap/README
+++ b/encap/README
@@ -26,8 +26,7 @@ As well as:
* encaps of optional documentation packages
== Internet resources ==
-For a more general overview of what this is, see:
- * http://trac.mcs.anl.gov/projects/bcfg2/wiki/EncapPackages
+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`
@@ -42,41 +41,120 @@ 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.
+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 differances from upstream sources ==
- * `/usr/local/etc/bcfg2.conf` is used instead of `/etc/bcfg2.conf`
+== 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`
-== About ostiary integration ==
-TODO
-
-== About daemontools integration ==
-TODO
-
-== Environment variables ==
-TODO
+== 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=""
- * FORCE_CONFIG="yes"
- *
+ * `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 (+svn) ||
-|| AIX || IBM || 5.3 || POWER || 4.1.0 || dc || 0.8.2 +r???? ||
-|| GNU/Linux || Debian || Sarge || i386 || 3.3.5 || dc || 0.8.2 +r???? ||
-|| GNU/Linux || Debian || Sid || i386 || 4.1.2 || dc || 0.8.2 +r???? ||
-|| GNU/Linux || Ubuntu || Dapper || i386 || 4.0.3 || dc || 0.8.2 +r???? ||
-|| Solaris || Sun || 10 || Sparc || 3.4.3 || dc || 0.8.2 +r???? ||
-|| Solaris || Sun || 10 || i386 || 3.4.3 || dc || 0.8.2 +r???? ||
+|| OS || Vendor || Version || Arch || GCC || By || Bcfg2 ||
+|| AIX || IBM || 5.3 || POWER || 4.1.0 || dc || 0.8.3 ||
+|| GNU/Linux || Debian || Sarge || i386 || 3.3.5 || dc || 0.8.3 ||
+|| GNU/Linux || Debian || Sid || i386 || 4.1.2 || dc || 0.8.3 ||
+|| GNU/Linux || Ubuntu || Dapper || i386 || 4.0.3 || dc || 0.8.3 ||
+|| Solaris || Sun || 10 || Sparc || 3.4.3 || dc || 0.8.3 ||
+|| Solaris || Sun || 10 || i386 || 3.4.3 || dc || 0.8.3 ||
dc: "Daniel Clark" <mailto:dclark@member.fsf.org>
@@ -103,13 +181,12 @@ 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.
+make sure everything still works, or install the bcfg2 client on a "clean"
+machine (without a gcc/g++ install) and test on that machine.
== Encap profile (.ep) documentation ==
Note that the doc for the encap profile format is in
-[wiki:EncapManEncapProfile "`man 5 encap_profile`"].
+[wiki:EncapManEncapProfile `man 5 encap_profile`].
== Next steps ==
1. Build and install; see [wiki:EncapInstall INSTALL]
diff --git a/encap/TODO b/encap/TODO
index e4ef34cdb..2ffd94b14 100644
--- a/encap/TODO
+++ b/encap/TODO
@@ -1,11 +1,7 @@
= EncapTodo: TODO =
== For 0.8.3 ==
-
- * Fix "from httplib import HTTPS" issue
-
- * Update README and post to Wiki
-
+
* Update EncapPackages on the Wiki
* Build everywhere, basic test
@@ -16,15 +12,15 @@
== For 0.8.4 ==
- * Move from lxml (+deps) to elementtree for client
- * Maybe just move to Python 2.5 (which includes elementtree) if final comes
- out on schedule (Sept 12th, 2006 is planned final release date)
-
* Possibly add GNU Readline library for python
+ * Write HOWTO
+
* Packages all deps of new reports (django etc.) for GNU/Linux
- * Write HOWTO
+ * Move from lxml (+deps) to elementtree for client
+ * Maybe just move to Python 2.5 (which includes elementtree) if final comes
+ out on schedule (Sept 12th, 2006 is planned final release date)
== For 0.8.5 or earlier ==
@@ -32,7 +28,13 @@
* Some platforms are now >150MB (installed)
* Remove unneeded doc / test code / etc.
* Perhaps make seperate -doc- or -extra- encap packages
-
+ * Might be able to make client-side only python 2.5 (statically linked to
+ deps like openssl), bcfg2, daemontools, ostiary, and bcfg2-site.
+ * http://groups.google.com/groups/starred?lnk=lnmst&hl=en
+ * Look into using http://sourceforge.net/projects/cx-freeze/ for client-side
+
+== For 0.8.6 or earlier ==
+
* Improve handling of libgcc/libstdc++
* Try to make build not effect the build host as much