Provided by: iwatch_0.2.2-10_all bug

NAME

       iwatch - realtime filesystem monitoring program using inotify

SYNOPSIS

       iwatch [-d] [-f <config file>] [-v] [-p <pid file>]
       iwatch [-c command] [-C charset] [-e event[,event[,..]]] [-h|--help] [-m <email address>]
              [-r] [-s <on|off>] [-t <filter string>] [-v] [--version] [-x exception]
              [-X <regex string as exception>] <target>

DESCRIPTION

       inotify (inode notify) is a Linux kernel subsystem that monitors events in filesystems and
       reports those events to applications in real time.

       inotify can be used to monitor individual  files  or  directories.  When  a  directory  is
       monitored,  inotify will return events for the directory itself, and for files inside this
       directory. The inotify support was added to Linux Kernel 2.6.13.

       Do  not  forget  to  consider  directories  as  "special  files".  See  more  details   at
       http://www.tldp.org/LDP/intro-linux/html/sect_03_01.html

       iWatch  is  a  Perl  wrap  to inotify to monitor changes in specific directories or files,
       sending alarms to the system administrator in real time. So, iWatch can do:

              •  Send notifications via email about changes.

              •  Take programmable actions immediately,  as  emit  alerts  via  XMPP  messengers,
                 WhatsApp or execute a local program or script.

              •  Act  as  HIDS  (Host-based  Intrusion Detection System) or an integrity checker,
                 complementing the local firewall systems.

       iWatch can run as  daemon,  as  well  a  simple  command.  The  daemon  mode  uses  a  XML
       configuration  file,  and  put  a  list of directories and files (targets) to monitor. The
       command line mode will run 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  cannot  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
       do not 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 or all_events. See the EVENTS section for more details.

       A good example of iWatch usage is to monitor the pages directory in webservers to  notify,
       in  real  time,  about  defacements  or  file  insertions. Other example is to synchronize
       configuration files between machines, when they are changed, as in DHCP servers acting  in
       failover mode. You also use to synchronize files, via rsync when these files are changed.

OPTIONS

       Usage for daemon mode (background) of iWatch:

              -d     Execute  the  application  as  daemon. iWatch will run in foreground without
                     this option.

              -f <config_file.xml>
                     Specify alternative configuration file. Default is /etc/iwatch/iwatch.xml.

              -p <pid_file>
                     Specify an alternate pid file. Default: /var/run/iwatch.pid.

              -v     Be verbose.

       Usage for command line mode (foreground) of iWatch:

              -c <command>
                     You can specify a command to be executed if an  event  occurs.  For  details
                     about the available strings, take a look at STRINGS FOR COMMAND section.

              -C <charset>
                     Specify the charset (default is utf-8).

              -e <event[,event[,..]]>
                     Specify  a list of events that you want to watch. For details about possible
                     events, take a look at EVENTS section.

              -h, --help
                     Print help message.

              -m <email_address>
                     Contact point's email address. Without this option, iWatch will not send any
                     email notification.

              -r     Recursivity when watching a directory.

              -s on|off
                     Enable or disable reports to the syslog (default is off/disabled).

              -t <filter>
                     Specify  a  filter  string (regex) to compare with the filename or directory
                     name. It will report events only if  the  file/directory  name  matches  the
                     filter  string.  It  is  useful if you want 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  notification. This is caused by the
                     application that changes passwd or shadow (e.g. passwd or chfn), they do not
                     change  the  files  directly, but create a new file and move it to passwd or
                     shadow file. So, this command  will  remove  the  inode  and  therefore  the
                     watcher.

              -v     Verbose mode. This option will show the main current action.

              --version
                     Print the version number.

              -x <exception file or directory>
                     Specify the file or directory which should not be watched.

              -X <regex string as exception>
                     Similar to -x but specifying a regex string as exception.

STRINGS FOR COMMANDS

       When using the '-c <command>' option, these strings will be available:

       %c     Event cookie number.

       %e     Event name. (e.g.: IN_CLOSE_WRITE)

       %f     Full path of the filename that gets an event. (e.g.: /var/www/index.html)

       %F     The old filename in case moved_to event.

       %p     Program name, always "iWatch".

       %v     Version number. (e.g.: 0.2.2)

