diff options
Diffstat (limited to 'encap/README')
| -rw-r--r-- | encap/README | 173 |
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 |