summaryrefslogtreecommitdiffstats
path: root/encap/README
diff options
context:
space:
mode:
Diffstat (limited to 'encap/README')
-rw-r--r--encap/README173
1 files changed, 0 insertions, 173 deletions
diff --git a/encap/README b/encap/README
deleted file mode 100644
index 653f6f274..000000000
--- a/encap/README
+++ /dev/null
@@ -1,173 +0,0 @@
-[[TracNav]]
-
-EncapPackages | '''EncapReadme''' | EncapPlatforms | 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
- * Runit 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:
- * Encaps of optional documentation packages
- * Optionally you can build the software the bcfg2 server requires (cd to
- the encap/src/encap-packages/server directory and type "make")
-
-== 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-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 runit integration ==
-In order to avoid a lot of platform/distribution-specific code, the encap
-bcfg2 distribution includes and uses [http://smarden.org/runit/useinit.html
-runit] instead of init scripts and cron.
-
-The bcfg2 client (.run) distribution uses runit 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/etc/sv/bcfg2-server /usr/local/var/service/
-}}}
-to enable the service.
-
-You can use `sv status /usr/local/var/service/bcfg2-server` to see the
-status, and `rm /usr/local/var/service/bcfg2-server` to remove it.
-
-Logs for all runit services are under `/usr/local/var/svlogd`.
-
-== 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 runit 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).
-
-Another useful way of running ostiary is to put the password in a text file
-(on the local filesystem with appropriate permissions) and then do:
-{{{
-for HOST in $(bcfg2-query -u); do
- printf "$HOST: "
- ostclient -a $HOST:1711 -f 0 < file-with-password.txt
- sleep 1
-done
-}}}
-This will run the ostiary command associated with the password in
-"file-with-password.txt" on all hosts bcfg2 thinks are up. The sleep
-delay is arbitrary and not really required, but can be useful if you
-are monitoring the bcfg2 server logs interactively for client connections.
-
-Logs of bcfg2-client runs kicked off via ostiary are in
-`/usr/local/var/svlogd/bcfg2-client-ostiary`
-
-== Encap profile (.ep) documentation ==
-Note that the doc for the encap profile format is in
-[wiki:EncapManEncapProfile `man 5 encap_profile`].
-
-== Next steps ==
- 1. You can check to see if your platform has been successfully
- bootstrapped before; see [wiki:EncapPlatforms PLATFORMS]
- 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