DIREVENT(8) Direvent User Reference DIREVENT(8) NAME direvent - directory event monitor SYNOPSIS direvent [-HVdfht] [-F NAME] [-P FILE] [-l PRIO] [-I DIR] [-T COMMAND] [--debug] [--facility=NAME] [--foreground] [--include=DIR] [--lint] [--pid- file=FILE] [--self-test=COMMAND] [--user=NAME] [CONFIG] direvent -h direvent --help direvent -H direvent --config-help direvent --usage direvent -V direvent --version DESCRIPTION GNU Direvent monitors a set of directories on the file system and reacts when a file system event occurs in any of them. Directories and events to monitor are specified in the configuration file. When an event occurs the utility reacts by invoking an external command configured for that event. The following generic events can be monitored by the program: create A file was created. delete A file was deleted. write A file was written to. change A file was modified and closed. This event is supported on GNU/Linux, FreeBSD, and NetBSD. attrib File attributes have changed. This includes changes in the file ownership, mode, link count, etc. Depending on the interface provided by the underlying operating system di- revent can trace various system-dependent events, which may offer a better resolution. These events are described in the section SYSTEM DEPENDENCIES below. A watcher is a configuration entity within direvent which associates a set of directories with a set of events and instructs the program to run a specified external command when any of these events occur in any of these directories. This external command (called a handler) can obtain informa- tion about the event that triggered its execution from the environment variables, or from its command line (see the HANDLER ENVIRONMENT section below). Watchers are declared in the program configuration file direvent.conf, lo- cated in the system configuration directory (normally /etc). An alternative configuration file can be used, by supplying its pathname as the command line argument (CONFIG parameter in the SYNOPSIS section above). OPTIONS -d, --debug Increase debug verbosity level. -F, --facility=FACILITY Log under this syslog facility. Allowed values for FACILITY are a decimal number or any of the following symbolic names: auth, auth- priv, cron, daemon, ftp, local0 through local7, lpr, mail, news, user, and uucp. The option -F 0 directs logging to the standard error. -f, --foreground Run in the foreground. -I, --include-directory=DIR Add DIR to the include search path. When looking for a file to be included in the #include (#include_once) statement, direvent scans first the directories given with -I options (in the same order as given on the command line), and then the directories in the standard include search path. The latter is defined at compile time and can be inspected in the output of the --help option. -l PRIO While connected to a terminal direvent outputs its diagnostics mes- sages to stderr and, if configured, to syslog. This option limits the amount of information output to the standard error. PRIO is one of the following priorities (in order of increasing severity): de- bug, info, notice, warning, err, crit, alert, emerg. When this op- tion is given, only messages with the priority level equal to or greater than PRIO will be duplicated on the standard error. -P, --pidfile=FILE Write PID to FILE. -T, --self-test=COMMAND Run in self-test mode. In this mode, direvent starts external com- mand supplied as the argument to this option and continues running until the command exits. If the command terminates normally, di- revent exits with the code returned by it. If the command termi- nates on SIGHUP, direvent exits with code 0. If it terminates on another signal, direvent exits with code 2. COMMAND can include any command line options or arguments, provided that it is properly quoted. It is invoked as /bin/sh -c COMMAND in the environment of the parent direvent process. The macro variable $self_test_pid holds the PID of the COMMAND (see section VARIABLE EXPANSION in direvent.conf(5)). -t, --lint Check configuration file for errors and exit. -u, --user=USER Run as this USER. Informative options cause the program to display the requested piece of in- formation and exit: -h, --help Output a terse help summary and exit. -H, --config-help Describe configuration file syntax. --usage Show available command line options. -V, --version Print program version and copyright information. CONFIGURATION The default configuration file is /etc/direvent.conf. If a file name is supplied as an argument to the program, that file will be read instead. The configuration file syntax is discussed in detail in direvent.conf(5). This section provides only a short description of it. Three types of comments are allowed: inline comments, that begin with a # or // and extend to the end of line, and multi-line comments, which com- prise everything enclosed between /* and */. Comments and empty lines are ignored. Whitespace characters are ignored as well, except as they serve to separate tokens. A token is a string of consecutive characters from the following classes: alphanumeric characters, underscores, dots, asterisks, slashes, semicolons, commercial at's, and dashes. Any other sequence of characters must be enclosed in double quotation marks in order to represent a single token. Configuration statements consist of a keyword and value separated by any amount of whitespace and is terminated with a semicolon. A block statement is a collection of statements enclosed in curly braces. The most important configuration statement is watcher. It is defined as follows: watcher { path PATHNAME [recursive [LEVEL]]; event EVENT-LIST; command COMMAND-LINE; user NAME; timeout NUMBER; environ ENV-SPEC; option STRING-LIST; } Each watcher statement instructs direvent to monitor the events listed in EVENT-LIST occurring in the directories specified by PATHNAMEs in path statements (any number of path statements can be given). When any such event is detected, the COMMAND-LINE will be executed. Each directory defined with the recursive keyword will be watched recur- sively. This means that for each subdirectory created in it, direvent will install a watcher similar to that of its parent directory. The optional LEVEL can be used to set up a cut-off nesting level, beyond which the re- cursive operation is disabled. The PATHNAME is not required to be a directory, it can as well be a file of any type. This file is not required to exist, either. If it does not, di- revent will defer configuring the watcher until the file is eventually cre- ated. The rest of statements are optional. The user statement can be used to ex- ecute the COMMAND-LINE as the user NAME (provided, of course, that direvent is started with root privileges). The timeout specifies the maximum amount of time (in seconds) the command is allowed to run. It defaults to 5. The environ statement modifies the command environment (see the following sec- tion). Finally, the option statement supplies additional options. It can be used, for example, to divert the command's output to syslog. The program's logging is controlled by the debug and syslog statements. debug NUMBER; Sets the debugging level to NUMBER -- an integer value between 0 and 4. Zero is the default and means the debugging is disabled. The bigger the NUMBER the more detailed debugging information will be output. The syslog statement controls the syslog logging: syslog { facility STRING; tag STRING; print-priority BOOL; } The pidfile statement instructs the program to write its PID to the named file after disconnecting from the controlling terminal. HANDLER ENVIRONMENT The handler to be executed on an event is defined by the command statement in the watcher configuration block (see direvent.conf(5)). Before execut- ing, the following operations are performed: 1. The current working directory is set to the directory where the event occurred. 2. If the global environ statement is present, the current environment is modified according to its rules. 3. If the environ statement is present in the watcher, the environment is further modified according to its rules. See the description of the environ statement in direvent.conf(5). 4. The standard input is closed. If the stdout option is supplied, the standard output is captured and redirected to the syslog. Otherwise it is closed. If the stderr option is supplied, the standard error is captured and redirected to the syslog. Otherwise it is closed. All file descriptors above 2 are closed. 5. Macro variables are expanded in the command line. Unless the shell option is set, environment variables are expanded as well. See the section VARIABLE EXPANSION in direvent.conf(5). For example, if the handler is about to be executed for the write event on the file somefile, and the command definition was: command "/libexec/handler -e '$genev_name' -f '$file'"; then the resulting command line will be: /libexec/handler -e 'open' -f 'somefile' 6. If the shell option is set, the handler is invoked via the shell, as $SHELL -c command. 7. Otherwise, word splitting is performed on the resulting command line. The first word is treated as the pathname of the program, which is then invoked via the execve system call. SYSTEM DEPENDENCIES Direvent relies on the event monitoring API provided by the kernel. Linux On Linux the program uses inotify(7). The maximum number of watches a user process can have is controlled by the fs.inotify.max_user_watches system variable. Normally it is set to 8192, which is quite enough for most purposes. However, if you monitor a big number or directories and/or are using recursive watchers, you may need more watches. In that case, use sysctl(8) to raise the limit, e.g.: sysctl -w fs.inotify.max_user_watches=16384 Most GNU/Linux distributions provide the file /etc/sysctl.conf which can be used to set this variable on startup. The following system-dependent events are defined on systems that use ino- tify(7): ACCESS A file was accessed. ATTRIB A file's metadata changed. CLOSE_WRITE A writable file was closed. CLOSE_NOWRITE An unwritable file closed. CREATE A file was created. DELETE A file was deleted. MODIFY A file was modified. MOVED_FROM A file was moved into a monitored directory. MOVED_TO A file was moved out from a monitored directory. OPEN A file was opened. BSD When compiled on BSD systems (including Darwin), direvent uses kqueue(2). This interface needs an open file handle for each file in a monitored di- rectory, which means that the number of watchers is limited by the maximum number of open files. Use ulimit -n NUM to raise it to a higher number. Since it operates on files, kqueue does not provide direct support for the create generic event. Direvent works over this disadvantage by keeping track of the contents of each monitored directory and rescanning it each time a WRITE system event is reported for it. It then generates the open event for each file that appeared after the last scan. Such a rescan can consume considerable time if a directory has a very large number of files in it. Further, the change event is supported only on FreeBSD and NetBSD. The following system-dependent events are available: DELETE The unlink() system call was called on the monitored file. WRITE A write occurred on the file. EXTEND The file was extended. ATTRIB The file attributes have changed. LINK The link count on the file changed. RENAME The file was renamed. REVOKE Access to the file was revoked via revoke(2) or the underlying file system was unmounted. Additionally, the following system events are supported by FreeBSD and NetBSD: CLOSE File opened read-only writing was closed. CLOSE_WRITE File opened for writing was closed. OPEN File was opened. READ File was read. Darwin Essentially the same as BSD. The main difference compared to Linux and BSD is that on Darwin the watchers are set after disconnecting from the con- trolling terminal, because Darwin lacks the rfork(2) call and the event queue cannot be inherited by the child process. EXIT CODE 0 Successful termination. 1 Command line usage error. 2 Another error occurred. SEE ALSO direvent.conf(5), inotify(7), kqueue(2). AUTHORS Sergey Poznyakoff BUG REPORTS Report bugs to <bug-direvent@gnu.org.ua>. COPYRIGHT Copyright (C) 2012-2021 Sergey Poznyakoff License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li- censes/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. DIREVENT December 29, 2021 DIREVENT(8)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | CONFIGURATION | HANDLER ENVIRONMENT | SYSTEM DEPENDENCIES | Linux | BSD | Darwin | EXIT CODE | SEE ALSO | AUTHORS | BUG REPORTS | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=direvent&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>