path: root/doc/direvent.texi

\input texinfo @c -*-texinfo-*-
@smallbook
@c %**start of header
@setfilename direvent.info
@settitle GNU Direvent
@c %**end of header
@c @setchapternewpage odd

@defcodeindex pr
@defcodeindex op
@defcodeindex kw
@defcodeindex fl

@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp
@syncodeindex op cp
@syncodeindex pr cp
@syncodeindex kw cp
@syncodeindex fl cp

@include version.texi

@macro GNUDIREVENT
@acronym{GNU} @command{direvent}
@end macro

@ifinfo
@dircategory Individual utilities
@direntry
* direvent: (direvent).                Monitor changes in directories.
@end direntry
@end ifinfo

@copying
Copyright @copyright{} 2013-2014 Sergey Poznyakoff

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, and with Front-Cover and Back-Cover at your option.
A copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end copying

@titlepage
@title GNU Direvent
@subtitle version @value{VERSION}, @value{UPDATED}
@author Sergey Poznyakoff.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnothtml
@page
@summarycontents
@page
@end ifnothtml
@contents

@ifnottex
@node Top
@top Direvent

This edition of the @cite{GNU Direvent} manual, last updated @value{UPDATED},
documents GNU Direvent Version @value{VERSION}.
@end ifnottex

@menu

* Intro::                   Introduction.
* Overview::
* Quick start::
* Invocation::
* Configuration::
* System dependencies::
* Reporting Bugs::          How to Report a Bug.

Appendices

* Copying This Manual::  The GNU Free Documentation License.
* Concept Index::        Index of Concepts.

@detailmenu
@end detailmenu
@end menu

@node Intro
@chapter Introduction
@GNUDIREVENT{} monitors events in file system directories.  For each
event that occurs in a set of pre-configured directories, the program
calls an external program associated with it, supplying it the
information about the event and the location within the file system
where it took place.

@GNUDIREVENT{} provides an easy way to configure
your system to react immediately if certain files undergo changes.
This may be helpful, for example, to track changes in important
configuration files.

Interfaces for tracking changes to file systems
are highly system-specific.  @GNUDIREVENT{} aims to provide a uniform
and system-independent command-level interface.  As of version
@value{VERSION} @command{direvent} works with modern Linux kernels
(since v. 2.6.13) and BSD systems (FreeBSD, NetBSD, OpenBSD, Darwin).

@node Overview
@chapter Overview
@GNUDIREVENT{} 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 program reacts by invoking an external command
configured for that event.			      

@cindex events
@cindex file system events
File system events can be divided into two major groups.  The
@dfn{system-dependent events} are specific for each particular kernel
interface.  In the contrast, @dfn{generic events} don't depend on the
underlying system.  They provide a higher level of abstraction and
make it possible to port @GNUDIREVENT{} configurations between various
systems and architectures.

@cindex generic events
@cindex events, generic
The generic events are:

@table @asis
@cindex create, generic event
@item create
A file was created.
@cindex delete, generic event
@item delete
A file was deleted;
@cindex write, generic event
@item write
A file was written to;
@cindex attrib, generic event
@item attrib
File attributes have changed.  This includes changes in the file
ownership, mode, link count, etc.
@end table

@cindex watcher, introduced
@cindex handler, introduced
A @dfn{watcher} is a configuration entity that associates a set of
directories with a set of events and instructs @command{direvent} to
run a specified external command when any of these events occur in any
of these directories.  This external command (called a @dfn{handler})
can obtain information about the event that triggered it
from the environment variables, or from its command line.

Watchers are defined in the configuration file, which
@command{direvent} reads at startup.  This file has a simple and easy
to use syntax.

