aboutsummaryrefslogtreecommitdiff
path: root/dircond.1
blob: 705558239e330e515ff626c234d113e915ad1f3f (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
.\" dircond - directory content watcher daemon -*- nroff -*-
.\" Copyright (C) 2012, 2013 Sergey Poznyakoff
.\"
.\" Dircond 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.
.\"
.\" Dircond 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 dircond. If not, see <http://www.gnu.org/licenses/>.
.TH DIRCOND 1 "March 8, 2013" "DIRCOND" "Dircond User Reference"
.SH NAME
dircond \- directory content watcher
.SH SYNOPSIS
\fBdircond\fR [\fB\-dft\fR] [\fB\-F\fR \fIFACILITY\fR] [\fB\-L\fR \fITAG\fR]\
 [\fB\-P\fR \fIFILE\fR]\
 [\fB\-u\fR \fIUSER\fR]\
 [\fICONFIG\fR]

.B dircond -h

.B dircond -V
.SH DESCRIPTION
.B Dircond
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 events can be monitored by the program:
.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.
.PP
When an event has been detected,
.B dircond
invokes the handler configured for it.  The handler is invoked in the
directory where the event occured.  Additional information about the
event is passed in the following environment variables:
.TP
.B DIRCOND_EVENT
Event symbolic name (see the event table above). 
.TP
.B DIRCOND_EVENT_CODE
Event code as obtained from
.BR inotify (8).
.TP
.B DIRCOND_FILE
The name of the affected file.
.PP
Apart from these variables, the
handler environment is inherited from the calling process. If you need
to restrict the environment, start
.B dircond
via
.BR env (1).
.SH OPTIONS
.TP
.B \-d
Increase debug verbosity level.
.TP
.B \-f
Run in the foreground.
.TP
\fB\-F\fR \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
\fB\-L\fR \fITAG\fR
Log with this syslog tag.
.TP
\fB\-P\fR \fIFILE\fR
Write PID to \fIFILE\fR.
.TP
\fB\-t\fR
Check configuration file for errors and exit.
.TP
\fB\-u\fR \fIUSER\fR
Run as this \fIUSER\fR.
.TP
\fB\-h\fR
Output a terse help summary and exit.
.TP
\fB\-V\fR
Print program version and copyright information.
.SH CONFIGURATION
The default configuration file is
.BR /etc/dircond.conf .
If a file name is supplied as an argument to the program, that file
will be read instead.
.PP
The configuration file has the traditional line-oriented format.  Very
long lines can be split into several physical lines by ending each of
them with a backslash immediately followed by a newline character.
.PP
Comments are introduced with a sharp sign and extend to the end of
logical line.
.PP
Empty lines are ignored.
.SS Global settings
.TP
\fBforeground\fR [\fBon\fR|\fBoff\fR]
Remain in foreground (if \fBon\fR or no argument given), or detach
from the controlling terminal and become a daemon (if \fBoff\fR).
The latter is the default.  See also the \fB\-f\fR option.
.TP
\fBdebug\fR \fIN\fR
Set debugging level.  See also the \fB\-d\fR option.
.TP
\fBpidfile\fR \fIFILE\fR
Store PID of the started process in \fIFILE\fR.  See also the
\fB\-P\fR option.
.TP
\fBuser\fR \fINAME\fR
Run as user \fINAME\fR.  See also the \fB\-u\fR option.
.SS Logging
The \fBsyslog\fR statement configures where the log output goes.  By
default, the program logs to standard error until it finishes parsing
the configuration file and processing command line options.  From then
on it begins logging to syslog with the facility \fBdaemon\fR.  The
syslog settings can be altered using this statement.
.TP
.B syslog off
Disable syslog output, log everything to standard error instead.  This
setting has effect only when running in the foreground.
.TP
\fBsyslog facility\fR \fIFNAME\fR
Log to syslog facility \fIFNAME\fR.  The latter can be either 
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 .
.TP
\fBsyslog tag\fR \fISTRING\fR
Log with the given syslog tag.
.SS Handler options
Handler options affect all event handlers defined in the \fBonevent\fR
statements appearing below them.
.TP 
\fBoption capture\fR \fIstream\fR [\fIenable\fR]
Capture the output stream of a handler.  The \fIstream\fR parameter
specifies which stream to capture.  Its possible values are:
\fBstdout\fR for the standard output, \fBstderr\fR for the standard
error, or \fBboth\fR for both streams.  Optional \fIenable\fR
parameter can be \fBon\fR to enable capturing and \fBoff\fR to disable
it.

When logging to syslog, the data read from the captured
.B stdout
will be logged with the priority
.BR LOG_INFO ,
and
.B stderr
will be logged with the priority
.BR LOG_ERROR .
.TP
\fBoption wait\fR
Wait for the handler to terminate before handling subsequent events.
This is the default.
.TP
\fBoption nowait\fR
Do not wait for the handler to terminate.  Start it in the background
and continue processing requests.
.TP
\fBoption timeout\fR \fIN\fR
Sets timeout in seconds for handler runtime.  The default value is 5
seconds.  Note, that the timeout setting affects both \fBwait\fR and
\fBnowait\fR handlers, i.e. any handler that runs longer
than \fIN\fR seconds will be terminated by
.B SIGKILL.
.SS Event handling
.TP
\fBevent\fR \fINAME\fR \fIEVENT-ID\fR [\fIEVENT-ID\fR...]
Add listed events to the event set \fINAME\fR, creating it if it does
not exist.  Each \fIEVENT-ID\fR is either a predefined event name (see
the \fBDESCRIPTION\fR section) or a \fINAME\fR of an event 
set defined in a previous
.B event
statement.
.TP
\fBpath\fR \fINAME\fR \fIDIR\fR [\fBrecursive\fR [\fIN\fR]]
Add directory \fIDIR\fR to the pathset \fINAME\fR.  If \fBrecursive\fR
is specified, all directories below \fIDIR\fR are also added to the
pathset.  If \fBrecursive\fR is followed by a decimal number \fIN\fR,
recursive inclusion is limited to directories located no deeper than
\fIN\fR levels of nesting.
.TP
\fBonevent\fR \fIEVENT-ID\fR \fBin\fR \fIPATH-NAME\fR \fBrun\fR \fICOMMAND\fR\
 [\fBas\fR \fIUSER\fR]
Configures the handler for events occurring in the given pathset.
\fICOMMAND\fR is the full pathname of an external program.  This
program will be started when one of the events from \fIEVENT-ID\fR
occur for any file in directories comprising the pathset \fIPATH-NAME\fR.
If the optional \fBas\fR \fIUSER\fR clause is supplied, the program
will be run with the UID and (main and supplementary) GIDs of \fIUSER\fR.
The latter must be either a valid user name or a numeric UID of an
existing user.
.SH EXAMPLE
.sp
.nf
.in +2
# Store the PID of the master process in this file:
pidfile /var/run/dircond.pid

# Log using syslog facility \fBlocal0\fR.
syslog facility local0

# Define event set \fBupdate\fR to match any modifications
# of file contents.
event update modify close_write moved_to

# Define event set \fBremove\fR to cover removal of a file
# from the watched directory.
event remove delete moved_from

# Add \fB/etc\fR and its subdirectories to pathset \fBconfigs\fR.
path configs /etc recursive

# Don't allow event handler to run longer than 10 seconds.
option timeout 10
# Capture both standard output and error and divert them
# to the log file.
option capture both

# If any file gets updated in \fB/etc\fR or any of its
# subdirectories, call the program \fB/usr/bin/confchange\fR.
onevent update in configs run /usr/bin/confchange as daemon

# Another handler, for removals in the configuration directory.
onevent delete in configs run /usr/bin/confdel
.in
.fi
.SH "EXIT CODE"
.IP 0
Successful termination.
.IP 1
Command line usage error.
.IP 2
Another error occurred.
.SH "SEE ALSO"
.BR inotify (8).
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <gray+dircond@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.