NAME

rwpollexec - Monitor a directory for files and execute a command on them

SYNOPSIS

  rwpollexec --incoming-directory=DIR_PATH --command=COMMAND
        --error-directory=DIR_PATH [--archive-directory=DIR_PATH]
        [--flat-archive] [--simultaneous=NUM]
        [--timeout=SIGNAL,SECS [--timeout=SIGNAL,SECS ...]]
        [--polling-interval=NUM]
        { --log-destination=DESTINATION
          | --log-pathname=FILE_PATH
          | --log-directory=DIR_PATH [--log-basename=LOG_BASENAME]
            [--log-post-rotate=COMMAND] }
        [--log-level=LEVEL] [--log-sysfacility=NUMBER]
        [--pidfile=FILE_PATH] [--no-chdir] [--no-daemon]
  rwpollexec --help
  rwpollexec --version

DESCRIPTION

rwpollexec is a daemon that monitors a directory for incoming files and executes a given command on each file. If the command runs successfully on a file, the file is either moved to an archive directory or deleted. If the command runs unsuccessfully or is terminated by a signal, the file is moved to an error directory.

rwpollexec executes a single command on each file. If you need to run multiple commands on a file, create a script to run the commands and have rwpollexec execute the script.

The --simultaneous switch specifies the maximum number of invocations of COMMAND that rwpollexec will run concurrently. The default is one, which causes rwpollexec to process the files one at a time.

If there is a possibility that the command will "hang" and cause rwpollexec to stop processing files, you may wish to specify that rwpollexec send a signal to the command after it has been running for some number of seconds by using the --timeout switch. This switch may be repeated to send different signals after various times.

When rwpollexec is signaled to exit, it waits for all running commands to terminate before exiting. If a command has "hung", rwpollexec does not exit until that command is killed, or until rwpollexec itself is sent a SIGKILL.

As rwpollexec scans the incoming file directory, it ignores a file if its size is 0 bytes or if its name begins with a dot ("."). On each scan, if rwpollexec detects a file name that was not present in the previous scan, it records the name and size of the file. If the file has a different size on the next scan, the new size is recorded. Once the file has the same size on two consecutive scans, rwpollexec executes the command on the file.

If the exit status of running the command of a file is zero, rwpollexec deletes the file unless the --archive-directory switch is specified, in which case the file is moved to that directory or to a subdirectory of that directory depending on whether the --flat-archive switch is specified.

If the exit status of the command is non-zero, the file is moved to the error directory. rwpollexec does not provide a method to re-try a command that fails.

OPTIONS

Option names may be abbreviated if the abbreviation is unique or is an exact match for an option. A parameter to an option may be specified as --arg=param or --arg param, though the first form is required for options that take optional parameters.

--incoming-directory=DIR_PATH

Periodically scan the directory DIR_PATH for files on which to run the command specified by the --command switch. As rwpollexec scans DIR_PATH, it ignores a file if its name begins with a dot (".") or if its size is 0 bytes. When a file is first detected, its size is recorded, and the file must have the same size for two consecutive scans before rwpollexec will execute the command on it. The interval between scans is set by --polling-interval. DIR_PATH must be a complete directory path. This switch is required.

--command=COMMAND

Run COMMAND on each file noticed in the directory specified by --incoming-directory. Each occurrence of the string %s in COMMAND is replaced with the full path to the file, and each occurrence of "%%" is replaced with "%". If any other character follows "%", rwpollexec exits with an error. If the exit status of COMMAND is zero, rwpollexec deletes the file unless the --archive-directory switch is specified, in which case rwpollexec moves the file to that directory. If the command exits with a non-zero status or is terminated by a signal, rwpollexec moves the file to the directory specified by --error-directory. This switch is required.

COMMAND is interpreted by the shell used by rwpollexec. When the "SILK_RWPOLLEXEC_SHELL" environment variable is set, its value is used as the shell. Otherwise, rwpollexec determines the shell as described in the "FILES" section. Any output on "stdout" or "stderr" from COMMAND will appear in the log when the log messages are being written to a local log file.

--error-directory=DIR_PATH

Move to this directory files where COMMAND either runs unsuccessfully (i.e., has a non-zero exit status) or terminates by a signal. DIR_PATH must be a complete directory path. This switch is required.

--archive-directory=DIR_PATH

Move to this directory the files where COMMAND runs successfully (i.e., has an exit status of zero). DIR_PATH must be a complete directory path. If this switch is not supplied, rwpollexec will delete these files instead. When the --flat-archive switch is also provided, incoming files are moved into DIR_PATH; when --flat-archive is not given, each file is moved to a subdirectory of DIR_PATH based on the current local time: DIR_PATH/YEAR/MONTH/DAY/HOUR/. Removing files from the archive-directory is not the job of rwpollexec; the system administrator should implement a separate process to clean this directory.

--flat-archive

When archiving input files via the --archive-directory switch, move the files into the top of the archive-directory, not into subdirectories of the archive-directory. This switch has no effect if --archive-directory is not also specified. This switch may be used to allow another process to watch for new files appearing in the archive-directory.

--simultaneous=NUM

Allow a maximum of NUM commands to be executed simultaneously. The default is one, which allows only one command to be run at a time. The maximum value allowed for this switch is 50.

--timeout=SIGNAL,SECS

Send SIGNAL to the running command if it has been executing for SECS seconds. SIGNAL may be a signal name, with or without a "SIG" prefix, or a signal number. A list of signals can be determined by running the command "kill -l" at a shell prompt (cf. kill(1)). This switch may be repeated to send different signals after various amounts of time.

