.\" Text automatically generated by txt2man
.TH iwatch 1 "04 Dec 2022" "iwatch-0.2.2" "realtime filesystem monitoring program using inotify"
.SH NAME
\fBiwatch \fP- realtime filesystem monitoring program using inotify
\fB
.SH SYNOPSIS
.nf
.fam C
\fBiwatch\fP [\fB-d\fP] [\fB-f\fP <config file>] [\fB-v\fP] [\fB-p\fP <pid file>]
\fBiwatch\fP [\fB-c\fP \fIcommand\fP] [\fB-C\fP \fIcharset\fP] [\fB-e\fP event[,event[,..]]] [\fB-h\fP|\fB--help\fP] [\fB-m\fP <email address>]
       [\fB-r\fP] [\fB-s\fP <on|off>] [\fB-t\fP <filter string>] [\fB-v\fP] [\fB--version\fP] [\fB-x\fP \fIexception\fP]
       [\fB-X\fP <regex \fIstring\fP \fIas\fP \fIexception\fP>] <target>

.fam T
.fi
.fam T
.fi
.SH DESCRIPTION
inotify (inode notify) is a Linux kernel subsystem that monitors events in filesystems and reports those events to
applications in real time.
.PP
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.
.PP
Do not forget to consider directories \fIas\fP "special files". See more details at http://www.tldp.org/LDP/intro-linux/html/sect_03_01.html
.PP
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:
.RS
.IP \(bu 3
Send notifications via email about changes.
.IP \(bu 3
Take programmable actions immediately, \fIas\fP emit alerts via XMPP messengers, WhatsApp or execute a local program or script.
.IP \(bu 3
Act \fIas\fP HIDS (Host-based Intrusion Detection System) or an integrity checker, complementing the local firewall systems.
.RE
.PP
iWatch can run \fIas\fP daemon, \fIas\fP well a simple \fIcommand\fP. The daemon mode uses a XML configuration file, and put a list
of directories and files (targets) to monitor. The \fIcommand\fP line mode will run without a configuration file. You just
need to put the necessary information (target to watch, email, \fIexception\fP, recursivity, events to monitor and \fIcommand\fP
to execute) in the \fIcommand\fP line. The options for both modes cannot be mixed together.
.PP
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 \fIcommand\fP 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.
.PP
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, \fIas\fP in
DHCP servers acting in failover mode. You also use to synchronize files, via rsync when these files are changed.
.SH OPTIONS
Usage for daemon mode (background) of iWatch:
.RS
.TP
.B
\fB-d\fP
Execute the application \fIas\fP daemon. iWatch will run in foreground without this option.
.TP
.B
\fB-f\fP <config_file.xml>
Specify alternative configuration file. Default is /etc/\fBiwatch\fP/iwatch.xml.
.TP
.B
\fB-p\fP <pid_file>
Specify an alternate pid file. Default: /var/run/iwatch.pid.
.TP
.B
\fB-v\fP
Be verbose.
.RE
.PP
Usage for \fIcommand\fP line mode (foreground) of iWatch:
.RS
.TP
.B
\fB-c\fP <\fIcommand\fP>
You can specify a \fIcommand\fP to be executed if an event occurs. For details about the available strings,
take a look at STRINGS FOR COMMAND section.
.TP
.B
\fB-C\fP <\fIcharset\fP>
Specify the \fIcharset\fP (default is utf-8).
.TP
.B
\fB-e\fP <event[,event[,..]]>
Specify a list of events that you want to watch. For details about possible events, take
a look at EVENTS section.
.TP
.B
\fB-h\fP, \fB--help\fP
Print help message.
.TP
.B
\fB-m\fP <email_address>
Contact point's email address. Without this option, iWatch will not send any email notification.
.TP
.B
\fB-r\fP
Recursivity when watching a directory.
.TP
.B
\fB-s\fP on|off
Enable or disable reports to the syslog (default is off/disabled).
.TP
.B
\fB-t\fP <filter>
Specify a filter \fIstring\fP (regex) to compare with the filename or directory name. It will
report events only if the file/directory name matches the filter \fIstring\fP. 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 \fIcommand\fP will
remove the inode and therefore the watcher.
.TP
.B
\fB-v\fP
Verbose mode. This option will show the main current action.
.TP
.B
\fB--version\fP
Print the version number.
.TP
.B
\fB-x\fP <\fIexception\fP file or directory>
Specify the file or directory which should not be watched.
.TP
.B
\fB-X\fP <regex \fIstring\fP \fIas\fP \fIexception\fP>
Similar to \fB-x\fP but specifying a regex \fIstring\fP \fIas\fP \fIexception\fP.
.SH STRINGS FOR COMMANDS
When using the '\fB-c\fP <\fIcommand\fP>' option, these strings will be available:
.TP
.B
%c
Event cookie number.
.TP
.B
%e
Event name. (e.g.: IN_CLOSE_WRITE)
.TP
.B
%f
Full path of the filename that gets an event. (e.g.: /var/www/index.html)
.TP
.B
%F
The old filename in case moved_to event.
.TP
.B
%p
Program name, always "iWatch".
.TP
.B
%v
Version number. (e.g.: 0.2.2)
.SH EVENTS
Following are the possible events you can use with the '\fB-e\fP' option:
.TP
.B
access
file/directory was accessed.
.TP
.B
attrib
file/directory attributes changed.
.TP
.B
close
file/directory closed, regardless of read/write mode.
.TP
.B
close_nowrite
file/directory closed, after being opened in read-only mode.
.TP
.B
close_write
file/directory closed, after being opened in writable mode.
.TP
.B
create
a file/directory was created within watched directory.
.TP
.B
delete
a file/directory was deleted within watched directory.
.TP
.B
delete_self
the watched file/directory was deleted.
.TP
.B
ignored
file was ignored.
.TP
.B
isdir
event occurred against a directory.
.TP
.B
modify
a file content was modified.
.TP
.B
move
a file/directory within watched directory was moved.
.TP
.B
moved_from
a file was moved away from.
.TP
.B
moved_to
a file was moved to.
.TP
.B
oneshot
only send event once.
.TP
.B
open
a file/directory was opened.
.TP
.B
q_overflow
event queued overflowed.
.TP
.B
unmount
file system on which watched file exists was unmounted.
.TP
.B
default
close_write, create, delete, move, delete_self and move_self.
.TP
.B
all_events
all possible events.
.SH COMMAND LINE USAGE EXAMPLES
.TP
.B
$ \fBiwatch\fP /tmp
Monitor changes in /tmp directory, using default events, without recursivity.
.TP
.B
$ \fBiwatch\fP \fB-r\fP \fB-e\fP access,create \fB-m\fP root@example.com \fB-x\fP /etc/mail /etc
Monitor only access and create events in /etc directory,
recursively, with /etc/mail \fIas\fP \fIexception\fP, and send email
notification to root@example.com if a listed event occurs.
.TP
.B
$ \fBiwatch\fP \fB-r\fP \fB-c\fP '(w; ps \fB-aux\fP)' | mail \fB-s\fP '%f was changed' root@localhost /bin
Monitor /bin directory, recursively, and execute the commands 'w' and 'ps \fB-aux\fP',
sending the results to root@localhost, using '<path_filename> was changed' \fIas\fP subject.
To see about '%f' take a look at STRINGS FOR COMMANDS section.
.TP
.B
$ \fBiwatch\fP \fB-r\fP \fB-X\fP '.svn' ~/projects
Monitor ~/projects directory, recursively, but exclude any .svn directories inside. This cannot be done
with a normal '\fB-x\fP' option since '\fB-x\fP' can only exclude the defined path.
.SH CONFIGURATION FILE EXAMPLE
The default configuration file is /etc/\fBiwatch\fP/iwatch.xml. See an example:
.PP
.nf
.fam C
    <?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>

.fam T
.fi
The two first lines will define the XML version and the file that defines the pattern used by iWatch
(the default is /etc/\fBiwatch\fP/iwatch.dtd). These lines needn't be changed.
.PP
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.
.PP
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.
.PP
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.
.PP
The showed example uses the sendxmpp \fIcommand\fP. Other good possibility is to apply the yowsup-cli \fIcommand\fP
to send WhatsApp messages.
.PP
A new example. With configuration showed below, iWatch will work over three <watchlist> blocks.
.PP
.nf
.fam C
    <?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>

.fam T
.fi
The first <watchlist> block monitors a directory and has special actions for a file but no execute a \fIcommand\fP 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,
.TP
.B
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.
.PP
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 '\fB-t\fP' at OPTIONS section.
.PP
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 \fIas\fP 'off'. So, iWatch will not send emails using the builtin mail engine.
However, in three lines the external \fIcommand\fP 'mail' was used to send personalized emails.
.SH LEARNING ABOUT EVENTS
A tip to learn about events is watch the iWatch \fIcommand\fP executing with '\fB-e\fP all_events' option. The following example
will monitor a 'ls /tmp' \fIcommand\fP.
.PP
.nf
.fam C
    $ 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

.fam T
.fi
Another example, that monitors the creating of a file inside /tmp:
.PP
.nf
.fam C
    $ 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

.fam T
.fi
So, in the last example occurred modify, open and close_write actions.
.SH RULES VALIDATION
Since version 0.2.0 iWatch checks the validity of XML file if it has following entry in the first two lines:
.PP
.nf
.fam C
    <?xml version="1.0" ?>
    <!DOCTYPE config SYSTEM "iwatch.dtd">

.fam T
.fi
The check will be made over a pattern described by /etc/\fBiwatch\fP/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 \fIas\fP normal without XML
validation. The iWatch's XML format is very simple and easy to understand, and it uses following DTD :
.PP
.nf
.fam C
    <!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"

.fam T
.fi
.SH CAVEATS
On Debian systems, when running \fBiwatch\fP \fIas\fP 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 \fIcommand\fP, you will need a .sendxmpprc
file under the /root/ directory.
.SH SEE ALSO
\fBinotify\fP(7), \fBsendxmpp\fP(1), \fByowsup-cli\fP(1)
.SH AUTHOR
iWatch was written by Cahya Wirawan <cahya@gmx.at>.
.PP
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).