This is cfengine-Reference.info, produced by makeinfo version 4.2 from
cfengine-Reference.texinfo.

INFO-DIR-SECTION System Utilities
START-INFO-DIR-ENTRY
* cfengine Reference: (cfengine-Reference.info).
                        Cfengine is a language based tool specifically
                        designed for configuring and maintaining BSD
                        and System-5-like operating systems attached
                        to a TCP/IP network.
END-INFO-DIR-ENTRY


File: cfengine-Reference.info,  Node: Top,  Next: Reference introduction,  Prev: (dir),  Up: (dir)

Cfengine-Reference
******************

   Copyright (C) 1995/96/97/98/99/2000 Mark Burgess

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the author instead of in
the original English.

   This manual corresponds to CFENGINE Edition 2.1.16 for version
2.1.16 as last updated 11 August 2005.

* Menu:

* Reference introduction::
* Cfkey::
* Cfshow::
* Cfagent reference::
* Cfservd.conf and cfrun reference::
* Cfexecd reference::
* Problem solving::
* Example configuration file::
* Variable Index::
* Concept Index::
* FAQ Index::


File: cfengine-Reference.info,  Node: Reference introduction,  Next: Cfkey,  Prev: Top,  Up: Top

Introduction to reference manual
********************************

   The purpose of the cfengine reference manual is to collect together
and document the raw facts about the different components of cfengine.
Once you have become proficient in the use of cfengine, you will no
longer have need of the tutorial. The reference manual, on the other
hand, changes with each version of cfengine. You will be able to use it
online, or in printed form to find out the details you require to
implement configurations in practice.

* Menu:

* Installation::
* Work directory::
* Hard classes::
* Evaluated classes and special functions::
* Filenames and paths::
* Debugging with signals::


File: cfengine-Reference.info,  Node: Installation,  Next: Work directory,  Prev: Reference introduction,  Up: Reference introduction

Installation
============

   In order to install cfengine, you should first ensure that the
following packages are installed.

OpenSSL
     Open source Secure Sockets Layer for encryption.
     URL: <http://www.openssl.org>

BerkeleyDB (version 3.2 or later)
     Light-weight flat-file database system.
     URL: <http://www.sleepycat.com>

The preferred method of installation is then

     tar zxf cfengine-x.x.x.tar.gz
     cd cfengine-x.x.x
     ./configure
     make
     make install

