---
name: "iwatch"
section: "1"
platform: "linux"
package: "iwatch"
version: "0.2.2-11"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/iwatch"
---

# iwatch(1)

realtime filesystem monitoring program using inotify

## 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)](/inotify/7.md), [sendxmpp(1)](/sendxmpp/1.md), [yowsup-cli(1)](/yowsup-cli/1.md)**

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