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: ACEs,  Next: Solaris ACLs,  Prev: acl,  Up: acl

Access control entries
----------------------

   An access control list is build of any number of individual access
control entries (ACEs). The ACEs has the following general syntax:

         ACL_TYPE:USER/GROUP:PERMISSIONS

The user or group is sometimes referred to as a _key_.

   For an explanation of ACL types and their use, refer to your local
manual page.  However, note that for each type of filesystem, there are
certain entries which must exist in an ACL. If you are creating a new
ACL from scratch, you must specify these.  For example, in Solaris ACLs
you must have entries for `user', `group' and `other'.  Under DFS you
need what DFS calls a `user_obj', `group_obj' and an `other_obj', and
in some cases `mask_obj'. In cfengine syntax these are called
`user:*:', `other:*:' and `mask:*:', as described below.  If you are
appending to an existing entry, you do not have to re-specify these
unless you want to change them.

   Cfengine can overwrite (replace) or append to one or more ACL
entries.

`overwrite'
     `method:overwrite' is the default. This sets the ACL according to
     the specified entries which follow.  The existing ACL will be
     overwritten completely.

`append'
     `method:append' adds or modifies one or more specified ACL entries.
     If an entry already exists for the specified type and user/group,
     the specified permission bits will be added to the old
     permissions. If there is no ACL entry for the given type and
     user/group, a new entry will be appended.

If the new ACL exactly matches the existing ACL, the ACL is not
replaced.

   The individual bits in an ACE may be either added subtracted or set
equal to a specified mask. The `+' symbol means add, the `-' symbol
subtract and `=' means set equal to.  Here are some examples:


       ACLTYPE:ID/*:MASK
     
       user:mark:+rx,-w
       user:ds:=r
       user:jacobs:noaccess
       user:forgiven:default
     
       user:*:rw
       group:*:r
       other:*:r

The keyword `noaccess' means set all access bits to zero for that user,
i.e. remove all permissions. The keyword `default' means remove the
named user from the access crontrol list altogether, so that the
default permissions apply. A star/asterisk in the centre field
indicates that the user or group ID is implicitly specified as of the
owner of the file, or that no ID is applicable at all (as is the case
for `other').


File: cfengine-Reference.info,  Node: Solaris ACLs,  Next: DFS ACLs,  Prev: ACEs,  Up: acl

Solaris ACLs
------------

   Under Solaris, the ACL type can be one of the following:

             user
             group
             mask
             other
             default_user
             default_group
             default_mask
             default_other

A user or group can be specified to the user, group, default_user and
default_group types.  Solaris ACL permissions are the normal UNIX
permissions bits `rwx', where:

         
             R - GRANTS READ PRIVILEGES.
             W - GRANTS WRITE PRIVILEGES.
             X - GRANTS EXECUTE PRIVILEGES.


File: cfengine-Reference.info,  Node: DFS ACLs,  Next: NT ACLs,  Prev: Solaris ACLs,  Up: acl

DFS ACLs
--------

In DCE, the ACL type can be one of the following:

             other
             mask
             any
             unauthenticated
             user
             group
             foreign_other
             foreign_user
             foreign_group

The `user', `group', `foreign_user' and `foreign_group'  types require
that you specify a user or group. The DCE documentation refers to types
`user_obj', `group_obj' and so on. In the cfengine implementation, the
ugly `_obj' suffix has been dropped to make these more in keeping with
the POSIX names. `user_obj::', is equivalent to `user:*:' is cfengine.
The star/asterisk implies that the ACL applies to the owner of the file
object.

   DFS permissions are comprised of the bits `crwxid', where:

             c - Grants control privileges, to modify an acl.
             r - Grants read  privileges.
             w - Grants write privileges.
             x - Grants execute privileges.
             i - Grants insert privileges.
             d - Grants delete privileges.

See the DCE/DFS documentation for more information about this.

   It is not possible to set ACLs in foreign cells currently using
cfengine, but you can still have all of your ACL definitions in the same
file. You must however arrange for the file to be executed on the server
for the cell concerned.  Note also that you must perform a DCE login
(normally as user `cell_admin') in order to set ACLs on files which are
not owned by the owner of the cfengine-process.  This is because you
must have a valid security ticket.


File: cfengine-Reference.info,  Node: NT ACLs,  Next: ACL Example,  Prev: DFS ACLs,  Up: acl

NT ACLs
-------

   NT ACEs are written as follows:

            acl_type:user/group:permissions:accesstype

   The actual change consists of the extra field containing the access
type. A star/asterisk in the field for USER/GROUP would normally imply
that the ACL applies to the owner of the file object. However this
functionality is as of today not yet implemented.

   In NT, the ACL type can be one of the following:

                user
                group
   Both types require that you specify the name of a user or a group.

   NT permissions are comprised of the bits `rwxdpo', where:

         r - Read privileges
         w - Write privileges
         x - Execute privileges
         d - Delete privileges
         p - Privileges to change the permissions on the file
         o - Privileges to take ownership of the file
   In addition to any combination of these bits, the word `noaccess' or
`default' can be used as explained in the previous section. NT comes
with some standard, predefined permissions. The standards are only a
predefined combination of the different bits specified above and are
provided with cfengine as well. You can use the standards by setting the
permission to `read', `change' or `all'. The bit implementation of each
standard is as on NT:

                read   - rx
                change - rwxd
                all    - rwxdpo
   where the bits follow the earlier definition. The keywords mentioned
above can only be used alone, and not in combination with `+', `-', `='
and/or other permission bits.

   NT defines several different access types, of which only two are
used in connection with the ACL type that is implemented in cfengine
for NT. The access type can be one of the following:

                allowed
                denied
   Intuitively, `allowed' access grants the specified permissions to
