README

iWatch: Realtime filesystem monitor
By Cahya Wirawan <cahya at gmx dot at>.

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
informations (target to watch, email, exception, recursivity, events
to monitor and command to execute) in the command line. The options for 
both mode can't be mixed together.

In the xml configuration file, each targets can have each 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.

Since version 0.2.2 we can specify a charset in command line or 
in xml file. The iwatch daemon can be reloaded using sighup signal.

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.

In the command line mode iWatch has following options:
Usage: iwatch [-c command] [-C charset] [-e event[,event[,..]]] [-h|--help] [-m <email address>] 
         [-r] [-r] [-s <on|off>] [-t filter] [-v] [--version] [-x exception]
         [-X <regex string as 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:
       %c Event cookie number
       %e Event name
       %f Full path of the filename that gets an event
       %F The old filename in case moved_to event
       %p Program name (iWatch)
       %v Version number
  -C charset
     Specify the charset (default is utf-8)
  -e event[,event[,..]]
     Specify a list of events you want to watch. Following are the possible events you can use:
       access        : file was accessed
       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 directory
       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.
  -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.
  --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"></contactpoint>
    <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"></contactpoint>
    <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"></contactpoint>
    <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+)>
<!ATTLIST config
   charset CDATA "utf-8"
>
<!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.