Provided by: direvent_5.0.90-1_amd64 bug


       direvent.conf - configuration file for direvent(8).


       The configuration file consists of statements and comments.

       There are three classes of lexical tokens: keywords, values, and separators. Blanks, tabs,
       newlines and comments, collectively called white space are ignored except as they serve to
       separate  tokens. Some white space is required to separate otherwise adjacent keywords and


       Comments may appear anywhere where white space  may  appear  in  the  configuration  file.
       There  are  two  kinds  of  comments:  single-line  and  multi-line comments.  Single-line
       comments start with # or // and continue to the end of the line:

           # This is a comment
           // This too is a comment

       Multi-line or C-style comments start with the two characters /* (slash, star) and continue
       until the first occurrence of */ (star, slash).

       Multi-line  comments  cannot  be  nested.   However,  single-line comments may well appear
       within multi-line ones.

   Pragmatic Comments
       Pragmatic comments are similar to the usual single-line comments, except that  they  cause
       some  changes  in  the way the configuration is parsed.  Pragmatic comments begin with a #
       sign and end with the next physical newline character.

       #include <FILE>
       #include FILE
              Include the contents of the file file.  Both forms are equivalent.  The  FILE  must
              be an absolute file name.

       #include_once <FILE>
       #include_once FILE
              Same  as  #include, except that, if the FILE has already been included, it will not
              be included again.

       #line num
       #line num "FILE"
              This line causes the parser to believe, for purposes of error diagnostics, that the
              line  number  of the next source line is given by num and the current input file is
              named by FILE. If the latter is absent, the remembered file name does not change.

       # num "FILE"
              This is a special form of the #line statement, understood  for  compatibility  with
              the C preprocessor.


   Simple statement
       A  simple statement consists of a keyword and value separated by any amount of whitespace.
       Simple statement is terminated with a semicolon (;).

       The following is a simple statement:

           pidfile /var/run/;

       See below for a list of valid simple statements.

       A value can be one of the following:

       number A number is a sequence of decimal digits.

              A boolean value is one of the following: yes, true, t or 1, meaning true,  and  no,
              false, nil, 0 meaning false.

       unquoted string
              An  unquoted  string  may  contain  letters,  digits,  and  any  of  the  following
              characters: _, -, ., /, @, *, :.

       quoted string
              A quoted string is any sequence of characters enclosed  in  double-quotes  (").   A
              backslash  appearing within a quoted string introduces an escape sequence, which is
              replaced with a single character according to the following rules:

                      Sequence  Expansion               ASCII
                      \\        \                       134
                      \"        "                       042
                      \a        audible bell            007
                      \b        backspace               010
                      \f        form-feed               014
                      \n        new line                012
                      \r        charriage return        015
                      \t        horizontal tabulation   011
                      \v        vertical tabulation     013

              In addition, the sequence \newline is removed from  the  string.   This  allows  to
              split long strings over several physical lines, e.g.:

                  "a long string may be\
                   split over several lines"

              If  the  character  following  a backslash is not one of those specified above, the
              backslash is ignored and a warning is issued.

              Two or more adjacent quoted strings are concatenated, which gives  another  way  to
              split  long  strings  over  several  lines  to  improve readability.  The following
              fragment produces the same result as the example above:

                  "a long string may be"
                  " split over several lines"

              A here-document is a special construct that allows to  introduce  strings  of  text
              containing embedded newlines.

              The <<word construct instructs the parser to read all the following lines up to the
              line containing only word, with possible trailing blanks.  Any lines thus read  are
              concatenated together into a single string.  For example:

                  A multiline

              The  body of a here-document is interpreted the same way as a double-quoted string,
              unless word is preceded by a backslash (e.g.  <<\EOT) or enclosed in double-quotes,
              in which case the text is read as is, without interpretation of escape sequences.

              If  word  is prefixed with - (a dash), then all leading tab characters are stripped
              from input lines and the line containing word.  Furthermore, -  is  followed  by  a
              single  space, all leading whitespace is stripped from them.  This allows to indent
              here-documents in a natural fashion.  For example:

                  <<- TEXT
                      The leading whitespace will be
                      ignored when reading these lines.

              It is important that the terminating delimiter be the only token on its line.   The
              only  exception  to  this  rule  is  allowed if a here-document appears as the last
              element of a statement.  In this case a semicolon can be placed on  the  same  line
              with its terminating delimiter, as in:

                   help-text <<-EOT
                       A sample help text.

       list   A  comma-separated  list of values, enclosed in parentheses.  The following example
              shows a statement whose value is a list of strings:

                  option (wait, stderr);

              In any context where a list is appropriate, a single value is allowed without being
              a  member  of  a list: it is equivalent to a list with a single member.  This means
              that, e.g.

                  option wait;

              is equivalent to

                  option (wait);

   Block Statement
       A block statement introduces a logical group of statements.  It  consists  of  a  keyword,
       followed  by  an  optional  value,  called a tag, and a sequence of statements enclosed in
       curly braces, as shown in the example below:

           watcher {
               path /etc;
               event create;

       The closing curly brace may be followed by a semicolon, although this is not required.


       Arguments of some statements  undergo  macro  expansion  before  use.   During  the  macro
       expansion  any  occurrence of ${NAME} is replaced by the value of macro NAME.  Macro names
       follow the usual convention: they begin with a  letter  and  contain  letters  digits  and
       underscores.   The  curly  braces around the NAME are optional.  They are required only if
       the macro reference is followed by a character that is not to be interpreted  as  part  of
       its name, as in ${command}string.

       The following macros are defined:

       file   Name of the file covered by the event.

              Generic  (system-independent)  event  code.   It is a bitwise OR of the event codes
              represented as a decimal number.

              Generic event name.  If several generic events  are  reported  simultaneously,  the
              value  of  this  variable  is  a list of event names separated by space characters.
              Each name corresponds to a bit in genev_code.

              The PID of the external command started  with  the  --self-test  (-T)  option.   If
              direvent is started without this option, this variable is not defined.

              System-dependent  event code.  It is a bitwise OR of the event codes represented as
              a decimal number.

              System-dependent event name.  If several events are reported,  the  value  of  this
              variable  is  a  list  of  event  names  separated  by space characters.  Each name
              corresponds to a bit  in  sysev_code.   See  the  section  SYSTEM  DEPENDENCIES  in
              direvent(8), for a list of system-dependent event names.


       user NAME;
              Sets the user to run as.  NAME must be a name of an existing user.

       foreground BOOL;
              Run in foreground.

       pidfile FILE;
              Upon successful startup store the PID of the daemon process in FILE.

       debug NUMBER;
              Set debug level.  Valid NUMBER values are 0 (no debug) to 3 (maximum verbosity).


       While connected to the terminal direvent outputs its diagnostics and debugging messages to
       the standard error.  After disconnecting from the controlling terminal it closes the first
       three  file  descriptors  and  directs  all  its  output  to  the syslog.  When running in
       foreground mode, its messages are sent both to the standard error and to the syslog.

       The following configuration statement controls the syslog output:

         syslog {
             facility STRING;
             tag STRING;
             print-priority BOOL;

       The statements are:

       facility STRING;
              Set syslog facility.  STRING is  one  of  the  following:  user,  daemon,  auth  or
              authpriv,  mail,  cron,  local0  through  local7  (case-insensitive), or a facility

       tag STRING;
              Tag syslog messages with STRING.  Normally the messages are tagged with the program

       print-priority BOOL;
              Prefix each message with its priority.

       An example syslog statement:

           syslog {
               facility local0;
               print-priority yes;


       The  watcher  statement  configures a single event watcher.  A watcher can control several
       events in multiple pathnames.   Any  number  of  watcher  statements  is  allowed  in  the
       configuration file, each one of them declaring a separate watcher.

         watcher {
             path PATHNAME [recursive [NUMBER]];
             file STRING-LIST;
             event STRING-LIST;
             command STRING;
             user NAME;
             timeout NUMBER;
             option STRING-LIST;
             environ ENV-SPEC;

       The statements within a watcher block are:

       path PATHNAME [recursive [NUMBER]];
              Defines a pathname to watch.  PATHNAME must be the name of an existing directory in
              the file system.  The watcher will watch events occurring for all files within that
              directory.   If  the optional recursive clause is specified, this directory will be
              watched recursively, i.e.  when any subdirectory is created in  it,  direvent  will
              set up a watcher for files in this subdirectory.  This new watcher will be an exact
              copy of the parent watcher, excepting  for  the  pathnames.   The  optional  NUMBER
              parameter defines a cut-off nesting level for recursive watching.  If supplied, the
              recursive behaviour will apply only to the directories that are nested  below  that

              Any  number  of  path  statements can appear in a watcher block.  At least one path
              must be defined.

       file STRING-LIST;
              Selects which files are eligible  for  monitoring.   The  argument  is  a  list  of
              globbing  patterns (in the sense of fnmatch(3)) and/or extended regular expressions
              ( regex(7)) one of which the file name must match in order for the watcher  to  act
              on  it.   Regular  expressions  must be surrounded by a pair of slashes, optionally
              followed by the following flags:

              b      Use basic regular expressions.

              i      Enable case-insensitive matching.

                     A pattern or regular expression prefixed with  !  matches  file  names  that
                     don't match the pattern without !.

       event STRING-LIST;
              Configures  the  filesystem  events to watch for in the directories declared by the
              path statements.  The argument is a list of event names.  Both generic and  system-
              dependent  event  namess  are  allowed.   Multiple  event statements accumulate.  A
              missing event statements means watch all events.  For example:

                  event (open,delete);

       command STRING;
              Defines a command to execute on event.  STRING is a command line just as you  would
              type  it in sh(1).  It may contain macro variables, which will be expanded prior to
              execution.  For example:

                  command "/bin/prog -event $genev_name -file $file";

              See the section HANDLER ENVIRONMENT in direvent(8), for a  detailed  discussion  of
              how the command is executed.

       user STRING;
              Run command as this user.

       timeout NUMBER;
              Terminate  the  command  if  it  runs longer than NUMBER seconds.  The default is 5

       option STRING-LIST;
              A list of additional options.  The following options are defined:

                       wait   Wait for the program to terminate before handling next  event  from
                              the event queue.  Normally the program runs asynchronously.

                       stdout Capture  the  standard output of the command and redirect it to the
                              syslog with the LOG_INFO priority.

                       stderr Capture the standard error of the command and redirect  it  to  the
                              syslog with the LOG_ERR priority.

       environ ENV-SPEC;
              Modify  command  environment.   By  default the command inherits the environment of
              direvent augmented with the following variables:

                        The system-dependent event code (see the ${sysev_code} variable).

                        The  system-dependent  event  name  or  names  (see   the   ${sysev_name}

                        The generic event code (see the ${genev_code} variable).

                        The generic event name or names (see the ${genev_name} variable).

                        The  name  of the affected file relative to the current working directory
                        (see the ${file} variable).

              The environ statement allows for trimming the environment.  Its argument is a  list
              of one or more of the folloeing environment modification directives:

                 - (a single dash)
                        Clear  the  inherited  environment,  but  retain  the  variables added by
                        direvent.  The removed environment variables can be selectively  restored
                        by  the  directives that follow.  This must be the first directive in the

                 -- (double-dash)
                        Clear the entire environment, including the variables added by  direvent.
                        This must be the first directive in the list.

                 -NAME  Unset the variable NAME.

                        Unset the environment variable NAME only if its value is VAL.

                 NAME   Restore  the environment variable NAME.  This directive is useful after -
                        or -- to retain some variables from the environment.

                        Define environment variable NAME to the VALUE.  VALUE can  contain  macro
                        variables, which will be expanded prior to the assignment.

                        Retain  the  variable NAME and append VALUE to its existing value.  If no
                        such variable is present in the  environment,  it  will  be  created  and
                        assigned  the  VALUE.  If VALUE begins with a punctuation character, this
                        character is removed from it before the assignment.  This  is  convenient
                        for using this construct with environment variables like PATH, e.g.:


                        In  this  example,  if  PATH  exists,  :/sbin  will  be  appended  to it.
                        Otherwise, it will be created and assigned the value /sbin.

                        The VALUE can contain macro variables, which will be  expanded  prior  to
                        the assignment.

                        Retain  the variable NAME and prepend VALUE to its existing value.  If no
                        such variable is present in the  environment,  it  will  be  created  and
                        assigned  the  VALUE.   In  this  case,  if VALUE ends with a punctuation
                        character, this character will be removed from it before the assignment.

                        The VALUE can contain macro variables, which will be  expanded  prior  to
                        the assignment.




       Copyright © 2012, 2013 Sergey Poznyakoff
       License GPLv3+: GNU GPL version 3 or later <>
       This  is free software: you are free to change and redistribute it.  There is NO WARRANTY,
       to the extent permitted by law.