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/
   -v Verbose mode.

In the command line mode iWatch has following options:
   iwatch [-c command] [-e event[,event[,..]]] [-h|--help] [-m <email address>]
             [-r] [-r] [-s <on|off>] [-t filter] [-v] [--version] [-x exception] <target>
                                                                                 Target is the directory or file you want to monitor.
   -c command
       You can specify a command to be executed if an event occurs. And you can use
       following special string format in the command:
      %f Full path of the filename that gets an event
  %p Program name (iWatch)
  %v Version number
   -e event [,event[,..]]
       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
    -h, --help
       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.
       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:
  <guard email="myadmin@localhost" name="IWatch"></guard>
  <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>
  <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>
  <title>Only Test</title>
  <contactpoint email="root@localhost" name="Administrator"/>
    <path type="single" alert="off" exec="(w;ps -ef)|mail -s %f
    <path type="single" events="access,close" alert="off" exec="(w;ps -ef)|mail -s %f
    <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>

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
<!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.