| 1 | EncapPackages | '''EncapReadme''' | EncapInstall | EncapHowto |
| 2 | |
| 3 | ---- |
| 4 | |
| 5 | = EncapReadme: Encap based bootstrap for bcfg2 and complete bcfg2 toolchain = |
| 6 | |
| 7 | This code is a method for getting bcfg2, including all dependencies, up and |
| 8 | running on many platforms as quickly as possible, from source. |
| 9 | |
| 10 | == What you get == |
| 11 | The end result is a self-extracting/self-installing bcfg2 client distribution |
| 12 | that does a complete client install, which includes: |
| 13 | * the epkg encap package manager |
| 14 | * all software on which bcfg2 depends |
| 15 | * bcfg2 itself |
| 16 | * ostiary to kick off bcfg2 client runs remotely |
| 17 | * daemontools to run bcfg2 client as a periodic service with logging |
| 18 | * all with site-specific configuration parameters, set at build time in a |
| 19 | single unified build-time configuration file, site-settings.conf |
| 20 | * optional install-time entry of bcfg2 and ostiary passwords, interactively |
| 21 | or via environment variables |
| 22 | |
| 23 | As well as: |
| 24 | * encap packages for software on which the bcfg2 server functionality |
| 25 | depends (glib, gamin, and cheetah) |
| 26 | * encaps of optional documentation packages |
| 27 | |
| 28 | == Internet resources == |
| 29 | For a more general overview, see http://www.bcfg2.org/wiki/EncapPackages |
| 30 | |
| 31 | You can obtain the latest version of the code from bcfg2 svn: |
| 32 | * `svn co https://svn.mcs.anl.gov/repos/bcfg/trunk/bcfg2/encap` |
| 33 | |
| 34 | == Operation notes == |
| 35 | Using the encap package manager this code automatically downloads, builds and |
| 36 | creates encap packages for bcfg2 and dependencies to `/usr/local/encap`, and |
| 37 | installs symbolic links to these packages from `/usr/local` (the usual encap |
| 38 | thing). |
| 39 | |
| 40 | It attempts to be as self contained as possible; everything gets linked to |
| 41 | under `/usr/local/lib/bcfg2`, except for bcfg2 itself and some dependent |
| 42 | software, which is prefixed by `b2-` (`b2-openssl`, `b2-python` etc.). |
| 43 | |
| 44 | To run the bcfg2 server, you also need to install gamin, which supports a |
| 45 | subset of the platforms bcfg2 client will work on, including GNU/Linux (but |
| 46 | first install glib, on which gamin depends). You also need to install the |
| 47 | cheetah templating system on the bcfg2 server if you wish to use the bcfg2 |
| 48 | templating functionality. |
| 49 | |
| 50 | == Important differences from upstream sources == |
| 51 | * In general, everything is under `/usr/local` instead of `/` |
| 52 | * `/usr/local/etc/bcfg2.conf` is used instead of `/etc/bcfg2.conf` |
| 53 | |
| 54 | == Environment variables and Sentinel files == |
| 55 | Before the initial make/gmake and before the client install, you can set some |
| 56 | environment variables to control some behaviors: |
| 57 | * `DEST="<path>"` - Set where the final build output goes. Default is |
| 58 | `./DIST` |
| 59 | * `REPLACE_CONFIG="yes"` - Unconditionally replace local configuration files |
| 60 | for bcfg2 and ostiary with those included in the distribution. The old |
| 61 | files are saved to <filename>-<date>. |
| 62 | * `LOC_BCFG2_PASSWD="<password>"` , `LOC_OST_PASSWD="<password>"` - Set the |
| 63 | bcfg2 server and ostiaryd daemon passwords, to avoid being interactively |
| 64 | prompted for them. |
| 65 | |
| 66 | There are also some "sentinel files" (zero byte files that only indicate |
| 67 | state) that you can create to control the operation of the install. This is |
| 68 | mostly useful so that installs don't clobber local changes / changes made by |
| 69 | bcfg2. |
| 70 | |
| 71 | Sentinel file names: |
| 72 | * `.SENTINEL_SITE` - Indicates that the bcfg2 client has been previously |
| 73 | installed. |
| 74 | * `.SENTINEL_BCFG2` - Indicates that the files have been modified by bcfg2 |
| 75 | itself. (If you change any of the config files mentioned below via bcfg2, |
| 76 | you'll want to put this sentinel file in the appropriate directory with |
| 77 | bcfg2 as well). |
| 78 | |
| 79 | If either of these files exist, the install will not overwrite the existing |
| 80 | config files unless `REPLACE_CONFIG="yes"` is set. |
| 81 | |
| 82 | {{{ |
| 83 | Directory with sentinel file(s) Covered config files |
| 84 | ----------------------------------- -------------------------------------- |
| 85 | /usr/local/etc bcfg2.conf , ostiary.conf |
| 86 | /usr/local/etc/default/bcfg2-client env/RUN_INTERVAL_SECONDS , env/OPTIONS |
| 87 | /usr/local/etc/default/bcfg2-server env/OPTIONS |
| 88 | /usr/local/sbin ost-bcfg2.sh |
| 89 | }}} |
| 90 | |
| 91 | == About daemontools integration == |
| 92 | In order to avoid a lot of platform/distribution-specific code, the encap |
| 93 | bcfg2 distribution includes and uses [http://cr.yp.to/daemontools.html |
| 94 | daemontools] (with some common patches) instead of init scripts and cron. |
| 95 | |
| 96 | The bcfg2 client (.run) distribution uses daemontools to run ostiary, and to |
| 97 | run the bcfg2 client periodically. |
| 98 | |
| 99 | On the server, edit `/usr/local/etc/default/bcfg2-server/env/OPTIONS` to |
| 100 | include the options you want to start up the bcfg2 server with, and then do |
| 101 | {{{ |
| 102 | ln -s /usr/local/var/svc.d/bcfg2-server /service/ |
| 103 | }}} |
| 104 | to enable the service. |
| 105 | |
| 106 | You can use `/command/svstat /service/bcfg2-server` to see the status, and |
| 107 | `/command/svrm /service/bcfg2-server` to remove it. |
| 108 | |
| 109 | Logs for all daemontools services are under `/usr/local/var/multilog`. |
| 110 | They use a highly precise time format; to translate into a readable format, |
| 111 | pipe the logs through `/command/tai64nlocal`. |
| 112 | |
| 113 | == About ostiary integration == |
| 114 | In order to enable the remote kickoff of bcfg2 client runs, the bcfg2 client |
| 115 | distribution includes [http://ingles.homeunix.org/software/ost/ ostiary], a |
| 116 | simple, very security-paranoid daemon that runs a script with fixed |
| 117 | arguments based on a password hash it receives. |
| 118 | |
| 119 | The following actions are available via ostiary; you can add more by editing |
| 120 | `/usr/local/etc/ostiary.cfg`. The <password> is a value you set during |
| 121 | compile-time or (preferably) .run file install time. |
| 122 | * `<password>-bcfg2-dvqn` : Run `bcfg2-client -d -v -q -n` |
| 123 | * `<password>-bcfg2-dvn` : Run `bcfg2-client -d -v -n` |
| 124 | * `<password>-bcfg2-dvq` : Run `bcfg2-client -d -v -q` |
| 125 | * `<password>-bcfg2-dv` : Run `bcfg2-client -d -v` |
| 126 | * `<password>-bcfg2-vq` : Run `bcfg2-client -v -q` |
| 127 | * `<password>-bcfg2-v` : Run `bcfg2-client -v` |
| 128 | * `<password>-bcfg2-restart` : Restart the bcfg2-client daemontools service |
| 129 | |
| 130 | There are plans for the future for a bcfg2 plugin that will set per-machine |
| 131 | passwords after the initial install, however as with cfengine the worst that |
| 132 | someone can do if they find your password is to bring your host into a |
| 133 | cleaner state. |
| 134 | |
| 135 | To execute one of these actions, you use the `ostclient` command, i.e.: |
| 136 | {{{ ostclient -a <address> -p <port> }}} |
| 137 | where <address> is the address of the machine you want to run the bcfg2 |
| 138 | client on, and <port> is the ostiary port number you set during the INSTALL |
| 139 | procedure. You will then be prompted to `Enter command secret: `, at which |
| 140 | point you will enter one of the above-listed values, such as |
| 141 | `<password>-bcfg2-dvqn` (the command to run and the password are |
| 142 | integrated into the same string). |
| 143 | |
| 144 | Logs of bcfg2-client runs kicked off via ostiary are in |
| 145 | `/usr/local/var/multilog/bcfg2-client-ostiary` |
| 146 | |
| 147 | == Supported Platforms == |
| 148 | Below is a table of platforms that have been successfully bootstrapped using |
| 149 | this code. |
| 150 | |
| 151 | || OS || Vendor || Version || Arch || GCC || By || Bcfg2 || |
| 152 | || AIX || IBM || 5.3 || POWER || 4.1.0 || dc || 0.8.3 || |
| 153 | || GNU/Linux || Debian || Sarge || i386 || 3.3.5 || dc || 0.8.3 || |
| 154 | || GNU/Linux || Debian || Sid || i386 || 4.1.2 || dc || 0.8.3 || |
| 155 | || GNU/Linux || Ubuntu || Dapper || i386 || 4.0.3 || dc || 0.8.3 || |
| 156 | || Solaris || Sun || 10 || Sparc || 3.4.3 || dc || 0.8.3 || |
| 157 | || Solaris || Sun || 10 || i386 || 3.4.3 || dc || 0.8.3 || |
| 158 | |
| 159 | dc: "Daniel Clark" <mailto:[email protected]> |
| 160 | |
| 161 | If you bootstrap a platform not listed above, please add a comment to: |
| 162 | * http://trac.mcs.anl.gov/projects/bcfg2/ticket/74 |
| 163 | so that platform can be added to the list. |
| 164 | |
| 165 | If you modified any of the files in this package to be able to bootstrap the |
| 166 | new platform, please include either diffs or a tarball of your modified |
| 167 | version in a new ticket so your changes can be incorporated into a new |
| 168 | release. |
| 169 | |
| 170 | Any other notes, such as where you got the GNU binaries or any issues people |
| 171 | should be aware of, would also be appreciated. |
| 172 | |
| 173 | You may want to scan all of the bootstrapped binaries and libraries with |
| 174 | `ldd` (or equivalent) to make sure there are no dependencies on libraries |
| 175 | other than those included with the base operating system and the libraries |
| 176 | built as part of the bootstrap process. |
| 177 | |
| 178 | == libgcc and libstdc++ == |
| 179 | On non-GNU operating systems, libgcc and libstdc++ are a run-time |
| 180 | requirement. These libraries are usually distributed with gcc/g++, so the |
| 181 | bootstrap system attempts to create encap packages containing those |
| 182 | libraries by copying them from the build machine. To test that this worked, |
| 183 | you'll want to either temporarily remove gcc/g++ from the build machine and |
| 184 | make sure everything still works, or install the bcfg2 client on a "clean" |
| 185 | machine (without a gcc/g++ install) and test on that machine. |
| 186 | |
| 187 | == Encap profile (.ep) documentation == |
| 188 | Note that the doc for the encap profile format is in |
| 189 | [wiki:EncapManEncapProfile `man 5 encap_profile`]. |
| 190 | |
| 191 | == Next steps == |
| 192 | 1. Build and install; see [wiki:EncapInstall INSTALL] |
| 193 | 1. Set up your server and clients; see [wiki:EncapHowto HOWTO] |
| 194 | |
| 195 | == Documentation Version == |
| 196 | * This is a copy of: $Id: README 2176 2006-09-04 13:30:26Z dclark $ |
| 197 | * Most recent version: http://www.bcfg2.org/browser/trunk/bcfg2/encap/README |