Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
rwpollexec(8)			SiLK Tool Suite			 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-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:

	   "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 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)

SiLK 3.19.1			  2020-08-27			 rwpollexec(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT | FILES | BUGS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=rwpollexec&sektion=8&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help