the user, whilst `denied' denies the user the specified permissions. If
no access type is specified, the default is `allowed'. This enables
cfengine's behaviour as on UNIX systems without any changes to the
configuration file. If the permissions `noaccess' or `default' is used,
the access type will be irrelevant.

ACL Example
===========

   Here is an example of a configuration file for an NT ACL:

     control:
             actionsequence = ( files )
             domain = ( iu.hioslo.no )
     
     files:
             $(HOME)/tt    acl=acl_alias1    action=fixall
     
     acl:
             { acl_alias1
     
             method:overwrite
             fstype:nt
     
             user:gustafb:rwx:allowed
             user:mark:all:allowed
             user:toreo:read:allowed
             user:torej:default:allowed
             user:ds2:+rwx:allowed
     
             group:dummy:all:denied
             group:iu:read:allowed
             group:root:all:allowed
             group:guest:dpo:denied
             }


File: cfengine-Reference.info,  Node: ACL Example,  Prev: NT ACLs,  Up: acl

ACL Example
-----------

   Here is an example of a configuration file for one Solaris ACL and
one DCE/DFS ACL:

     control:
             actionsequence = ( files )
             domain = ( iu.hioslo.no )
     
     files:
             $(HOME)/tt    acl=acl_alias1    action=fixall
             /:/bigfile    acl=acl_alias2    action=fixall
     
     acl:
             { acl_alias1
     
             method:overwrite
             fstype:posix
     
             user:*:rwx
             user:mark:=rwx
             user:sowille:=rx
             user:toreo:=rx
             user:torej:default
             user:ds2:+rwx
             group:*:rx
             group:iu:r
             group:root:x
             mask:*:rx
             other:*:rx
     
             default_user:*:=rw
             default_user:mark:+rwx
             default_user:ds:=rwx
             default_group::=r
             default_group:iu:+r
             default_mask::w
             default_other::rwx
             }
     
             { acl_alias2
     
             method:overwrite
             fstype:dfs
     
             user:*:rwxcid
             group:*:rxd
             other:*:wxir
             mask:*:rxw
             user:/.../iu.hioslo.no/cell_admin:rc
             group:/.../iu.hioslo.no/acct-admin:rwxcid
             user:/.../iu.hioslo.no/root:rx
             }


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

alerts
======

   Alerts are normally just messages that are printed when classes
become activated in order to alert the system administrator to some
condition that has arisen.  Alerts can also be special functions, like
`ShowState()' that generate system output.

   Alerts cannot belong to the class `any', that would generate a
message from every host. In a huge network this could result in vast
amounts of Email. This behaviour can be forced, however, by creating an
alias for the class `any' that is defined on the affected hosts.


     alerts:
     
        class::
     
           QUOTED MESSAGE ifelapsed=TIME
           ShowState(PARAMETER)
           SysLog(PRIORITY,MESSAGE)
           SetState(NAME,TTL,POLICY)
           UnSetState(NAME)
           FriendStatus(HOURS)
   For example:


     alerts:
     
       "Reminder: say hello every hour" ifelapsed=60
     
       nfsd_in_high_dev2::
     
       "High NFS server access rate 2dev at $(host) value $(value_nfsd_in) av $(average_nfsd_in) pm $(stddev_nfsd_in)"
       ShowState(incoming.nfs)
     
      # ROOT PROCS
     
       anomaly_hosts.RootProcs_high_dev2::
     
        "RootProc anomaly high 2 dev on $(host) value $(value_rootprocs) av $(average_rootprocs) pm $(stddev_rootprocs)"
       ShowState(procs)

   The `ShowState()' function reports on state gathered by the cfenvd
daemon.

     ShowState(incoming.tcpsyn)
     ShowState(outgoing.smtp)
     ShowState(incoming.www)
     ShowState(outgoing.www)
     ShowState(procs)
     ShowState(users)

   To limit the frequency of alerts, you can set locking times:

      # ROOT PROCS
     
       anomaly_hosts.RootProcs_high_dev2::
     
        "RootProc anomaly high 2 dev on $(host) value $(value_rootprocs) av $(average_rootprocs) pm $(stddev_rootprocs)"
     
        ShowState(procs)  ifelapsed=10 expireafter=20
   Alerts can also be channeled directly to syslog, to avoid extraneous
console messages or email.


       SysLog(LOG_ERR,"Test syslog message")
   One application for alerts is to pass signals from one cfengine to
another by persistent, shared memory.  For example, suppose a
short-lived anomaly event triggers a class that relates to a security
alert. The event class might be too short-lived to be followed up by
cfagent in full. One could thus set a long term class that would
trigger up several follow-up checks.  A persistent class could also be
used to exclude an operation for an interval of time.

   Persistent class memory can be added through a system alert
functions to give timer behaviour.  For example, consider setting a
class that acts like a non-resettable timer. It is defined for exactly
10 minutes before expiring.


       SetState("preserved_class",10,Preserve)
   Or to set a class that acts as a resettable timer. It is defined for
