This is cfengine-Reference.info, produced by makeinfo version 4.0 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: 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: secureinput,  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: secureinput,  Next: sensiblecount,  Prev: repository,  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: site,  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: site,  Next: SplayTime,  Prev: showactions,  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: SplayTime,  Next: split,  Prev: site,  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: suspiciousnames,  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 in
the following cases:

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

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

   * in the directory field of a tidy action,

   * in the directory field of the files action,

   * in the ignore action.


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


File: cfengine-Reference.info,  Node: suspiciousnames,  Next: sysadm,  Prev: split,  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.  *Note Using the help 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: timezone,  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: timezone,  Next: TimeOut,  Prev: Syslog,  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: warnnonusermail,  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: warnnonusermail,  Next: warnnonownermail,  Prev: Warnings,  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: Command 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: Command 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=SILENT/FIX
                             backup=true/FALSE
                             repository=BACKUP DIRECTORY
                             stealth=TRUE/ON/FALSE/OFF
                             timestamps=preserve/keep
                             symlink=PATTERN
                             include=PATTERN
                             exclude=PATTERN
                             ignore=PATTERN
                             filter=FILTERALIAS
                             recurse=NUMBER/INF/0
                             type=ctime/MTIME/CHECKSUM/SUM/BYTE/BINARY
                             linktype=absolute/symbolic/RELATIVE/HARD/NONE/COPY
                             typecheck=true/on/FALSE/OFF
                             define=CLASS-LIST(,:.)
                             elsedefine=CLASS-LIST(,:.)
     
                             force=TRUE/ON/false/off
                             size=SIZE LIMITS
                             server=SERVER-HOST
                             secure=TRUE/false
                             purge=TRUE/false
                             syslog=TRUE/ON/FALSE/OFF
                             inform=TRUE/ON/FALSE/OFF

`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. If the master and image are
     directories then all of the child files _which are not
     directories_ are copied from source to destination.

`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' or `silent'. 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.

`backup'
     If the `backup' option is set to "false", cfengine will not make a
     backup copy of the file before copying.

`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.

`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::.

`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.

`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 `cfd' daemon, and you must make sure that you have
     defined the variable `domain' in the control section of the
     `cfengine.conf' file. If you don't define a domain you will
     probably receive an error of the form `cfengine: Hey! cannot stat
     file'.

`secure'
     Has an effect only when used in conjuction with copy from a remote
     file server.  This causes cfengine to use 3DES key encryption and
     one-time keys on transferred data.  This provides good enough
     privacy for the purposes of system adminstration, but it is not
     meant to be a super-secure means of encryption. Generally speaking
     the only case in which this function makes sense is in
     transferring shadow password files. If you are encrypting the
     transfer of system binaries, you need your head examining. When
     encrypt is specified, an md5 checksum is always used to verify the
     file. Note: the encryption keys required to get files from cfd are
     those for the user under which cfd is running (normally root). Cfd
     will not switch keys for other users, so encrypted transfer will
     not work for all users. If a file _requires_ encrypted transfer
     (secure flag in cfd) then normal users will not be able to collect
     it.

`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'
     Switches on/off error messages if source and existing destination
     files do not match in type, e.g. if a file would overwrite a
     directory or link.

`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. 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._

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: Command 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

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.


File: cfengine-Reference.info,  Node: disks,  Next: directories,  Prev: defaultroute,  Up: Command 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(,:.)

   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 (the default units
are kilobytes, but you may specify bytes or megabytes), e.g.


File: cfengine-Reference.info,  Node: directories,  Next: disable,  Prev: disks,  Up: Command reference

directories
===========

   Directories declarations consist of a number of directories to be
created.  Directories and files may also be checked and created using
the `touch' option in the `files' actions.  *Note files::.

   The form of a declaration is:


       directories:
     
          CLASSES::
     
              /DIRECTORY
                              mode=MODE
                              owner=UID
                              group=GID
                              define=CLASSLIST
                              syslog=TRUE/ON/FALSE/OFF
                              inform=TRUE/ON/FALSE/OFF

For example


     directories:
     
       CLASS::
     
          /usr/local/bin  mode=755 owner=root group=wheel

