From 2b89d1f041c6f46c52dac18c0f8107c3596c38a4 Mon Sep 17 00:00:00 2001 From: Daniel Joseph Barnhart Clark Date: Mon, 4 Sep 2006 13:30:26 +0000 Subject: 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 --- encap/README | 139 ++++++++++++++++++++++++++++++++++++++++++++++------------- encap/TODO | 24 ++++++----- 2 files changed, 121 insertions(+), 42 deletions(-) (limited to 'encap') 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=""` - 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 -. + * `LOC_BCFG2_PASSWD=""` , `LOC_OST_PASSWD=""` - 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 is a value you set during +compile-time or (preferably) .run file install time. + * `-bcfg2-dvqn` : Run `bcfg2-client -d -v -q -n` + * `-bcfg2-dvn` : Run `bcfg2-client -d -v -n` + * `-bcfg2-dvq` : Run `bcfg2-client -d -v -q` + * `-bcfg2-dv` : Run `bcfg2-client -d -v` + * `-bcfg2-vq` : Run `bcfg2-client -v -q` + * `-bcfg2-v` : Run `bcfg2-client -v` + * `-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
-p }}} +where
is the address of the machine you want to run the bcfg2 +client on, and 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 +`-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" @@ -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 -- cgit v1.2.3-1-g7c22