60 minutes unless the SetState call is called again to extend its
lifetime.


       SetState(non_preserved_class,60,Reset)
   Existing persistent classes can be deleted with:


               UnsetState(myclass)
   The `FriendStatus' function is available from version 2.1.4 and
displays a message if hosts that normally have a cfengine protocol
connection with the current host have not connected for more than than
specified number of hours. If the number of hours is set to zero,
cfengine uses a machine-learned expectation value for the time and uses
this to report. The friend status of a host is thus the expectation that
there is a problem with a remote peer. Expected contact rates of more
than the variable `LastSeenExpireAfter' are ignored as spurious, *Note
lastseenexpireafter::.


File: cfengine-Reference.info,  Node: binservers,  Next: broadcast,  Prev: alerts,  Up: Cfagent reference

binservers
==========

   The `binservers' declaration need only be used if you are using
cfengine's model for mounting NFS filesystems.  This declaration informs
hosts of which other hosts on the network possess filesystems containing
software (binary files) which client hosts should mount.  This includes
resources like programs in `/usr/local' and so on.  A host may have
several binary servers, since there may be several machines to which
disks are physically attached.  In most cases, on a well organized
network, there will be only one _architecture server_ per UNIX platform
type, for instance a SunOS server, an ULTRIX server and so on.

   Binary servers are defined as follows:


     binservers:
     
        physics.sun4::   sunserver sunserver2
        physics.linux::  linuxserver

The meaning of this declaration is the following.  All hosts of type
`sun4' which are members of the group `physics' should mount any
binaries declared in the `mountables' resource list which belong to
hosts `sunserver' or `sunserver2'.  Similarly all `linux' machines
should mount binary filesystems in the mountables list from
`linuxserver'.

   Cfengine knows the difference between binaries and home directories
in the `mountables' list, because home directories match the pattern
given by `homepattern'.  *Note homepattern::.  *Note homeservers::.

   Note that every host is a binary server for itself, so that the first
binary server (and that with highest priority) is always the current
host.  This ensures that local filesystems are always used in preference
to NFS mounted filesystems.  This is only relevant in connection with
the variable `$(binserver)'.


File: cfengine-Reference.info,  Node: broadcast,  Next: control,  Prev: binservers,  Up: Cfagent reference

broadcast
=========

   This information is used to configure the network interface for each
host.

   Every local area network has a convention for determining which
internet address is used for broadcast requests.  Normally this is an
address of the form `aaa.bbb.ccc.255' or `aaa.bbb.ccc.0'.  The
difference between these two forms is whether all of the bits in the
last number are ones or zeroes respectively.  You must find out which
convention is used at your establishment and tell cfengine using a
declaration of the form:

     broadcast:
     
       any::
     
          ones     # or zeros, or zeroes

In most cases you can use the generic class `any', since all of the
hosts on the same subnet have to use the same convention.  If your
configuration file encompasses several different subnets with different
conventions then you will need to use a more specific.

   Cfengine computes the actual value of the broadcast address using the
value specified above and the netmask *Note netmask::.


File: cfengine-Reference.info,  Node: control,  Next: classes,  Prev: broadcast,  Up: Cfagent reference

control
=======

   The fundamental piece of any cfengine script or configuration file is
the control section.  If you omit this part of a cfengine script, it
will not do anything! The control section is used to define certain
variables, set default values and define the order in which the various
actions you have defined will be carried out.  Because cfengine is a
declarative or descriptive language, the order in which actions appear
in the file does not necessarily reflect the order in which they are
executed. The syntax of declarations here is:

       control:
     
          CLASSES::
     
             VARIABLE = ( LIST OR VALUE FUNCTION(ARGS) )

   The control section is a sequence of declarations which looks
something like the following example:


     control:
     
       site     = ( univ )
       domain   = ( univ.edu )
       sysadm   = ( admin@computing.univ.edu )
       netmask  = ( 255.255.252.0 )
       timezone = ( EDT )
       nfstype  = ( nfs )
     
       childlibpath = ( /usr/local:/mylibs )
     
       sensiblesize  = ( 1000 )
       sensiblecount = ( 2 )
       editfilesize  = ( 4000 )
     
       actionsequence =
          (
          links.some
          mountall
          links.others
          files
          )
     
       myvariable = ( something )
       mymacro    = ( somethingelse )
       myrandom   = ( RandomInt(3,6) )
       myexcerpt  = ( ReadFile("/etc/services",220))

Parentheses are required when making a declaring information in
cfengine.  Note that a limited number of built-in functions exists:
   * `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)' Is substituted for a random number between (a,b).

   * `ReadFile'(FILENAME,MAX NUMBER OF BYTES) A maximum number of bytes
     is read from the named file and placed in a variable.
   For more functions, *Note Setting variables with functions::.

   The meaning of each of these lines is described below.

* Menu:

* access::
* actionsequence::
* addclasses::
* addinstallable::
* AllowRedefinitionOf::
* AutoDefine::
* BinaryPaddingChar::
* ChecksumDatabase::
* BindToInterface(cfagent)::
* ChecksumPurge::
* ChecksumUpdates::
* childlibpath::
* copylinks::
* defaultcopytype::
* defaultpkgmgr::
* deletenonuserfiles::
* deletenonownerfiles::
* deletenonusermail::
* deletenonownermail::
* domain::
* dryrun::
* dpkginstallcommand::
* editbinaryfilesize::
* editfilesize::
* emptyresolvconf::
* exclamation::
* excludecopy::
* excludelinks::
* ExpireAfter::
* homepattern::
* HostnameKeys::
* IfElapsed::
* Inform::
* interfacename::
* lastseenexpireafter::
* fileextension::
* lastseen::
* linkcopies::
* LogDirectory::
* LogTidyHomeFiles::
* moduledirectory::
* mountpattern::
* netmask::
* nonalphanumfiles::
* nfstype::
* repchar::
* repository::
* RPMcommand::
* rpminstallcommand::
* schedule::
* secureinput::
* sensiblecount::
* sensiblesize::
* showactions::
* singlecopy::
* site::
* SkipIdentify::
* Smtpserver::
* SplayTime::
* split::
* spooldirectories::
* suninstallcommand::
* suspiciousnames::
* sysadm::
* Syslog::
* SyslogFacility::
* timezone::
* TimeOut::
* Verbose::
* Warnings::
* warnnonuserfiles::
* warnnonownerfiles::
* warnnonusermail::
* warnnonownermail::


File: cfengine-Reference.info,  Node: access,  Next: actionsequence,  Prev: control,  Up: control

access
------

   The `access' list is a list of users who are to be allowed to