Three types of comments are allowed: inline comments, that begin with
a @samp{#} or @samp{//} and extend to the end of line, and multi-line
comments, which comprise everything enclosed between @samp{/*} and
@samp{*/}.  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.

A configuration statement consists 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.

@cindex watcher declaration, summary
The following block statement declares a watcher:

@example
@group
watcher @{
    path @var{pathname} [recursive [@var{level}]];
    file @var{pattern-list};
    event  @var{event-list};
    command @var{command-line};
    user @var{name};
    timeout @var{number};
    environ @var{env-spec};
    option @var{string-list};
@}
@end group
@end example

Each @code{watcher} statement instructs @command{direvent} to monitor
events listed in @var{event-list} occurring in the directories
specified by @var{pathname}s in @code{path} statements (any number of
@code{path} statements can be given).  When any such event is detected,
the supplied @var{command-line} will be executed.

Each directory defined with the @code{recursive} keyword will be
watched recursively.  This means that for each subdirectory created in
it, @command{direvent} will install a watcher similar to that of its parent
directory.  Optional @var{level} statement 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 @code{file} statement
instructs @GNUDIREVENT{} to react only if the event concerned the
file whose name matches one of the patterns given in its argument.
The @code{user} statement can be used to execute the
@var{command-line} as the user @var{name} (provided, of course, that
@command{direvent} is started with root privileges).  The
@code{timeout} specifies the maximum amount of time (in seconds) the
command is allowed to run.  It defaults to 5.  The @code{environ}
statement modifies the command environment.  Finally, the
@code{option} statement supplies additional options.  It can be used,
for example, to divert the command's output to syslog.

@node Quick start
@chapter Quick Start
Let's suppose you have a directory where users can upload their files
and you want these files to be processed right after upload, in real
time.  Let this directory be @file{/home/ftp/incoming} and the program
to process the upload be @file{/usr/bin/upload}.  Let's also suppose
that this program expects name of the uploaded file as its argument.

To make @command{direvent} handle this task, you would need to create a
watcher for the upload directory which would handle the @samp{create} event:

@example
watcher @{
    path /home/ftp/incoming;
    event create;
    # @r{more statements follow...}
@end example

On this event, the watcher is to invoke @file{/usr/bin/upload}
with the name of the created file as an argument.  To make it
possible, the @command{direvent} configuration file provides @dfn{macro
variables}, which can be used in the @code{command} argument at
configuration time and which are expanded to the actual values before
the command is executed.  Macro variables are referred to using the
same syntax as shell variables: a dollar sign followed by the variable
name, optionally enclosed in curly braces.  The @samp{file} variable
is expanded to the name of the file for which the event is reported.
This name is relative to the current working directory which, by the
time the handler is executed, is set to the directory where the event
occurred.  Thus, the handler can be configured as:

@example
    command "/usr/bin/upload $file";
@end example

To summarize, the watcher declaration is:

@example
watcher @{
    path /home/ftp/incoming;
    event create;
    command "/usr/bin/upload $file";
@}    
@end example

@cindex handler execution environment
@anchor{handler environment}
Before invoking the handler, the following operations are performed:

@enumerate 1
@item
The current working directory is set to the directory where the event
occurred.
@item
If the @code{environ} statement is present in the watcher, the
environment is modified according to its rules.  (@pxref{environ,
environment modification})
@item
The standard input is closed.
@item
If the @samp{stdout} option is supplied,
the standard output is captured and redirected to the syslog.
Otherwise it is closed.
@item
If the @samp{stderr} option is supplied,
the standard error is captured and redirected to the syslog.
Otherwise it is closed.
@item
File descriptors above 2 are closed.
@item
Macro variables are expanded.  @xref{macro expansion}.
@item
Word splitting is performed on the resulting command line.  The first
word is treated as the pathname of the program to be executed.
@item
The program is invoked.
@end enumerate

@node Invocation
@chapter Invocation
The invocation syntax is:

@example
direvent  [@var{options}] [@var{config}]
@end example

@noindent
where @var{options} are command line options discussed below and
optional @var{config} supplies the configuration file to use instead
of the default @file{/etc/direvent.conf}.

The options are:

@table @option
@opindex -F
@opindex --facility
@item -F @var{name}
@itemx --facility=@var{name}
Set syslog facility.
@opindex -P
@opindex --pidfile
@item -P @var{file}
@itemx --pidfile=@var{file}
Upon successful startup store the PID of the daemon process in
@var{file}.
@opindex -d
@opindex --debug
@item -d
@itemx --debug
Increase debug level.
@opindex -f
@opindex --foreground
@item -f
@itemx --foreground
Remain in foreground.
@opindex -l
@item -l @var{prio}
While connected to a terminal, @command{direvent} outputs its diagnostics
messages to stderr and, if configured, to syslog.  This option
limits the amount of information output to the standard error.
The @var{prio} argument is one of the following priorities (in order
of increasing severity): @samp{debug}, @samp{info}, @samp{notice},
@samp{warning}, @samp{err}, @samp{crit}, @samp{alert}, @samp{emerg}.
When this option is given, only messages with the priority level equal
to or greater than @var{prio} will be duplicated on the standard error.
@end table

The following options are @dfn{informative}.  They cause the program
to display the requested piece of information and terminate:

@table @option
@opindex -H
@opindex --config-help
@item -H
@itemx --config-help
Show configuration file summary.
@opindex -V
@opindex --version
@item -V
@itemx --version
Print program version.
@opindex -h
@opindex --help
@item -h
@itemx --help
Give a short usage summary.
@item --usage
Display available command line options.
@end table
      
@node Configuration
@chapter Configuration

@menu
* syntax::
* macro expansion::
* general settings::
* syslog::
* watcher::
@end menu

@node syntax
@section Configuration Syntax
  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
@dfn{white space} are ignored except as they serve to separate
tokens.  Some white space is required to separate otherwise adjacent 
keywords and values.

@menu
* Comments::
* Pragmatic Comments::
* Statements::
@end menu

@node Comments
@subsection Comments
@cindex Comments in a configuration file
@cindex single-line comments
  @dfn{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.  @dfn{Single-line} comments start
with @samp{#} or @samp{//} and continue to the end of the line:

@smallexample
# This is a comment
// This too is a comment
@end smallexample

@cindex multi-line comments
  @dfn{Multi-line} or @dfn{C-style} comments start with the two
characters @samp{/*} (slash, star) and continue until the first
occurrence of @samp{*/} (star, slash).

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

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

@table @code
@kwindex #include
@item #include <@var{file}>
@itemx #include @var{file}
Include the contents of the file @var{file}.

@kwindex #include_once
@item #include_once <@var{file}>
@itemx #include_once @var{file}
  Same as @code{#include}, except that, if the @var{file} has already
been included, it will not be included again.

@kwindex #line
@item #line @var{num}
@itemx #line @var{num} "@var{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
@var{num} and the current input file is named by @var{file}.
If the latter is absent, the remembered file name does not change.

@item # @var{num} "@var{file}"
  This is a special form of @code{#line} statement, understood for
compatibility with the @sc{c} preprocessor.
@end table

@node Statements
@subsection Statements
@cindex statements, configuration file
@cindex configuration file statements
@cindex statement, simple
@cindex simple statements
  A @dfn{simple statement} consists of a keyword and value
separated by any amount of whitespace.  Simple statement is terminated
with a semicolon (@samp{;}).

  The following is a simple statement:

@smallexample
standalone yes;
pidfile /var/run/direvent.pid;
@end smallexample

  A @dfn{keyword} begins with a letter and may contain letters,
decimal digits, underscores (@samp{_}) and dashes (@samp{-}).
Examples of keywords are: @samp{expression}, @samp{output-file}.

  A @dfn{value} can be one of the following:

@table @asis
@item number
  A number is a sequence of decimal digits.

@item boolean
@cindex boolean value
  A boolean value is one of the following: @samp{yes}, @samp{true},
@samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no},
@samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}.
  
@item unquoted string
@cindex string, unquoted
  An unquoted string may contain letters, digits, and any of the
following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/},
@samp{@@}, @samp{*}, @samp{:}.

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

@float Table, backslash-interpretation
@caption{Backslash escapes}
@multitable @columnfractions 0.30 .5
@item Sequence @tab Replaced with
@item \a @tab Audible bell character (@acronym{ASCII} 7)
@item \b @tab Backspace character (@acronym{ASCII} 8)
@item \f @tab Form-feed character (@acronym{ASCII} 12)
@item \n @tab Newline character (@acronym{ASCII} 10)
@item \r @tab Carriage return character (@acronym{ASCII} 13)
@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
@item \v @tab Vertical tabulation character (@acronym{ASCII} 11)
@item \\ @tab A single backslash (@samp{\})
@item \" @tab A double-quote.
@end multitable
@end float

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

@smallexample
@group
"a long string may be\
 split over several lines"
@end group
@end smallexample

  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:

@smallexample
@group
"a long string may be"
" split over several lines"
@end group
@end smallexample

@anchor{here-document}
@item Here-document
@cindex here-document
  A @dfn{here-document} is a special construct that allows to introduce
strings of text containing embedded newlines.  

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

@smallexample
@group
<<EOT
A multiline
string
EOT
@end group
@end smallexample

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

  If @var{word} is prefixed with @code{-} (a dash), then all leading
tab characters are stripped from input lines and the line containing
@var{word}.  Furthermore, if @code{-} 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:

@smallexample
@group
<<- TEXT
    The leading whitespace will be
    ignored when reading these lines.
TEXT
@end group
@end smallexample

  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: 

@smallexample
help-text <<-EOT
        A sample help text.
EOT;
@end smallexample

@item list
@cindex list
  A @dfn{list} is a comma-separated list of values.  Lists are
enclosed in parentheses.  The following example shows a statement
whose value is a list of strings:

@smallexample
option (stdout,stderr);
@end smallexample

  In any case 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.

@smallexample
option wait;
@end smallexample

@noindent
is equivalent to

@smallexample
option (wait);
@end smallexample
@end table

@cindex statement, block
@cindex block statement
  A @dfn{block statement} introduces a logical group of 
statements.  It consists of a keyword, followed by an optional value,
and a sequence of statements enclosed in curly braces, as shown in
the example below:

@smallexample
@group
syslog @{
  facility local0;
  tag "direvent";
@}
@end group
@end smallexample

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

@node macro expansion
@section Macro Expansion
@cindex macro expansion
Arguments of some statements undergo macro expansion before use.
During the macro expansion any occurrence of @samp{$@var{name}} is replaced
by the value of the macro @var{name}.  Macro names follow the usual
convention: they begin with a letter and contain letters, digits and
underscores.  Curly braces around the @var{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
@samp{$@{command@}string}.

The following macros are defined:

@table @asis
@anchor{$file}
@kwindex file, macro variable
@item file
Name of the file that triggered the event.

@anchor{$sysev_code}
@kwindex sysev_code, macro variable
@item sysev_code
A system-dependent event code.  It is a bitwise OR of the event codes
represented as a decimal number.  

@anchor{$sysev_name}
@kwindex sysev_name, macro variable
@item sysev_name
A 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 @samp{sysev_code}.
@xref{System dependencies}, for a list of system-dependent event names.

@anchor{$genev_code}
@kwindex genev_code, macro variable
@item genev_code
Generic (system-independent) event code.  It is a bitwise OR of
the event codes represented as a decimal number.

@anchor{$genev_name}
@kwindex genev_name, macro variable
@item 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 @samp{$genev_code}. 
@end table

@node general settings
@section General Settings

@deffn {Config} user @var{name}
Sets the user to run as.  The @var{name} argument must be a name of an
existing user.
@end deffn

@deffn {Config} foreground @var{bool}
Run in foreground.
@end deffn

@deffn {Config} pidfile @var{file}
Upon successful startup store the PID of the daemon process in @var{file}.
@end deffn

@deffn {Config} debug @var{number}
Set debug level.  Valid @var{number} values are @samp{0} (no debug) to @samp{3}
(maximum verbosity).
@end deffn

@node syslog
@section Syslog
@cindex syslog
@cindex logging
While connected to the terminal, @command{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:

@example
syslog @{
    facilit