README
1inotify cron system
2===================
3
4(c) Andreas Altair Redmer, 2014, 2015
5 Lukas Jelinek, 2006, 2007, 2008, 2009, 2012
6
7Content
8=======
91. About
102. Install a binary version
113. Obtain the source code
124. Requirements
135. How to build
146. How to use
157. Bugs, suggestions
168. Licensing
17
181. About
19========
20This program is the "inotify cron" system. It consist of a daemon and
21a table manipulator. You can use it a similar way as the regular cron.
22The difference is that the inotify cron handles filesystem events
23rather than time periods.
24
25This project was kicked off by Lukas Jelinek in 2006 and then
26unfortunatally abandoned in 2012. Upstream development and
27bug-tracking/fixing continued in 2014 on GitHub:
28https://github.com/ar-/incron .
29
302. Install a binary version
31===========================
32On Debian and Ubuntu based systems you can install this software with
33sudo apt-get install incron
34
35On all other Linux based systems you have to build it from source.
36
373. Obtain the source code
38=========================
39You can download the latest stable version from
40https://github.com/ar-/incron/archive/master.tar.gz
41
42You can download older versions from
43https://github.com/ar-/incron/releases
44
454. Requirements
46===============
47* Linux kernel 2.6.13 or later (with inotify compiled in)
48* inotify headers (inotify.h, sometimes inotify-syscalls.h) installed in
49 <INCLUDE_DIR>/sys. The most common place is /usr/include/sys.
50* GCC 4.x compiler (probably works also with GCC 3.4, possibly with
51 older versions too)
52
53
545. How to build
55===============
56Short:
57
58make -j8 && sudo make install
59
60Long:
61This software does not contain a standard
62portable build mechanism. There is only a Makefile which may be
63modified manually. On many Linux systems you need not to change
64anything.
65
66Please review the Makefile BEFORE you type 'make'. Especially
67check the PREFIX and other common variables. If done you can
68now build the files ('make').
69
70The binaries must be of course installed as root.
71
72If you want to use (after editing) the example configuration
73file simply rename it from /etc/incron.conf.example to
74/etc/incron.conf (you can also use -f <config> for one-time
75use of a custom configuration file).
76
77Making a release of the source tree relies on the 'VERSION' file.
78The file should contain only a simple version string such as '0.5.9'
79or (if you wish) something more comlex (e.g. '0.5.9-improved').
80The doxygen program must be installed and its control file 'Doxygen'
81created for generating the API documentation.
82
83
846. How to use
85=============
86The incron daemon (incrond) must be run under root (typically from
87runlevel script etc.). It loads the current user tables and hooks
88them for later changes.
89
90The incron table manipulator may be run under any regular user
91since it SUIDs. For manipulation with the tables use basically
92the same syntax as for the crontab program. You can import a table,
93remove and edit the current table.
94
95The user table rows have the following syntax:
96 <path> <mask> <command>
97
98Where:
99
100 <path> is a filesystem path (currently avoid whitespaces!)
101 <mask> is a symbolic (see inotify.h; use commas for separating
102 symbols) or numeric mask for events
103 <command> is an application or script to run on the events
104
105The command may contain these wildcards:
106
107 $$ - a dollar sign
108 $@ - the watched filesystem path (see above)
109 $# - the event-related file name
110 $% - the event flags (textually)
111 $& - the event flags (numerically)
112
113The mask may additionaly contain a special symbol loopable=true which
114disables events occurred during the event handling (to avoid loops).
115It also may contain recursive=false to ignore sub-directories.
116The mask can also be extended by dotdirs=true which will include
117dotdirectories (hidden directories and hidden files) into the search.
118
119**Example 1**: You need to run program 'abc' with the full file path as
120an argument every time a file is changed in /var/mail. One of
121the solutions follows:
122
123/var/mail IN_CLOSE_WRITE abc $@/$#
124
125Example 2: You need to run program 'efg' with the full file path as
126the first argument and the numeric event flags as the second one.
127It have to monitor all events on files in /tmp. Here is it:
128
129/tmp IN_ALL_EVENTS efg $@/$# $&
130
131Since 0.4.0 also system tables are supported. They are located in
132/etc/incron.d and their commands use root privileges. System tables
133are intended to be changed directly (without incrontab).
134
135Some parameters of both incrontab and incrond can be changed by
136the configuration. See the example file for more information.
137
138Example 3: You need to run program 'playmp3' with the full file path as
139an argument every time a MP3 file is moved to in /home/u1/Music. One of
140the solutions follows:
141
142/home/u1/Music/*.mp3 IN_MOVED_TO playmp3 $@/$#
143
144Example 4: You need to observe the directory /etc/
145recursively and report every change in the syslog. One of
146the solutions follows:
147
148/etc/ IN_CLOSE_WRITE echo $@/$# | logger
149
150Example 5: You need to observe the directory /etc/apache
151but exclude the sub-directories and report every change in the syslog.
152One of the solutions follows:
153
154/etc/apache IN_CLOSE_WRITE,recursive=false echo $@/$# | logger
155
156Example 6: You need to observe the directory /home/user1
157recursively, including all the hidden sub-directories and hidden files
158(dotfiles/dotdirectories) and report every change in the syslog.
159One of the solutions follows:
160
161/home/user1 IN_CLOSE_WRITE,dotdirs=true echo $@/$# | logger
162
163
1647. Bugs, suggestions
165====================
166incrond is currently not resistent against looping.
167
168If you find a bug or have a suggestion how to improve the program,
169please use the bug tracking system at
170https://github.com/ar-/incron/issues.
171
172
1738. Licensing
174============
175This program is free software; you can redistribute it and/or
176modify it under the terms of the GNU General Public License,
177version 2 (see LICENSE-GPL).
178
179Some parts may be also covered by other licenses.
180Please look into the source files for detailed information.
181
182
README.md
1# inotify cron system
2
3[](https://travis-ci.org/ar-/incron)
4
5(c) Andreas Altair Redmer, 2014, 2015
6 Lukas Jelinek, 2006, 2007, 2008, 2009, 2012
7
8## Content
9
101. About
112. Install a binary version
123. Obtain the source code
134. Requirements
145. How to build
156. How to use
167. Bugs, suggestions
178. Licensing
18
19## 1. About
20
21This program is the "inotify cron" system. It consist of a daemon and
22a table manipulator. You can use it a similar way as the regular cron.
23The difference is that the inotify cron handles filesystem events
24rather than time periods.
25
26This project was kicked off by Lukas Jelinek in 2006 and then
27unfortunatally abandoned in 2012. Upstream development and
28bug-tracking/fixing continued in 2014 on GitHub:
29https://github.com/ar-/incron .
30
31## 2. Install a binary version
32
33On Debian and Ubuntu based systems you can install this software
34(the version maintained by Debian) with
35sudo apt-get install incron
36
37There is a daily build running on Launchpad. You can install that
38build from a PPA in Ubuntu, to have always an up-to-date build.
39
40
41 sudo add-apt-repository ppa:altair-ibn-la-ahad/incron
42 sudo apt-get update
43 sudo apt-get install incron
44
45
46For more information follow the link to the PPA:
47https://code.launchpad.net/~altair-ibn-la-ahad/+archive/ubuntu/incron
48
49The build logs are available here:
50https://code.launchpad.net/~altair-ibn-la-ahad/+recipe/incron-daily
51
52On all other Linux based systems you have to build it from source.
53If you would like to add a build script for other linux flavors
54(Gentoo, Suse, Ret Hat, ...) please send me a pull request. I will
55be happy to include it.
56
57## 3. Obtain the source code
58
59You can download the latest stable version from
60https://github.com/ar-/incron/archive/master.tar.gz
61
62You can download older versions from
63https://github.com/ar-/incron/releases
64
65## 4. Requirements
66
67* Linux kernel 2.6.13 or later (with inotify compiled in)
68* inotify headers (inotify.h, sometimes inotify-syscalls.h) installed in
69 <INCLUDE_DIR>/sys. The most common place is /usr/include/sys.
70* GCC 4.x compiler (probably works also with GCC 3.4, possibly with
71 older versions too)
72
73## 5. How to build
74
75### Short:
76
77`
78make -j8 && sudo make install
79`
80
81### Long:
82This software does not contain a standard
83portable build mechanism. There is only a Makefile which may be
84modified manually. On many Linux systems you need not to change
85anything.
86
87Please review the Makefile BEFORE you type 'make'. Especially
88check the PREFIX and other common variables. If done you can
89now build the files ('make').
90
91The binaries must be of course installed as root.
92
93If you want to use (after editing) the example configuration
94file simply rename it from /etc/incron.conf.example to
95/etc/incron.conf (you can also use -f <config> for one-time
96use of a custom configuration file).
97
98Making a release of the source tree relies on the 'VERSION' file.
99The file should contain only a simple version string such as '0.5.9'
100or (if you wish) something more comlex (e.g. '0.5.9-improved').
101The doxygen program must be installed and its control file 'Doxygen'
102created for generating the API documentation.
103
104
105## 6. How to use
106
107The incron daemon (incrond) must be run under root (typically from
108runlevel script etc.). It loads the current user tables and hooks
109them for later changes.
110
111The incron table manipulator may be run under any regular user
112since it SUIDs. For manipulation with the tables use basically
113the same syntax as for the crontab program. You can import a table,
114remove and edit the current table.
115
116The user table rows have the following syntax:
117 <path> <mask> <command>
118
119Where:
120
121 <path> is a filesystem path (currently avoid whitespaces!)
122 <mask> is a symbolic (see inotify.h; use commas for separating
123 symbols) or numeric mask for events
124 <command> is an application or script to run on the events
125
126The command may contain these wildcards:
127
128* $$ - a dollar sign
129* $@ - the watched filesystem path (see above)
130* $# - the event-related file name
131* $% - the event flags (textually)
132* $& - the event flags (numerically)
133
134The mask may additionaly contain a special symbol loopable=true which
135disables events occurred during the event handling (to avoid loops).
136It also may contain recursive=false to ignore sub-directories.
137The mask can also be extended by dotdirs=true which will include
138dotdirectories (hidden directories and hidden files) into the search.
139
140**Example 1**: You need to run program 'abc' with the full file path as
141an argument every time a file is changed in /var/mail. One of
142the solutions follows:
143
144`
145/var/mail IN_CLOSE_WRITE abc $@/$#
146`
147
148**Example 2**: You need to run program 'efg' with the full file path as
149the first argument and the numeric event flags as the second one.
150It have to monitor all events on files in /tmp. Here is it:
151
152`
153/tmp IN_ALL_EVENTS efg $@/$# $&
154`
155
156Since 0.4.0 also system tables are supported. They are located in
157/etc/incron.d and their commands use root privileges. System tables
158are intended to be changed directly (without incrontab).
159
160Some parameters of both incrontab and incrond can be changed by
161the configuration. See the example file for more information.
162
163**Example 3**: You need to run program 'playmp3' with the full file path as
164an argument every time a MP3 file is moved to in /home/u1/Music. One of
165the solutions follows:
166
167`
168/home/u1/Music/*.mp3 IN_MOVED_TO playmp3 $@/$#
169`
170
171**Example 4**: You need to observe the directory /etc/
172recursively and report every change in the syslog. One of
173the solutions follows:
174
175`
176/etc/ IN_CLOSE_WRITE echo $@/$# | logger
177`
178
179**Example 5**: You need to observe the directory /etc/apache
180but exclude the sub-directories and report every change in the syslog.
181One of the solutions follows:
182
183`
184/etc/apache IN_CLOSE_WRITE,recursive=false echo $@/$# | logger
185`
186
187**Example 6**: You need to observe the directory /home/user1
188recursively, including all the hidden sub-directories and hidden files
189(dotfiles/dotdirectories) and report every change in the syslog.
190One of the solutions follows:
191
192`
193/home/user1 IN_CLOSE_WRITE,dotdirs=true echo $@/$# | logger
194`
195
196## 7. Bugs, suggestions
197
198incrond is currently not resistent against looping.
199
200If you find a bug or have a suggestion how to improve the program,
201please use the bug tracking system at
202https://github.com/ar-/incron/issues.
203
204
205## 8. Licensing
206
207This program is free software; you can redistribute it and/or
208modify it under the terms of the GNU General Public License,
209version 2 (see LICENSE-GPL).
210
211Some parts may be also covered by other licenses.
212Please look into the source files for detailed information.
213
214
){kind=link}