Syntax

A files-statement can have several options. We can begin by examining the form of the statement in pseudo-code:

  files:

     classes::

        /file-object
                          mode=mode
                          owner=uid-list
                          group=gid-list
                          action=fixall/other-options/warnall 
                          links=false/stop/traverse/follow/tidy

                          ignore=pattern
                          include=pattern
                          exclude=pattern
                          filter=filter alias

                          define=classlist
                          elsedefine=classlist

                          checksum=md5
                          flags=BSD flags
                          syslog=true/on/false/off
                          inform=true/on/false/off

An example would be the following:

   any::

      /var/spool/printQ  mode=0775  r=0 o=daemon g=daemon  act=fixdirs

The meaning of these item is sketched out below and becomes clearer on looking at a number of examples. Note that, each of the options below can be written in either upper or lower case and abbreviated by any unique abbreviation. A file object is interpreted as a directory if you write it in the following form: `/directory-path/.'. i.e. a trailing dot signifies a directory. This then becomes the same as the directory command.

/directory

This is the only obligatory part of a file action. This is a directory at which a file search should begin. This may be a single file or a directory. The recursion specifier may be used to force cfengine to descend into subdirectories in a controlled fashion, starting from this point, checking files there also. The wildcard home may also be used. See section home directive.

mode=modestring

Specifies what the allowed permissions for files are. If cfengine finds that a file's mode is incorrect, the value of the action option determines what will be done about it. The modestring should consist of either a three digit octal numbers with `+', `-' or `=' symbols, or a text string like that used by the command chmod. For instance: mode=u=rwx,og+rx would mean set the read/write and execute flags for the user (file owner) and add the read/execute flags for others and group bits. An example of the numerical form might be -002 which would mean that the read-for-others flag should either not be set or should be unset, depending on the action you choose. +2000 would mean that the setuid flag should be present or set, depending on the action. +2000,-002 would be a combination of these. The `=' sign sets to an absolute value, so =755 would set the file mode to mode 755.

flags=BSD flags

The free BSD Unices have additional filesystem flags which can be seton files. Refer to the BSD chflags documentation for this. For example,

   /tmp/flags.01  mode=0600 owner=0 group=0
                  flags=uappnd,uchg,uunlnk,nodump,opaque,sappnd,schg,sunlnk
                  action=touch      

recurse=number/inf

This specifier tells cfengine whether or not to recurse into subdirectories. If the value is zero, only the named file or directory is affected. If the value is 1, it will open at most one level of subdirectory and affect the files within this scope. If the value is inf then cfengine opens all subdirectories and files beginning from the specified filename.See section Recursion.

owner=owner list

This is a list of allowed owners, or uids by number, separated by commas. For example root,2,3,sysadm. In cases where you ask cfengine to fix the ownership automatically, the owner will be set to the first owner in the list if and only if it is not one of the named uids in the list.

group=group list

This is a list of allowed groups, or gids by number, separated by commas. For example wheel,2,3,sysadm. In cases where you ask cfengine to fix the ownership automatically, the group will be set to the first group in the list if and only if it is not one of the named gids in the list.

action=action

The action is one of the following keywords.

warnall warndirs warnplain
 fixall fixdirs fixplain
touch linkchildren create compress alert

The upper line results only in warnings being issued. The actions beginning `fix' prompt cfengine to fix encountered problems without bothering the user. No message is issued unless in verbose mode. The special features on the third line will be explained separately. Alert is like -print in the find command, it triggers on the existence of files which have not been ignored, excluded or filtered. This should normally be used together filter, in order to locate files of particular types.

include=wildcard/pattern

You can include this option several times to specify specific patterns which are to be included in the search. Once you specify one pattern you exclude all files not matching at least one of the patterns. The case be useful for restricting a search, or for modifying the permissions of only certain files.

exclude=wildcard/pattern

You can include this option several times to specify specific patterns which are to be excluded from the search. This overrides any patterns given in the include= list.

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.

links=stop/traverse/tidy

Normally cfengine does not descend into subdirectories which are pointed to by symbolic links. If you wish to force it to do so (without using the -l command line option) you may give this option the value true, or traverse, or follow. To specify no recursion you set the value false or stop. Note that the value set here in the cfengine program always overrides the value set by the -l command line option, so you can protect certain actions from this command line option by specifying a negative value here. If you specify no value here, the behaviour is determined by what you specify on the command line. The value links=tidy has the same effect as the `-L' command line option except that here it may be specified per item rather than globally. Setting this value causes links which point to non-existent files to be deleted. If the warn directive is used (for directories, plain files or both) then only a warning message is issued if the file being tested does not match the specification given. If the fix directives are used then cfengine does not issue a warning, it simply fixes the value silently. Non-existent files are created by the touch command. A directory may be touched (created) by writing the filename /a/b/c/. with a dot as the last character. (This may also be achieved with the directories directive, See section directories.)

define=classlist

If a file operation results in action being taken to fix a file, the colon, comma or dot separated list of classes becomes defined. Warnings do not activate the classes.

checksum=md5

If set this option causes cfengine to add a checksum for the named file to a database. Changes in the value of this checksum are then warned as a security issue. This should normally only be used to monitor binary files which one would not expect to change often. Note also that the use of this option can mean a significant performance penalty. The variable ChecksumDatabase should be set in control: to the filename of a database file which is used to cache checksum values. Note that it is also possible to use a database file for cfd's remote copying by checksum. If you use the same file for both purposes you risk losing warnings. Security warning messages are issued only once and the value in the database is then changed to the new value of the file automatically i.e. the behaviour is similar to that of setuid root program detection, @xref{Checksum Databases,Checksum Databases,Checksum Databases,cfengine-Tutorial}.

The default values are mode=+000, recurse=0, action=warnall and any owner or group is acceptable. The default for links is to not traverse links unless the -l option is set on the command line.

Go to the first, previous, next, last section, table of contents.