This results in binaries being installed in `/usr/local/sbin'.  Since
this is not necessarily a local file system on all hosts, users are
encouraged to keep local copies of the binaries on each host, inside
the cfengine trusted work directory.


File: cfengine-Reference.info,  Node: Work directory,  Next: Hard classes,  Prev: Installation,  Up: Reference introduction

Work directory
==============

   In order to achieve the desired simplifications, it was decided to
reserve a private work area for the cfengine tool-set. In cfengine 1.x,
the administrator could choose the locations of configuration files,
locks, and logging data independently. In cfengine 2.x, this diversity
has been simplified to a single directory which defaults to
`/var/cfengine' (similar to `/var/cron'):

     /var/cfengine
     /var/cfengine/bin
     /var/cfengine/inputs
     /var/cfengine/outputs

   The installation location `/usr/local/sbin' is not necessarily a
local file system, and cannot therefore be trusted to a) be present,
and b) be authentic on an arbitrary system.

   Similarly, a trusted cache of the input files must now be maintained
in the `inputs' subdirectory. When cfengine is invoked by the
scheduler, it reads only from this directory. It is up to the user to
keep this cache updated, on each host. This simplifies and consolidates
the cfengine resources in a single place. The environment variable
`CFINPUTS' still overrides this default location, as before, but in its
absence or when called from the scheduler, this becomes the location of
trusted files.  A special configuration file `update.conf' is parsed
and run before the main configuration is parsed, which is used to
ensure that the currently caches policy is up-to-date. This has private
classes and variables.  If no value is set for `CFINPUTS', then the
default location is the trusted cfengine directory
`/var/cfengine/inputs'.

   The `outputs' directory is now a record of spooled run-reports. These
are mailed to the administrator, as previously, or can be copied to
another central location and viewed in an alternative browser..


File: cfengine-Reference.info,  Node: Hard classes,  Next: Evaluated classes and special functions,  Prev: Work directory,  Up: Reference introduction

Cfengine hard classes
=====================

   A single class can be one of several things:

   * The name of an operating system architecture e.g.  `ultrix',
     `sun4', etc.  This is referred to as a _hard class_.

   * The unqualified name of a particular host. If your system returns
     a fully qualified domain name for your host, cfagent truncates it
     at the first dot.

   * The name of a user-defined group of hosts.

   * A day of the week (in the form `Monday, Tuesday, Wednesday, ..').

   * An hour of the day (in the form `Hr00, Hr01 ... Hr23').

   * Minutes in the hour (in the form `Min00, Min17 ... Min45').

   * A five minute interval in the hour (in the form `Min00_05,
     Min05_10 ... Min55_00')

   * A day of the month (in the form `Day1 ... Day31').

   * A month (in the form `January, February, ... December').

   * A year (in the form `Yr1997, Yr2004').

   * An arbitrary user-defined string.

   * The IP address octets of any active interface (in the form
     `ipv4_192_0_0_1', `ipv4_192_0_0', `ipv4_192_0', `ipv4_192').


   To see all of the classes define on a particular host, run

     host# cfagent -p -v
   as a privileged user. Note that some of the classes are set only if
a trusted link can be established with cfenvd, i.e. if both are running
with privilege, and the `/var/cfengine/env_data' file is secure.


File: cfengine-Reference.info,  Node: Evaluated classes and special functions,  Next: Filenames and paths,  Prev: Hard classes,  Up: Reference introduction

Evaluated classes and special functions
=======================================

   Cfengine provides a number of built-in functions for evaluating
classes, based on file tests. Using these built-in functions is quicker
than calling the shell `test' function. The time functions place their
arguments in chronological order.

`IsNewerThan(F1,F2)'
     True if file 2 was modified more recently than file 1 (UNIX mtime)

`AccessedBefore(F1,F2)'
     True if file 1 was accessed more recently than file 2 (UNIX atime)

`ChangedBefore(F1,F2)'
     True if file 1's attributes were changed in any way more recently
     than file 2's (UNIX ctime)

`FileExists(FILE)'
     True if the named file object exists.

`IPRange(ADDRESS-RANGE)'
     True if the current host lies within the specified IP range

`HostRange(BASENAME,START-STOP)'
     True if the current relative domain name begins with basename and
     ends with an integer between start and stop

`IsDefined(VARIABLE-ID)'
     True if the named variable is defined. Note well: use the variable
     name, not its contents (that is, `IsDefined(var)', and not
     `IsDefined(${var})')

`IsDir(F)'
     True if the file f is a directory

`IsLink(F)'
     True if the file f is a symbolic link

`IsPlain(F)'
     True if the file f is a plain file

`PrepModule(MODULE,ARG1 ARG2...)'
     True if the named module exists and can be executed. The module is
     assumed to follow the standard programming interface for modules
     (see Writing plugin modules in tutorial).  Unlike actionsequence
     modules, these modules are evaluated immediately on parsing.  Note
     that the module should be specified relative to the authorized
     module directory.

`Regcmp(REGEXP,STRING OR LIST SEPARATED STRING)'
     True if the string matched the regular expression regexp.

`ReturnsZero(COMMAND)'
     True if the named shell command returns with exit code zero
     (success).

`Strcmp(S1,S2)'
     True if the string s1 exactly matches s2

`IsGreaterThan(S1,S2)'
     Returns true if the value of s1 is greater than the value of s2.
     Note that, if the strings have numerical values, a numerical
     comparison is performed, otherwise a string comparison is used.

`IsLessThan(S1,S2)'
     Returns true if the value of s1 is less than the value of s2. Note
     that, if the strings have numerical values, a numerical comparison
     is performed, otherwise a string comparison is used.

          	control:
          
            	 actionsequence = ( files )
          
          	 a = ( 2.12 )
           	 b = ( 2.11 )
          
          	classes:
          
          	lt = ( LessThan(${a},${b}) )
             	gt = ( GreaterThan(${a},${b}) )
          
          	alerts:
          
          	  lt:: "$(a) LESS THAN $(b)"
          	  gt:: "$(a) GREATER THAN $(b)"

For example:


     classes:
     
      access_to_dir = ( ReturnsZero(/bin/cd /mydir) )
      compare       = ( ChangedBefore(/etc/passwd_master,/etc/passwd) )
      isplain       = ( IsPlain(/tmp/import) )
      inrange       = ( IPRange(128.39.89.10-15) )
      CIDR          = ( IPRange(128.39.89.10/24) )
      compute_nodes = ( HostRange(cpu-,01-32)
      gotinit       = ( PrepModule(startup2,"arg1 arg2") )


File: cfengine-Reference.info,  Node: Filenames and paths,  Next: Debugging with signals,  Prev: Evaluated classes and special functions,  Up: Reference introduction

Filenames and paths
===================

   Filenames in Unix-like operating systems

   The directory separator is the forward slash '/' character. All
references to file locations must be absolute pathnames in cfengine,
i.e. they must begin with a complete specification of which directory
they are in. For example:

     /etc/passwd
     /usr/local/masterfiles/distfile

The only place where it makes sense to refer to a file without a
complete directory specification is when searching through directories
for different kinds of file, e.g.

     tidy:
     
       /home/user pattern=core age=0 recurse=inf

Here, one can write `core' without a path, because one is looking for
any file of that name in a number of directories.

   Cfengine was implemented primarily on Unix-like operating systems,
but has since been ported to Windows operating systems and MacOS X. The
Windows operating systems traditionally use a different filename
convention.  The following are all valid absolute file names under
Windows:

      c:\winnt
      c:/winnt
      /var/cfengine/inputs
      //FILESERVER/share2/dir
   The `drive' name "C:" in Windows refers to a partition or device.
Unlike Unix, Windows does not integrate these seamlessly into a single
file-tree.  This is not a valid absolute filename:

     \var\cfengine\inputs
   Paths beginning with a backslash are assumed to be win32 paths.  They
must begin with a drive letter or double-slash server name.


File: cfengine-Reference.info,  Node: Debugging with signals,  Prev: Filenames and paths,  Up: Reference introduction

Debugging with signals
======================

   It is possible to turn debugging output on or off on a running
cfagent.  This is useful for troubleshooting the cause of hangups, or
for getting debugging output from a cfagent launched from cfexecd.

   A running cfagent process that receives a SIGUSR1 will immediately
begin to behave as if it had been invoked with the '-d2' option.  A
SIGUSR2 will cause a running cfagent to run as if the '-d2' option had
not been invoked.

   Note that this output is often quite verbose.

* Menu:

* Cfagent reference::
* Cfservd.conf and cfrun reference::
* Cfexecd reference::
* Problem solving::
* Example configuration file::
* Variable Index::
* Concept Index::
* FAQ Index::


File: cfengine-Reference.info,  Node: Cfkey,  Next: Cfshow,  Prev: Reference introduction,  Up: Top

Cfkey reference
***************

   The very first thing you should do on every host is to establish a
public-private key pair. To do this, you need to run the program

     everyhost# cfkey

on every host. This program needs to produce random numbers, and needs a
source of randomness. A good strategy is to install and run the
`cfenvd' program for a week or two in advance of deploying cfengine 2,
since `cfenvd' collects random events, which are an excellent source of
entropy for random number generation.

   If you get the error message "PRNG not seeded", it means that
insufficient data were found in order to make a random key. In that
case, run `cfenvd' for a few days more and try again.

* Menu:

* Cfagent reference::
* Cfservd.conf and cfrun reference::
* Cfexecd reference::
* Problem solving::
* Example configuration file::
* Variable Index::
* Concept Index::
* FAQ Index::


File: cfengine-Reference.info,  Node: Cfshow,  Next: Cfagent reference,  Prev: Cfkey,  Up: Top

Cfshow reference
****************

   The `cfshow' command was introduced in cfengine 2.1.11 in order to
provide a simple way to show some of the data stored by cfagent for
operational purposes.

     everyhost# cfshow -a
     everyhost# cfshow -l
     everyhost# cfshow -c
     everyhost# cfshow -s

The command line options are

`-a `--active''
     This prints a list of any currently active locks, i.e. tasks that
     cfengine believes it is currently enagaged in.

`-l `--locks''
     This prints a list of the locks and the last times an active lock
     was secured for each cfengine acivity. This list is potentially
     very long.

`-s `--last-seen''
     This lists the IP addresses of all known peers and the times they
     were last engaged in communication with the current host. The
     expected interval between communications is also printed. See
     FriendStatus. The output format is in a form that can easily be
     parsed by user scripts. e.g.

          192.0.2.1 (answered us) at [Wed May 26 16:39:03 2004] i.e. not seen for !2860.08! hours; <delta_t> = {63325.64} hours
          192.0.2.3 (answered us) at [Wed May 26 16:39:03 2004] i.e. not seen for !2860.08! hours; <delta_t> = {90465.20} hours

`-c `--checksum''
     This lists all of the files and their current checksum values in
     the current checksum database.

* Menu:

* Cfagent reference::
* Cfservd.conf and cfrun reference::
* Cfexecd reference::
* Problem solving::
* Example configuration file::
* Variable Index::
* Concept Index::
* FAQ Index::


File: cfengine-Reference.info,  Node: Cfagent reference,  Next: Cfservd.conf and cfrun reference,  Prev: Cfshow,  Up: Top

Cfagent reference
*****************

* Menu:

* Cfagent intro::
* Variable expansion and contexts::
* Cfengine classes::
* acl::
* alerts::
* binservers::
* broadcast::
* control::
* classes::
* copy::
* defaultroute::
* disks::
* directories::
* disable::
* editfiles::
* files::
* filters::
* groups::
* homeservers::
* ignore::
* import::
* interfaces::
* links::
* mailserver::
* methods::
* miscmounts::
* mountables::
* processes::
* packages::
* rename::
* required::
* resolve::
* shellcommands::
* strategies::
* tidy::
* unmount::


File: cfengine-Reference.info,  Node: Cfagent intro,  Next: Variable expansion and contexts,  Prev: Cfagent reference,  Up: Cfagent reference

Cfagent intro
=============

   Cfagent is the workhorse of cfengine. It interprets and computes the
necessary strategies for implementing convergent maintenance. In order
to carry out work efficiently, the agent groups similar actions
together. The order of these actions is goverened by a list called the
actionsequence.

   In many cases, cfagent will be able to complete all its work in a
single pass of the actionsequence. However, in complex configurations,
it is hard to resolve all of the ordering dependencies automatically in
a single pass. Cfagent keeps track both of all actions that have been
performed and of those that might still need to be performed (given that
some actions depend on the later outcomes of others). If there is a
possibility that an action ordering dilemma might occur, it runs a
second pass of the actionsequence to more quickly resolve the dependency
(avoiding the wait for next scheduled run).  No actions are performed
twice however, since the agent checks off actions that have already been
performed to avoid unnecessary duplication.

* Menu:

* The file cfagent.conf::
* Cfagent Runtime Options::


File: cfengine-Reference.info,  Node: The file cfagent.conf,  Next: Cfagent Runtime Options,  Prev: Cfagent intro,  Up: Cfagent intro

The file cfagent.conf
---------------------


      control:
     
        CLASSES::
     
            domain = ( DNS-DOMAIN-NAME )
     
      classes:
     
        CLASS/GROUP DEFINITIONS
     
      import:
     
        FILES TO IMPORT
     
      # other items



File: cfengine-Reference.info,  Node: Cfagent Runtime Options,  Prev: The file cfagent.conf,  Up: Cfagent intro

Cfagent runtime options
-----------------------

Note that GNU long options are available with the syntax
`--longoption'.  The long names are given in brackets.

`-a'
     (`--sysadm') Print only the name of the system administrator then
     quit.

`-A'
     (`--auto') Can be used to signify an automatic run of cfengine, as
     opposed to a manual run. The distinction is not predetermined. Use
     of this option currently causes cfengine to ignore locks. This
     option is reserved for future development.

`-b'
     (`--force-net-copy') Normally cfengine detects attempts to copy
     from a server via the network that will loop back to the localhost.
     It then avoids using the network to make the copy. This option
     forces cfengine to copy using the network. _Yes, someone thinks
     this is useful!_

`-c'
     (`--no-check-files') Do not check file systems for ownership /
     permissions etc.

`-C'
     (`--no-check-mounts') Check mount points for consistency.  If this
     option is specified then directories which lie in the "mount point"
     area are checked to see whether there is anything mounted on them.
     Normally this is _off_ since not all machines use mounted file
     systems in the same way.  e.g.  HPUX does not generally operate
     with partitions, but nevertheless one might wish to mimick a
     partition-like environment there, but it would be irritating to be
     informed that nothing was mounted on the mount point.

`-d'
     (`--debug') Enable debugging output.  Normally you will want to
     send this to a file using the shell script command or a pipe.
     -d1 shows only parsing output.  -d2 shows only runtime action
     output.  -d0 shows both levels. Debugging ouput is intended mainly
     for the author's convenience and is not a supported feature. The
     details of this output may change at any time.

`-D'
     (`--define') Define a compound class symbol of the form
     _alpha.beta.gamma_.

`-e'
     (`--no-edits') Suppress file editing.

`-E'
     (`--enforce-links') Globally force links to be created where plain
     files or links already exist. Since this option is a big hammer,
     you have to use it in interactive mode and answer a yes/no query
     before cfengine will run like this.

`-f'
     (`--file') Parse filename after this switch.  By default cfengine
     looks for a file called _cfengine.conf_ in the current directory.

`-h'
     (`--help') Help information.  Display version banner and options
     summary.

`-H'
     (`--no-hard-classes'). Prevents cfengine from generating any
     built-in class name information. Can be used for emulation
     purposes.

`-i'
     (`--no-ifconfig') Do not attempt to configure the local area
     network interface.

`-I'
     (`--inform') Switches on the inform output level, whereby cfengine
     reports everything it changes..

`-k'
     (`--no-copy') Do not copy/image any files.

`-K'
     (`--no-lock') Ignore locks when running.

`-l'
     (`--traverse-links') Normally cfengine does not follow symbolic
     links when recursively parsing directories.  This option will
     force it to do so.

`-L'
     (`--delete-stale-links') Delete links which do not point to
     existing files (except in user home directories, which are not
     touched).

`-m'
     (`--no-mount') Do not attempt to mount file systems or edit the
     filesystem table.

`-M'
     (`--no-modules') Ignore modules in actionsequence.

`-n'
     (`--recon',`--dry-run',`--just-print') No action.  Only print what
     has to be done without actually doing it.

`-N'
     (`--negate',`--undefine') Cancel a set of classes, or undefine
     (set value to _false_) a compound class of the form
     _alpha.beta.gamma_.

`-p'
     (`--parse-only') Parse file and then stop.  Used for checking the
     syntax of a program.  You do not have to be superuser to use this
     option.

`-q'
     (`--no-splay') Switch off host splaying (sleeping).

`-Q'
     (`--quert') Query the values of the comma separated list of
     variable names.

`-s'
     (`--no-commands') Do not execute scripts or shell commands.

`-S'
     (`--silent') Silence run time warnings.

`-t'
     (`--no-tidy') Do not tidy file systems.

`-u'
     (`--use-env') Causes cfengine to generate an environment variable
     `CFALLCLASSES' which can be read by child processes (scripts). This
     variable contains a summary of all the currently defined classes
     at any given time. This option causes some System V systems to
     generate a Bus Error or segmentation fault. The same information
     is available from the cfengine built-in variable `$(allclasses)'
     and can be passed as a parameter to scripts.

`-U'
     (`--underscore-classes'). When this option is set, cfengine adds
     an underscore to the beginning of the hard system classes (like
     `_sun4', `_linux' etc. The longer compound classes are not
     underscored, since these are already complex and would unlikely
     result in collisions.) This can be used to avoid naming conflicts
     if you are so unjudicious as to name a host by the name of a hard
     class. Other classes are not affected.

`-v'
     (`--verbose') Verbose mode.  Prints detailed information about
     actions and state.

`-V'
     (`--version') Print only the version string and then quit.

`-x'
     (`--no-preconf') Do not execute the `cf.preconf' net configuration
     file.

`-X'
     (`--no-links') Do not execute the `links' section of a program.

`-w'
     (`--no-warn',`--quiet') Do not print warning messages.

`-z'
     (`--schedule') Print the exec schedule for the LAN (used by
     cfexecd).

   In version 2.0.4, an abbreviation for actionsequence exclusions was
added:

     $ cfagent --avoid resolve,copy
     $ cfagent --just tidy --just shellcommands


File: cfengine-Reference.info,  Node: Variable expansion and contexts,  Next: Cfengine classes,  Prev: Cfagent intro,  Up: Cfagent reference

Variable expansion and contexts
===============================

   Variables in cfengine 2 are defined in contexts. Variables in a
given context refer to the different phases of execution of cfengine:
global, update and main.  In the "current" context, variables have the
form

     $(variable) ${variable}
   and are expanded either on parsing or at execution. Variables that
cannot be expanded remain as dollar strings. Variables belonging to a
context that is not the current one may be referred to as

     $(CONTEXT.variable) ${CONTEXT.variable}
   e.g.

     $(global.env_time)
   Some variables in cfengine are associative arrays (as made famous by
Perl).  Such arrays are referred to by square brackets:


     $(array[key])  $(array[$(key)])

and so on. Note carefully that cfengine requires parentheses or braces
around variable names. Unlike in the shell, they cannot be omitted.

* Menu:

* Setting variables with functions::
* Special variables::
* Iteration over lists::


File: cfengine-Reference.info,  Node: Setting variables with functions,  Next: Special variables,  Prev: Variable expansion and contexts,  Up: Variable expansion and contexts

Setting variables with functions
--------------------------------

   A number of special functions can be used to set variables in
cfengine.  You can import values from the execution of a shell command
by prefixing a command with the word `exec'. This method is deprecated
as of cfengine version 2; use the `ExecResult' function instead.


       control:
     
        # old method
     
        listing = ( "exec /bin/ls -l" )
     
        # new method
     
        listing = ( ExecResult(/bin/ls -l) )

This sets the variable `listing' to the output of the command in the
quotes.

   Some other built-in functions are

`A(X,Y)'
     Makes an associative array entry, associating X and Y. For
     instance:

          control:
          
           assoc_array = ( A(B,"is for bird") A(C,"is for cat") )

     results in:


          OBJECT: main
             4569 : assoc_array[B]=is for bird
             4630 : assoc_array[C]=is for cat
     Another example:

          control:
          
           binhost = ( A(linux,machine1) A(solaris,machine2) )
          
          copy:
          
           # Contact machine 1 for linux
           # Contact machine 2 for solaris
          
           /etc/source dest=/etc/receve server=$(binhost[$(class)])

`ExecResult(COMMAND)'
     Executes the named shell command and inserts the output into the
     variable. Note that, when this is used in cfengine built-in list
     variables, any spaces are interpreted as list separators. In other
     lists, normal rules for iteration apply.

`RandomInt(A,B)'
     Generate a random integer between a and b.

`ReadArray(FILENAME,FILEFORMAT,SEPARATOR,COMMENT,MAX NUMBER OF BYTES)'
     Reads up to a maximum number of bytes from a properly formatted
     file into a one-dimensional associated array. File formats are:
    `autokey'
          If this format is specified, `ReadArray' tries to interpret
          the file as a table of items separated with the separator
          character. Blank lines and comments (to end of line) are
          ignored.  Items are keyed numerically starting from 1 to the
          maximum number in the file.  The newline `$(n)' is always
          considered to be a separator, no matter what the current
          separator is.

    `textkey'
          If this format is specified, `ReadArray' tries to interpret
          the file as a list of lines of the form:

                 key,value

`ReadFile(FILENAME,MAX NUMBER OF BYTES)'
     Read a maximum number of bytes from a file.

`ReadTable(FILENAME,FILEFORMAT,SEPARATOR,COMMENT,MAX NUMBER OF BYTES)'
     Reads up to a maximum number of bytes from a properly formatted
     file into a two-dimensional associated array.
    `autokey'
          If this format is specified, `ReadArray' tries to interpret
          the file as a table of items separated with the separator
          character. Blank lines and comments (to end of line) are
          ignored.  Items are keyed numerically starting from 1 to the
          maximum number in the file.  Any lines that do not contain
          the correct number of separators cause the function to fail
          without making any assignment.

    `textkey'
          If this format is specified, `ReadArray' tries to interpret
          the file as a list of lines of the form:

                 key1,key2,,value

`ReadList(FILENAME,FILEFORMAT,COMMENT,MAX NUMBER OF BYTES)'
     Reads up to a maximum number of bytes from a properly formatted
     file into a listvariable. File formats are:
    `lines'
          If this format is specified, `ReadList' tries to interpret
          the file as a list of items on separate lines. The value
          returned is a list formatted by the `Split' character.


          hosts = ( ReadList(/var/cfengine/inputs/datafile,lines,#,1000) )

`ReadTCP(HOST/IP,PORTNUMBER,SEND STRING,MAX NUMBER OF BYTES)'
     Reads up to a maximum number of bytes from a TCP service. Can be
     used to test whether certain services are responding to queries.
     It is recommended that this be used primarily to check services
     running on localhost. Bear in mind that this clause, executed on
     100 hosts will produce the effect of a distributed denial of
     service attack, so the probe should be restricted to a single
     representative tester-host. For example:


          one_host_only::
          
           # USE WITH CAUTION !
          
           probewww = ( ReadTCP(localhost,80,'GET index.html',1000) )
     Or testing a network service:
          control:
          
           checkhost::
          
           probesmtp = ( ReadTCP(localhost,25,"",1024) )
           probewww  = ( ReadTCP(project.iu.hio.no,80,"GET /viewcvs HTTP/1.0 ${n}${n}",1024) )
          
          classes:
          
            viewcvs_error = ( RegCmp(".*Python Traceback.*","${probewww}") )
          
          alerts:
          
            viewcvs_error::
          
               "Received viewcvs error from web server"

`SelectPartitionGroup(FILENAME,COMMENT,POLICY,GROUP SIZE)'
     This function is for use in peer to peer monitoring applications.
     It allows individual hosts to identify themselves as part of a
     group and find their peers. The function returns a list variable,
     delimited by the list separation character, for use with Split.


           control:
          
             allpeers = ( SelectPartitionGroup(/var/cfengine/inputs/cfrun.hosts,#,random,4) )
          
           copy:
          
             /data/file dest=/p2prepository/file server=$(allpeers)

`SelectPartitionLeader(FILENAME,COMMENT,POLICY,GROUP SIZE)'
     This function is for use in peer to peer monitoring applications.
     It allows individual hosts to identify themselves as part of a
     group and select a leader.  This function reads a text file of
     hostnames or IP addresses, one host per line, with blank lines and
     comments and partitions it into groups of a fixed size. It then
     returns picks a leader for the the group and returns its name as
     the value of the function.


           control:
          
             leader = ( SelectPartitionLeader(/var/cfengine/inputs/cfrun.hosts,#,random,4) )
          
           copy:
          
             /data/file dest=/p2prepository/file server=$(leader)

   Note that functions should have no spaces between the function name
and the leading parenthesis, but should themselves be surrounded by
white space.

For example:


     control:
     
      variable2 = ( RandomInt(0,23) )
     
      variable3 = ( ExecResult(/bin/ls -a /opt) )
     
      myexcerpt  = ( ReadFile("/etc/services",220) )
     
      listvar = ( ReadArray(/tmp/array,textkey,",","#",100) )

   In the latter case, the file could look like this:

     host$ more /tmp/array
     one,String to tbe read
     two,Nothing string
     three,Everything comes in threes

and results in the definition of (verify with `cfagent -p -d3'):

     OBJECT: main
        960 : listvar[one]=String to tbe read
        259 : listvar[two]=Nothing string
        224 : listvar[three]=Everything comes in threes

* Menu:

* Special variables::
* Iteration over lists::


File: cfengine-Reference.info,  Node: Special variables,  Next: Iteration over lists,  Prev: Setting variables with functions,  Up: Variable expansion and contexts

Special variables
-----------------

   Variables are referred to in either of two different ways, depending
on your taste.  You can use the forms `$(variable)' or `${variable}'.
The variable in braces or parentheses can be the name of any user
defined macro, environment variable or one of the following special
built-in variables.

`AllClasses'
     A long string in the form `CFALLCLASSES=class1:class2...'.  This
     variable is a summary of all the defined classes at any given
     time. It is always kept up to date so that scripts can make use of
     cfengine's class data.

`arch'
     The current detailed architecture string--an amalgamation of the
     information from _uname_. _A constant_.

`binserver'
     The default server for binary data. _A constant_.

`ChecksumDatabase'
     If set to the name of a file, cfagent will use this to store
     checksums of important files, and give `tripwire functionality',
     *Note ChecksumDatabase::.

`ChecksumUpdates'
     If set to `on', security information is automatically updated,
     *Note ChecksumUpdates::.

`class'
     The currently defined system hard-class (e.g. `sun4', `hpux'). _A
     constant_.

`date'
     The current date string. Note that if you use this in a shell
     command it might be interpreted as a list variable, since it
     contains the default separator `:'.

`domain'
     The currently defined domain.

`EmailFrom'
     The email address from whom email from cfexecd should appear to
     originate.

`EmailMaxLines'
     Most lines of output to email from a single cfexecd-induced run of
     cfagent. If undefined, defaults to 100. If set to 0, no email is
     sent by cfexecd. If set to `inf', no maximum is enforced.

`EmailTo'
     The E-mail address to whom mail should be sent (overrides `sysadm'
     variable).

`faculty'
     The faculty or site as defined in control (see `site').

`fqhost'
     The fully qualified hostname of the system.

`host'
     The hostname of the machine running the program.

`ipaddress'
     The numerical form of the Internet address of the host currently
     running cfengine found by a reverse lookup in DNS.

`ipv4[INTERFACE]'
     The IPv4 address of the named interface as determined from a probe
     of the interfaces. This variable belongs in the global context and
     refers to as in the following examples:


          ${global.ipv4[hme0]}
          ${global.ipv4[eth0]}

`MaxCfengines'
     The maximum number of cfengines which should be allowed to run
     concurrently on the system. This can prevent excessive load due to
     unintentional spamming in situations where several cfengines are
     started independently. The default value is unlimited.

`ostype'
     A short for of `$(arch)'.

`OutputPrefix'
     This quoted string can be used to change the default `cfengine:'
     prefix on output lines to something else. You might wish to shorten
     the string, or have a different prefix for different hosts. The
     value in this variable is appended with the name of the host. The
     default is equivalent to,

            OutputPrefix = ( "cfengine:$(host):")

`RepChar'
     The character value of the string used by the file repository in
     constructing unique filenames from path names. This is the
     character which replaces `/'.

`site'
     This variable is identical to `$(faculty)' and may be used
     interchangeably.

`smtpserver'
     The name of the host to which mail output should be sent.

`split'
     The character on which list variables are split.

`sysadm'
     The name or mail address of the system administrator.

`timezone'
     The current timezone as defined in `control'.

`UnderscoreClasses'
     If this is set to `on' cfengine uses hard classes which begin with
     an underscore to avoid name collisions. See also the section
     Runtime Options.

`version'
     The current version string as defined in the code.

`year'
     The current year.

These variables are kept special because they play a special role in
setting up a system configuration.  You are encouraged to use them to
define fully generalized rules in your programs.  Variables can be used
to advantage in defining filenames, directory names and in passing
arguments to shell commands.  The judicious use of variables can reduce
many definitions to a single one if you plan carefully.

   _NOTE: the above control variables are not case sensitive, unlike
user macros, so you should not define your own macros with these names._


   The following variables are also reserved and may be used to produce
troublesome special characters in strings.
`cr'
     Expands to the carriage return character.

`colon'
     Expands to the colon `:' character.

`dblquote'
     Expands to a double quote `"'

`dollar'
     Expands to `$'.

`lf'
     Expands to a line-feed character (Unix end of line).

`n'
     Expands to a newline character.

`quote'
     Expands to a single quote `''.

`spc'
     Expands simply to a single space. This can be used to place spaces
     in filenames etc.

`tab'
     Expands to a single tab character.


File: cfengine-Reference.info,  Node: Iteration over lists,  Prev: Special variables,  Up: Variable expansion and contexts

Iteration over lists
--------------------

   Variables can be used as iterators in some situations. Iteration
over lists is currently rather limited in cfengine and is something to
be improved on in a future version. When a variable is used as an
iterator, a character is chosen to represent a list separator, as in
the shell `IFS' variable.  The default separator is the colon `:'
character:

     control:
     
      listvar = ( one:two:three:four )
   The action that contains a variable to be interpreted as a list
appears as separate actions, one for each case:

     shellcommand:
     
       "/bin/echo $(listvar)"
   is equivalent to

     shellcommand:
     
       "/bin/echo one"
       "/bin/echo two"
       "/bin/echo three"
       "/bin/echo four"
   If multiple iterators are used, these are handled as nested loops:

     cfengine::/bin/echo one 1:     one 1
     cfengine::/bin/echo one 2:     one 2
     cfengine::/bin/echo one 3:     one 3
     cfengine::/bin/echo one 4:     one 4
     cfengine::/bin/echo two 1:     two 1
     cfengine::/bin/echo two 2:     two 2
     cfengine::/bin/echo two 3:     two 3
     cfengine::/bin/echo two 4:     two 4
     cfengine::/bin/echo three:     three 1
     cfengine::/bin/echo three:     three 2
     cfengine::/bin/echo three:     three 3
     cfengine::/bin/echo three:     three 4
     cfengine::/bin/echo four :     four 1
     cfengine::/bin/echo four :     four 2
     cfengine::/bin/echo four :     four 3
     cfengine::/bin/echo four :     four 4
   Where iterators are not allowed, the implied lists are treated as
scalars:


     alerts:
     
      amnexus::
     
       "do $(list1) $(list2)"
   e.g.


     cfengine:: do one:two:three:four 1:2:3:4

   Iterative expansion is currently restricted to:
   * In the directory field of the admit/deny server access rules,

   * In the `from' field of a copy action,

   * In the server field of the copy action,

   * In the directory field of the disable action,

   * In the directory field of the files action,

   * In the `to' field of a multiple link action,

   * In the directory field of the required/disk action,

   * In a resolve item.

   * In the directory field of a tidy action,

   * Names in the ignore action.



File: cfengine-Reference.info,  Node: Cfengine classes,  Next: acl,  Prev: Variable expansion and contexts,  Up: Cfagent reference

Cfengine classes
================

   A _cfengine action_ looks like this:


     ACTION-TYPE:
     
        COMPOUND-CLASS::
     
            DECLARATION

A single class can be one of several things:

   * The name of an operating system architecture e.g.  `ultrix',
     `sun4', etc.  This is referred to as a _hard class_.

   * The unqualified name of a particular host. If your system returns
     a fully qualified domain name for your host, cfagent truncates it
     at the first dot.

   * The name of a user-defined group of hosts.

   * A day of the week (in the form `Monday, Tuesday, Wednesday, ..').

   * An hour of the day (in the form `Hr00, Hr01 ... Hr23').

   * Minutes in the hour (in the form `Min00, Min17 ... Min45').

   * A five minute interval in the hour (in the form `Min00_05,
     Min05_10 ... Min55_00')

   * A quart hour (in the form `Q1, Q2, Q3, Q4')

   * An abbreviated time with quarter hour specified (in the form
     `Hr00_Q1, Hr23_Q4' etc.)

   * A day of the month (in the form `Day1 ... Day31').

   * A month (in the form `January, February, ... December').

   * A year (in the form `Yr1997, Yr2004').

   * An arbitrary user-defined string.

   * The IP address octets of any active interface (in the form
     `ipv4_192_0_0_1', `ipv4_192_0_0', `ipv4_192_0', `ipv4_192').


   A compound class is a sequence of simple classes connected by dots or
`pipe' symbols (vertical bars).  For example:


     myclass.sun4.Monday::
     
     sun4|ultrix|osf::

A compound class evaluates to `true' if all of the individual classes
are separately true, thus in the above example the actions which follow
`compound_class::' are only carried out if the host concerned is in
`myclass', is of type `sun4' and the day is Monday!  In the second
example, the host parsing the file must be either of type `sun4' _or_
`ultrix' _or_ `osf'.  In other words, compound classes support two
operators: AND and OR, written `.' and `|' respectively.   From
cfengine version 2.1.1, I bit the bullet and added `&' as a synonym for
the AND operator.  Cfengine doesn't care how many of these operators
you use (since it skips over blank class names), so you could write
either


     solaris|irix::

or


     solaris||irix::

depending on your taste. On the other hand, the order in which cfengine
evaluates AND and OR operations _does_ matter, and the rule is that AND
takes priority over OR, so that `.' binds classes together tightly and
all AND operations are evaluated before ORing the final results
together. This is the usual behaviour in programming languages. You can
use round parentheses in cfengine classes to override these preferences.

   Cfengine allows you to define switch on and off dummy classes so that
you can use them to select certain subsets of action.  In particular,
note that by defining your own classes, using them to make compound
rules of this type, and then switching them on and off, you can also
switch on and off the corresponding actions in a controlled way.  The
command line options `-D' and `-N' can be used for this purpose.  See
also `addclasses' in the Reference manual.

   A logical NOT operator has been added to allow you to exclude
certain specific hosts in a more flexible way. The logical NOT operator
is (as in C and C++) `!'. For instance, the following example would
allow all hosts except for `myhost':

        ACTION:
     
         !myhost::
     
             COMMAND

and similarly, so allow all hosts in a user-defined group `mygroup',
_except_ for `myhost', you would write

        ACTION:
     
         mygroup.!myhost::
     
             COMMAND

which reads `mygroup AND NOT myhost'. The NOT operator can also be
combined with OR. For instance


        CLASS1|!CLASS2

would select hosts which were either in class 1, or those which were
not in class 2.

   Finally, there is a number of reserved classes.  The following are
hard classes for various operating system architectures.  They do not
need to be defined because each host knows what operating system it is
running.  Thus the appropriate one of these will always be defined on
each host.  Similarly the day of the week is clearly not open to
definition, unless you are running cfengine from outer space.  The
reserved classes are:

     ultrix, sun4, sun3, hpux, hpux10, aix, solaris, osf, irix4, irix, irix64
        sco, freebsd, netbsd, openbsd, bsd4_3, newsos, solarisx86, aos,
               nextstep, bsdos, linux, debian, cray, unix_sv, GnU, NT

If these classes are not sufficient to distinguish the hosts on your
network, cfengine provides more specific classes which contain the name
and release of the operating system. To find out what these look like
for your systems you can run cfengine in `parse-only-verbose' mode:


       cfagent -p -v

and these will be displayed. For example, Solaris 2.4 systems generate
the additional classes `sunos_5_4' and `sunos_sun4m', `sunos_sun4m_5_4'.

   Cfengine uses both the unqualified and fully host names as classes.
Some sites and operating systems use fully qualified names for their
hosts. i.e. `uname -n' returns to full domain qualified hostname. This
spoils the class matching algorithms for cfengine, so cfengine
automatically truncates names which contain a dot `.'  at the first `.'
it encounters. If your hostnames contain dots (which do not refer to a
domain name, then cfengine will be confused. The moral is: don't have
dots in your host names! _NOTE: in order to ensure that the fully
qualified name of the host becomes a class you must define the domain
variable._ The dots in this string will be replaced by underscores.

   In summary, the operator ordering in cfengine classes is as follows:

`()'
     Parentheses override everything.

`!'
     The NOT operator binds tightest.

`. &'
     The AND operator binds more tightly than OR.

`|'
     OR is the weakest operator.


File: cfengine-Reference.info,  Node: acl,  Next: alerts,  Prev: Cfengine classes,  Up: Cfagent reference

acl
===


        acl:
     
           CLASS::
     
              { ACL-ALIAS
     
              ACTION
              }

Cfengine's `ACL' feature is a common interface for managing filesystem
access control lists (ACLs). An access control list is an extended file
permission. It allows you to open or close a file to a named list of
users (without having to create a group for those users); similarly, it
allows you to open or close a file for a list of groups.  Several
operating systems have access control lists, but each typically has a
different syntax and different user interface to this facility, making
it very awkward to use.  This part of a cfengine configuration
simplifies the management of ACLs by providing a more convenient user
interface for controlling them and--as far as possible--a common syntax.

   An ACL may, by its very nature, contain a lot of information.
Normally you would set ACLs in a `files' command, *Note files::, or a
`copy' command, *Note copy::. It would be too cumbersome to repeat all
of the information in every command in your configuration, so cfengine
simplifies this by first associating an alias together with a complex
list of ACL information. This alias is then used to represent the whole
bundle of ACL entries in a `files' or `copy' command.  The form of an
ACL is similar to the form of an `editfiles' command.  It is a bundle
of information concerning a file's permissions.


      { ACL-ALIAS
     
       method:overwrite/APPEND
       fstype:POSIX/SOLARIS/DFS/AFS/HPUX/NT
     
       ACL_TYPE:USER/GROUP:PERMISSIONS
       ACL_TYPE:USER/GROUP:PERMISSIONS
       ...
      }

The name ACL-ALIAS can be any identifier containing alphanumeric
characters and underscores. This is what you will use to refer to the
ACL entries in practice. The method entry tells cfengine how to
interpret the entries: should a file's ACLs be overwritten or only
adjusted?  Since the filesystems from different developers all use
different models for ACLs, you must also tell cfengine what kind of
filesystem the file resides on. Currently only Solaris and DCE/DFS ACLs
are implemented.

   NOTE: if you set both file permissions and ACLs the file permissions
override the ACLs.

* Menu:

* ACEs::
* Solaris ACLs::
* DFS ACLs::
* NT ACLs::
* ACL Example::

