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: lastseenexpireafter,  Next: fileextension,  Prev: interfacename,  Up: control

LastSeenExpireAfter
-------------------

   This value (in days) sets the time after which unseen friend hosts
are purged from the `last seen' database, as viewed by the
`FriendStatus' function, *Note alerts::.


       LastSeenExpireAfter = ( 2 )


File: cfengine-Reference.info,  Node: fileextension,  Next: lastseen,  Prev: lastseenexpireafter,  Up: control

FileExtensions
--------------

   This list may be used to define a number of extensions which are
regarded as being plain files by the system.  As part of the general
security checking cfengine will warn about any directories which have
names using these extensions. They may be used to conceal directories.


       FileExtensions = ( c o gif jpg html )


File: cfengine-Reference.info,  Node: lastseen,  Next: linkcopies,  Prev: fileextension,  Up: control

LastSeen
--------

   This option is true by default. If set to off or false it prevents
cfengine and/or cfservd from learning about last times hosts were
observed connecting to one another. Some users with broken resolvers
(particularly in view of the change over to IPv6 compatible libraries)
might find this useful when processes appear to hang on connecting.


       LastSeen = ( off )


File: cfengine-Reference.info,  Node: linkcopies,  Next: LogDirectory,  Prev: lastseen,  Up: control

LinkCopies
----------

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

     excludelinks = ( *.gif *.jpg )
   The same facility can be specified for each individual link
operation using the `symlink' 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::
     
           LinkCopies = ( PATTERN )

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


File: cfengine-Reference.info,  Node: LogDirectory,  Next: LogTidyHomeFiles,  Prev: linkcopies,  Up: control

LogDirectory
------------

   This is now deprecated.

   Specify an alternative directory for keeping cfengine's log data.
This defaults to `/var/run/cfengine' or `/var/cfengine'.


       LogDirectory = ( /var/cfengine )


File: cfengine-Reference.info,  Node: LogTidyHomeFiles,  Next: moduledirectory,  Prev: LogDirectory,  Up: control

LogTidyHomeFiles
----------------


       LogTidyHomeFiles = ( off )

   If set to "off", no log is made of user files, in their home
directories, of the files which are tidied by cfengine.


File: cfengine-Reference.info,  Node: moduledirectory,  Next: mountpattern,  Prev: LogTidyHomeFiles,  Up: control

moduledirectory
---------------

        moduledirectory  = ( DIRECTORY FOR PLUGIN MODULES )

   This is the directory where cfengine will look for plug-in modules
for the actionsequence, *Note actionsequence::. Plugin modules may be
used to activate classes using special algorithms.  *Note Writing
plugin modules: (cfengine-Tutorial)Writing plugin modules.  This
variable defaults to `/var/cfengine/modules' for privileged users and
to `$HOME)/.cfengine/modules' for non-privileged users.


File: cfengine-Reference.info,  Node: mountpattern,  Next: netmask,  Prev: moduledirectory,  Up: control

mountpattern
------------

        mountpattern  = ( MOUNT-POINT )

   The `mountpattern' list 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::.

   It is used together with the value of `homepattern' to locate and
identify what filesystems are local to a given host and which are
mounted over the network.  For this list to make sense you need to
stick to a rigid convention for mounting your filesystems under a single
naming scheme as described in the section mentioned above.  If you
follow the recommended naming scheme then you will want to set the value
of mountpattern to

     mountpattern = ( /$(site)/$(host) )

which implies that cfengine will look for local disk partitions under a
unique directory given by the name of the host and site.  Any
filesystems which are physically located on the current host lie in this
directory.  All mounted filesystems should lie elsewhere. If you insist
on keeping mounted file systems in more than one location, you can make
a list like this:

     mountpattern = ( /$(site)/users /$(site)/projects )


File: cfengine-Reference.info,  Node: netmask,  Next: nonalphanumfiles,  Prev: mountpattern,  Up: control

netmask
-------

        netmask = ( AAA.BBB.CCC.DDD )

   The netmask variable defines the partitioning of the subnet
addresses on your network.  Its value is defined by your network
administrator.  On most systems it is likely to be `255.255.255.0'.
This is used to configure the network interface in `netconfig'.  *Note
actionsequence::.

   Every host on the internet has its own unique address.  The addresses
