aboutsummaryrefslogtreecommitdiff
path: root/doc/direvent.8
blob: 03644ff8ed99609dbc1e4276950201bd967b6456 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
.\" direvent - directory content watcher daemon -*- nroff -*-
.\" Copyright (C) 2012-2016 Sergey Poznyakoff
.\"
.\" Direvent is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 3 of the License, or (at your
.\" option) any later version.
.\"
.\" Direvent is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with direvent. If not, see <http://www.gnu.org/licenses/>.
.TH DIREVENT 8 "June 20, 2016" "DIREVENT" "Direvent User Reference"
.SH NAME
direvent \- directory event monitor
.SH SYNOPSIS
\fBdirevent\fR [\fB\-HVdfh\fR] [\fB\-F\fR \fINAME\fR]\
 [\fB\-P\fR \fIFILE\fR]\
 [\fB\-l\fR \fIPRIO\fR]\
 [\fB\-I\fR \fIDIR\fR]\
 [\fB\-T\fR \fICOMMAND\fR]\
 [\fB\-\-debug\fR]\
 [\fB\-\-facility\fR=\fINAME\fR]\
 [\fB\-\-foreground\fB]\
 [\fB\-\-include=\fIDIR\fR]\
 [\fB\-\-pidfile\fR=\fIFILE\fR]\
 [\fB\-\-self\-test\fR=\fICOMMAND\fR]\
 [\fB\-\-user\fR=\fINAME\fR]\
 [\fBCONFIG\fR]

.B direvent \-h
.br
.B direvent \-\-help

.B direvent \-H
.br
.B direvent \-\-config\-help

.B direvent \-\-usage

.B direvent \-V
.br
.B direvent \-\-version

.SH DESCRIPTION
.B 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.	
.PP
The following
.B generic
events can be monitored by the program:
.TP
.B create
A file was created;
.TP
.B delete
A file was deleted;
.TP
.B write
A file was written to;
.TP
.B attrib
File attributes have changed.  This includes changes in the file
ownership, mode, link count, etc.
.PP
Depending on the interface provided by the underlying operating system
.B direvent
can trace various
.B system-dependent
events, which may offer a better resolution.  These events are
described in the section
.B SYSTEM DEPENDENCIES
below.
.PP
A
.B watcher
is a configuration entity within
.B 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 \fBhandler\fR) can obtain information
about the event that triggered its execution from the environment
variables, or from its command line (see the \fBHANDLER ENVIRONMENT\fR
section below).
.PP
Watchers are declared in the program configuration file
.BR direvent.conf ,
located in the system configuration directory (normally \fB/etc\fR).
.PP
An alternative configuration file can be used, by supplying its pathname
as the command line argument (\fICONFIG\fR parameter in the \fBSYNOPSIS\fR
section above).
.SH OPTIONS
.TP
.BR \-d ", " \-\-debug 
Increase debug verbosity level.
.TP
\fB\-F\fR, \fB\-\-facility=\fIFACILITY\fR
Log under this syslog facility.  Allowed values for \fIFACILITY\fR are
a decimal number or any of the following symbolic names:
.BR auth ,
.BR authpriv ,
.BR cron ,
.BR daemon ,
.BR ftp ,
.BR local0 " through " local7 ,
.BR lpr ,
.BR mail ,
.BR news ,
.BR user ,
and
.BR uucp .

The option \fB\-F 0\fR directs logging to the standard error.
.TP
.BR \-f ", " \-\-foreground 
Run in the foreground.
.TP
\fB\-I\fR, \fB\-\-include=\fIDIR\fR
Add \fIDIR\fR to the include search path.  When looking for a file to
be included in the \fB#include\fR (\fB#include_once\fR) statement,
\fBdirevent\fR scans first the directories given with \fB\-I\fR
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
\fB\-\-help\fR option.
.TP
\fB\-l\fR \fIPRIO\fR
While connected to a terminal \fBdirevent\fR outputs its diagnostics
messages to stderr and, if configured, to \fBsyslog\fR.  This option
limits the amount of information output to the standard error.
\fIPRIO\fR is one of the following priorities (in order of increasing
severity):
.BR debug ,
.BR info ,
.BR notice ,
.BR warning ,
.BR err ,
.BR crit ,
.BR alert ,
.BR emerg .
When this option is given, only messages with the priority level equal
to or greater than \fIPRIO\fR will be duplicated on the standard error.
.TP
\fB\-P\fR, \fB\-\-pidfile=\fIFILE\fR
Write PID to \fIFILE\fR.
.TP
\fB\-T\fR, \fB\-\-self\-test=\fICOMMAND\fR
Run in \fIself-test mode\fR.  In this mode, \fBdirevent\fR starts
external command supplied as the argument to this option and continues
running until the command exits.  If the command terminates normally,
\fBdirevent\fR exits with the code returned by it.  If the command
terminates on \fBSIGHUP\fR, \fBdirevent\fR exits with code 0.  If it
terminates on another signal, \fBdirevent\fR exits with code 2.

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

