xenial (1) iwatch.1.gz

Provided by: iwatch_0.2.2-3_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.

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

              •  Send notifications via email about changes.

              •  Take  programmable actions immediately, as emit alerts via XMPP messages, 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.

OPTIONS

       Usage for daemon mode (background) of iWatch:

              -d     Execute the application as daemon. iWatch will run in foregroud 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 COMMAND

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

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

EVENTS

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

       access file was accessed.

       attrib file attributes changed.

       close  file closed, regardless of read/write mode.

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

       close_write
              file closed, after being opened in writeable mode.

       create a file was created within watched directory.

       delete a file was deleted within watched directory.

       delete_self
              the watched file was deleted.

       ignored
              file was ignored.

       isdir  event occurred against dir.

       modify file was modified.

       move   a file/dir within watched directory was moved.

       moved_from
              file was moved away from.

       moved_to
              file was moved to.

       oneshot
              only send event once.

       open   file 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 events.

COMMAND LINE USAGE EXAMPLES

       $ iwatch /tmp
              Monitor changes in /tmp directory with default events.

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

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

       The first <watchlist> block monitors a directories and has special actions for two files but no execute a
       command   in   neither   of   them.    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 (close_write, create, delete, move, delete_self and
       move_self) will be used. The second path is the file /var/www/localhost/htdocs/About. This file is inside
       the  last  directory.   The  difference  is  that  all  activities  over  this  file  will  be  logged in
       /var/log/syslog. The third path will monitor, recursively, the directory /var/www/localhost/htdocs/Photos
       (also inside of the first directory). No log. Default events will be notified via mail.

       The  second block has five 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' in OPTIONS section.

       The  last  block  monitors  a default event in first line and several non default events in the following
       three lines. In all 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"

SEE ALSO

       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 updated/improved by Joao Eriberto
       Mota Filho <eriberto@debian.org> for the Debian project (but may be used by others).