iwatch(1)

📦
version 0.2.2 · 2 versions
  • 0.2.2 · debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
  • 0.2.2 · ubuntu jammy
, in debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 iwatch(1) — realtime filesystem monitoring program using inotify 💖

okay bestie, sit down, hydrate, and let me tell you about iwatch, a realtime filesystem monitoring program using inotify. this is section 1 of the manual, there's more coming, so don't go anywhere 💅

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

two whole modes, two whole vibes, pick your fighter ✨

🎀 DESCRIPTION 🎀

okay so first things first: inotify (inode notify) is a Linux kernel subsystem that monitors events in filesystems and reports those events to applications in real time. the kernel is literally gossiping to your app and i love that for us 💖

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", bestie. 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</u> (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. 🚫 no mixing, that's the rule, periodt.

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. it's giving sysadmin main character energy fr fr ✨

💅 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. 1️⃣
  • 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. literally all of them, the whole menu 🌟

⭐ 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. 🦋

and that's part one, bestie — don't wander off, there's more coming 💜

🌸 CONFIGURATION FILE EXAMPLE 🌸

ok so the default config file is /etc/iwatch/iwatch.xml, bestie. here's what an example looks like:

<?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 first two lines are giving XML version + the file that defines the pattern iWatch uses (default is /etc/iwatch/iwatch.dtd). those two lines? don't touch them, they're fine 💅

the <config> statement marks where the config starts. and the last line has to be </config>. periodt. the guard email line is where you set the sender email and name for email notifications — like, it literally defines the From: field. and <watchlist></watchlist> wraps up a block of definitions about a watch, or a bunch of watch procedures.

so inside the <config></config> zone you can have several <watchlist></watchlist> blocks. and inside those blocks, the <title></title> spot is where you drop a title that says what the block is for. it's purely visual text, a lil label saying what the block does. <title></title> literally does nothing — it's just a tag for the humans reading the file 🫶. the contactpoint line holds the destination email (the To:) and the name used when sending email notifications.

each <path></path> line can monitor a file/directory and run actions. the first path line up there monitors the /var/www directory recursively. since no events were defined, iWatch is gonna use the default event (close_write, create, delete, move, delete_self and move_self events). if an event happens, syslog will not log it, and instead a message reporting the program name (%p = iWatch), the event (%e) and the monitored file/directory name (%f) gets sent over the XMPP protocol (via the external sendxmpp program) to foo@jabber-br.org. heads up: alert="off" disables any email sending. another way to dodge an email is just dropping the contactpoint line entirely. and one more big thing — that second line is excluding /var/www/counter from being observed 👀

the example uses the sendxmpp command, but a really good alternative is using the yowsup-cli command to fire off WhatsApp messages. slay.

ok new example, new me. with the config below, iWatch will work across 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>

so the first <watchlist> block monitors a directory and has special actions for a file, but doesn't execute a command for it. the first path is a single (non recursive) directory /var/www/localhost/htdocs, and any notification goes to the contact point webmaster@example.com. notice there are no events specified? so the default events get used: close_write, create, delete, move, delete_self and move_self. the second path monitors /var/www/localhost/htdocs/Photos recursively (and yeah, that's also inside the first directory). default events will be notified via mail 💌

the second block has four monitoring paths. all notifications go to admin@localhost. the big new thing here vs the first block is that a path uses a filter instruction to watch /etc/shadow and /etc/passwd at the same time 😤 to understand that better, go look at the -t in the OPTIONS section.

the last block monitors default events on the first line, and several non-default events on the following three lines. on several lines alert is set to off. so iWatch will not send emails using the builtin mail engine. BUT — on three of those lines the external mail command was used to send personalized emails. main character energy fr.

✨ LEARNING ABOUT EVENTS ✨

here's a tip for learning about events: watch the iWatch command run with the -e all_events option. this next example monitors an 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

and another one, this time monitoring 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 that last example, modify, open and close_write actions all went down. iconic behavior tbh.

💜 RULES VALIDATION 💜

since version 0.2.0, iWatch checks the validity of the XML file if it has the following entry in the first two lines:

<?xml version="1.0" ?>
<!DOCTYPE config SYSTEM "iwatch.dtd">

the check runs against a pattern described by the /etc/iwatch/iwatch.dtd file. without those two lines shown above, iWatch will just give you a warning that you have to use a DTD file — and then it keeps running as normal, no XML validation. the iWatch XML format is super simple and easy to get, and it uses this 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"
⚠️ okay so real talk — copy that DTD block exactly as it is. do not get creative with it. bestie, just don't. 🙈

🚨 CAVEATS 🚨

on Debian systems, when you run iwatch as a daemon via systemd, it will run under the root user. be sure your system is ready to do all the things via the root user. like, for example, if you're using the sendxmpp command, you'll need a .sendxmpprc file under the /root/ directory. no cap, this trips people up 😭

🦋 SEE ALSO 🦋

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

and that's the whole page, bestie 💖✨ this one's for iwatch-0.2.2, dated 04 Dec 2022, and it's the iwatch(1) page. go forth and monitor things, you absolute legend 🎀🦋💅

📦 where this page comes from