The macro variable
.B $self_test_pid
holds the PID of the \fICOMMAND\fR (see section
.B MACRO EXPANSION
in
.BR direvent.conf (5)).
.TP
.BR \-t ", " \-\-lint 
Check configuration file for errors and exit.
.TP
\fB\-u\fR, \fB\-\-user=\fIUSER\fR
Run as this \fIUSER\fR.
.PP
Informative options cause the program to display the requested piece
of information and exit:
.TP
.BR \-h ", " \-\-help 
Output a terse help summary and exit.
.TP
.BR \-H ", " \-\-config\-help 
Describe configuration file syntax.
.TP
.B \-\-usage
Show available command line options.
.TP
.BR \-V ", " \-\-version
Print program version and copyright information.
.SH CONFIGURATION
The default configuration file is
.BR /etc/direvent.conf .
If a file name is supplied as an argument to the program, that file
will be read instead.
.PP
The configuration file syntax is discussed in detail in
.BR direvent.conf (5).
This section provides only a short description of it.
.PP
Three types of comments are allowed: inline comments, that begin with
a \fB#\fR or \fB//\fR and extend to the end of line, and multi-line
comments, which comprise everything enclosed between \fB/*\fR and
\fB*/\fR.  Comments and empty lines are ignored.  Whitespace
characters are ignored as well, except as they serve to separate
tokens.
.PP
A token is a string of consecutive characters from the following
classes: alphanumeric characters, underscores, dots, asteriscs,
slashes, semicolons, commercial at's, and dashes.
.PP
Any other sequence of characters must be enclosed in double quotation
marks in order to represent a single token.
.PP
Adjacent quoted strings are concatenated.
.PP
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.
.PP
The most important configuration statement is
.BR watcher .
It is defined as follows:
.sp
.nf
.in +2
.B watcher {
.in +4
\fBpath\fR \fIPATHNAME\fR [\fBrecursive\fR [\fILEVEL\fR]];
.BI "event " EVENT\-LIST ;
.BI "command " COMMAND\-LINE ;
.BI "user " NAME ;
.BI "timeout " NUMBER ;
.BI "environ " ENV\-SPEC ;
.BI "option " STRING\-LIST ;
.in -4
.B }
.in
.fi
.PP
Each \fBwatcher\fR statement instructs \fBdirevent\fR to monitor
the events listed in \fIEVENT\-LIST\fR occurring in the directories
specified by \fIPATHNAME\fRs in \fBpath\fR statements (any number of
\fBpath\fR statements can be given).  When any such event is detected,
the \fICOMMAND\-LINE\fR will be executed.
.PP
Each directory defined with the \fBrecursive\fR keyword will be
watched recursively.  This means that for each subdirectory created in
it, \fBdirevent\fR will install a watcher similar to that of its parent
directory.  The optional \fILEVEL\fR can be used to set up a cut-off
nesting level, beyond which the recursive operation is disabled.
.PP
The rest of statements are optional.  The \fBuser\fR statement can be
used to execute the \fICOMMAND\-LINE\fR as the user \fINAME\fR
(provided, of course, that \fBdirevent\fR is started with root
privileges).  The \fBtimeout\fR specifies the maximum amount of time
(in seconds) the command is allowed to run.  It defaults to 5.  The
\fBenviron\fR statement modifies the command environment (see the
following section).  Finally, the \fBoption\fR statement supplies
additional options.  It can be used, for example, to divert the
command's output to \fBsyslog\fR.
.PP
The program's logging is controlled by the \fBdebug\fR and
\fBsyslog\fR statements.
.TP
.BI "debug " NUMBER ;
Sets the debugging level to \fINUMBER\fR -- an integer value between 0
and 3.  Zero is the default and means the debugging is disabled.  The
bigger the \fINUMBER\fR the more detailed debugging information will
be output.
.PP
The \fBsyslog\fR statement controls the syslog logging:
.sp
.nf
.in +2
.B syslog {
.in +4
.BI "facility " STRING ;
.BI "tag " STRING ;
.BI "print\-priority " BOOL ;
.in -4
.B }
.PP
The \fBpidfile\fR statement instructs the program to write its PID to
the named file after disconnecting from the controlling terminal.
.SH "HANDLER ENVIRONMENT"
The handler to be executed on an event is defined by the \fBcommand\fR
statement in the \fBwatcher\fR configuration block (see
.BR direvent.conf (5)).
Before executing, the following operations are performed:
.nr step 1 1
.IP \n[step].
The current working directory is set to the directory where the event
occurred.
.IP \n+[step].
If the \fBenviron\fR statement is present in the watcher, the
environment is modified according to its rules.  See the description
of the \fBenviron\fR statement in
.BR direvent.conf (5).
.IP \n+[step].
The standard input is closed.
.IP
If the \fBstdout\fR option is supplied,
the standard output is captured and redirected to the \fBsyslog\fR.
Otherwise it is closed.
.IP
If the \fBstderr\fR option is supplied,
the standard error is captured and redirected to the \fBsyslog\fR.
Otherwise it is closed.
.IP
All file descriptors above 2 are closed.
.IP \n+[step].
\fBMacro variables\fR are expanded.  See the section
.B MACRO EXPANSION
in
.BR direvent.conf (5).
For example, if the handler is about to be executed for the
\fBwrite\fR event on the file \fBsomefile\fR, and the \fBcommand\fR
definition was:
.RS
.sp
.nf
.in +4
command "/libexec/handler \-e '$genev_name' \-f '$file'";
.in
.fi
.RE
.IP
then the resulting command line will be:
.RS
.sp
.nf
.in +4
/libexec/handler \-e 'open' \-f 'somefile'
.in
.fi
.RE
.IP \n+[step].
Word splitting is performed on the resulting command line.  The first
word is treated as the pathname of the program to be executed.
.IP \n+[step].
The program is invoked.
.SH "SYSTEM DEPENDENCIES"
\fBDirevent\fR relies on the event monitoring API provided by the
kernel.
.SH Linux
On \fBLinux\fR the program uses
.BR inotify (7).
.PP
The maximum number of watches a user process can have is controlled by
the
.B 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
.BR sysctl (8)
to raise the limit, e.g.:
.sp
.nf
.in +4
sysctl \-w fs.inotify.max_user_watches=16384
.in
.fi
.PP
Most GNU/Linux distributions provide the file
.B /etc/sysctl.conf
which can be used to set this variable on startup.
.PP
The following system-dependent events are defined on systems that use
.BR inotify (7):
.TP
.B ACCESS
A file was accessed.
.TP
.B ATTRIB
A file's metadata changed.
.TP
.B CLOSE_WRITE
A writable file was closed.
.TP
.B CLOSE_NOWRITE
An unwritable file closed.
.TP
.B CREATE
A file was created.
.TP
.B DELETE
A file was deleted.
.TP
.B MODIFY
A file was modified.
.TP
.B MOVED_FROM
A file was moved into a monitored directory.
.TP
.B MOVED_TO
A file was moved out from a monitored directory.
.TP
.B OPEN
A file was opened.
.SH BSD
When compiled on \fBBSD\fR systems (including \fBDarwin\fR),
\fBdirevent\fR uses
.BR 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
.BI "ulimit -n " NUM
to raise it to a higher number.
.PP
Since it operates on files, \fBkqueue\fR does not provide direct
support for the \fBcreate\fR generic event.  \fBDirevent\fR works
over this disadvantage by keeping track of the contents of each
monitored directory and rescanning it each time a \fBWRITE\fR system
event is reported for it.  It then generates the
\fBopen\fR 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.
.PP
The following system-dependent events are available:
.TP
.B DELETE
The \fBunlink()\fR system call was called on the monitored file.
.TP
.B WRITE
A write occurred on the file.
.TP
.B EXTEND
The file was extended.
.TP
.B ATTRIB
The file attributes have changed.
.TP
.B LINK
The link count on the file changed.
.TP
.B RENAME
The file was renamed.
.TP
.B REVOKE
Access to the file was revoked via
.BR revoke (2)
or the underlying file system was unmounted.
.SH Darwin
Essentially the same as
.BR BSD .
The main difference compared to \fBLinux\fR and \fBBSD\fR is that on
\fBDarwin\fR the watchers are set after disconnecting from the
controlling terminal, because \fBDarwin\fR lacks the
.BR rfork (2)
call and the event queue cannot be inherited by the child process.
.SH "EXIT CODE"
.IP 0
Successful termination.
.IP 1
Command line usage error.
.IP 2
Another error occurred.
.SH "SEE ALSO"
.BR direvent.conf (5),
.BR inotify (7),
.BR kqueue (2).
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <bug-direvent@gnu.org.ua>.
.SH COPYRIGHT
Copyright \(co 2012, 2013 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:

Return to:

Send suggestions and report system problems to the System administrator.