WebSVN - public - Diff - Rev 69 and 84 - /incron/tags/incron-0.5.7/README


inotify cron system

(c) Lukas Jelinek, 2006, 2007

1. About
2. Requirements
3. How to use
4. Bugs, suggestions
5. Licensing
6. Documentation


========================================================================


1. About
This program is the "inotify cron" system. It consist of a daemon and
a table manipulator. You can use it a similar way as the regular cron.
The difference is that the inotify cron handles filesystem events
rather than time periods.

2. Requirements
* Linux kernel 2.6.13 or later (with inotify compiled in)
* inotify headers (inotify.h, sometimes inotify-syscalls.h) installed in
  <INCLUDE_DIR>/sys. The most common place is /usr/include/sys.
* GCC 4.x compiler (probably works also with GCC 3.4, possibly with
  older versions too)

  
3. How to build
Because this version is very early it does not contain a standard
portable build mechanism. There is only a Makefile which must be
modified manually. On many Linux systems you need not to change
anything.

Please review the Makefile BEFORE you type 'make'. Especially
check the PREFIX and other common variables. If done you can
now build the files ('make').

The binaries must be of course installed as root.

If you want to use (after editting) the example configuration
file simply rename it from /etc/incron.conf.example to
/etc/incron.conf (you can also use -f <config> for one-time
use of a custom configuration file).


4. How to use
The incron daemon (incrond) must be run under root (typically from
runlevel script etc.). It loads the current user tables and hooks
them for later changes.

The incron table manipulator may be run under any regular user
since it SUIDs. For manipulation with the tables use basically
the same syntax as for the crontab program. You can import a table,
remove and edit the current table.

The user table rows have the following syntax:
 <path> <mask> <command>

Where:

  <path> is a filesystem path (currently avoid whitespaces!)
  <mask> is a symbolic (see inotify.h; use commas for separating
         symbols) or numeric mask for events
  <command> is an application or script to run on the events

The command may contain these wildcards:

  $$ - a dollar sign
  $@ - the watched filesystem path (see above)
  $# - the event-related file name
  $% - the event flags (textually)
  $& - the event flags (numerically)

The mask may additionaly contain a special symbol IN_NO_LOOP which
disables events occurred during the event handling (to avoid loops).

Example 1: You need to run program 'abc' with the full file path as
an argument every time a file is changed in /var/mail. One of
the solutions follows:

/var/mail IN_CLOSE_WRITE abc $@/$#

Example 2: You need to run program 'efg' with the full file path as
the first argument and the numeric event flags as the second one.
It have to monitor all events on files in /tmp. Here is it:

/tmp IN_ALL_EVENTS efg $@/$# $&

Since 0.4.0 also system tables are supported. They are located in
/etc/incron.d and their commands use root privileges. System tables
are intended to be changed directly (without incrontab).

Some parameters of both incrontab and incrond can be changed by
the configuration. See the example file for more information.


5. Bugs, suggestions
THIS PROGRAM IS AN ALPHA VERSION. IT PROBABLY CONTAINS BUGS AND
THEREFORE IT IS NOT INTENDED FOR PRODUCTION USE.

If you find a bug or have a suggestion how to improve the program,
please use the bug tracking system at http://bts.aiken.cz.


6. Licensing
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License,
version 2  (see LICENSE-GPL).

Some parts may be also covered by other licenses.
Please look into the source files for detailed information.

Subversion Repositories public

(root)/incron/tags/incron-0.5.7/README - Rev 69 → 84

