RWPOLLEXEC(8)

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-directory=DIR_PATH [--log-basename=BASENAME]
          | --log-pathname=FILE_PATH }
        [--log-level=LEVEL] [--log-sysfacility=NUMBER]
        [--pidfile=FILE_PATH] [--no-daemon]

  rwpollexec --help

  rwpollexec --version

DESCRIPTION
rwpollexec is a daemon that monitors a directory for incoming files, and then runs 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 allows a single command to be specified. If you need to run multiple commands on a file, create a script to run these commands and have rwpollexec run the script.

The --simultaneous switch specifies the maximum number of commands 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 will not exit until that command is killed, or rwpollexec itself is sent a SIGKILL.

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
    Monitor this directory for new files to handle. DIR_PATH must be a complete directory path. For each new file in this directory, rwpollexec will run the command specified by the --command switch. rwpollexec ignores any files in this directory that are empty or whose names begin with a dot ("."). In addition, new files will only be considered when their size is constant for one polling-interval after they are first noticed. 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 will be replaced with the full path to the file. If the exit status of COMMAND is zero, rwpollexec will delete 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. If the "SILK_RWPOLLEXEC_SHELL" environment variable is set, its value will be used as the shell. Otherwise, "/bin/sh" will be used. Any output on "stdout" or "stderr" from COMMAND will end up in the log, unless --no-daemon is used.

--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 the top of DIR_PATH; when --flat-archive is not given, each file is moved to a subdirectory 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 can 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 can 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".

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

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

    "none"
        Messages are not written anywhere.

    "stdout"
        Messages are written to the standard output.

    "stderr"
        Messages are written to the standard error.

    "syslog"
        Messages are written using the syslog(3) facility.

    "both"
        Messages are written to the syslog facility and to the standard error (this option is not available on all platforms).

--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 will be rotated: at midnight local time a new log will be opened and the previous day's log file will be compressed using gzip(1). (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) will also be 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 will not be rotated.

The following set of switches is optional:

--log-level=LEVEL
    Set the severity of messages that will be 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 for the files in the log directory. See the description of the --log-directory switch.

--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-daemon
    Force rwpollexec to stay in the foreground---it does not become a daemon. Useful for 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 is not set, "/bin/sh" will be used as the shell.

BUGS
The command that rwpollexec runs is executed via the shell in $SILK_RWPOLLEXEC_SHELL, or "/bin/sh" if not set. Some variants of "/bin/sh" do not exec their subcommands, but instead wait for them to exit or be killed. When signals are sent via the --timeout mechanism and these shells are used, the signal will be sent to the shell rather than the subcommand. This is often not the desired behavior, so on these systems it is best to set the "SILK_RWPOLLEXEC_SHELL" variable to a saner shell. SunOS in particular is susceptible to this problem. Try using ksh or bash instead.

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.

SEE ALSO
kill(1), syslog(3)