1DIREVENT.CONF(5) Direvent User Reference DIREVENT.CONF(5)
2
6 direvent.conf - configuration file for direvent(8).
7
9 The configuration file consists of statements and comments.
10 There are three classes of lexical tokens: keywords, values, and sepa‐
12 rators. Blanks, tabs, newlines and comments, collectively called white
13 space are ignored except as they serve to separate tokens. Some white
14 space is required to separate otherwise adjacent keywords and values.
15
17 Comments may appear anywhere where white space may appear in the con‐
18 figuration file. There are two kinds of comments: single-line and
19 multi-line comments. Single-line comments start with # or // and con‐
20 tinue to the end of the line:
21 # This is a comment
23 // This too is a comment
24 Multi-line or C-style comments start with the two characters /* (slash,
26 star) and continue until the first occurrence of */ (star, slash).
27 Multi-line comments cannot be nested. However, single-line comments
29 may well appear within multi-line ones.
30 Pragmatic Comments
32 Pragmatic comments are similar to the usual single-line comments, ex‐
33 cept that they cause some changes in the way the configuration is
34 parsed. Pragmatic comments begin with a # sign and end with the next
35 physical newline character.
36 #include <FILE>
38 #include FILE
39 Include the contents of the file FILE. If FILE is an absolute
40 file name, the named file is included. An error message will be
41 issued if it does not exist.
42 If FILE contains wildcard characters (*, [, ], or ?), it is in‐
44 terpreted as a shell globbing pattern and all files matching
45 that pattern are included, in lexicographical order. If no
46 matching files are found, the directive is replaced with an
47 empty line.
48 Otherwise, the form with angle brackets searches for file in the
50 include search path, while the second one looks for it in the
51 current working directory first, and, if not found there, in the
52 include search path. If the file is not found, an error message
53 will be issued.
54 The order of directories is as follows. First, direvent scans
56 any directories given with -I options, in the same order as
57 given on the command line, and then the directories in the stan‐
58 dard include search path. The latter is defined at compile time
59 and can be inspected in the output of the --help option.
60 #include_once <FILE>
62 #include_once FILE
63 Same as #include, except that, if the FILE (or any of the files
64 it expands to) has already been included, it will not be in‐
65 cluded again.
66 #line num
68 #line num "FILE"
69 This line causes the parser to believe, for purposes of error
70 diagnostics, that the line number of the next source line is
71 given by num and the current input file is named by FILE. If the
72 latter is absent, the remembered file name does not change.
73 # num "FILE"
75 This is a special form of the #line statement, understood for
76 compatibility with the C preprocessor.
77
79 Simple statement
80 A simple statement consists of a keyword and value separated by any
81 amount of whitespace. Simple statement is terminated with a semicolon
82 (;).
83 The following is a simple statement:
85 pidfile /var/run/direvent.pid;
87 See below for a list of valid simple statements.
89 A value can be one of the following:
91 number A number is a sequence of decimal digits.
93 boolean
95 A boolean value is one of the following: yes, true, t or 1,
96 meaning true, and no, false, nil, 0 meaning false.
97 unquoted string
99 An unquoted string may contain letters, digits, and any of the
100 following characters: _, -, ., /, @, *, :.
101 quoted string
103 A quoted string is any sequence of characters enclosed in dou‐
104 ble-quotes ("). A backslash appearing within a quoted string
105 introduces an escape sequence, which is replaced with a single
106 character according to the following rules:
107 Sequence Expansion ASCII
109 \\ \ 134
110 \" " 042
111 \a audible bell 007
112 \b backspace 010
113 \f form-feed 014
114 \n new line 012
115 \r charriage return 015
116 \t horizontal tabulation 011
117 \v vertical tabulation 013
118 In addition, the sequence \newline is removed from the string.
120 This allows to split long strings over several physical lines,
121 e.g.:
122 "a long string may be\
124 split over several lines"
125 If the character following a backslash is not one of those spec‐
127 ified above, the backslash is ignored and a warning is issued.
128 Two or more adjacent quoted strings are concatenated, which
130 gives another way to split long strings over several lines to
131 improve readability. The following fragment produces the same
132 result as the example above:
133 "a long string may be"
135 " split over several lines"
136 Here-document
138 A here-document is a special construct that allows to introduce
139 strings of text containing embedded newlines.
140 The <<word construct instructs the parser to read all the fol‐
142 lowing lines up to the line containing only word, with possible
143 trailing blanks. Any lines thus read are concatenated together
144 into a single string. For example:
145 <<EOT
147 A multiline
148 string
149 EOT
150 The body of a here-document is interpreted the same way as a
152 double-quoted string, unless word is preceded by a backslash
153 (e.g. <<\EOT) or enclosed in double-quotes, in which case the
154 text is read as is, without interpretation of escape sequences.
155 If word is prefixed with - (a dash), then all leading tab char‐
157 acters are stripped from input lines and the line containing
158 word. Furthermore, - is followed by a single space, all leading
159 whitespace is stripped from them. This allows to indent here-
160 documents in a natural fashion. For example:
161 <<- TEXT
163 The leading whitespace will be
164 ignored when reading these lines.
165 TEXT
166 It is important that the terminating delimiter be the only token
168 on its line. The only exception to this rule is allowed if a
169 here-document appears as the last element of a statement. In
170 this case a semicolon can be placed on the same line with its
171 terminating delimiter, as in:
172 help-text <<-EOT
174 A sample help text.
175 EOT;
176 list A comma-separated list of values, enclosed in parentheses. The
178 following example shows a statement whose value is a list of
179 strings:
180 option (wait, stderr);
182 In any context where a list is appropriate, a single value is
184 allowed without being a member of a list: it is equivalent to a
185 list with a single member. This means that, e.g.
186 option wait;
188 is equivalent to
190 option (wait);
192 Block Statement
194 A block statement introduces a logical group of statements. It con‐
195 sists of a keyword, followed by an optional value, called a tag, and a
196 sequence of statements enclosed in curly braces, as shown in the exam‐
197 ple below:
198 watcher {
200 path /etc;
201 event create;
202 }
203 The closing curly brace may be followed by a semicolon, although this
205 is not required.
206
208 Arguments of some statements undergo macro expansion before use. Dur‐
209 ing the macro expansion any occurrence of ${NAME} is replaced by the
210 value of macro NAME. Macro names follow the usual convention: they be‐
211 gin with a letter and contain letters digits and underscores. The
212 curly braces around the NAME are optional. They are required only if
213 the macro reference is followed by a character that is not to be inter‐
214 preted as part of its name, as in ${command}string.
215 The following macros are defined:
217 file Name of the file covered by the event.
219 genev_code
221 Generic (system-independent) event code. It is a bitwise OR of
222 the event codes represented as a decimal number.
223 genev_name
225 Generic event name. If several generic events are reported si‐
226 multaneously, the value of this variable is a list of event
227 names separated by space characters. Each name corresponds to a
228 bit in genev_code.
229 self_test_pid
231 The PID of the external command started with the --self-test
232 (-T) option. If direvent is started without this option, this
233 variable is not defined.
234 sysev_code
236 System-dependent event code. It is a bitwise OR of the event
237 codes represented as a decimal number.
238 sysev_name
240 System-dependent event name. If several events are reported,
241 the value of this variable is a list of event names separated by
242 space characters. Each name corresponds to a bit in sysev_code.
243 See the section SYSTEM DEPENDENCIES in direvent(8), for a list
244 of system-dependent event names.
245
247 user NAME;
248 Sets the user to run as. NAME must be a name of an existing
249 user.
250 foreground BOOL;
252 Run in foreground.
253 pidfile FILE;
255 Upon successful startup store the PID of the daemon process in
256 FILE.
257 debug NUMBER;
259 Set debug level. Valid NUMBER values are 0 (no debug) to 3
260 (maximum verbosity).
261
263 While connected to the terminal direvent outputs its diagnostics and
264 debugging messages to the standard error. After disconnecting from the
265 controlling terminal it closes the first three file descriptors and di‐
266 rects all its output to the syslog. When running in foreground mode,
267 its messages are sent both to the standard error and to the syslog.
268 The following configuration statement controls the syslog output:
270 syslog {
272 facility STRING;
273 tag STRING;
274 print-priority BOOL;
275 }
276 The statements are:
278 facility STRING;
280 Set syslog facility. STRING is one of the following: user, dae‐
281 mon, auth or authpriv, mail, cron, local0 through local7 (case-
282 insensitive), or a facility number.
283 tag STRING;
285 Tag syslog messages with STRING. Normally the messages are
286 tagged with the program name.
287 print-priority BOOL;
289 Prefix each message with its priority.
290 An example syslog statement:
292 syslog {
294 facility local0;
295 print-priority yes;
296 }
297
299 The watcher statement configures a single event watcher. A watcher can
300 control several events in multiple pathnames. Any number of watcher
301 statements is allowed in the configuration file, each one of them
302 declaring a separate watcher.
303 watcher {
305 path PATHNAME [recursive [NUMBER]];
306 file STRING-LIST;
307 event STRING-LIST;
308 command STRING;
309 user NAME;
310 timeout NUMBER;
311 option STRING-LIST;
312 environ ENV-SPEC;
313 }
314 The statements within a watcher block are:
316 path PATHNAME [recursive [NUMBER]];
318 Defines a pathname to watch. PATHNAME must be the name of an
319 existing directory in the file system. The watcher will watch
320 events occurring for all files within that directory. If the
321 optional recursive clause is specified, this directory will be
322 watched recursively, i.e. when any subdirectory is created in
323 it, direvent will set up a watcher for files in this subdirec‐
324 tory. This new watcher will be an exact copy of the parent
325 watcher, excepting for the pathnames. The optional NUMBER pa‐
326 rameter defines a cut-off nesting level for recursive watching.
327 If supplied, the recursive behaviour will apply only to the di‐
328 rectories that are nested below that level.
329 Any number of path statements can appear in a watcher block. At
331 least one path must be defined.
332 file STRING-LIST;
334 Selects which files are eligible for monitoring. The argument
335 is a list of globbing patterns (in the sense of fnmatch(3))
336 and/or extended regular expressions ( regex(7)) one of which the
337 file name must match in order for the watcher to act on it.
338 Regular expressions must be surrounded by a pair of slashes, op‐
339 tionally followed by the following flags:
340 b Use basic regular expressions.
342 i Enable case-insensitive matching.
344 A pattern or regular expression prefixed with ! matches
346 file names that don't match the pattern without !.
347 event STRING-LIST;
349 Configures the filesystem events to watch for in the directories
350 declared by the path statements. The argument is a list of
351 event names. Both generic and system-dependent event namess are
352 allowed. Multiple event statements accumulate. A missing event
353 statements means watch all events. For example:
354 event (open,delete);
356 command STRING;
358 Defines a command to execute on event. STRING is a command line
359 just as you would type it in sh(1). It may contain macro vari‐
360 ables, which will be expanded prior to execution. For example:
361 command "/bin/prog -event $genev_name -file $file";
363 See the section HANDLER ENVIRONMENT in direvent(8), for a de‐
365 tailed discussion of how the command is executed.
366 user STRING;
368 Run command as this user.
369 timeout NUMBER;
371 Terminate the command if it runs longer than NUMBER seconds.
372 The default is 5 seconds.
373 option STRING-LIST;
375 A list of additional options. The following options are de‐
376 fined:
377 shell Invoke the handler command as /bin/sh -c "com‐
379 mand".
380 wait Wait for the program to terminate before han‐
382 dling next event from the event queue. Normally
383 the program runs asynchronously.
384 stdout Capture the standard output of the command and
386 redirect it to the syslog with the LOG_INFO pri‐
387 ority.
388 stderr Capture the standard error of the command and
390 redirect it to the syslog with the LOG_ERR pri‐
391 ority.
392 environ ENV-SPEC;
394 Modify command environment. By default the command inherits the
395 environment of direvent augmented with the following variables:
396 DIREVENT_SYSEV_CODE
398 The system-dependent event code (see the ${sysev_code}
399 variable).
400 DIREVENT_SYSEV_NAME
402 The system-dependent event name or names (see the
403 ${sysev_name} variable).
404 DIREVENT_GENEV_CODE
406 The generic event code (see the ${genev_code} vari‐
407 able).
408 DIREVENT_GENEV_NAME
410 The generic event name or names (see the ${genev_name}
411 variable).
412 DIREVENT_FILE
414 The name of the affected file relative to the current
415 working directory (see the ${file} variable).
416 The environ statement allows for trimming the environment. Its
418 argument is a list of one or more of the folloeing environment
419 modification directives:
420 - (a single dash)
422 Clear the inherited environment, but retain the vari‐
423 ables added by direvent. The removed environment
424 variables can be selectively restored by the direc‐
425 tives that follow. This must be the first directive
426 in the list.
427 -- (double-dash)
429 Clear the entire environment, including the variables
430 added by direvent. This must be the first directive
431 in the list.
432 -NAME Unset the variable NAME.
434 -NAME=VAL
436 Unset the environment variable NAME only if its value
437 is VAL.
438 NAME Restore the environment variable NAME. This directive
440 is useful after - or -- to retain some variables from
441 the environment.
442 NAME=VALUE
444 Define environment variable NAME to the VALUE. VALUE
445 can contain macro variables, which will be expanded
446 prior to the assignment.
447 NAME+=VALUE
449 Retain the variable NAME and append VALUE to its ex‐
450 isting value. If no such variable is present in the
451 environment, it will be created and assigned the
452 VALUE. If VALUE begins with a punctuation character,
453 this character is removed from it before the assign‐
454 ment. This is convenient for using this construct
455 with environment variables like PATH, e.g.:
456 PATH+=:/sbin
458 In this example, if PATH exists, :/sbin will be ap‐
460 pended to it. Otherwise, it will be created and as‐
461 signed the value /sbin.
462 The VALUE can contain macro variables, which will be
464 expanded prior to the assignment.
465 NAME=+VALUE
467 Retain the variable NAME and prepend VALUE to its ex‐
468 isting value. If no such variable is present in the
469 environment, it will be created and assigned the
470 VALUE. In this case, if VALUE ends with a punctuation
471 character, this character will be removed from it be‐
472 fore the assignment.
473 The VALUE can contain macro variables, which will be
475 expanded prior to the assignment.
476
478 direvent(8).
479
481 Copyright © 2012, 2013 Sergey Poznyakoff
482 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li‐
483 censes/gpl.html>
484 This is free software: you are free to change and redistribute it.
485 There is NO WARRANTY, to the extent permitted by law.
486DIREVENT June 20, 2016 DIREVENT.CONF(5)