incrontab(5)

🌸 NAME 🌸

incrontab — tables for driving inotify cron (incron) 💅

Okay bestie, welcome to incrontab(5) — the incron documentation page that explains these incrontab files, and it is lowkey the blueprint for telling the incrond(8) daemon what to do. 🫶

✨ DESCRIPTION ✨

An incrontab file contains instructions to the incrond(8) daemon of the general form: “run this command on these file events.” 💖 There are two categories of tables: system tables (with root privileges) and user tables (with user privileges).

System tables are (by default) located in /etc/incron.d and may have any names. Each system table exists separately inside incron and their watches never collide. No cap, they stay in their own lane. 🦋

Each user has their own table, and commands in any given incrontab will be executed as the user who owns the incrontab. System users (such as apache, postfix, nobody etc.) may have their own incrontab. Yes bestie, even the service accounts can have a little main character energy. 👑

incrontab files are read when the incrond(8) daemon starts and after any change (incrontab files are being hooked when incrond is running).

Blank lines are ignored. Periodt. The general line format is the following:

<path> <mask> <command>

Where path is an absolute filesystem path, mask is an event mask (in symbolic or numeric form) and command is an executable file (or a script) with its arguments. See below for event mask symbols. The executable file may be noted as an absolute path or only as the name itself (PATH locations are examined).

Please remember that the same path may occur only once per table (otherwise only the first occurrence takes effect and an error message is emitted to the system log). Also please note that the * wildcard is allowed to observe a range of files. Don’t try to sneak duplicate paths in there, bestie — it’s not the vibe. 🙈

🌈 EVENT SYMBOLS 🌈

These basic event mask symbols are defined, and they are giving very specific file-event lore:

• IN_ACCESS — File was accessed (read) (*)
• IN_ATTRIB — Metadata changed (permissions, timestamps, extended attributes, etc.) (*)
• IN_CLOSE_WRITE — File opened for writing was closed (*)
• IN_CLOSE_NOWRITE — File not opened for writing was closed (*)
• IN_CREATE — File/directory created in watched directory (*)
• IN_DELETE — File/directory deleted from watched directory (*)
• IN_DELETE_SELF — Watched file/directory was itself deleted
• IN_MODIFY — File was modified (*)
• IN_MOVE_SELF — Watched file/directory was itself moved
• IN_MOVED_FROM — File moved out of watched directory (*)
• IN_MOVED_TO — File moved into watched directory (*)
• IN_OPEN — File was opened (*)

When monitoring a directory, the events marked with an asterisk (*) above can occur for files in the directory, in which case the name field in the returned event data identifies the name of the file within the directory. That name field is doing the detective work, iykyk. 🔍

The IN_ALL_EVENTS symbol is defined as a bit mask of all of the above events. Two additional convenience symbols are IN_MOVE, which is a combination of IN_MOVED_FROM and IN_MOVED_TO, and IN_CLOSE which combines IN_CLOSE_WRITE and IN_CLOSE_NOWRITE.

The following further symbols can be specified in the mask:

• IN_DONT_FOLLOW — Don’t dereference pathname if it is a symbolic link
• IN_ONESHOT — Monitor pathname for only one event
• IN_ONLYDIR — Only watch pathname if it is a directory

Additionally, there is a symbol which doesn’t appear in the inotify symbol set. It is loopable=true. This symbol disables monitoring events until the current one is completely handled (until its child process exits). Also, there is the symbol recursive=false. This symbol limits the observation on the specified directory and does not include subdirectories. Finally, there is also the symbol dotdirs=true. This symbol will include the hidden directories (where the names starts with a dot) in the observation. Hidden dirs? In this economy? Apparently yes. 💀

🦋 WILDCARDS 🦋

The following wildcards may be used inside command specification. They are your little command-line besties:

• $$ — dollar sign
• $@ — watched filesystem path (see above)
• $# — event-related file name
• $% — event flags (textually)
• $& — event flags (numerically)

🍓 EXAMPLE 🍓

These are some example rules which can be used in an incrontab file. Copy the energy, not the typos, bestie:

/tmp IN_ALL_EVENTS abcd $@/$# $%

/usr/bin IN_ACCESS,loopable=true abcd $#

/home IN_CREATE /usr/local/bin/abcd $#

/home IN_CREATE,dotdirs=true /usr/local/bin/abcd $#

/home IN_CREATE,recursive=false /usr/local/bin/abcd $#

/var/log 12 abcd $@/$#

First line: monitors all events on the /tmp directory. When an event occurs it runs an application called abcd with the full path of the file as the first argument and the event flags as the second one.

Second line: monitors accesses (readings) on the /usr/bin directory. The application abcd is run as a handler and the appropriate event watch is disabled until the program finishes. The file name (without the directory path) is passed in as an argument.

Third example: is used for monitoring the /home directory for newly created files or directories (it practically means an event is sent when a new user is added). This event is processed by a program specified by an absolute path.

Fourth example: is the third example, but it will include hidden directories in the observation.

Fifth example: is the third example, but it will exclude sub-directories from the observation.

Final line: shows how to use numeric event mask instead of textual one. The value 12 is exactly the same as IN_ATTRIB,IN_CLOSE_WRITE.

🔥 SEE ALSO 🔥

Go look at these when you need the full lore: incrond(8), incrontab(1), incron.conf(5). ✨

💜 AUTHOR 💜

Andreas Altair Redmer <altair.ibn.la.ahad.sy@gmail.com> (please report bugs to https://github.com/ar-/incron/issues ). Lukas Jelinek <lukas@aiken.cz> .

🎀 COPYING 🎀

This program is free software. It can be used, redistributed and/or modified under the terms of the GNU General Public License, version 2. Slay, open source. 💖

Later bestie — footer source/version credit goes to Lukas Jelinek, version 0.5.12, and incrontab(5); there’s literally no date line in the footer, so no fake date, fr fr. 🌈