are assigned hierarchically.  Each network gets a _domain name_ and can
attach something like 65,000 hosts to that network.  Since this is
usually too many to handle in one go, every such network may be divided
up into subnets.  The administrator of the network can decide how the
division into subnets is made.  The decision is a trade-off between
having many subnets with few hosts, or many hosts on few subnets.  This
choice is made by setting the value of a variable called `netmask'.
The netmask looks like an internet address.  It takes the form:


        aaa.bbb.ccc.mmm

The first two numbers `aaa.bbb' are the address of the domain.  The
remainder `ccc.mmm' specifies both the subnet and the hostname.  The
value of `netmask' tells all hosts on the network: how many of the bits
in the second half label different subnets and how many label different
hosts on each of the subnets?

   The most common value for the netmask is `255.255.255.0'.  It is
most helpful to think of the netmask in terms of bits.  Each base-10
number between 0-255 represents 8 bits which are either set or not set.
Every bit which is set is a network address and every bit which is zero
is part of a host address.  The first two parts of the address
`255.255' always takes these values.  If the third number is `255', it
means that the domain is divided up into 256 sub networks and then the
remaining bits which are zero can be used to give 255 different host
addresses on each of the subnets.

   If the value had been `255.255.255.254', the network would be
divided up into 2^15 subnets, since fifteen of the sixteen bits are
one.  The remaining bit leaves enough room for two addresses 0 and 1.
One of those is reserved for _broadcasts_ to all hosts, the other can
be an actual host -- there would only be room for one host per subnet.
This is a stupid example of course, the main point with the subnet mask
is that it can be used to trade subnets for hosts per subnet.  A value
of `255.255.254.0' would allow 128 different subnets with 2*256-1 = 511
hosts on each.

   We needn't be concerned with the details of the netmask here.
Suffice it to say that its value is determined for your entire domain
by the network administrator and each host has to be told what the
value is.

   Each host must also know what convention is used for the _broadcast
address_.  This is an address which hosts can send to if they wish to
send a message to every other host on their subnet simultaneously.  It
is used a lot by services like NIS to ask if any hosts are willing to
perform a particular service.  There are two main conventions for the
broadcast address: address zero (all host bits are zero) and the highest
address on the subnet (all host bits are ones).  The convention can be
different on every subnet and it is decided by the network
administrator.  When you write a cfengine program you just specify the
convention used on your subnet and cfengine works out the value of the
broadcast address from the netmask and the host address *Note
broadcast::.  Cfengine works out the value of the broadcast address
using the value of the netmask.


File: cfengine-Reference.info,  Node: nonalphanumfiles,  Next: nfstype,  Prev: netmask,  Up: control

NonAlphaNumFiles
----------------

   If enabled, this option causes cfengine to detect and disable files
which have purely non-alphanumeric filenames, i.e. files which might be
accidental or deliberately concealed. The files are then marked with a
suffix `.cf-nonalpha' and are rendered visible.


       NonAlphaNumFiles = ( on )

   These files can then be tidied by searching for the suffix. Note
that alphanumeric means ascii codes less than 32 and greater than 126.


File: cfengine-Reference.info,  Node: nfstype,  Next: repchar,  Prev: nonalphanumfiles,  Up: control

nfstype
-------

        nfstype = ( NFS-TYPE )

   This variable is included only for future expansion.  If you do not
define this variable, its value defaults to "nfs".

   At present cfengine operates only with NFS (the network file system).
When cfengine looks for network file systems to mount, it adds lines in
the filesystem table (`/etc/fstab',`/etc/checklist' etc.)  to try to
mount filesystems of type "nfs".  In principle you might want to use a
completely different system for mounting filesystems over the network,
in which case the `mount type' would not be "nfs" but something else.

   At the time of writing certain institutions are replacing NFS with
AFS (the Andrew filesystem) and DFS (from the distributed computing
environment).  The use of these filesystems really excludes the need to
use the mount protocol at all.  In other words if you are using AFS or
DFS, you don't need to use cfengine's mounting commands at all.


File: cfengine-Reference.info,  Node: repchar,  Next: repository,  Prev: nfstype,  Up: control

RepChar
-------

        RepChar  = ( CHARACTER )

   The value of this variable determines the characters which is used by
cfengine in creating the unique filenames in the file repository.
Normally, its value is set to `_' and each `/' in the path name of the
file is changed to `_' and stored in the repository. If you prefer a
different character, define it here. Note that the character can be
quoted with either single or double quotes in order to encompass spaces
etc.


File: cfengine-Reference.info,  Node: repository,  Next: RPMcommand,  Prev: repchar,  Up: control

Repository
----------

        Repository  = ( DIRECTORY )

   Defines a special directory where all backup and junk files are
collected. Files are assigned a unique filename which identifies the
path from which they originate.  This affects files saved using
`disable', `copy', `links' and `editfiles' *Note Disabling and the file
repository: (cfengine-Tutorial)Disabling and the file repository.


File: cfengine-Reference.info,  Node: RPMcommand,  Next: rpminstallcommand,  Prev: repository,  Up: control

RPMcommand
----------

   The default value of the Red Hat Package manager command `/bin/rpm'
can be altered for non-standard systems with this variable.
     RPMcommand = ( /usr/bin/rpm )


File: cfengine-Reference.info,  Node: rpminstallcommand,  Next: schedule,  Prev: RPMcommand,  Up: control

RPMInstallCommand
-----------------

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

     RPMInstallCommand = ( "/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: schedule,  Next: secureinput,  Prev: rpminstallcommand,  Up: control

Schedule
--------

        schedule  = (  Min00_05 Min30_35 TIME CLASS )

   When `cfexecd' is used in daemon mode, it defaults to running once
an hour, on the hour, i.e..
        schedule  = (  Min00_05 )
   This can be extended to make the agent run more often. The time
