Documentation
What is iWatch?
iWatch is a realtime filesystem monitoring program. Its purpose is to monitor any changes in a specific directory or file and send email notification immediately after the change. This can be very useful to watch a sensible file or directory against any changes, like files /etc/passwd,/etc/shadow or directory /bin or to monitor the root directory of a website against any unwanted changes.
This application is written in Perl and need inotify support in Linux kernel >= 2.6.13. And it needs also following third party perl modules: Linux::Inotify2, Event, Mail::Sendmail and XML::Simple. You can have all this modules from cpan as usual.
iWatch can be executed in two modes, the first mode is daemon mode where you can use an xml configuration file, and put a list of directories and files (targets) to monitor. And the second mode is command line mode where you can run it without a configuration file, you just need to put the necessary information (target to watch, email, exception, recursivity, events to monitor and command to execute) in the command line. The options for both modes can't be mixed together.
In the xml configuration file, each target can have its own email contact point. This contact point will get an email notification for any changes in the monitored targets. You can monitor a directory recursively, and you can also setup a list of exceptions where you don't want to monitor directory/file inside a monitored directory. It is also possible to disable email notification, and instead setup a command to be executed if an event occurs. Per default iWatch only monitor following events: close_write, create, delete, move, delete_self and move_self. But you can specify any possible events, like access, attrib, modify all_events and default.
How To Use:
In the daemon mode iWatch has following options:
Usage: iwatch [-d] [-f <config file>] [-v]
-d Execute the application as daemon. iWatch will run in foregroud without this option.
-f Specify an alternate xml configuration file. Per default, iWatch will
read /etc/iwatch.xml as it's configuration file.
-p Specify an alternate pid file (default: /var/run/iwatch.pid)
-v Verbose mode.
| %f Full path of the filename that gets an event | |
| %p Program name (iWatch) | |
| %v Version number |
Specify a list of events you want to watch. Following are the possible events you
can use:
| access | : file was modified | |
| modify | : file was modified | |
| attrib | : file attributes changed | |
| close_write | : file closed, after being opened in writeable mode | |
| close_nowrite | : file closed, after being opened in read-only mode | |
| close | : file closed, regardless of read/write mode | |
| open | : file was opened | |
| moved_from | : File was moved away from. | |
| moved_to | : File was moved to. | |
| move | : a file/dir within watched directory was moved | |
| create | : a file was created within watched director | |
| delete | : a file was deleted within watched directory | |
| delete_self | : the watched file was deleted | |
| unmount | : file system on which watched file exists was unmounted | |
| q_overflow | : Event queued overflowed | |
| ignored | : File was ignored | |
| isdir | : event occurred against dir | |
| oneshot | : only send event once | |
| all_events | : All events | |
| default | : close_write, create, delete, move, delete_self and move_self. |
Print this help.
-m <email address>
Specify the contact point's email address. Without this option, iwatch will not send
any email notification. -r Recursivity of the watched directory.
-s <on|off>
Enable or disable reports to the syslog (default is off/disabled)
-t <filter string>
Specify a filter string (regex) to compare with the filename or directory name. It will
report events only if the file/directory name matchs the filter string. It is useful if you
watch a file like /etc/passwd or /etc/shadow. Instead watching this single file, just
watch the /etc directory with filter="passwd|shadow", because if you watch only the
passwd/shadow file, the watcher will be deleted after one change of this file, and you
will not get another notifications. This is caused by the application that changes
passwd or shadow (e.g. passwd or chfn), they don't change the files directly, but
create a new file and move it to passwd or shadow file, this will remove the inode and
therefore the watcher.
-v verbose mode.
--version
Print the version number.
-x exception
Specify the file or directory which should not be watched.
-X <regex string as exception>
Specify a regex string as exception
example of config file:
|
<config>
<guard email="myadmin@localhost" name="IWatch"></guard>
<watchlist>
<title>Public Website</title>
<contactpoint email="webmaster@localhost" name="Web Master"/>
<path type="single">/var/www/localhost/htdocs</path>
<path type="single" syslog="on">/var/www/localhost/htdocs/About</path>
<path type="recursive">/var/www/localhost/htdocs/Photos</path>
</watchlist>
<watchlist>
<title>Operating System</title>
<contactpoint email="admin@localhost" name="Administrator"/>
<path type="recursive">/etc/apache2</path>
<path type="single">/etc/passwd</path>
<path type="recursive">/etc/mail</path>
<path type="exception">/etc/mail/statistics</path>
<path type="single" filter="shadow|passwd">/etc</path>
</watchlist>
<watchlist>
<title>Only Test</title>
<contactpoint email="root@localhost" name="Administrator"/>
<path type="single" alert="off" exec="(w;ps -ef)|mail -s %f
root@localhost">/tmp/dir1</path> <path type="single" events="access,close" alert="off" exec="(w;ps -ef)|mail -s %f
root@localhost">/tmp/dir2</path> <path type="single" events="default,access" alert="off" exec="(w;ps -ef)|mail -s '%f is
accessed' root@localhost">/tmp/dir3</path> <path type="single" events="all_events" alert="off">/tmp/dir4</path>
</watchlist>
</config>
|
With this configuration, iwatch will monitor a single directory /var/www/localhost/htdocs withouth it's sub directories, and any notification will be sent to the contact point webmaster@localhost. But it will monitor the whole directory tree of /etc/apache2, including any sub directories created later after the IWatch is started. You can use also exception here if you don't want to get notification for a file or subdirectory inside the monitored directory.
Version 0.1.x and older don't check the validity of xml file against it's DTD, but since version 0.2.0 it will check the validity of xml file if it has following entry in the first two lines:
<?xml version="1.0" ?>
<!DOCTYPE config SYSTEM "iwatch.dtd">
Without this two lines, iwatch will just give a warning that you have to use DTD file, and it continues to run as normal without xml validation. The iwatch's xml format is very simple and easy to understand, and it uses following DTD :
<!ELEMENT config (guard,watchlist+)>
<!ELEMENT guard (#PCDATA)>
<!ATTLIST guard
email CDATA #REQUIRED
name CDATA #IMPLIED
>
<!ELEMENT watchlist (title,contactpoint,path+)>
<!ELEMENT title (#PCDATA)>
<!ELEMENT contactpoint (#PCDATA)>
<!ATTLIST contactpoint
email CDATA #REQUIRED
name CDATA #IMPLIED
>
<!ELEMENT path (#PCDATA)>
<!ATTLIST path
type CDATA #REQUIRED
alert (on|off) "off"
events CDATA #IMPLIED
exec CDATA #IMPLIED
filter CDATA #IMPLIED
syslog (on|off) "off"
>
Example of the command line mode:
iwatch /tmp
monitor changes in /tmp directory with default events
iwatch -r -e access,create -m cahya@localhost -x /etc/mail /etc
monitor only access and create events in /etc directory recursively with /etc/mail as
exception and send email notification to cahya@localhost.
iwatch -r -c "(w;ps -ef)|mail -s '%f was changed' cahya@localhost" /bin
monitor /bin directory recursively and execute the command.
iwatch -r -X '\.svn' ~/projects
monitor ~/projects directory recursively, but exclude any .svn directories inside. This can't be done with a normal '-x' option since '-x' can only exclude the defined path.