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