execute a cfengine program.  If the list does not exist then all users
are allowed to run a program.

        access = ( USER1 USER2 ...  )

The list may consist of either numerical user identifiers or valid
usernames from the password database.  For example:

        access = ( mark aurora 22 456 )

would restrict a script to users mark, aurora and user id 22 and 456.


File: cfengine-Reference.info,  Node: actionsequence,  Next: addclasses,  Prev: access,  Up: control

actionsequence
--------------

   The action sequence determines the order in which collective actions
are carried out.  Here is an example containing the full list of
possibilities:

        actionsequence =
           (
           mountall               # mount filesystems in fstab
           mountinfo              # scan mounted filesystems
           checktimezone          # check timezone
           netconfig              # check net interface config
           resolve                # check resolver setup
           unmount                # unmount any filesystems
           packages               # check for required packages
           shellcommands          # execute shell commands
           editfiles              # edit files
           addmounts              # add new filesystems to system
           directories            # make any directories
           links                  # check and maintain links (single and child)
           mailcheck              # check mailserver
           mountall               # (again)
           required               # check required filesystems
           tidy                   # tidy files
           disable                # disable files
           files                  # check file permissions
           copy                   # make a copy/image of a master file
           processes              # signal / check processes
           module:name            # execute a user-defined module
           )

Here is a more complete description of the meaning of these keywords.

`addmounts'
     causes cfengine to compute which NFS filesystems are missing from
     the current host and add them. This includes editing the
     filesystem table, creating the mount-directory, if required.  This
     command relies on information provided by `mountinfo', so it
     should normally only be called after `mountinfo'. If the
     filesystem already appears to be in the filesystem table, a
     warning is issued.

`checktimezone'
     runs a check on the timezone defined for the shell running
     cfengine.

`directories'
     executes all the commands defined under the `directories' section
     of the program. It builds new directories.

`disable'
     executes all the commands defined under the `disable' section of
     the program.

`editfiles'
     executes all the commands defined under the `editfiles' section of
     the program.

`files'
     executes all the commands defined under the `files' section of the
     program.

`links'
     executes all the commands defined under the `links' section of the
     program.

`mailcheck'
     tests for the presence of the NFS-mounted mail spooling directory
     on the current host. The name of the mail spool directory is
     defined in the `mailserver' section of the cfengine program. If
     the current host is the same as the mailserver (the host which has
     the physical spool directory disk) nothing is done. Otherwise the
     filesystem table is edited so as to include the mail directory.

`module'
     Normally cfengine's ability to detect the systems condition is
     limited to what it is able to determine while excuting predefined
     actions. Classes may be switched on as a result of actions cfengine
     takes to correct a problem. To increase the flexibility of
     cfengine, a mechanism has been introduced in version 1.5 which
     allows you to include a module of your own making in order to
     define or undefine a number of classes.  The syntax

            module:mytests
          
            "module:mytests arg1 arg2 .."
     declares a user defined module which can potentially set the
     classes CLASS1 etc. Classes returned by the module must be
     declared so that cfengine knows to pay attention to rules which
     use these classes when parsing; this is done using
     `AddInstallable'. If arguments are passed to the module, the whole
     string must be quoted like a shellcommand.  *Note Writing plugin
     modules: (cfengine-Tutorial)Writing plugin modules.  Whether or
     not these classes become set or not depends on the behaviour of
     your module. The classes continue to apply for all actions which
     occur after the module's execution. The module must be owned by
     the user executing cfengine or root (for security reasons), it
     must be named `module:MODULE-NAME' and must lie in a special
     directory, *Note moduledirectory::.

`mountall'
     mounts all filesystems defined in the hosts filesystem table.  This
     causes new NFS filesystems added by `addmounts' and `mailcheck' to
     be actually mounted. This should probably be called both before
     `mountinfo' and after `addmounts' etc.  A short timeout is placed
     on this operation to avoid hanging RPC connections when parsing
     NFS mounted file systems.

`mountinfo'
     builds internal information about which filesystems are presently
     mounted on the current host.  Cfengine assumes that
     required-filesystems which are not found need to be mounted. A
     short timeout is placed on this operation to avoid hanging RPC
     connections when parsing NFS mounted file systems. If this times
     out, no further mount operations are considered reliable and are
     summarily cancelled.

`netconfig'
     checks the netmask, hostname, IP address and broadcast address for
     the current host. The correct values for the netmask and broadcast
     address are set if there is an error. The defaultroute is matched
     against the static routing table and added if no default route
     exists. This does not apply to DHCP clients, which set a default
     route automatically.