--polling-interval=NUM

Configure rwpollexec to check the incoming directory for new files every NUM seconds. The default polling interval is 15 seconds.

One of the following logging switches is required:

--log-destination=DESTINATION

Specify the destination where logging messages are written. When DESTINATION begins with a slash "/", it is treated as a file system path and all log messages are written to that file; there is no log rotation. When DESTINATION does not begin with "/", it must be one of the following strings:

--log-directory=DIR_PATH

Use DIR_PATH as the directory where the log files are written. DIR_PATH must be a complete directory path. The log files have the form

 DIR_PATH/LOG_BASENAME-YYYYMMDD.log
    

where YYYYMMDD is the current date and LOG_BASENAME is the application name or the value passed to the --log-basename switch when provided. The log files are rotated: At midnight local time, a new log is opened, the previous file is closed, and the command specified by --log-post-rotate is invoked on the previous day's log file. (Old log files are not removed by rwpollexec; the administrator should use another tool to remove them.) When this switch is provided, a process-ID file (PID) is also written in this directory unless the --pidfile switch is provided.

--log-pathname=FILE_PATH

Use FILE_PATH as the complete path to the log file. The log file is not rotated.

The following set of switches is optional:

--log-level=LEVEL

Set the severity of messages that are logged. The levels from most severe to least are: "emerg", "alert", "crit", "err", "warning", "notice", "info", "debug". The default is "info".

--log-sysfacility=NUMBER

Set the facility that syslog(3) uses for logging messages. This switch takes a number as an argument. The default is a value that corresponds to "LOG_USER" on the system where rwpollexec is running. This switch produces an error unless --log-destination=syslog is specified.

--log-basename=LOG_BASENAME

Use LOG_BASENAME in place of the application name in the name of log files in the log directory. See the description of the --log-directory switch. This switch does not affect the name of the process-ID file.

--log-post-rotate=COMMAND

Run COMMAND on the previous day's log file after log rotation. When this switch is not specified, the previous day's log file is compressed with gzip(1). When the switch is specified and COMMAND is the empty string, no action is taken on the log file. Each occurrence of the string %s in COMMAND is replaced with the full path to the log file, and each occurrence of "%%" is replaced with "%". If any other character follows "%", rwpollexec exits with an error. Specifying this switch without also using --log-directory is an error.

--pidfile=FILE_PATH

Set the complete path to the file in which rwpollexec writes its process ID (PID) when it is running as a daemon. No PID file is written when --no-daemon is given. When this switch is not present, no PID file is written unless the --log-directory switch is specified, in which case the PID is written to LOGPATH/rwpollexec.pid.

--no-chdir

Do not change directory to the root directory. When rwpollexec becomes a daemon process, it changes its current directory to the root directory so as to avoid potentially running on a mounted file system. Specifying --no-chdir prevents this behavior, which may be useful during debugging. The application does not change its directory when --no-daemon is given.

--no-daemon

Force rwpollexec to run in the foreground---it does not become a daemon process. This may be useful during debugging.

--help

Print the available options and exit.

--version

Print the version number and information about how SiLK was configured, then exit the application.

ENVIRONMENT

SILK_RWPOLLEXEC_SHELL

The shell to use for executing commands. If this variable is not set, rwpollexec tests the list of shells specified in "FILES" to find a shell that uses a member of the execl(3) family of functions to run the command. More details are available in the "BUGS" section.

FILES

${SILK_RWPOLLEXEC_SHELL}

/bin/sh

/bin/bash

/bin/ksh

/usr/bin/sh

/usr/bin/bash

/usr/bin/ksh

Shells that rwpollexec may use to invoke the command specified by --command. The shell specified in SILK_RWPOLLEXEC_SHELL is always used when that variable is set. Otherwise, rwpollexec checks the list of shells to find one that uses execl(3) to invoke the command. When a suitable shell is not found, rwpollexec uses /bin/sh. See "BUGS" for additional information.

BUGS

rwpollexec uses a subshell to execute the command specified as the argument to --command. How the subshell invokes the command is important when the --timeout switch is specified. Many shells use a member of execl(3) family of functions to invoke the command, which causes the command's process to replace the shell process. For these shells, signals sent by rwpollexec are received by the command process directly. However, some shells use a combination of fork(2) and wait(2) to invoke the command. In these shells, the signal is received by the subshell instead of the command, and this can lead to undesirable or unreliable behavior. When the SILK_RWPOLLEXEC_SHELL environment variable is set, rwpollexec uses that shell regardless of how it invokes its command, though if the specified shell uses fork(2), rwpollexec will emit a warning to the standard error and to the log. When SILK_RWPOLLEXEC_SHELL is not set, rwpollexec attempts to find a shell that uses execl(3). If rwpollexec fails to find a suitable shell, it uses /bin/sh and emits a warning message to standard error and to the log. The list of shells rwpollexec checks are specified in the "FILES" section.

rwpollexec is unable to tell the difference between a command returning a non-zero exit status and a command that fails because the command does not exist or is malformed. Both appear as a failed command with a non-zero exit status. The shell may emit messages that explain why a command has failed. In these instances, these messages will appear in the log.

rwpollexec only attempts to run the command one time. There is no way to tell rwpollexec to attempt the command multiple times.

SEE ALSO

silk(7), kill(1), gzip(1), syslog(3), fork(2), wait(2), execl(3)