specifiers are cfengine classes, and are written as intervals of time
rather the precise times.  Cfengine's time resolution is purposely
limited to five minutes because the auto-correlation time of user
resources is generally greater than this. Thus, it is assumed that
precision timing is not required and the start time of cfengine, when
scheduled in daemon mode, is not better than a few minutes.  The daemon
does not require precision, but offers many other strategic features
for load balancing and security.

   Other time classes can be used in the schedule list, but note that
cfexecd will not run the agent more than once every five minutes.  This
is treated as a fundamental granularity.


File: cfengine-Reference.info,  Node: secureinput,  Next: sensiblecount,  Prev: schedule,  Up: control

SecureInput
-----------

        SecureInput = ( on )

   If this is set cfengine will not import files which are not owned by
the uid running the program, or    which are writable by groups or
others.


File: cfengine-Reference.info,  Node: sensiblecount,  Next: sensiblesize,  Prev: secureinput,  Up: control

SensibleCount
-------------

        SensibleCount  = ( COUNT )

   This variable is used by the action `required'.  It defines for
cfengine what you consider to be the minimum number of files in a
`required' directory.  If you declare a directory as being required,
cfengine will check to see if it exists.  Then, if the directory
contains fewer than the value of `sensiblecount' files, a warning is
issued.  The default value for this variable is 2.


File: cfengine-Reference.info,  Node: sensiblesize,  Next: showactions,  Prev: sensiblecount,  Up: control

SensibleSize
------------

        SensibleSize  = ( SIZE )

   This variable is used by the action `required'.  It defines for
cfengine what you consider to be the minimum size for a `required' file.
If you declare a file as being required, cfengine will check to see if
the file exists.  Of course, the file may exist but be empty, so the
size of the file is also checked against this constant.  If the file is
smaller than the value of `sensiblesize' a warning is issued.  The
default value for this variable is 1000 bytes.


File: cfengine-Reference.info,  Node: showactions,  Next: singlecopy,  Prev: sensiblesize,  Up: control

ShowActions
-----------

        ShowActions  = ( ON )

   This causes cfengine to produce detailed output of what action is
being carried out as part of the prefix information during output.
This is intended only for third party tools which collect and parse the
cfengine output. It will be of little interest to humans.


File: cfengine-Reference.info,  Node: singlecopy,  Next: site,  Prev: showactions,  Up: control

SingleCopy
----------


     	singlecopy = ( on )

   If `singlecopy' is defined the behavior of copy: is modified so that
a file will only be copied once, helping to achieve hierarchical or
"most specific" file copy overrides, provided that the most specific
file occurs first.  With the following file structure on a host running
cfservd:

   	/dist/hosts/loghost1.example.com/etc/syslog.conf
/dist/solaris/etc/syslog.conf 	/dist/all/etc/syslog.conf

   The configuration:

     control:
     	singlecopy = ( on )
     
     copy:
     
      /dist/${fqhost}       dest=/ inform=true syslog=true r=inf server=disthost
      /dist/${ostype}       dest=/ inform=true syslog=true r=inf server=disthost
      /dist/all             dest=/ inform=true syslog=true r=inf server=disthost

Would result in:

     /dist/hosts/loghost1.example.com/etc/syslog.conf being copied to loghost1.example.com
     /dist/solaris/etc/syslog.conf being copied to Solaris systems
     /dist/all/etc/syslog.conf being copied to all other systems

   CAUTION: this feature is necessarily memory intensive.


File: cfengine-Reference.info,  Node: site,  Next: SkipIdentify,  Prev: singlecopy,  Up: control

site/faculty
------------

       site    = ( SITENAME )
       faculty = ( FACULTYNAME )

   This variable defines a convenient name for your site configuration.
It is useful for making generic rules later on, because it means for
instance that you can define the name of a directory to be

     /$(site)/$(host)/local

without having to redefine the rule for a specific site.  This is a
handy trick for making generic rules in your files which can be imported
into a configuration for any site.

   `faculty' is a synonym for `site'.  The two names may be used
interchangeably.


File: cfengine-Reference.info,  Node: SkipIdentify,  Next: Smtpserver,  Prev: site,  Up: control

SkipIdentify
------------

       SkipIdentify = ( true )

   This is the client side directive corresponding to the server
directive `SkipVerify'. It tells cfengine not to assume that the client
is registered in the Domain Name Service (DNS). Sometimes the
assumption of DNS registration can break connectivity between hosts,
particularly if firewalls or Network Address Translation is in use.


File: cfengine-Reference.info,  Node: Smtpserver,  Next: SplayTime,  Prev: SkipIdentify,  Up: control

smtpserver
----------

       smtpserver = ( MAILHOST )

   This variable specified the destination for Email sent by cfexecd.


File: cfengine-Reference.info,  Node: SplayTime,  Next: split,  Prev: Smtpserver,  Up: control

SplayTime
---------

       SplayTime = ( TIME-IN-MINUTES )

   This variable is used to set the maximum time over which cfengine
will share its load on a server, *Note Splaying host times:
(cfengine-Tutorial)Splaying host times.


File: cfengine-Reference.info,  Node: split,  Next: spooldirectories,  Prev: SplayTime,  Up: control

Split
-----

        Split  = ( CHARACTER )

   The value of this variable is used to define the list separator in
variables which are expected to be treated as lists. The default value
of this variable is the colon `:'.  Cfengine treats variables
containing this character as lists to be broken up and iterated over,
*Note Iteration over lists::.

   This typically allows communication with PATH-like environment