`required'
     executes all the commands defined under the `required' section of
     the program. It checks for the absence of important NFS resources.

`resolve'
     checks and corrects the DNS domain name and the order of
     nameservers in the file `/etc/resolv.conf'.

`packages'
     executes commands defined under the `packages' section of the
     program.  This will query the system's package database for the
     specified packages, at the specified versions, set classes based
     on whether or not those packages exist, and optionally install
     those packages using a pre-defined package manager command.

`shellcommands'
     executes all the commands defined under the `shellcommands'
     section of the program.

`tidy'
     executes all the commands defined under the `tidy' section of the
     program.

`unmount'
     executes all the commands defined under the `unmount' section of
     the program. The filesystem table is edited so as to remove the
     unwanted filesystems and the unmount operation is executed.

`processes'
     executes commands defined under the `processes' section of the
     program.

   Under normal circumstances this coarse ordering is enough to suit
most purposes.  In some cases you might want to, say, only perform half
the link operations before mounting filesystems and then, say, perform
the remainder.  You can do this (and similar things) by using the idea
of defining and undefining classes. *Note Defining classes:
(cfengine-Tutorial)Defining classes.

   The syntax


     actionsequence =
        (
        links.firstpass.include
        ...
        links.secondpass
        )

means that cfengine first executes `links' with the classes `firstpass'
and `include' _defined_.  Later it executes `links' with `secondpass'
defined.  You can use this method of adding classes to distinguish more
finely the flow of control in programs.

   A note about style: if you define and undefine lots of classes to do
what you want to do, you might stop and ask yourself if your `groups'
are defined as well as they should be.  *Note groups::.  Programming in
cfengine is about doing a lot for only a little writing.  If you find
yourself writing a lot, you are probably not going about things in the
right way.


File: cfengine-Reference.info,  Node: addclasses,  Next: addinstallable,  Prev: actionsequence,  Up: control

AddClasses
----------

        AddClasses  = ( LIST OF IDENTIFIERS )

   The `AddClasses' directive is used to define a list of class
attributes for the current host.  Normally only the hard classes defined
by the system are `true' for a given host.  It is convenient though to
be able to define classes of your own to label certain actions, mainly
so that they can later be excluded so as to cut short or filter out
certain actions.  This can be done in two ways.  *Note actionsequence::.

   To define a list of classes for the current session, you write:

     AddClasses = ( exclude shortversion )

This is equivalent to (though more permanent than) defining classes on
the command line with the `-D' option.  You can now use these to
qualify actions.  For example


       any.exclude::
           ...

   Under normal circumstances `exclude' is always true -- because you
have defined it to be so, but you can _undefine_ it in two ways so as
to prevent the action from being carried out.  One way is to undefine a
class on the command line when you invoke cfengine:

     host#  cfengine -N exclude

or

     host#  cfengine -N exclude.shortversion
     
     host#  cfengine -N a.b.c.d

These commands run cfengine with the named classes _undefined_.  That
means that actions labelled with these classes are excluded during that
run.

   Another way to restrict classes is to add a list of classes to be
undefined in the actionsequence.  See next section.


File: cfengine-Reference.info,  Node: addinstallable,  Next: AllowRedefinitionOf,  Prev: addclasses,  Up: control

AddInstallable
--------------

        AddInstallable  = ( LIST OF IDENTIFIERS )

   Some actions in your cfengine program will be labelled by classes
which only become defined at run time using a `define=' option. Cfengine
is not always able to see these classes until it meets them and tries to
save space by only loading actions for classes which is believes will
become defined at some point in the program. This can lead to some
actions being missed if the action is parsed before the place where the
class gets switched on, since cfengine is a one-pass interpreter,.  To
help cfengine determine classes which _might become defined_ during a
run, you can declare them in this list. It does no harm to declare
classes here anyway.  Here is an example where you need to declare a
class because of the ordering of the actions.


     control:
     
         AddInstallable  = ( myclass )
     
     files:
     
        myclass::
     
          /tmp/test mode=644 action=fixall
     
     copy:
     
          /tmp/foo dest=/tmp/test define=myclass

If we remove the declaration, then when cfengine meets the files
command, it skips it because it knows nothing about the class
`myclass'--when the copy command follows, it is too late.  Remember
that imported files are always parsed after the main program so
definitions made in imported files always come later than things in the
main program.


File: cfengine-Reference.info,  Node: AllowRedefinitionOf,  Next: AutoDefine,  Prev: addinstallable,  Up: control

AllowRedefinitionOf
-------------------

   Normally cfagent warns about redefinitions of variables during
parsing.  This is presumed to be a mistake. To avoid this behaviour,
add the name of the variable to this list, and the warning disappears.

     control:
     
     actionsequence = ( copy )
     
     AllowRedefinitionOf = ( cfrep )
     
     cfrep = ( bla )
     
     cfrep = ( blo )


File: cfengine-Reference.info,  Node: AutoDefine,  Next: BinaryPaddingChar,  Prev: AllowRedefinitionOf,  Up: control

AutoDefine
----------


     control:
     
        hup_syslogd::
     
          autodefine = ( /etc/syslog.conf )

   Referring to the class that prefixes it, `autodefine' will define
