Next: , Previous: files, Up: Command reference


1.14 filters

A filter is a way of selecting or pruning during a search over files or processes. Since filter rules could apply to several objects, cfengine allows you to define filter conditions as separate objects to be applied in different contexts.

Filter objects can be used in copy, editfiles, files, tidy and processes. In most cases one writes

     .. filter=<i>filteralias</i>

in the appropriate command. The exception is editfiles, where the syntax is

     {
     ..
     Filter "filteralias"
     ..
     }

Example:

     
     files:
     
      /tmp filter=testfilteralias action=alert r=inf
     

Filters are defined in a separate section. Filters for files and processes are defined together. They differ only in the criteria they contain. Here is are examples of file filters:

     Filters:
     
       { filteralias1
     
       Owner:     "mark|cell|motd"
       Group:     "ecg|mark"
       Mode:      "700"
     
       FromCtime: "date(2000,1,1,0,0,0)"    # absolute date
       ToCtime:   "now"
     
       FromMtime: "tminus(1,0,0,2,30,0)"    # relative "ago" from now
       ToMtime:   "inf"                     # end of time
     
       FromAtime: "date(1997,2,22,0,0,0)"
       ToAtime:   "inf"
     
       FromSize:  "10000"                   # File size interval
       ToSize:    "10mb"
     
       ExecRegex: "/usr/bin/file(.*ascii.*)"# Result from "files" command
     
       Type:      "dir|link"                # reg|link|dir|socket|fifo|door|char|block
     
       NameRegex: ".*.asc"                  # regex matching file name
     
       IsSymLinkTo: "/dev/null"             # True if file is a link to object name regex
     
       Result:    "Type"                    # Result which shouldbe returned
     
       }
     
      #########################################
     
       { testfilteralias2
     
       ExecProgram: "/bin/ls $(this)"       # True if the program returns true. $(this) is the current object
       }
     
      #########################################
     
       { testfilteralias3
     
       Owner: "mark"
       }

Filters are evaluated like classes. In fact, the filtering works by evaluating the class attributes for each file.

File filters:

Owner:
and Group can use numerical id's or names, or "none" for users or groups which are undefined in the system passwd/group file.
Mode: applies only to file objects. It shares syntax with the mode= strings in the files command. This test returns true if the bits which are specified as `should be set' are indeed set, and those which are specified as `should not be set' are not set.
Atime:,Ctime:,Mtime:
apply only to file objects. These specify ranges From and To. If the file's time stamps lie in the specified range, this returns true. Times are specfied by a six component vector
          (year,month,day,hour,minutes,seconds)
     

This may be evaluated as two functions: date() or tminus() which give absolute times and times relative to the current time respectively. In addition, the words now and inf may be used. e.g.

            FromCtime: "date(2000,1,1,0,0,0)"   # absolute date
            ToCtime:   "now"
          
            FromMtime: "tminus(1,0,0,2,30,0)"     # relative "ago" from now
            ToMtime:   "inf"                     # end of time
     

Type:
applies only to file objects may be a list of file types which are to be matched. The list should be separated by the OR symbol `|', since these types are mutually exclusive. The possible values are currently
          reg|link|dir|socket|fifo|door|char|block
     

ExecRegex:
matches the test string against the output of the specified command.
NameRegex:
matches the name of the file with a regular expression.
IsSymLinkTo:
applies only when the file object $(this) is a symbolic link. It is true if the regular expression matches the contents of the link.
ExecProgram:
matches if the command returns successfully (with return code 0). Note that this feature introduces an implicit dependency on the command being called. This might be exploitable as a security weakness by advanced intruders.
Result:
specifies the way in which the above elements are combined into a single filter.

Process filters:

PID:
process ID (quoted regex)
PPID:
parent process ID (quoted regex)
PGID:
process group ID (quoted regex)
RSize:
resident size (quoted regex)
VSize:
virtual memory size (quoted regex)
Status:
status (quoted regex)
Command:
CMD or COMMAND fields (quoted regex)
(From/To)TTime:
Total elasped time in TIME field (accumulated time)
(From/To)STime:
Starting time for process in STIME or START field (accumulated time)
TTY:
terminal type, or none (quoted regex)
Priority:
PRI or NI field (quoted regex)
Threads:
NLWP field for SVR4 (quoted regex)
Result:
logical combination of above returned by filter (quoted regex)
Examples: processes started between 18th Nov 2000 and now.
       { filteralias
     
       FromSTime: "date(2000,11,18,0,0,0)"
       ToSTime:   "now"
       }

All processes which have accumulated between 1 and 20 hours of CPU time.

       { filteralias
     
       FromTTime:  "accumulated(0,0,0,1,0,0)"
       ToTTime:    "accumulated(0,0,0,20,0,0)"
       }