Provided by: direvent_5.1-1_amd64 bug

NAME

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

DESCRIPTION

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

COMMENTS

       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.  If FILE is an absolute file name, the named
              file is included.  An error message will be issued if it does not exist.

              If  FILE contains wildcard characters (*, [, ], or ?), it is interpreted as a shell
              globbing  pattern  and  all  files  matching  that   pattern   are   included,   in
              lexicographical  order.   If no matching files are found, the directive is replaced
              with an empty line.

              Otherwise, the form with angle brackets searches for file  in  the  include  search
              path,  while  the  second  one looks for it in the current working directory first,
              and, if not found there, in the include search path.  If the file is not found,  an
              error message will be issued.

              The  order  of  directories  is  as follows.  First, direvent scans any directories
              given with -I options, in the same order as given on the command line, and then the
              directories  in the standard include search path.  The latter is defined at compile
              time and can be inspected in the output of the --help option.

       #include_once <FILE>
       #include_once FILE
              Same as #include, except that, if the FILE (or any of the files it expands to)  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.

STATEMENTS

   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/direvent.pid;

       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.

       boolean
              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 one 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"

       Here-document
              A here-document is a special construct that allows one 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:

                  <<EOT
                  A multiline
                  string
                  EOT

              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  one  to
              indent here-documents in a natural fashion.  For example:

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

              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.
                   EOT;

       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.

MACRO EXPANSION

       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.

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

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

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

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

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

GENERAL SETTINGS

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

LOGGING

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

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

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

       An example syslog statement:

           syslog {
               facility local0;
               print-priority yes;
           }

WATCHER

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

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

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

                       shell  Invoke the handler command as /bin/sh -c "command".

                       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:

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

                 DIREVENT_SYSEV_NAME
                        The   system-dependent   event  name  or  names  (see  the  ${sysev_name}
                        variable).

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

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

                 DIREVENT_FILE
                        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
                        list.

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

                 -NAME=VAL
                        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.

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

                 NAME+=VALUE
                        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.:

                            PATH+=:/sbin

                        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.

                 NAME=+VALUE
                        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.

SEE ALSO

       direvent(8).

COPYRIGHT

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