the class if the names file is copied in any statement.  This helps to
avoid having to write a large number of file-specific copy: lines with
define=class configured.


File: cfengine-Reference.info,  Node: BinaryPaddingChar,  Next: ChecksumDatabase,  Prev: AutoDefine,  Up: control

BinaryPaddingChar
-----------------

     BinaryPaddingChar = ( \0 )
   This specifies the type of character used to pad strings of unequal
length in `editfiles' during binary editing.  The default value is the
space character, since this is normally used to edit filenames or text
messages within program code.


File: cfengine-Reference.info,  Node: ChecksumDatabase,  Next: BindToInterface(cfagent),  Prev: BinaryPaddingChar,  Up: control

ChecksumDatabase
----------------

     ChecksumDatabase = ( /var/cfengine/cfdb )

   If this filename is defined, cfengine will use it to store message
digests (i.e. cryptographic checksums) of files for security purposes,
*Note files::, `checksum='.


File: cfengine-Reference.info,  Node: BindToInterface(cfagent),  Next: ChecksumPurge,  Prev: ChecksumDatabase,  Up: control

BindToInterface
---------------

   If this is set to a specific IP address of an IP configured
interface, cfagent will use that address for outgoing connections.  On
Multi-homed hosts this allows one to restrict the traffic to a known
interface. An interface must be configured with an IP address in order
to be bound.

   This feature is not available for old operating systems.


File: cfengine-Reference.info,  Node: ChecksumPurge,  Next: ChecksumUpdates,  Prev: BindToInterface(cfagent),  Up: control

ChecksumPurge
-------------

     ChecksumPurge = ( on )

   This variable defaults to `off'. If set to true, cfagent will look
at all of the registered files in the database and check whether thet
still exist. If the file no longer exists, it is removed from the
database and a warning is issued.

   To purge files now and then, but at no particular time, one could do
something like this:


     strategies:
     
      { purging
     
      NowAndThen: 1
      ElseWhen:   49
      }
     
     control:
     
      NowAndThen::
     
        ChecksumPurge = ( on )


File: cfengine-Reference.info,  Node: ChecksumUpdates,  Next: childlibpath,  Prev: ChecksumPurge,  Up: control

ChecksumUpdates
---------------

     ChecksumUpdates = ( on )

   This variable defaults to `off'. If set to true, cfagent will
automatically update the checksum of a file, if it changes on the disk.
This means that a security warning will be issued only once about files
which have changed, and the changed version will be re-registered as
the correct version. This option could be switched on after a system
upgrade, for instance, in order to update the database, and then
switched to `off' again to reduce the risk of missing a security alert.
Alternatively, if you are confident that the first message is
sufficient, it can be left as `on' so that only one message is given.


File: cfengine-Reference.info,  Node: childlibpath,  Next: copylinks,  Prev: ChecksumUpdates,  Up: control

ChildLibPath
------------

   Sets a value for LD_LIBRARY_PATH in child processes:

      childlibpath = ( /usr/local/lib:/local/mysql/lib )
   Note that the variables LD_LIBRARY_PATH is special. This library
path is needed to run processes as children of cfengine.  Often, if the
agent is started from cron (which is started by init), there is no
suitable library path set, and shellcommands will fail with strange
errors about not being able to load shared objects. Setting a library
path here is a useful way of correcting this problem.


File: cfengine-Reference.info,  Node: copylinks,  Next: defaultcopytype,  Prev: childlibpath,  Up: control

CopyLinks
---------

   This list is used to define a global list of names or patterns which
are to be copied rather than linked symbolically. For example

     CopyLinks = ( *.config )
   The same facility can be specified for each individual link
operation using the `copy' option *Note links::.  Copying is performed
using a file age comparison.

   Note that all entries defined under a specified class are valid only
as long as that class is defined. For instance

       CLASS::
     
           CopyLinks = ( PATTERN )

would define a pattern which was only valid when CLASS is defined.


File: cfengine-Reference.info,  Node: defaultcopytype,  Next: defaultpkgmgr,  Prev: copylinks,  Up: control

DefaultCopyType
---------------

   This parameter determines the default form of copying for all copy
operations parsed after this variable. The legal values are `ctime'
(intial default), `mtime', `checksum' and `binary'.  e.g.


      DefaultCopyType = ( mtime )


File: cfengine-Reference.info,  Node: defaultpkgmgr,  Next: deletenonuserfiles,  Prev: defaultcopytype,  Up: control

DefaultPkgMgr
-------------

   Sets the default value of the `pkgmgr' attribute for `packages'
items.

     DefaultPkgMgr = ( rpm )

   By default, this variable is not set, meaning there will be no