variables in the shell.


File: cfengine-Reference.info,  Node: spooldirectories,  Next: suninstallcommand,  Prev: split,  Up: control

SpoolDirectories
----------------

   A list of additional spool directories for cfengine to police. In
these directories, filenames should correspond to existing users of the
system.  When users lost their accounts, this list plus the mail spool
directory will be checked for files owned by deprecated users.  See
also: `DeleteNonOwnerFiles', `DeleteNonUserFiles'.

       SpoolDirectories = ( /var/spool/cron/crontabs /var/spool/cron/atjobs )


File: cfengine-Reference.info,  Node: suninstallcommand,  Next: suspiciousnames,  Prev: spooldirectories,  Up: control

SUNInstallCommand
-----------------

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

     SUNInstallCommand = ( "/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: suspiciousnames,  Next: sysadm,  Prev: suninstallcommand,  Up: control

suspiciousnames
---------------

       SuspiciousNames = ( .mo lrk3 )

   Filenames in this list are treated as suspicious and generate a
warning as cfengine scans directories. This might be used to detect
hacked systems or concealed programs. Checks are only made in
directories which cfengine scans in connection with a command such as
files, tidy or copy.


File: cfengine-Reference.info,  Node: sysadm,  Next: Syslog,  Prev: suspiciousnames,  Up: control

sysadm
------

        sysadm = ( MAIL ADDRESS )

   The mail address of your system administrator should be placed here.
This is used in two instances.  If cfengine is invoked with the option
`-a', then it simply prints out this value.  This is a handy feature
for making scripts.

   The administrators mail address is also written into the personal log
files which cfengine creates for each user after tidying files, so you
should make this an address which users can mail if they have troubles.


File: cfengine-Reference.info,  Node: Syslog,  Next: SyslogFacility,  Prev: sysadm,  Up: control

Syslog
------


       Syslog = ( ON/off )

   This variable activates syslog logging of cfengine output at the
`inform' level.

   To set this output level one writes:


      CLASSES::
     
        Syslog = ( on )


File: cfengine-Reference.info,  Node: SyslogFacility,  Next: timezone,  Prev: Syslog,  Up: control

SyslogFacility
--------------


       SyslogFacility = ( FACILITY )

   This variable alters the syslog facility level.  e.g.


        SyslogFacility = ( LOG_LOCAL1 )

   Valid arguments are

     LOG_USER
     LOG_DAEMON
     LOG_LOCAL0
     LOG_LOCAL1
     LOG_LOCAL2
     LOG_LOCAL3
     LOG_LOCAL4


File: cfengine-Reference.info,  Node: timezone,  Next: TimeOut,  Prev: SyslogFacility,  Up: control

timezone
--------

        timezone = ( 3-CHARACTER TIMEZONE )

   The timezone variable is a list of character strings which define
your local timezone.  Normally you will only need a single timezone,
but sometimes there are several aliases for a given timezone e.g. MET
and CET are synonymous.  Currently only the first three characters of
this string are checked against the timezone which cfengine manages to
glean from the system.  If a mismatch is detected a warning message is
printed.  cfengine does not attempt to configure the timezone.  This
feature works only as a reminder, since the timezone should really be
set once and for all at the time the system is installed.  On some
systems you can set the timezone by editing a file, a procedure which
you can automate with cfengine *Note editfiles::.

   The value of the `timezone' can be accessed by variable substitution
in the usual way. It expands to the first item in your list.

     shellcommands:
     
            "echo ${timezone} | mail ${sysadm}"


File: cfengine-Reference.info,  Node: TimeOut,  Next: Verbose,  Prev: timezone,  Up: control

TimeOut
-------


       TimeOut = ( 10 )

   The default timeout for network connections is 10 seconds. This is
too short on some routed networks. It is not permitted to set this
variable smaller than 3 seconds or larger than 60 seconds.


File: cfengine-Reference.info,  Node: Verbose,  Next: Warnings,  Prev: TimeOut,  Up: control

Verbose
-------


       Verbose = ( ON/off )

   This variable switches on the output level whereby cfengine reports
everything it does during a run in great detail. Normally only urgent
messages or clear errors are printed, *Note Inform::.  This option is
almost equivalent to using the `--verbose' of `-v' command-line
options. The only difference is that system environment reporting
information, which is printed prior to parsing, is not shown.  To set
this output level on selected hosts one writes:


      CLASSES::
     
        Verbose = ( on )

   For related more limited output, *Note Inform::.


File: cfengine-Reference.info,  Node: Warnings,  Next: warnnonuserfiles,  Prev: Verbose,  Up: control

Warnings
--------


       Warnings = ( ON/off )

   This variable switches on the parser-output level whereby cfengine
reports non-fatal warnings.  This is equivalent to setting the command
line switch `--no-warn', or `-w'.  To set this output level on selected
hosts one writes:


      CLASSES::
     
        Warnings = ( on )


File: cfengine-Reference.info,  Node: warnnonuserfiles,  Next: warnnonownerfiles,  Prev: Warnings,  Up: control

WarnNonUserFiles
----------------

   If this parameter is set to true, cfengine will warn about files in
spool directories which do not have a name belonging to a known user id.

   See also `DeleteNonUserFiles'.


File: cfengine-Reference.info,  Node: warnnonownerfiles,  Next: warnnonusermail,  Prev: warnnonuserfiles,  Up: control

WarnNonOwnerFiles
-----------------

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


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

   See also `DeleteNonOwnerFiles'. This generalizes and succeeds
`DeleteNonOwnerMail'.


File: cfengine-Reference.info,  Node: warnnonusermail,  Next: warnnonownermail,  Prev: warnnonownerfiles,  Up: control

WarnNonUserMail
---------------

   If this parameter is set to true, cfengine will warn about 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: warnnonownermail,  Prev: warnnonusermail,  Up: control

WarnNonOwnerMail
----------------

   If this parameter is set to true, cfengine will warn about 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: classes,  Next: copy,  Prev: control,  Up: Cfagent reference

classes
=======

   The `classes' keyword is an alias for `groups' as of version 1.4.0
of cfengine.


File: cfengine-Reference.info,  Node: copy,  Next: defaultroute,  Prev: classes,  Up: Cfagent reference

copy
====

   Cfengine copies files between locally mounted filesystems and via the
network from registered servers.  The copy algorithm avoids
race-conditions which can occur due to network and system latencies by
copying first to a file called `FILE.cfnew' on the local filesystem,
and then renaming this quickly into place.  The aim of this roundabout
procedure is to avoid situations where the direct rewriting of a file
is interrupted midway, leaving a partially written file to be read by
other processes.  Cfengine attempts to preserve hard links to
non-directory file-objects, but see the caution below.

   _Caution should be exercised in copying files which change rapidly
in size.  This can lead to file corruption, if the size changes during
copying. Cfengine attempts to prevent this during remote copies._

   The syntax summary is:


     copy:
     
        CLASS::
     
           MASTER-FILE
                             dest=DESTINATION-FILE
                             mode=MODE
                             owner=OWNER
                             group=GROUP
                             action=WARN/SILENT/FIX
                             backup=true/FALSE/TIMESTAMP
                             repository=BACKUP DIRECTORY
                             stealth=TRUE/ON/FALSE/OFF
                             timestamps=preserve/keep
                             symlink=PATTERN
     
                             include=PATTERN
                             exclude=PATTERN
                             ignore=PATTERN
                             filter=FILTERALIAS
                             xdev=TRUE/ON/false/off
     
                             recurse=NUMBER/INF/0
                             type=ctime/MTIME/CHECKSUM/SUM/BYTE/BINARY/ANY
                             linktype=absolute/symbolic/RELATIVE/HARD/NONE/COPY
                             typecheck=true/on/FALSE/OFF
                             define=CLASS-LIST(,:.)
                             elsedefine=CLASS-LIST(,:.)
     
                             force=TRUE/ON/false/off
                             forcedirs=TRUE/ON/false/off
                             forceipv4=TRUE/ON/false/off
                             size=SIZE LIMITS
                             server=SERVER-HOST
                             failover=CLASSES
     
                             trustkey=TRUE/false
                             secure=[deprecated]
                             encrypt=TRUE/false
                             verify=TRUE/false
                             oldserver=TRUE/false
     
                             purge=TRUE/false
     
                             syslog=TRUE/ON/FALSE/OFF
                             inform=TRUE/ON/FALSE/OFF
     
                             findertype=MACOSX FINDER TYPE

`dest'
     The destination file is the only obligatory item. This must be the
     name of an object which matches the type of the master object i.e.
     if the master is a plain file, the destination must also be the
     explicit name of a plain file. An implicit `copy file to
     directory' syntax is not allowed.  Symbolic links are copied as
     symbolic links, plain files are copied as plain files and special
     files are copied as special files.  The `recurse' option is
     required to copy the contents of subdirectories.

     If the destination file name is of the form
     `filename/..namedfork/rsrc', then it is assumed that you are
     copying the resource fork of a file to an HFS+ file system on OS X
     Jaguar. In the absence of the destination file being in this form
     (just dest=filename), cfengine will assume that you are working
     with the data fork of the file.

     For a resource fork copy to properly work, the data fork must have
     already been copied. Ie the OS will not allow you to copy the
     resource fork for a file that does not exist. And, copying a data
     fork after the resource fork will overwrite the resource fork. So,
     order is important.  Copy the data fork, first. Then, copy the
     resource fork.

     To split the data and resource forks of a file into two parts,
     open up a terminal.  The following commands will copy MyFile 's
     data and resource forks into two separate files which can then be
     recombined by cfengine:

          	cp MyFile MyFile-datafork
          	cp MyFile/..namedfork/rsrc MyFile-rsrcfork

`mode, owner, group'
     The file mode, owner and group of the images are specified as in
     the `files' function *Note files::.

`action'
     The action may take the values `warn', `silent' or `fix'. The
     default action is `fix', i.e.  copy files. If `warn' is specified,
     only a warning is issued about files which require updating. If
     `silent' is given, then cfengine will copy the files but not
     report the fact.

`force'
     If set to `true', this option causes cfengine to copy files
     regardless of whether it is up to date.

`forceipv4'
     If you are working on an ipv6 enabled pair of hosts, cfengine will
     normally select ipv6 for communication between them. If you wish
     to force the use of ipv4 for some reason, set this option to true.

`forcedirs'
     If set to `true', this option causes files or links which block the
     creation of directories, during recursive copying, to be moved
     aside forcably. A single non-supressable warning is given when this
     occurs; the file is moved to filename`.cf-moved'.

`backup'
     If the `backup' option is set to "false", cfengine will not make a
     backup copy of the file before copying. The default value is
     "true".  If the option "timestamp" is chosen, a unique timestamp
     will be appended to the saved filename.

`repository'
     This allows a local override of the `Repository' variable, on an
     item by item basis. If set to "off" or "none" it cancels the value
     of a global repository.

     Copy makes a literal image of the master file at the destination,
     checking whether the master is newer than the image. If the image
     needs updating it is copied. Existing files are saved by appending
     `.cfsaved' to the filename.

`stealth'
     If set to `on' causes cfengine to preserve atime and mtime on
     source files during _local_ file copies. File times cannot be
     preserved on remote copies. This option should normally only be
     used together with a checksum copy, since preserving atime and
     mtime implies changing ctime which will force continual copying.
     This is a weakness in the Unix file system. Ctime cannot be
     preserved. Before version 1.5.0, there was a typo which made this
     option active on many file copies.

`timestamps'
     If this is set to `preserve' or `keep', the times of the source
     files are kept by the destination files during copying. This is
     like the `p' option of the `tar' command.

`recurse'
     Specifies the depth of recursion when copying whole file-trees
     recursively. The value may be a number or the keyword `inf'.
     Cfengine crosses device boundaries or mounted filesystems when
     descending recursively through file trees. To prevent this it is
     simplest to specify a maximum level of recursion.

`symlink'
     This option may be repeated a number of times to specify the names
     of files, or wildcards which match files which are to be
     symbolically linked instead of copied. A global list of patterns
     can also be defined in the control section of the program *Note
     linkcopies::.

`ignore'
     This works like the global ignore directive but here you may
     provide a private list of ignorable directories and files.  Unlike
     include, exclude this affects the way cfengine parses directory
     trees.

`include'
     This option may be repeated a number of times to specify the names
     of files, or wildcards which match files which are to be included
     in a copy operation. Specifying one of these automatically
     excludes everything else except further include patterns.  A
     global list of patterns can also be defined in the control section
     of the program.

     If the `purge' option is used in copying, then the `ignore' option
     has the effect of the excluding files from the purge, i.e.
     `ignore' means `keep' the named files.

`exclude'
     This option may be repeated a number of times to specify the names
     of files, or wildcards which match files which are to be excluded
     from a copy operation. A global list of patterns can also be
     defined in the control section of the program `excludes' override
     `includes'.  *Note excludelinks::.

`xdev'
     Prevents cfengine from descending into file systems that are not
     on the same device as the root of the rescurion path.

`type'
     Normally cfengine uses the ctime date-stamps on files to determine
     whether a file needs to be copied: a file is only copied if the
     master is newer than the copy or if the copy doesn't exist. If the
     type is set to `checksum' or `sum', then a secure MD5 checksum is
     used to determine whether the source and destination files are
     identical. If `byte' or `binary' is specified, a byte by byte
     comparison is initiated.  An `mtime' comparison does not take into
     account changes of file permissions, only modifications to the
     contents of the files.

`findertype'
     	Sets the four letter file type code in an HFS+ file system on Mac
     OS X 	Jaguar. For example, the four letter code APPL
     indicates the file is an 	Application (and will be executed
     when double-clicked). The four letter 	code TEXT indicates
     the file is a text file and will be opened by the 	default text
     editor.

     	If the file also has an extension (for example `.txt'), then if
     setting the finder type code, you should make sure your finder
     type code does not conflict with the file extension.

     	Files both without extensions and finder type codes are mostly
     useless 	to OS X, so be sure to do one or the other!

     	Also note that finder type codes should not be applied to the
     resource 	forks of files.

`server'
     If you want to copy a file remotely from a server, you specify the
     name of the server here. This must be the name of a host which is
     running the `cfservd' daemon, and you must make sure that you have
     defined the variable `domain' in the control section of the
     `cfagent.conf' file. If you don't define a domain you will
     probably receive an error of the form `cfengine: Hey! cannot stat
     file'. If the server name is `localhost', cfengine will perform a
     local copy, without using a connection to cfservd.

`failover'
     If a file copy fails due to an error, the classes in this
     assignment will become active, allowing failover rules to become
     active.

`oldserver'
     If this is true, cfengine uses the old protocol specification for
     temporary compatibility with early version 2 alphas.

`trustkey'
     This option defaults to 'no' or 'false'. If set to true, cfagent
     will accept a public key from a server whose public key is
     presently unknown to the agent, on trust. This option should be
     used to bootstrap public key transfer between hosts. Once a public
     key has been accepted, it will not be replaced automatically.
     Dated public keys must be removed by hand.

`encrypt'
     Has an effect only when used in conjuction with copy from a remote
     file server.  This causes cfengine to use encryption and one-time
     keys on transferred data.  (This requires RSA keys to be installed
     on both client and server hosts, and provides strong
     authentication and encryption, using random session keys.) The
     preferred algorithm is Blowfish, with a 128 bit key. Generally
     speaking the only case in which this function makes sense is in
     transferring shadow password files.  Encrypting the transfer of
     system binaries makes little sense. Note: the encryption keys
     required to get files from cfservd are those for the user under
     which cfservd is running (normally root).

`verify'
     If verify is true, cfagent attempts to verify the integrity of a
     remote file transfer before the new file is installed. This takes
     time, since an MD5 computation and transaction must take place.

`size'
     With this option you can specify that a file is only to be copied
     if the source file meets a size critereon. This could be used to
     avoid installing a corrupted file (the copying of an empty
     password file, for instance). Sizes are in bytes by default, but
     may also be quoted in kilobytes or megabytes using the notation:


          NUMBERbytes
          NUMBERkbytes
          NUMBERmbytes

     Only the first characters of these strings are significant, so
     they may be written however is convenient: e.g. `14kB', `14k',
     `14kilobytes' etc.   Examples are:


             size=<400  # copy if file size is < 400 bytes
             size=400   # copy if file size is equal to 400 bytes
             size=>400  # copy if file size > 400 bytes

`linktype'
     This option determines the type of link used to make links. This
     only applies if the file is linked rather than copied because it
     matches a pattern set by `symlink'. The default type is a direct
     symbolic link. The values `relative' or `absolute' may be used, but
     hard links may not be created in place of copied files, since hard
     links must normally reside on the same filesystem as their files,
     and it is assumed that most links will be between filesystems. If
     this value is set to `copy' or `none', symbolic links will be
     replaced by actual copies of the files they point to. Note that
     for directories, this option is ignored.

`typecheck'
     Controls whether cfengine allows files of one type to overwrite
     files of another type, i.e. switches on/off errors if source and
     existing destination files do not match in type, e.g. if a file
     would overwrite a directory or link. The default is on for safety
     reasons.

`define'
     This option is followed by a list of classes which are to be
     `switched on' if and only if the named file was copied.  In
     multiple (recursive) copy operations the classes become defined if
     any of the files in the file tree were copied. This feature is
     useful for switching on other actions which are to be performed
     after the installation of key files (e.g.  package installation
     scripts etc).

`purge'
     If this option is set to true, cfengine will remove files in the
     destination directory which are not also in the source directory.
     This allows exact images of filesystems to be mantained. Note that
     if the copy command has includes or excludes or ignored files,
     cfengine will purge only those files on the client machine which
     are also on the server. Included files are not purged.  This means
     that some files (such as system specific work files) can be
     excluded from copies without them being destroyed.  Note that
     purging is disallowed if contant with a remote server fails.  This
     means that local files will not be destroyed by a denial of service
     attack. _You should not use this option to synchronize NFS mounted
     file systems. If the NFS server goes down, cfengine cannot then
     tell the difference between a valid empty directory and a missing
     NFS file system.  If you use purge, use a remote copy also._ If we
     specify purge, then the following options will also be set and
     cannot be altered: `forcedirs=true', `typecheck=false', since
     other defaults could be very destructive.

Example:


     copy:
     
           /local/etc/aliases dest=/etc/aliases m=644 o=root g=other
           /local/backup-etc  dest=/etc
     
        solaris::
     
           /local/etc/nsswitch.conf dest=/etc/nsswitch.conf

In the first example, a global aliases file is copied from the master
site file `/local/etc/aliases' to `/etc/aliases', setting the owner and
protection as specified. The file gets installed if `/etc/aliases'
doesn't exist and updated if `/local/etc/aliases' is newer than
`/etc/aliases'. In the second example, `backup-etc' is a directory
containing master configuration files (for instance, `services',
`aliases', `passwd'...). Each of the files in `backup-etc' is installed
or updated under `/etc'. Finally, a global `nsswitch.conf' file is kept
up to date for Solaris systems.

   The `home' directive can be used as a destination, in which case
cfengine will copy files to every user on the system. This is handy for
distributing setup files and keeping them updated:


     copy:
     
        /local/masterfiles/.cshrc  dest=home/.cshrc mode=0600

You can force the copying of files, regardless of the date stamps by
setting the option `force=true' or `force=on'. The default is
`force=false' or `force=off'.

* Menu:

* hard links in copy::
* Too many open files::


File: cfengine-Reference.info,  Node: hard links in copy,  Next: Too many open files,  Prev: copy,  Up: copy

Hard links in copying
---------------------

   Hard links are not like symbolic links, they are not merely pointers
to other files, but alternative names for the same file. The name of
every file is a hard link, the first so to speak. You can add
additional names which _really are_ the file, they are not just
pointers. For the technically minded, they are not separate inodes,
they are additional directory references to the same inode.  When you
perform a copy operation on multiple files, cfengine attempts to
preserve hard links but this is a difficult task.

   Because a hard link just looks like an ordinary file (it cannot be
distingiushed from the original, the way a symbolic link can) there is
a danger that any copy operation will copy two hard links to the same
file as two separate copies of the same file. The difference is that
changes a hard-linked file propagate to the links, whereas two copies
of a file are completely independent thereafter.  In order to
faithfully reproduce all hardlinks to all files, cfengine needs to
examine every file on the same filesystem and check whether they have
the same inode-number. This would be an enourmous overhead, so it is
not done. Instead what happens is that cfengine keeps track of only the
files which it is asked to examine, for each atomic copy-command, and
makes a note of any repeated inodes within this restricted set.  It
does not try to go off, wandering around file systems looking to other
files which might be hardlinks.

   To summarize, cfengine preserves hardlinks during copying, only
within the scope of the present search. No backups are made of hard
links, only of the first link or name of the file is backed up. This is
a necessary precaution to avoid dangling references in the inode table.
As a general rule, hard links are to be avoided because they are
difficult to keep track of.


File: cfengine-Reference.info,  Node: Too many open files,  Prev: hard links in copy,  Up: copy

Too many open files
-------------------

   In long recursive copies, where you descend into many levels of
diretories, you can quickly run out of file descriptors. The number of
file descriptors is a resource which you can often set in the shell. It
is a good idea to set this limit to a large number on a host which will
be copying a lot of files. For instance, in the C shell you would write,


     limit descriptors 1024

Most systems should have adequate defaults for this parameter, but on
some systems it appears to be set to a low value such as 64, which is
not sufficient for large recursive tree searches.


File: cfengine-Reference.info,  Node: defaultroute,  Next: disks,  Prev: copy,  Up: Cfagent reference

defaultroute
============

   Dynamical routing is not configurable in cfengine, but for machines
with static routing tables it is useful to check that a default route is
configured to point to the nearest gateway or router.  The syntax for
this statement is simply:


     defaultroute:
     
        CLASS::
     
           my_gateway

For example:


     defaultroute:
     
       most::
     
          129.240.22.1
     
       rest::
     
          small_gw
     
       no_default_route::
     
          192.168.1.1

Gateways and routers usually have internet address `aaa.bbb.ccc.1' --
i.e.  the first address on the subnet.  You may use the numerical form
or a hostname for the gateway.

   The class `no_default_route' is defined if the current host does not
have a currently defined default route, but specifies one in its
configuration.


File: cfengine-Reference.info,  Node: disks,  Next: directories,  Prev: defaultroute,  Up: Cfagent reference

disks
=====

   This is a synonyn for `required', *Note required::.  This action
tests for the existence of a file or filesystem.  It should be called
after all NFS filesystems have been mounted.  You may use the special
variable `$(binserver)' here.


       disks:
     
         /FILESYSTEM freespace=SIZE-LIMIT define=CLASS-LIST(,:.)
     
          inform=TRUE
          log=TRUE
     
          scanarrivals=TRUE
          force=TRUE
     
          ifelapsed=MINS
          expireafter=MINS

   Files or filesystems which you consider to be essential to the
operation of the system can be declared as `required'.  Cfengine will
warn if such files are not found, or if they look funny.

   Suppose you mount your filesystem `/usr/local' via NFS from some
binary server.  You might want to check that this filesystem is not
empty! This might occur if the filesystem was actually _not_ mounted as
expected, but failed for some reason.  It is therefore not enough to
check whether the directory `/usr/local' exists, one must also check
whether it contains anything sensible.

   Cfengine uses two variables: `sensiblesize' and `sensiblecount' to
figure out whether a file or filesystem is sensible or not.  You can
change the default values of these variables (which are 1000 and 2
respectively) in the `control' section.  *Note control::.

   If a file is smaller than `sensiblesize' or does not exist, it fails
the `required' test.  If a directory does not exist, or contains fewer
than `sensiblecount' files, then it also fails the test and a warning
is issued.


     disks:
     
        any::
     
           /$(site)/$(binserver)/local

   If you set the `freespace' variable to a value and set `inform=true',
cfagent issues warnings when free disk space falls below this threshold.
Any define-classes also become defined in this instance.  (the default
units are kilobytes, but you may specify bytes or megabytes), e.g.

   If the option `force=true' is used, cfengine will parse filesystems
even on NFS mounted filesystems. Normally it does not make sense to
check filesystems that are not native to the local host, but
occasionally ne would like to force such a check in order to set a
class, based on the result, for instance.

   If the `scanarrivals' option is set, the agent will recursively
descend through the file system building a database of file
modification times. This data is used for research purposes and will
eventually be used to trigger classes that determine optimal times for
backup of filesystem.

