Subversion Repositories public

Rev

Rev 102 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
110 luk 1
.TH "incrontab" "5" "0.5.10" "Lukas Jelinek" "incron documentation"
57 luk 2
.SH "NAME"
3
incrontab \- tables for driving inotify cron (incron)
4
.SH "DESCRIPTION"
67 luk 5
An incrontab file contains instructions to the \fIincrond\fR(8) daemon of the general form: "run this command on these file events". There are two categories of tables: system tables (with root privileges) and user tables (with user privileges).
57 luk 6
 
69 luk 7
System tables are (by default) located in /etc/incron.d and may have any names. Each system table exists separately inside incron and their watches never collide.
67 luk 8
 
9
Each user has their own table, and commands in any given incrontab will be executed as the user who owns the incrontab. System users (such as apache, postfix, nobody etc.) may have their own incrontab.
10
 
57 luk 11
incrontab files are read when the \fIincrond\fR(8) daemon starts and after any change (incrontab file are being hooked when incrond is running).
12
 
13
Blank lines are ignored. The general line format is the following:
14
 
15
<path> <mask> <command>
16
 
83 luk 17
Where \fIpath\fR is an absolute filesystem path, \fImask\fR is an event mask (in symbolic or numeric form) and \fIcommand\fR is an executable file (or a script) with its arguments. See bellow for event mask symbols. The executable file may be noted as an absolute path or only as the name itself (PATH locations are examined).
57 luk 18
 
67 luk 19
Please remember that the same path may occur only once per table (otherwise only the first occurrence takes effect and an error message is emitted to the system log).
83 luk 20
.SH "EVENT SYMBOLS"
21
These basic event mask symbols are defined:
22
 
23
\fBIN_ACCESS\fR 		File was accessed (read) (*)
24
.br
25
\fBIN_ATTRIB\fR 		Metadata changed (permissions, timestamps, extended attributes, etc.) (*)
26
.br
27
\fBIN_CLOSE_WRITE\fR 	File opened for writing was closed (*)
28
.br
29
\fBIN_CLOSE_NOWRITE\fR 	File not opened for writing was closed (*)
30
.br
31
\fBIN_CREATE\fR 		File/directory created in watched directory (*)
32
.br
33
\fBIN_DELETE\fR 		File/directory deleted from watched directory (*)
34
.br
35
\fBIN_DELETE_SELF\fR 		Watched file/directory was itself deleted
36
.br
37
\fBIN_MODIFY\fR 		File was modified (*)
38
.br
39
\fBIN_MOVE_SELF\fR 		Watched file/directory was itself moved
40
.br
41
\fBIN_MOVED_FROM\fR 		File moved out of watched directory (*)
42
.br
43
\fBIN_MOVED_TO\fR 		File moved into watched directory (*)
44
.br
45
\fBIN_OPEN\fR 			File was opened (*)
46
 
47
When monitoring a directory, the events marked with an asterisk (*) above can occur for files in the directory, in which case the name field in the returned event data identifies the name of the file within the directory.
48
 
49
The \fBIN_ALL_EVENTS\fR symbol is defined as a bit mask of all of the above events. Two additional convenience symbols are \fBIN_MOVE\fR, which is a combination of \fBIN_MOVED_FROM\fR and \fBIN_MOVED_TO\fR, and \fBIN_CLOSE\fR which combines \fBIN_CLOSE_WRITE\fR and \fBIN_CLOSE_NOWRITE\fR.
50
 
51
The following further symbols can be specified in the mask:
52
 
53
\fBIN_DONT_FOLLOW\fR 	Don't dereference pathname if it is a symbolic link
54
.br
55
\fBIN_ONESHOT\fR 		Monitor pathname for only one event
56
.br
57
\fBIN_ONLYDIR\fR 		Only watch pathname if it is a directory
58
 
59
Additionaly, there is a symbol which doesn't appear in the inotify symbol set. It it \fBIN_NO_LOOP\fR. This symbol disables monitoring events until the current one is completely handled (until its child process exits).
60
 
61
.SH "WILDCARDS"
62
The following wildards may be used inside command specification:
63
 
64
\fB$$\fR	dollar sign
65
.br
66
\fB$@\fR	watched filesystem path (see above)
67
.br
68
\fB$#\fR	event-related file name
69
.br
70
\fB$%\fR	event flags (textually)
71
.br
72
\fB$&\fR	event flags (numerically)
73
 
57 luk 74
.SH "EXAMPLE"
75
These are some example rules which can be used in an incrontab file:
76
 
83 luk 77
\fB/tmp IN_ALL_EVENTS abcd $@/$# $%\fR
57 luk 78
 
83 luk 79
\fB/usr/bin IN_ACCESS,IN_NO_LOOP abcd $#\fR
57 luk 80
 
83 luk 81
\fB/home IN_CREATE /usr/local/bin/abcd $#\fR
57 luk 82
 
83 luk 83
\fB/var/log 12 abcd $@/$#\fR
57 luk 84
 
85
The first line monitors all events on the /tmp directory. When an event occurs it runs a application called 'abcd' with the full path of the file as the first arguments and the event flags as the second one.
86
 
87
The second line monitors accesses (readings) on the /usr/bin directory. The application 'abcd' is run as a handler and the appropriate event watch is disabled until the program finishes. The file name (without the directory path) is passed in as an argument.
88
 
89
The third example is used for monitoring the /home directory for newly create files or directories (it practically means an event is sent when a new user is added). This event is processed by a program specified by an absolute path.
90
 
91
And the final line shows how to use numeric event mask instead of textual one. The value 12 is exactly the same as IN_ATTRIB,IN_CLOSE_WRITE.
67 luk 92
 
57 luk 93
.SH "SEE ALSO"
75 luk 94
incrond(8), incrontab(1), incron.conf(5)
57 luk 95
.SH "AUTHOR"
102 luk 96
Lukas Jelinek <lukas@aiken.cz> (please report bugs to http://bts.aiken.cz or <bugs@aiken.cz>).
57 luk 97
.SH "COPYING"
98
This program is free software. It can be used, redistributed and/or modified under the terms of the GNU General Public License, version 2.