Rev 69		Rev 84
1	inotify cron system	1	inotify cron system
2		2
3	(c) Lukas Jelinek, 2006, 2007	3	(c) Lukas Jelinek, 2006, 2007
4		4
5	1. About	5	1. About
6	2. Requirements	6	2. Requirements
7	3. How to use	7	3. How to use
8	4. Bugs, suggestions	8	4. Bugs, suggestions
9	5. Licensing	9	5. Licensing
10	6. Documentation	10	6. Documentation
11		11
12		12
13	========================================================================	13	========================================================================
14		14
15		15
16	1. About	16	1. About
17	This program is the "inotify cron" system. It consist of a daemon and	17	This program is the "inotify cron" system. It consist of a daemon and
18	a table manipulator. You can use it a similar way as the regular cron.	18	a table manipulator. You can use it a similar way as the regular cron.
19	The difference is that the inotify cron handles filesystem events	19	The difference is that the inotify cron handles filesystem events
20	rather than time periods.	20	rather than time periods.
21		21
22	2. Requirements	22	2. Requirements
23	* Linux kernel 2.6.13 or later (with inotify compiled in)	23	* Linux kernel 2.6.13 or later (with inotify compiled in)
24	* inotify headers (inotify.h, sometimes inotify-syscalls.h) installed in	24	* inotify headers (inotify.h, sometimes inotify-syscalls.h) installed in
25	<INCLUDE_DIR>/sys. The most common place is /usr/include/sys.	25	<INCLUDE_DIR>/sys. The most common place is /usr/include/sys.
26	* GCC 4.x compiler (probably works also with GCC 3.4, possibly with	26	* GCC 4.x compiler (probably works also with GCC 3.4, possibly with
27	older versions too)	27	older versions too)
28		28
29		29
30	3. How to build	30	3. How to build
31	Because this version is very early it does not contain a standard	31	Because this version is very early it does not contain a standard
32	portable build mechanism. There is only a Makefile which must be	32	portable build mechanism. There is only a Makefile which must be
33	modified manually. On many Linux systems you need not to change	33	modified manually. On many Linux systems you need not to change
34	anything.	34	anything.
35		35
36	Please review the Makefile BEFORE you type 'make'. Especially	36	Please review the Makefile BEFORE you type 'make'. Especially
37	check the PREFIX and other common variables. If done you can	37	check the PREFIX and other common variables. If done you can
38	now build the files ('make').	38	now build the files ('make').
39		39
40	The binaries must be of course installed as root.	40	The binaries must be of course installed as root.
41		41
42	If you want to use (after editting) the example configuration	42	If you want to use (after editting) the example configuration
43	file simply rename it from /etc/incron.conf.example to	43	file simply rename it from /etc/incron.conf.example to
44	/etc/incron.conf (you can also use -f <config> for one-time	44	/etc/incron.conf (you can also use -f <config> for one-time
45	use of a custom configuration file).	45	use of a custom configuration file).
46		46
47		47
48	4. How to use	48	4. How to use
49	The incron daemon (incrond) must be run under root (typically from	49	The incron daemon (incrond) must be run under root (typically from
50	runlevel script etc.). It loads the current user tables and hooks	50	runlevel script etc.). It loads the current user tables and hooks
51	them for later changes.	51	them for later changes.
52		52
53	The incron table manipulator may be run under any regular user	53	The incron table manipulator may be run under any regular user
54	since it SUIDs. For manipulation with the tables use basically	54	since it SUIDs. For manipulation with the tables use basically
55	the same syntax as for the crontab program. You can import a table,	55	the same syntax as for the crontab program. You can import a table,
56	remove and edit the current table.	56	remove and edit the current table.
57		57
58	The user table rows have the following syntax:	58	The user table rows have the following syntax:
59	<path> <mask> <command>	59	<path> <mask> <command>
60		60
61	Where:	61	Where:
62		62
63	<path> is a filesystem path (currently avoid whitespaces!)	63	<path> is a filesystem path (currently avoid whitespaces!)
64	<mask> is a symbolic (see inotify.h; use commas for separating	64	<mask> is a symbolic (see inotify.h; use commas for separating
65	symbols) or numeric mask for events	65	symbols) or numeric mask for events
66	<command> is an application or script to run on the events	66	<command> is an application or script to run on the events
67		67
68	The command may contain these wildcards:	68	The command may contain these wildcards:
69		69
70	$$ - a dollar sign	70	$$ - a dollar sign
71	$@ - the watched filesystem path (see above)	71	$@ - the watched filesystem path (see above)
72	$# - the event-related file name	72	$# - the event-related file name
73	$% - the event flags (textually)	73	$% - the event flags (textually)
74	$& - the event flags (numerically)	74	$& - the event flags (numerically)
75		75
76	The mask may additionaly contain a special symbol IN_NO_LOOP which	76	The mask may additionaly contain a special symbol IN_NO_LOOP which
77	disables events occurred during the event handling (to avoid loops).	77	disables events occurred during the event handling (to avoid loops).
78		78
79	Example 1: You need to run program 'abc' with the full file path as	79	Example 1: You need to run program 'abc' with the full file path as
80	an argument every time a file is changed in /var/mail. One of	80	an argument every time a file is changed in /var/mail. One of
81	the solutions follows:	81	the solutions follows:
82		82
83	/var/mail IN_CLOSE_WRITE abc $@/$#	83	/var/mail IN_CLOSE_WRITE abc $@/$#
84		84
85	Example 2: You need to run program 'efg' with the full file path as	85	Example 2: You need to run program 'efg' with the full file path as
86	the first argument and the numeric event flags as the second one.	86	the first argument and the numeric event flags as the second one.
87	It have to monitor all events on files in /tmp. Here is it:	87	It have to monitor all events on files in /tmp. Here is it:
88		88
89	/tmp IN_ALL_EVENTS efg $@/$# $&	89	/tmp IN_ALL_EVENTS efg $@/$# $&
90		90
91	Since 0.4.0 also system tables are supported. They are located in	91	Since 0.4.0 also system tables are supported. They are located in
92	/etc/incron.d and their commands use root privileges. System tables	92	/etc/incron.d and their commands use root privileges. System tables
93	are intended to be changed directly (without incrontab).	93	are intended to be changed directly (without incrontab).
94		94
95	Some parameters of both incrontab and incrond can be changed by	95	Some parameters of both incrontab and incrond can be changed by
96	the configuration. See the example file for more information.	96	the configuration. See the example file for more information.
97		97
98		98
99	5. Bugs, suggestions	99	5. Bugs, suggestions
100	THIS PROGRAM IS AN ALPHA VERSION. IT PROBABLY CONTAINS BUGS AND	100	THIS PROGRAM IS AN ALPHA VERSION. IT PROBABLY CONTAINS BUGS AND
101	THEREFORE IT IS NOT INTENDED FOR PRODUCTION USE.	101	THEREFORE IT IS NOT INTENDED FOR PRODUCTION USE.
102		102
103	If you find a bug or have a suggestion how to improve the program,	103	If you find a bug or have a suggestion how to improve the program,
104	please use the bug tracking system at http://bts.aiken.cz.	104	please use the bug tracking system at http://bts.aiken.cz.
105		105
106		106
107	6. Licensing	107	6. Licensing
108	This program is free software; you can redistribute it and/or	108	This program is free software; you can redistribute it and/or
109	modify it under the terms of the GNU General Public License,	109	modify it under the terms of the GNU General Public License,
110	version 2 (see LICENSE-GPL).	110	version 2 (see LICENSE-GPL).
111		111
112	Some parts may be also covered by other licenses.	112	Some parts may be also covered by other licenses.
113	Please look into the source files for detailed information.	113	Please look into the source files for detailed information.