bionic (8) direvent.8.gz

Provided by: direvent_5.1-1_amd64 bug

NAME

       direvent - directory event monitor

SYNOPSIS

       direvent  [-HVdfh]  [-F  NAME]  [-P  FILE]  [-l  PRIO]  [-I DIR] [-T COMMAND] [--debug] [--facility=NAME]
       [--foreground] [--include=DIR] [--pidfile=FILE] [--self-test=COMMAND] [--user=NAME] [CONFIG]

       direvent -h
       direvent --help

       direvent -H
       direvent --config-help

       direvent --usage

       direvent -V
       direvent --version

DESCRIPTION

       GNU Direvent monitors a set of directories on the file system and reacts when a file system event  occurs
       in  any  of  them.   Directories  and events to monitor are specified in the configuration file.  When an
       event occurs the utility reacts by invoking an external command configured for that event.

       The following generic events can be monitored by the program:

       create A file was created;

       delete A file was deleted;

       write  A file was written to;

       attrib File attributes have changed.  This includes changes in the file ownership, mode, link count, etc.

       Depending on the interface provided by the underlying operating system direvent can trace various system-
       dependent  events, which may offer a better resolution.  These events are described in the section SYSTEM
       DEPENDENCIES below.

       A watcher is a configuration entity within direvent which associates a set of directories with a  set  of
       events  and  instructs  the program to run a specified external command when any of these events occur in
       any of these directories.  This external command (called a handler)  can  obtain  information  about  the
       event  that  triggered  its  execution  from the environment variables, or from its command line (see the
       HANDLER ENVIRONMENT section below).

       Watchers  are  declared  in  the  program  configuration  file  direvent.conf,  located  in  the   system
       configuration directory (normally /etc).

       An  alternative  configuration  file  can be used, by supplying its pathname as the command line argument
       (CONFIG parameter in the SYNOPSIS section above).