package manager selected, and each item in the `packages' section must
specify its own package manager, or it will not be checked.  For
information on the values of this variable, *Note packages::.


File: cfengine-Reference.info,  Node: deletenonuserfiles,  Next: deletenonownerfiles,  Prev: defaultpkgmgr,  Up: control

DeleteNonUserFiles
------------------

   If this parameter is set to true, cfengine will delete files which
do not have a name belonging to a known user id.

     DeleteNonUserFiles = ( true )
     
     SpoolDirectories = ( /var/spool/cron/crontabs )

   This is an generalization of DeleteNonUserMail and makes it
redundant.  it is formally executed as a part of the "tidy" action.


File: cfengine-Reference.info,  Node: deletenonownerfiles,  Next: deletenonusermail,  Prev: deletenonuserfiles,  Up: control

DeleteNonOwnerFiles
-------------------

   If this parameter is set to true, cfengine will delete files on
mailservers whose names do not correspond to a known user name, but
might be owned by a known user.

     DeleteNonOwnerFiles = ( true )
     
     SpoolDirectories = ( /var/spool/cron/crontabs )

   This is an generalization of DeleteNonOwnerMail and makes it
redundant.


File: cfengine-Reference.info,  Node: deletenonusermail,  Next: deletenonownermail,  Prev: deletenonownerfiles,  Up: control

DeleteNonUserMail
-----------------

   If this parameter is set to true, cfengine will delete mail files on
mailservers which do not have a name belonging to a known user id. This
does not include lock files.


File: cfengine-Reference.info,  Node: deletenonownermail,  Next: domain,  Prev: deletenonusermail,  Up: control

DeleteNonOwnerMail
------------------

   If this parameter is set to true, cfengine will delete files on
mailservers whose names do not correspond to a known user name, but
might be owned by a known user.


File: cfengine-Reference.info,  Node: domain,  Next: dpkginstallcommand,  Prev: deletenonownermail,  Up: control

domain
------

       domain = ( DOMAIN NAME )

   This variable defines the domainname for your site.  You must define
it here, because your system might not know its domainname when you run
cfengine for the first time.  The domainname can be used as a cfengine
variable subsequently by referring to $(domain).  The domainname
variable is used by the action `resolve'. The domain is also used
implicitly by other matching routines. You should define the domain as
early as possible in your configuration file so as to avoid problems,
especially if you have the strange practice of naming hosts with their
fully qualified host names since groups which use fully qualified names
can fail to be defined if cfengine is not able to figure out the domain
name.


File: cfengine-Reference.info,  Node: dpkginstallcommand,  Next: dryrun,  Prev: domain,  Up: control

DPKGInstallCommand
------------------

   Sets the command used to install packages that need to be installed
under the DPKG package manager.

     DPKGInstallCommand = ( "/usr/bin/pkgmgr %s" )

   By default, this variable is not set, meaning that any packages with
action=install will NOT be installed if installation is required.  Note
the "'s around the string, and the %s is replaced with the list of
packages to be installed, each separated by a ' ' (space).


File: cfengine-Reference.info,  Node: dryrun,  Next: editbinaryfilesize,  Prev: dpkginstallcommand,  Up: control

DryRun
------


       DryRun = ( ON/off )

   This variable has the same effect as the command line options
`--dry-run' or `-n'. It tells cfengine to only report what it should do
without actually doing it.


      CLASSES::
     
        DryRun = ( on )


File: cfengine-Reference.info,  Node: editbinaryfilesize,  Next: editfilesize,  Prev: dryrun,  Up: control

editbinaryfilesize
------------------

        EditBinaryFileSize  = ( SIZE )

   Cfengine will refuse to edit a file which is larger than the value of
`editbinaryfilesize' in bytes.  This is to prevent possible accidents
from occurring.  The default value for this variable is 10000000 bytes.
If you don't like this feature, simply set the value to be a very
large number or to zero.  If the value is zero, cfengine will ignore it.


File: cfengine-Reference.info,  Node: editfilesize,  Next: emptyresolvconf,  Prev: editbinaryfilesize,  Up: control

editfilesize
------------

        EditfileSize  = ( SIZE )

   This variable is used by cfengine every time it becomes necessary to
edit a file.  Since file editing applies only to text files, the files
are probably going to be relatively small in most cases.  Asking to edit
a very large (perhaps binary) file could therefore be the result of an
error.

   A check is therefore made as a security feature.  Cfengine will
refuse to edit a file which is larger than the value of `editfilesize'
in bytes.  This is to prevent possible accidents from occurring.  The
default value for this variable is 10000 bytes.  If you don't like this
feature, simply set the value to be a very large number or to zero.  If
the value is zero, cfengine will ignore it.


File: cfengine-Reference.info,  Node: emptyresolvconf,  Next: exclamation,  Prev: editfilesize,  Up: control

EmptyResolvConf
---------------

        EmptyResolvConf  = ( true )

   Normally cfengine does not tidy up old entries in the
`/etc/resolv.conf' file. This option causes cfengine to remove all
existing content from the file.


File: cfengine-Reference.info,  Node: exclamation,  Next: excludecopy,  Prev: emptyresolvconf,  Up: control

Exclamation
-----------

   This variable defaults to "on". If set to "off", no exclamation marks
(Br. pling, Am: shriek) are printed during security alerts, e.g. for
checksum violations.

        Exclamation  = ( off )


File: cfengine-Reference.info,  Node: excludecopy,  Next: excludelinks,  Prev: exclamation,  Up: control

ExcludeCopy
-----------

   This list is used to define a global list of names or patterns which
are to be excluded from copy operations. For example

      ExcludeCopy = ( *~ *% core )
   The same facility can be specified for each individual link
operation using the `exclude' option *Note copy::.

   Note that all entries defined under a specified class are valid only
as long as that class is defined. For instance

       CLASS::
     
           ExcludeCopy = ( PATTERN )

would define a pattern which was only valid when CLASS is defined.


File: cfengine-Reference.info,  Node: excludelinks,  Next: ExpireAfter,  Prev: excludecopy,  Up: control

ExcludeLink
-----------

   This list is used to define a global list of names or patterns which
are to be excluded from linking operations. For example

      ExcludeLink = ( *~ *% core )
   The same facility can be specified for each individual link