EVENTS

       Following are the possible events you can use with the '-e' option:

       access file/directory was accessed.

       attrib file/directory attributes changed.

       close  file/directory closed, regardless of read/write mode.

       close_nowrite
              file/directory closed, after being opened in read-only mode.

       close_write
              file/directory closed, after being opened in writable mode.

       create a file/directory was created within watched directory.

       delete a file/directory was deleted within watched directory.

       delete_self
              the watched file/directory was deleted.

       ignored
              file was ignored.

       isdir  event occurred against a directory.

       modify a file content was modified.

       move   a file/directory within watched directory was moved.

       moved_from
              a file was moved away from.

       moved_to
              a file was moved to.

       oneshot
              only send event once.

       open   a file/directory was opened.

       q_overflow
              event queued overflowed.

       unmount
              file system on which watched file exists was unmounted.

       default
              close_write, create, delete, move, delete_self and move_self.

       all_events
              all possible events.

COMMAND LINE USAGE EXAMPLES

       $ iwatch /tmp
              Monitor changes in /tmp directory, using default events, without recursivity.

       $ iwatch -r -e access,create -m root@example.com -x /etc/mail /etc
              Monitor  only  access  and  create  events  in  /etc  directory,  recursively, with
              /etc/mail as exception, and send email notification to root@example.com if a listed
              event occurs.

       $ iwatch -r -c '(w; ps -aux)' | mail -s '%f was changed' root@localhost /bin
              Monitor  /bin  directory,  recursively, and execute the commands 'w' and 'ps -aux',
              sending the results to  root@localhost,  using  '<path_filename>  was  changed'  as
              subject.  To see about '%f' take a look at STRINGS FOR COMMANDS section.

       $ iwatch -r -X '.svn' ~/projects
              Monitor ~/projects directory, recursively, but exclude any .svn directories inside.
              This cannot be done with a normal '-x' option  since  '-x'  can  only  exclude  the
              defined path.

CONFIGURATION FILE EXAMPLE

       The default configuration file is /etc/iwatch/iwatch.xml. See an example:

           <?xml version="1.0" ?>
           <!DOCTYPE config SYSTEM "/etc/iwatch/iwatch.dtd" >

           <config>
            <guard email="root@example.com" name="iWatch"/>
            <watchlist>
            <title>WEB server integrity monitoring</title>
            <contactpoint email="someone@example.com" name="Administrator"/>
               <path type="recursive" syslog="off" alert="off" exec="echo %p: %e %f | /usr/bin/sendxmpp -t foo@jabber-br.org">/var/www</path>
               <path type="exception">/var/www/counter</path>
            </watchlist>
           </config>

       The two first lines will define the XML version and the file that defines the pattern used
       by iWatch (the default is /etc/iwatch/iwatch.dtd). These lines needn't be changed.

       The <config> statement is used to mark the configuration start point. The last line of the
       configuration  must  be  </config>.  The  'guard email' line is used to specify the sender
       email and name to be used when sending notifications by email. In other words,  this  line
       defines  the  'From:'  email  field.  The  <watchlist></watchlist>  delimits  a  block  of
       definitions about a watch or some watches procedures.

       The <config></config> place can have several <watchlist></watchlist> blocks. Inside  these
       blocks  (<watchlist></watchlist>),  the  <title></title> space is used to add a title that
       will identify the purpose of the block. This field is a visual text to indicate  what  the
       block  does.  The  <title></title>  does  nothing.  It  is  a  tag  for people reading the
       configuration file. The 'contactpoint' line contains the destination email  address  (To:)
       and name when sending notifications by email.

       Each  <path></path>  line can monitor a file/directory and execute actions. The first path
       line showed will monitor recursively the directory /var/www. As  no  events  was  defined,
       iWatch  will  employ the default event (close_write, create, delete, move, delete_self and
       move_self events). If an event occurs, the syslog will  not  register  it  and  a  message
       reporting  the program name (%p = iWatch), the event (%e) and the monitored file/directory
       name (%f) will be sent via XMPP protocol (sendxmpp external program) to foo@jabber-br.org.
       Note  that alert="off" will disable any sending email. Other way to avoid an email message
       is drop the line "contactpoint".  Another  important  point  is  that  a  second  line  is
       excluding the /var/www/counter file/directory from observation.

       The  showed  example  uses  the  sendxmpp  command. Other good possibility is to apply the
       yowsup-cli command to send WhatsApp messages.

       A new example. With configuration showed below, iWatch will work  over  three  <watchlist>
       blocks.

           <?xml version="1.0" ?>
           <!DOCTYPE config SYSTEM "iwatch.dtd">

           <config>
            <guard email="admin@localhost" name="iWatch"></guard>
            <watchlist>
            <title>Public Website</title>
            <contactpoint email="webmaster@example.com" name="WebMaster"/>
               <path type="single">/var/www/localhost/htdocs</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="recursive">/etc/mail</path>
               <path type="exception">/etc/mail/statistics</path>
               <path type="single" filter="shadow|passwd">/etc</path>
            </watchlist>
            <watchlist>
            <title>Only a test</title>
            <contactpoint email="root@localhost" name="Administrator"/>
                <path type="single" alert="off" exec="(w;ps -aux) | mail -s %f root@localhost">/tmp/dir1</path>
                <path type="single" events="access,close" alert="off" exec="(w;ps -aux) | mail -s %f root@localhost">/tmp/dir2</path>
                <path type="single" events="default,access" alert="off" exec="(w;ps -aux) | mail -s '%f is accessed' root@localhost">/tmp/dir3</path>
                <path type="single" events="all_events">/tmp/dir4</path>
            </watchlist>
           </config>

       The first <watchlist> block monitors a directory and has special actions for a file but no
       execute a command  for  it.   The  first  path  is  a  single  (non  recursive)  directory
       /var/www/localhost/htdocs  and  any  notification  will  be  sent  to  the  contact  point
       webmaster@example.com. Note  that  have  no  events  specified.  So,  the  default  events
       (close_write,

       create, delete, move, delete_self
              and  move_self)  will  be  used.  The  second  path  will monitor, recursively, the
              directory /var/www/localhost/htdocs/Photos (also inside of  the  first  directory).
              Default events will be notified via mail.

       The  second  block  has four monitoring. All notification will be sent to admin@localhost.
       The main novelty over the first block is that a path uses a 'filter' instruction to  watch
       /etc/shadow and /etc/passwd at the same time. To understand better this situation, see the
       '-t' at OPTIONS section.

       The last block monitors default events in first line and several non default events in the
       following  three lines.  In several lines the 'alert' is defined as 'off'. So, iWatch will
       not send emails using the builtin mail engine.   However,  in  three  lines  the  external
       command 'mail' was used to send personalized emails.

