"A Terse Guide to Cfengine: Host Roles, Executables, Configuration, Caveats, File Locations and Command Line Execution" written by Steve Rader Thursday March 11th 2004 Client vs Server: Policy Server, File Servers and Clients --------------------------------------------------------- All cfengine hosts are "clients" which "speak cfengine" over TCP/IP port 5308. Any cfengine host can be a cfengine "file server". This offers infinite flexibility, but can been a little daunting at first. The central point of cfengine management is the cfengine "policy server". When testing, it may be wise to use the policy server as your only file server. Executables ----------- The "cfservd" executable is a daemon which speaks cfengine (provides the "cfengine service".) This daemon should always be running on all cfengine hosts. The "cfagent" command actually does updates and such. The "cfexecd" executable is a daemon which provides scheduling and reporting services on cfengine client hosts. Think of it as a cfengine's cron-like service. It's default behavior is to run cfagent every hour. If you want a host to use cfengine's scheduling service, this daemon should be running. The "cfrun" command runs cfagent on clients. It's used to "push" updates to clients. The "cfenvd" daemon executable is an optional component of cfengine. You can safely ignore it until after you've got cfengine working. Behavior and Configuration Files -------------------------------- Cfengine does a sequence of two types updates: first, cfengine does "configuration updates", which are specified in update.conf and second, cfengine does "system updates", which are specified in cfagent.conf. The cfengine configuration file syntax is very similar to the "make" command's makefile syntax. Make's makefiles automatically determine which code needs to be recompiled; cfengine configuration files automatically determine how systems should be updated. To be more specific, a makefile's "rules" specify what commands need ran and each rule's "dependencies" specify if those commands should be ran. Instead of make rules, cfengine has "actions" for doing the vast majority of systems management tasks. Instead of having dependencies, cfengine has "classes" for specifying if cfengine actions should be taken. Classes can be conditionally (and/or) compared--doing so creates "compound classes". An actual definition of an action is called a "declaration". Together, cfengine actions, compound classes and declarations provide a very flexible, terse and readable format for automating an infinite number of systems management tasks. The fundamental syntax for cfengine's configuration files is: action: compound-class:: declaration Caveats ------- Cfengine does not like to run often--it's a built-in safeguard to keep servers from being overloaded. This is called "ifelapsed". The default behavior is to only allow one run per minute (or even longer?) This can make the initial testing/debugging difficult and/or frustrating. While testing, set ifelapsed = ( 0 ) in cfagent.conf so cfengine will run promptly. Cfengine avoids running a bunch of clients at the same time--it's another build-in safeguard to keep servers from being overloaded. This is called "splay". By default, cfengine will sleep some random about of time between zero and two minutes. While testing, use cfrun with the "--no-splay" (aka -q) flag so that cfengine will run promptly on clients. Because it's a "hands-off" automated system, cfengine does not like to report about what it has done. Use the "--inform", "--verbose", "-d1" or "-d2" options to get cfagent to report (progressively more) details about it's operation. Sometimes changes to cfengine don't "take" during the first run. This is because the first run only updates the cfengine configuration. In this case, the second run updates the system as per the updated cfengine configuration. If an updated cfengine configuration (update.conf & cfagent.conf) contains syntax errors, then subsequent updates may fail because cfengine can't parse the updated configuration. Verifying the cfengine configuration with the --parse-only (-p) flag to cfagent will catch problems of this type before they happen. If an updated cfengine server configuration (cfservd.conf) removes access from your policy server, then subsequent updates will fail. (Think: "shoot yourself in the foot".) In this case, your only option is to update the cfservd.conf file by hand. The cfengine policy server and file servers must have client security keys. To create a host's security key, run "cfkey" as root. To "seed" clients keys into the servers, run "cfrun" with the -T option. Because cfengine provides per-host and per-user authentication, cfengine can be used by end-users as well as root. Files and File Locations ------------------------ Getting cfengine to work with cfengine files in non-standard locations is not easy; use the default locations at first. The rest of the document assumes you are root, use the standard configuration and use standard file locations... - The "master files" are put in /var/cfengine/masterfiles on the policy server. - The "master configuration files" are put in /var/cfengine/masterfiles/inputs on the policy server. - Cfengine "lives" in /var/cfengine. - The cfengine client configuration files exist in /var/cfengine/inputs. - Security keys for root are put in /var/cfengine/ppkeys - Security keys for normal users are put in ~/.cfengine/ppkeys - On the policy server, the update.conf file causes cfagent to copy the master configuration files (/var/cfengine/masterfiles/inputs) to the client configuration file location (/var/cfengine/inputs). - The update.conf file also causes the cfengine executables in /usr/local/sbin/ to be copied to /var/cfengine/bin This creates a self-contained directory tree for running cfengine. - On the policy server, the cfagent.conf file specifies the actions cfengine takes. This is were "the balk of the work" is done. As the complexity of your cfengine configuration grows, you'll want to split up the cfagent.conf file into many files using the "import:" action. - On the policy server, the cfrun.hosts file lists the clients that should be updated by the cfrun command. Command Line Execution ---------------------- To "pull" the cfengine configuration and do cfengine updates, do the following: cfagent --no-splay # rather silent cfagent --inform --no-splay # informational msgs cfagent --verbose --no-splay # some debug msgs cfagent -d1 --no-splay # debug msgs cfagent -d2 --no-splay # even more debug To "push" the cfengine configuration and do cfengine updates to a single client, do the following: cfrun some_client -T # rather silent cfrun some_client -T -- --inform # informational msgs cfrun some_client -T -- --verbose # some debug msgs cfrun some_client -T -- -d1 # debug msgs cfrun some_client -T -- -d2 # even more debug To push cfengine to all clients, run the cfrun command above without the "some_client" argument. Amazingly, the commands above can (usually) be ran on any client. Running cfservd in debug mode can be helpful when trying to understand the cfengine client/server behavior... cfservd --no-fork -d # debug cfservd --no-fork -d3 # logs of debug Contact ------- If you have any questions or comments, please don't hesitate to contact me via email: rader@hep.wisc.edu. steve - - - systems & network guy high energy physics university of wisconsin $Id: OVERVIEW,v 1.3 2004/04/21 15:27:28 rader Exp $