operation using the `exclude' option *Note links::.

   Note that all entries defined under a specified class are valid only
as long as that class is defined. For instance

       CLASS::
     
           ExcludeLink = ( PATTERN )

would define a pattern which was only valid when CLASS is defined.


File: cfengine-Reference.info,  Node: ExpireAfter,  Next: homepattern,  Prev: excludelinks,  Up: control

ExpireAfter
-----------

   If you change the value of this parameter, it should be one of the
first things you do in your configuration script.

   This parameter controls the global value of the ExpireAfter
parameter.  *Note Spamming and security: (cfengine-Tutorial)Spamming
and security. This parameter controls the maximum time in minutes which
a cfengine action is allowed to live. After this time cfengine will try
to kill the cfengine which seems to have hung and attempt to restart
the action.


      ExpireAfter = ( TIME-IN-MINUTES )

This parameter may also be set per action in the action sequence by
appending a pseudo-class called `ExpireAfterTIME'.  For instance,


      actionsequence = ( copy.ExpireAfter15 )

sets the expiry time parameter to 15 minutes for this copy command.
This method should be considered old and deprecated however.  As of
version 2.1.0, you can define the expiry time on a per-command basis,
as options of the form `expireafter=10'.


File: cfengine-Reference.info,  Node: homepattern,  Next: HostnameKeys,  Prev: ExpireAfter,  Up: control

HomePattern
-----------

        HomePattern  = ( LIST OF PATTERNS )

   The `homepattern' variable is used by the cfengine model for
mounting nfs filesystems.  *Note NFS resources: (cfengine-Tutorial)NFS
resources.  It is also used in the evaluation of the pseudo variable
`home', See *Note files::, *Note tidy::.

   `homepattern' is in fact a list and is used like a wildcard or
_pattern_ to determine which filesystems in the list of mountables are
home directories.  *Note mountables::.  This relies on your sticking to
a rigid naming convention as described in the first reference above.

   For example, you might wish to mount (or locate directly if you are
not using a separate partition for home directories) your home
directories under `mountpattern' in directories `u1', `u2' and so on.
In this case you would define `homepattern' to match these numbers:

     homepattern = ( u? )

Cfengine now regards any directory matching `$(mountpattern)/u?' as
being a user login directory.

   Suppose you want to create mount home directories under
`$(mountpattern)/home' and make subdirectories for staff and students.
Then you would be tempted to write:

      HomePattern = ( home/staff home/students )

Unfortunately this is not presently possible. (This is, in principle, a
bug which should be fixed in the future.) What you can do instead is to
achieve the same this as follows:

      MountPattern = ( /$(site)/$(host) /$(site)/$(host)/home )
      HomePattern = ( staff students )


File: cfengine-Reference.info,  Node: HostnameKeys,  Next: IfElapsed,  Prev: homepattern,  Up: control

HostnameKeys
------------

   If this variable is set to true/on, it causes cfagent to lookup and
store trusted public keys according to their DNS fully qualified host
name, instead of using the IP address.  This can be useful in
environments where hosts do not have fixed IP addresses, but do have
fixed hostnames.


       HostnameKeys = ( on )
   This method of storing keys is not recommended for sites with fixed
IP addresses, since it removes one security barrier from a potential
attacker by potentially allowing DNS spoofing.

   Note that there is a corresponding variable to be set in
`cfrun.hosts' for consistency.


File: cfengine-Reference.info,  Node: IfElapsed,  Next: Inform,  Prev: HostnameKeys,  Up: control

IfElapsed
---------

   If you change the value of this parameter, it should be one of the
first things you do in your configuration script.

   This parameter controls the global value of the IfElapsed parameter,
*Note Spamming and security: (cfengine-Tutorial)Spamming and security.
This parameter controls the minimum time which must have elapsed for an
action in the action sequence before which it will be executed again.


      IfElapsed = ( TIME-IN-MINUTES )

This parameter may also be set per action in the action sequence by
appending a pseudo-class called `IfElapsedTIME'.  For instance,


      ActionSequence = ( copy.IfElapsed15 )

sets the elapsed time parameter to 15 minutes for this copy command.
This method should be considered old and deprecated however.  As of
version 2.1.0, you can define the expiry time on a per-command basis,
as options of the form `ifelapsed=15'.


File: cfengine-Reference.info,  Node: Inform,  Next: interfacename,  Prev: IfElapsed,  Up: control

Inform
------


       Inform = ( ON/off )

   This variable switches on the output level whereby cfengine reports
changes it makes during a run. Normally only urgent messages or clear
errors are printed. Setting `Inform' to `on' makes cfengine report on
all actions not explicitly cancelled with a `silent' option.  To set
this output level one writes:


      CLASSES::
     
        Inform = ( on )


File: cfengine-Reference.info,  Node: interfacename,  Next: lastseenexpireafter,  Prev: Inform,  Up: control

InterfaceName
-------------

   If you have an operating system which is installed on some
non-standard hardware, you might have to specifically set the name of
the network interface. For example:


       control:
     
         nextstep.some::
     
            InterfaceName = ( en0 )
     
         nextstep.others::
     
            InterfaceName = ( ec0 )

It is only necessary to set the interface name in this fashion if you
have an operating system which is running on special hardware. Most
users will not need this.  The choice set here overrides the system
defaults and the choices made in the `cfrc' file, *Note cfrc resource
file::.