OPTIONS

       -d, --debug
              Increase debug verbosity level.

       -F, --facility=FACILITY
              Log under this syslog facility.  Allowed values for FACILITY are a decimal number or  any  of  the
              following  symbolic  names:  auth,  authpriv, cron, daemon, ftp, local0 through local7, lpr, mail,
              news, user, and uucp.

              The option -F 0 directs logging to the standard error.

       -f, --foreground
              Run in the foreground.

       -I, --include=DIR
              Add DIR to the include search path.  When looking for a  file  to  be  included  in  the  #include
              (#include_once) statement, direvent scans first the 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.

       -l PRIO
              While  connected  to  a  terminal  direvent  outputs  its  diagnostics  messages to stderr and, if
              configured, to syslog.  This option limits the amount of information output to the standard error.
              PRIO  is  one  of the following priorities (in order of increasing severity): debug, info, notice,
              warning, err, crit, alert, emerg.  When this option is given,  only  messages  with  the  priority
              level equal to or greater than PRIO will be duplicated on the standard error.

       -P, --pidfile=FILE
              Write PID to FILE.

       -T, --self-test=COMMAND
              Run in self-test mode.  In this mode, direvent starts external command supplied as the argument to
              this option and continues running until the command exits.  If the  command  terminates  normally,
              direvent  exits with the code returned by it.  If the command terminates on SIGHUP, direvent exits
              with code 0.  If it terminates on another signal, direvent exits with code 2.

              COMMAND can include any command line options or arguments, provided that it  is  properly  quoted.
              It is invoked as /bin/sh -c COMMAND in the environment of the parent direvent process.

              The  macro  variable  $self_test_pid  holds the PID of the COMMAND (see section MACRO EXPANSION in
              direvent.conf(5)).

       -t, --lint
              Check configuration file for errors and exit.

       -u, --user=USER
              Run as this USER.

       Informative options cause the program to display the requested piece of information and exit:

       -h, --help
              Output a terse help summary and exit.

       -H, --config-help
              Describe configuration file syntax.

       --usage
              Show available command line options.

       -V, --version
              Print program version and copyright information.

CONFIGURATION

       The default configuration file is /etc/direvent.conf.  If a file name is supplied as an argument  to  the
       program, that file will be read instead.

       The  configuration  file syntax is discussed in detail in direvent.conf(5).  This section provides only a
       short description of it.

       Three types of comments are allowed: inline comments, that begin with a # or // and extend to the end  of
       line,  and multi-line comments, which comprise everything enclosed between /* and */.  Comments and empty
       lines are ignored.  Whitespace characters are ignored as well, except as they serve to separate tokens.

       A token is a string of consecutive  characters  from  the  following  classes:  alphanumeric  characters,
       underscores, dots, asteriscs, slashes, semicolons, commercial at's, and dashes.

       Any  other  sequence  of  characters  must  be enclosed in double quotation marks in order to represent a
       single token.

       Adjacent quoted strings are concatenated.

       Configuration statements consist of a keyword and value separated by any  amount  of  whitespace  and  is
       terminated with a semicolon.  A block statement is a collection of statements enclosed in curly braces.

       The most important configuration statement is watcher.  It is defined as follows:

         watcher {
             path PATHNAME [recursive [LEVEL]];
             event EVENT-LIST;
             command COMMAND-LINE;
             user NAME;
             timeout NUMBER;
             environ ENV-SPEC;
             option STRING-LIST;
         }

       Each  watcher  statement  instructs  direvent to monitor the events listed in EVENT-LIST occurring in the
       directories specified by PATHNAMEs in path statements (any number of path statements can be given).  When
       any such event is detected, the COMMAND-LINE will be executed.

       Each  directory defined with the recursive keyword will be watched recursively.  This means that for each
       subdirectory created in it, direvent will install a watcher similar to that of its parent directory.  The
       optional  LEVEL  can  be  used to set up a cut-off nesting level, beyond which the recursive operation is
       disabled.

       The rest of statements are optional.  The user statement can be used to execute the COMMAND-LINE  as  the
       user  NAME  (provided,  of course, that direvent is started with root privileges).  The timeout specifies
       the maximum amount of time (in seconds) the command is allowed to run.  It defaults to  5.   The  environ
       statement  modifies  the  command environment (see the following section).  Finally, the option statement
       supplies additional options.  It can be used, for example, to divert the command's output to syslog.

       The program's logging is controlled by the debug and syslog statements.

       debug NUMBER;
              Sets the debugging level to NUMBER -- an integer value between 0 and 3.  Zero is the  default  and
              means  the  debugging  is disabled.  The bigger the NUMBER the more detailed debugging information
              will be output.

       The syslog statement controls the syslog logging:

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

       The pidfile statement instructs the program to write its PID to
       the named file after disconnecting from the controlling terminal.

HANDLER ENVIRONMENT

       The handler to be executed on an event is defined by the command statement in the  watcher  configuration
       block (see direvent.conf(5)).  Before executing, the following operations are performed:

       1.     The current working directory is set to the directory where the event occurred.

       2.     If  the  environ statement is present in the watcher, the environment is modified according to its
              rules.  See the description of the environ statement in direvent.conf(5).

       3.     The standard input is closed.

              If the stdout option is supplied, the standard output is captured and redirected  to  the  syslog.
              Otherwise it is closed.

              If  the  stderr  option  is supplied, the standard error is captured and redirected to the syslog.
              Otherwise it is closed.

              All file descriptors above 2 are closed.

       4.     Macro variables are expanded.  See the section MACRO EXPANSION in direvent.conf(5).  For  example,
              if  the  handler is about to be executed for the write event on the file somefile, and the command
              definition was:

                  command "/libexec/handler -e '$genev_name' -f '$file'";

              then the resulting command line will be:

                  /libexec/handler -e 'open' -f 'somefile'

       5.     Word splitting is performed on the resulting command line.  The  first  word  is  treated  as  the
              pathname of the program to be executed.

       6.     The program is invoked.

SYSTEM DEPENDENCIES

       Direvent relies on the event monitoring API provided by the kernel.

Linux

       On Linux the program uses inotify(7).

       The  maximum  number  of watches a user process can have is controlled by the fs.inotify.max_user_watches
       system variable.  Normally it is set to 8192, which is quite enough for most purposes.  However,  if  you
       monitor  a  big number or directories and/or are using recursive watchers, you may need more watches.  In
       that case, use sysctl(8) to raise the limit, e.g.:

           sysctl -w fs.inotify.max_user_watches=16384

       Most GNU/Linux distributions provide the file /etc/sysctl.conf which can be used to set this variable  on
       startup.

       The following system-dependent events are defined on systems that use inotify(7):

       ACCESS A file was accessed.

       ATTRIB A file's metadata changed.

       CLOSE_WRITE
              A writable file was closed.

       CLOSE_NOWRITE
              An unwritable file closed.

       CREATE A file was created.

       DELETE A file was deleted.

       MODIFY A file was modified.

       MOVED_FROM
              A file was moved into a monitored directory.

       MOVED_TO
              A file was moved out from a monitored directory.

       OPEN   A file was opened.

BSD

       When  compiled  on BSD systems (including Darwin), direvent uses kqueue(2).  This interface needs an open
       file handle for each file in a monitored directory, which means that the number of watchers is limited by
       the maximum number of open files.  Use ulimit -n NUM to raise it to a higher number.

       Since  it  operates  on  files,  kqueue  does  not  provide  direct support for the create generic event.
       Direvent works over this disadvantage by keeping track of the contents of each  monitored  directory  and
       rescanning  it  each  time a WRITE system event is reported for it.  It then generates the open event for
       each file that appeared after the last scan.  Such a rescan can consume considerable time if a  directory
       has a very large number of files in it.

       The following system-dependent events are available:

       DELETE The unlink() system call was called on the monitored file.

       WRITE  A write occurred on the file.

       EXTEND The file was extended.

       ATTRIB The file attributes have changed.

       LINK   The link count on the file changed.

       RENAME The file was renamed.

       REVOKE Access to the file was revoked via revoke(2) or the underlying file system was unmounted.

Darwin

       Essentially  the  same  as  BSD.   The  main  difference  compared to Linux and BSD is that on Darwin the
       watchers are set after disconnecting from the controlling terminal, because  Darwin  lacks  the  rfork(2)
       call and the event queue cannot be inherited by the child process.

EXIT CODE

       0      Successful termination.

       1      Command line usage error.

       2      Another error occurred.

SEE ALSO

       direvent.conf(5), inotify(7), kqueue(2).

AUTHORS

       Sergey Poznyakoff

BUG REPORTS

       Report bugs to <bug-direvent@gnu.org.ua>.

       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.