The form of the command is similar to that of `files' but this command
is only used to create new directories.  Valid options are `mode',
`owner', `group' and are described under `files' *Note files::. This
interface is only for convenience.  It is strictly a part of the
`files' functionality and is performed together with other `files'
actions at run time.

   The creation of a path will fail if one of the links in the path is a
plain file or device node.  A list of classes may optionally be defined
here if a directory is created.


File: cfengine-Reference.info,  Node: disable,  Next: editfiles,  Prev: directories,  Up: Command reference

disable
=======

   Disabling a file means renaming it so that it becomes harmless.  This
feature is useful if you want to prevent certain dangerous files from
being around, but you don't want to delete them-- a deleted file cannot
be examined later.  The syntax is


      disable:
     
        CLASS::
     
           /FILENAME
                           type=PLAIN/FILE/LINK/LINKS
                           rotate=EMPTY/TRUNCATE/NUMERICAL-VALUE
                           size=NUMERICAL-VALUE
                           define=CLASSLIST
                           syslog=TRUE/ON/FALSE/OFF
                           inform=TRUE/ON/FALSE/OFF
                           repository=DESTINATION DIRECTORY

Cfengine renames a given file by appending the name of the file with the
suffix `.cfdisabled'.  A typical example of a file you would probably
want to disable would be the `/etc/hosts.equiv' file which is often
found with the `+' symbol written in it, opening the system concerned
to the entire NIS universe without password protection!  Here is an
example:


     disable:
     
           /etc/hosts.equiv
           /etc/nologin
           /usr/lib/sendmail.fc
     
        sun4::
     
           /var/spool/cron/at.allow

Hint: The last example disables a file which restricts access to the
`at' utility.  Such a command could be followed by a file action, *Note
files::,

     files:
     
        some::
     
           /var/spool/cron/at.allow =0644 N [root] [wheel] touch

which would create an empty security file `at.allow'.  See also your
system manual pages for the `at' command if you don't understand why
this could be useful.

   Disabling a link deletes the link. If you wish you may use the
optional syntax


     disable:
     
         /directory/name type=file

to specify that a file object should only be disabled if it is a plain
file. The optional element `type=' can take the values `plain', `file',
`link' or `links'. If one of these is specified, cfengine checks the
type and only disables the object if there is a match. This allows you
to disable a file and replace it by a link to another file for instance.

   NOTE that if you regularly disable a file which then gets recreated
by some process, the disabled file `FILENAME.cfdisabled' will be
overwritten each time cfengine disables the file and therefore the
contents of the original are lost each time. The `rotate' facility was
created for just this contingency.

   The disable feature can be used to control the size of system log
files, such as `/var/adm/messages' using a further option `rotate'.  If
the value rotate is set to 4, say,


      disable:
     
         FILENAME  rotate=4

then cfengine renames the file concerned by appending `.1' to it and a
new, empty file is created in its place with the same owner and
permissions. The next time disable is executed `.1' is renamed to `.2'
and the file is renamed `.1' and a new empty file is created with the
same permissions. Cfengine continues to rotate the files like this
keeping a maximum of four files. This is similar to the behaviour of
syslog.

   If you simply want to empty the contents of a log file, without
retaining a copy then you can use `rotate=empty' or `rotate=truncate'.
For instance, to keep control of your World Wide Web server logs:

     disable:
     
        Sunday|Wednesday::
     
            /usr/local/httpd/logs/access_log  rotate=empty

This keeps a running log which is emptied each Sunday and Wednesday.

   The `size=' option in disable allows you to carry out a disable
operation only if the size of the file is less than, equal to or greater
than some specified size. 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  # disable if file size is < 400 bytes
        size=400   # disable if file size is equal to 400 bytes
        size=>400  # disable if file size > 400 bytes

This options works with `rotate' or normal disabling; it is just an
extra condition which must be satisfied.

   If a disable command results in action being taken by cfengine, an
optional list of classes becomes can be switched on with the aid of a
statement `define=CLASSLIST' in order to trigger knock-on actions.

   The `repository' declaration 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 and leaves the
disabled file in the same directory.