LEARNING ABOUT EVENTS

       A  tip  to  learn  about events is watch the iWatch command executing with '-e all_events'
       option. The following example will monitor a 'ls /tmp' command.

           $ iwatch -e all_events /tmp
           [17/Jun/2014 11:22:59] IN_ISDIR,IN_OPEN /tmp
           [17/Jun/2014 11:22:59] IN_ISDIR,IN_CLOSE_NOWRITE /tmp

       Another example, that monitors the creating of a file inside /tmp:

           $ iwatch -e all_events /tmp
           [17/Jun/2014 11:29:43] IN_MODIFY /tmp/file.txt
           [17/Jun/2014 11:29:43] IN_OPEN /tmp/file.txt
           [17/Jun/2014 11:29:43] IN_MODIFY /tmp/file.txt
           [17/Jun/2014 11:29:43] IN_CLOSE_WRITE /tmp/file.txt
           [17/Jun/2014 11:29:43] * /tmp/file.txt is closed

       So, in the last example occurred modify, open and close_write actions.

RULES VALIDATION

       Since version 0.2.0 iWatch checks the validity of XML file if it has  following  entry  in
       the first two lines:

           <?xml version="1.0" ?>
           <!DOCTYPE config SYSTEM "iwatch.dtd">

       The  check  will  be made over a pattern described by /etc/iwatch/iwatch.dtd file. Without
       the showed 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"

CAVEATS

       On Debian systems, when running iwatch as a daemon via systemd, it  will  work  under  the
       root user. Be sure that your system is ready to make all things via root user. E.g. if you
       are using sendxmpp command, you will need a .sendxmpprc file under the /root/ directory.

SEE ALSO

       inotify(7), sendxmpp(1), yowsup-cli(1)

AUTHOR

       iWatch was written by Cahya Wirawan <cahya@gmx.at>.

       This manual page was written by Michael Prokop <mika@debian.org> and was  updated/expanded
       by  Joao Eriberto Mota Filho <eriberto@debian.org> for the Debian project (but may be used
       by others).