NAME¶

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 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:

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 command line mode (foreground) of iWatch:

STRINGS FOR COMMANDS¶

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

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¶

    <?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 <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>

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¶

    $ 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

    $ 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

RULES VALIDATION¶

    <?xml version="1.0" ?>
    <!DOCTYPE config SYSTEM "iwatch.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¶

AUTHOR¶

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