CFengine

CFengine is a program that helps distribute configuration files to many different machines. Its homepage is http://www.cfengine.org/ and its reference documentation can be found at http://www.cfengine.org/docs/cfengine-Reference.html We run cfengine version 2.

How to update its files
CFengine's files are kept in an bazaar repository for versioning. You can edit files in /afs/.ugcs/ugcs-admin/cfengine, and then commit them with "bzr commit" (or "make commit" it the top dir).

You can then update the version in demeter:/srv/cfengine (where the stuff actually comes from) by running "update-stable-cfengine" on demeter.

Files that come from Configurator can be updated by running "make build" in the top dir. Running "make check" will run basic checks on the files there.

In the future, we will have a development version of the cfengine files so that you can easily test changes before pushing them out to all of our machines.

Details
CFengine is run by a series of configuration files in /etc/cfengine on each machine. Quite cleverly, cfengine is used to push these files out too. All files are pulled over NFS from demeter:/srv/cfengine, which is mounted as /ug/nfs/cfengine on every machine. /srv/cfengine is broken down into several different hierarchies. Some of them are self-explanatory, but here are the important ones:
 * global: Files that all machines need
 * global/inputs: Actual cfengine configuration files. They are named by the service that they configure.
 * hosts: Files that are specific to a host or a service are put here.

Once the configuration files are in place, you can run "cfengine" to have it process its directives. However, since running that on every machine would be tedious, there is a program called "cfrun" that lets you do it remotely. It uses public-key authentication to handle access control.

How to set up a service to use cfengine

 * Place appropriate config files in a directory in demeter:/srv/cfengine/hosts/servicename
 * Create a class for machines running your service, and add the appropriate machines to it (see stuff already in cfagent.conf)
 * Create a cfengine config file for your service. See existing ones for guidelines, as well as the cfengine docs.
 * Make sure cfagent.conf includes your file (see the imports section)
 * Test it

How to fix key auth
Sometimes the public key auth gets messed up. CFengine stores the keys in /var/lib/cfengine2/ppkeys. Each machine should have localhost.{pub,priv}. This is the keypair that it uses to identify itself. It may also have keys of the form -.pub (where user is usually root). Most importantly, it should have one for demeter (root-131.215.176.66.pub). Authentication may fail if any of the keys go out of sync with demeter.

On demeter, the directory contains public keys for all the other machine. If no key exists, cfrun will let you accept a key based on trust (which we usually do).

For coreservers, it is possible to fix key authentication by moving the public key (/var/lib/cfengine2/ppkeys/localhost.pub) to demeter (/var/lib/cfengine2/ppkey/root- .ugcs.caltech.edu.pub). Then, restart the coreserver's cfengine2 service. If this doesn't work, you can try regenerating the key on the coreserver with "cfkey" and copying the new public key to demeter (don't forget to restart cfengine2).

For shellservers, the keys are copied from the keys NFS share on apollo (apollo:/srv/keys/ mounted on /ug/nfs/keys/). When replacing the keys, both the public and private keys need to be moved to apollo:/srv/keys/ / -cfengine.{pub,priv}. Otherwise, on reboot they will be copied over with the old keys (or possibly none at all, if the keypair is missing from NFS).

Finally, cfrun is not too clear with machines are having auth problems. Either use "cfrun -v" to see which machines are failing, "cfrun " to get individual output, or cfrun and then look in /tmp/cfrun. Any files in the folder which are empty are having authentication issues.

How to use to mass-install/upgrade packages

 * 1) Install the package on a test machine and make sure it works correctly.  If it has debconf questions, copy the responses to the debconf push directory in demeter:/srv/cfengine/hosts/apt
 * 2) Add an appropriate entry in the packages.conf file (demeter:/srv/cfengine/global/inputs/packages.conf)  See the other ones for a template.  If it absolutely can't be installed on a machine, make sure you have that set up correctly (with classes, etc)
 * 3) Run "cfrun -- -v -- coreserver" to make each coreserver update, which should cause the new packages install.  You can then check with "mssh coreserver dpkg -l packagename".
 * 4) You then have to run cfagent on hera/zeus/charon manually since they aren't in cfrun for security reasons

This works through cfengine's package action. CFengine will look at each package, compare its version to the one installed, and install it if necessary. The package command is set up to answer "yes" to most questions; however, this system isn't foolproof (silly apt). I've already set up the correct command template; it should just work about as well as it can.