Changes between Initial Version and Version 1 of EncapReadme

09/04/06 08:30:50 (16 years ago)



  • EncapReadme

    v1 v1  
     1EncapPackages | '''EncapReadme''' | EncapInstall | EncapHowto 
     5= EncapReadme: Encap based bootstrap for bcfg2 and complete bcfg2 toolchain = 
     7This code is a method for getting bcfg2, including all dependencies, up and 
     8running on many platforms as quickly as possible, from source. 
     10== What you get == 
     11The end result is a self-extracting/self-installing bcfg2 client distribution 
     12that 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 
     23As 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 
     28== Internet resources == 
     29For a more general overview, see 
     31You can obtain the latest version of the code from bcfg2 svn: 
     32 * `svn co` 
     34== Operation notes == 
     35Using the encap package manager this code automatically downloads, builds and 
     36creates encap packages for bcfg2 and dependencies to `/usr/local/encap`, and 
     37installs symbolic links to these packages from `/usr/local` (the usual encap 
     40It attempts to be as self contained as possible; everything gets linked to 
     41under `/usr/local/lib/bcfg2`, except for bcfg2 itself and some dependent 
     42software, which is prefixed by `b2-` (`b2-openssl`, `b2-python` etc.).   
     44To run the bcfg2 server, you also need to install gamin, which supports a 
     45subset of the platforms bcfg2 client will work on, including GNU/Linux (but 
     46first install glib, on which gamin depends). You also need to install the 
     47cheetah templating system on the bcfg2 server if you wish to use the bcfg2 
     48templating functionality. 
     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` 
     54== Environment variables and Sentinel files == 
     55Before the initial make/gmake and before the client install, you can set some  
     56environment 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. 
     66There are also some "sentinel files" (zero byte files that only indicate 
     67state) that you can create to control the operation of the install. This is 
     68mostly useful so that installs don't clobber local changes / changes made by 
     71Sentinel 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). 
     79If either of these files exist, the install will not overwrite the existing 
     80config files unless `REPLACE_CONFIG="yes"` is set. 
     83Directory 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 
     91== About daemontools integration ==  
     92In order to avoid a lot of platform/distribution-specific code, the encap 
     93bcfg2 distribution includes and uses [ 
     94daemontools] (with some common patches) instead of init scripts and cron.  
     96The bcfg2 client (.run) distribution uses daemontools to run ostiary, and to 
     97run the bcfg2 client periodically.  
     99On the server, edit `/usr/local/etc/default/bcfg2-server/env/OPTIONS` to 
     100include the options you want to start up the bcfg2 server with, and then do 
     102ln -s /usr/local/var/svc.d/bcfg2-server /service/  
     104to enable the service.  
     106You can use `/command/svstat /service/bcfg2-server` to see the status, and 
     107`/command/svrm /service/bcfg2-server` to remove it. 
     109Logs for all daemontools services are under `/usr/local/var/multilog`. 
     110They use a highly precise time format; to translate into a readable format, 
     111pipe the logs through `/command/tai64nlocal`. 
     113== About ostiary integration == 
     114In order to enable the remote kickoff of bcfg2 client runs, the bcfg2 client 
     115distribution includes [ ostiary], a 
     116simple, very security-paranoid daemon that runs a script with fixed 
     117arguments based on a password hash it receives. 
     119The 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 
     121compile-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 
     130There are plans for the future for a bcfg2 plugin that will set per-machine 
     131passwords after the initial install, however as with cfengine the worst that 
     132someone can do if they find your password is to bring your host into a 
     133cleaner state. 
     135To execute one of these actions, you use the `ostclient` command, i.e.: 
     136{{{ ostclient -a <address> -p <port> }}} 
     137where <address> is the address of the machine you want to run the bcfg2 
     138client on, and <port> is the ostiary port number you set during the INSTALL 
     139procedure. You will then be prompted to `Enter command secret: `, at which 
     140point you will enter one of the above-listed values, such as 
     141`<password>-bcfg2-dvqn` (the command to run and the password are 
     142integrated into the same string). 
     144Logs of bcfg2-client runs kicked off via ostiary are in 
     147== Supported Platforms ==  
     148Below is a table of platforms that have been successfully bootstrapped using 
     149this code. 
     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 || 
     159dc: "Daniel Clark" <mailto:[email protected]> 
     161If you bootstrap a platform not listed above, please add a comment to: 
     162 * 
     163so that platform can be added to the list.  
     165If you modified any of the files in this package to be able to bootstrap the 
     166new platform, please include either diffs or a tarball of your modified 
     167version in a new ticket so your changes can be incorporated into a new 
     170Any other notes, such as where you got the GNU binaries or any issues people 
     171should be aware of, would also be appreciated.  
     173You 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 
     175other than those included with the base operating system and the libraries 
     176built as part of the bootstrap process.  
     178== libgcc and libstdc++ == 
     179On non-GNU operating systems, libgcc and libstdc++ are a run-time 
     180requirement. These libraries are usually distributed with gcc/g++, so the 
     181bootstrap system attempts to create encap packages containing those 
     182libraries by copying them from the build machine. To test that this worked, 
     183you'll want to either temporarily remove gcc/g++ from the build machine and 
     184make sure everything still works, or install the bcfg2 client on a "clean" 
     185machine (without a gcc/g++ install) and test on that machine. 
     187== Encap profile (.ep) documentation == 
     188Note that the doc for the encap profile format is in  
     189[wiki:EncapManEncapProfile `man 5 encap_profile`]. 
     191== Next steps == 
     192 1. Build and install; see [wiki:EncapInstall INSTALL] 
     193 1. Set up your server and clients; see [wiki:EncapHowto HOWTO] 
     195== Documentation Version == 
     196 * This is a copy of: $Id: README 2176 2006-09-04 13:30:26Z dclark $ 
     197 * Most recent version: