NAME
shush - Run a command and optionally report its output by mail
SYNOPSIS
shush [ -h | -V ]
shush [ -c dir ] [ -S | -s facility ] [ -vfmk ] name [ ID ]
shush [ -c dir ] [ -H to ] [ -R to ] [ -T to ] -C name [ stdout [
stderr ] ]
shush [ -i | -u | -r ] [ -c dir ]
DESCRIPTION
shush runs a command and optionally reports its output by mail. It is
a useful wrapper around cron jobs. By default, shush will not produce
any output when running as everything (if anything) is reported by
mail. However, configuration as well as critical errors will be
reported on the standard error and (optionally) syslog. Because
interrupting shush has dire consequences including the likely loss of
any output from the command, the following commonly used signals are
ignored by shush: SIGHUP, SIGINT, SIGQUIT and SIGTERM. If one really
wants to kill a running instance of shush rather than killing the
running managed command, SIGKILL may be used and shall serve as a
reminder of how inappropriate such action typically is.
For a command to be run using shush, a configuration file name must
exist in the configuration directory ($HOME/.shush by default). This
file defines how the command should be run as well when to send reports
by mail. For details on available configuration parameters, see the
CONFIGURATION section below.
Two additional configuration files may exist: name.stdout and
name.stderr (by default). These files are used to look at the standard
output and standard error (respectively) produced by the command. For
details on how to use these, see the COMMAND OUTPUT section below.
When the -C option is specified, shush will only load the
configuration, optionally analyze the standard output and standard
error from the specified files and finally produce sample reports if
desired. This may also be used to produce reports if shush failed to
properly terminate when running a command. (The standard output and
error from the command are normally found in files located under /tmp.)
shush is able to manage crontab(5) entries based on configurations
defined by the user. This may be done in one of two ways. If a file
named "schedule" exists in the configuration directory, then it is read
for scheduling information. Each line should contain a single entry
containing three fields separated by whitespace(s). The fields are (in
order) the hostname for which the entry applies or the character "*" to
include all hosts, the configuration name, and finally, the scheduling
information in the same format as is used by the schedule parameter
(see below). To specify an ID, use name:ID as the second field. If
there is no file named "schedule", then shush checks the configuration
directory for configuration files and adds them to the current user’s
crontab(5) file as specified by the included schedule parameter (see
below). Files whose names start with the character "#" or end with the
character "~" are ignored.
OPTIONS
-h Display a brief help message.
-V Display the version information. Prefix with -v to display
compile time defaults.
-c dir Specify the directory where configurations are stored.
-s facility
Defines the syslog facility to use for logging.
-S Disable syslog logging.
-v Copy information log messages to the standard output.
-f Fast mode: Any configured randomdelay is ignored.
-m Monitor and display the command’s standard output and error in
real time.
-k Keep the command’s output log files instead of deleting them
upon completion.
-C Check the configuration without running any command.
-H to Send a sample HTML report to the specified recipient(s).
-R to Send a sample enriched report to the specified recipient(s).
-T to Send a sample text report to the specified recipient(s).
-i Use crontab(1) to install a new crontab(5) file for the current
user. The user must not already have a crontab(5) file.
-u Use crontab(1) to update the current user’s crontab(5) file,
which must already exist.
-r Remove any entry added by the -u option from the current user’s
crontab(5).
CONFIGURATION
shush configuration files consist of a main section, report section(s)
and parameters. The main section defines global parameters as well as
defaults for reports. Each report section begins with the name of the
report between brackets. Lines beginning with the character "#" are
ignored. Parameters should be specified only once. If specified
multiple times, all but the last occurrence will be ignored, unless
noted otherwise. Parameters are defined using the following syntax:
name=value
or:
name@hostname=value
or:
name%ID=value
or finally:
name@hostname%ID=value
The second and fourth formats will be ignored unless shush is running
on the specified hostname. The third and fourth formats allow defining
multiple instances of a single configuration file. Such configuration
files require an instance ID to be specified in order to run. Any
configuration line using the third or fourth formats will be ignored if
the ID found on that line does not match the instance ID used to run
shush.
The following parameters may appear in the main section:
command
The actual command to run. shush sets two environment variables
before running the command: SHUSH_NAME is set to name, and
SHUSH_ID is set to ID.
config This defaults to the full path of the main configuration file.
The other two configuration file names are obtained by appending
the ".stdout" and ".stderr" suffixes to the value of this
parameter.
lock If set, this parameter instructs shush to obtain a lock file
before running the command, and defines the actions to take in
case the lockfile is held by another process. The format is a
comma separated list of actions. Valid actions are: a time
duration (during which shush should simply wait and keep trying
to obtain the lockfile), the string "abort" (indicating that
shush should terminate immediately if the lockfile already
exists), the string "ignore" (indicating that shush should
ignore an existing lockfile), the string "loop" (to mark where
to start again from when all actions have been executed) and the
string "notify=" followed by mail addresses to which a
notification mail should be sent. Actions are executed in the
order they are provided, and shush will wait forever trying to
obtain the lockfile once all the actions have been executed,
unless the string "loop" is one of defined actions. Time
durations may be specified in units of w(eeks), d(ays), h(ours),
m(inutes) or s(econds). If no unit is specified, it is assumed
to be minutes.
lockfile
By default, shush will use a file located in the same directory
as the configuration file, and named after the configuration and
host names. An alternate filename may be specified using this
parameter.
lockmsg
If set, this string will be used as subject for lock
notification(s) mail messages. The default is "[%u@%h]
**PENDING** %N [%t]". See the MAIL SUBJECT section for details
on the format.
path shush does not modify the environment, except to set the PATH
variable if the path parameter is set.
randomdelay
If this parameter is set, shush will wait up to the specified
amount of time before starting the command unless invoked with
the -f. Valid time units are: s(econds), m(inutes), h(ours),
d(ays), w(eeks). If no unit is specified, it is assumed to be
minutes.
schedule
This defines when to run this command as a cron job, in a
crontab(5) compatible format. Multiple entries may be specified
using the character ";" as separator. Entries prefixed by the
character "#" will be skipped. This parameter is not directly
used by shush to run the command, but used by the -i and -u
options.
sendmail
This may be used to override the command used to send mail.
shell By default, the Bourne shell sh(1) is used to run the command,
allowing any shell syntax to be used. An alternate shell may be
defined using this parameter.
statedir
This defines the directory where the status of shush is saved
and defaults to the ".state" directory under where the
configuration is located. An error is generated if the
directory does not exist unless this option was not set.
Setting this option to an empty string will prevent shush from
saving its status. shlast(1) uses these state files to report
on running instances of shush as well as previous runs.
syslog This parameter is only used by the -i and -u options and has no
other effect on shush. It allows overriding the default syslog
facility used for logging and defined at compile time. If left
blank, this suppresses the use of syslog.
timeout
This parameter allows one to control how long the command may
run. It should be a comma separated list of actions. Valid
actions are: a time duration (during which shush should simply
wait for the command to terminate), a signal (either "SIGNAME"
or "-SIGNUMBER") that should be sent to the command’s process
group, a signal (either "=SIGNAME" or "=SIGNUMBER") that should
be sent to the shell used to spawn the command, the string
"loop" (to mark where to start again from when all actions have
been executed) and the string "notify=" followed by mail
addresses to which a notification mail should be sent. Actions
are executed in the order they are provided, and shush will wait
forever if the command is still running once all the actions
have been executed unless the string "loop" is one of defined
actions. Time durations may be specified in units of w(eeks),
d(ays), h(ours), m(inutes) or s(econds). If no unit is
specified, it is assumed to be minutes.
timeoutmsg
If set, this string will be used as subject for timeout
notification(s) mail messages. The default is "[%u@%h]
**TIMEOUT** %N [%t]". See the MAIL SUBJECT section for details
on the format.
The following parameters may appear anywhere in the configuration. If
specified in the main section, they define defaults settings that will
apply to any report for which the same parameter has not been defined.
to, cc, bcc
Where to send the mail report.
subject
Subject of the mail report. See the MAIL SUBJECT section for
details on the format.
header Additional mail header(s). Note that this parameter may be
repeated to specify multiple headers. However, only headers
from the report (if specified) or from the main section will be
used for a given report.
hostprefix
By default, specified subjects are prefixed with the host name
between brackets. This parameter allows one to customize this
prefix. A positive integer indicates how many components of the
fully qualified hostname should be shown. A negative integer
indicates how many trailing components of the fully qualified
hostname should be trimmed. The integer zero indicates that the
prefix should be omitted. This parameter is ignored if the
"subject" contains any "%" character.
userprefix
By default, specified subjects are prefixed with the username
between brackets. This parameter allows to disable this prefix.
Any non zero value indicates that the username should be shown
while zero causes the prefix to be omitted. This parameter is
ignored if the "subject" contains any "%" character.
output (previously "stderr")
This defines how the command’s standard output and standard
error are captured and reported to the user: "errfirst",
"mixed", "outfirst". When using "mixed", the name.stderr
configuration file is ignored. When using "errfirst" or
"outfirst", individual reports may use one of the following two
additional options "outonly" and "erronly".
format Mail messages sending the output of the command may be sent in
three different formats: "text" (the default), "enriched" text
or "html".
sizelimit
By default, the entire output of the command is sent in mail
reports. This parameter may be used to limit the size of the
output included in a report. Note that the total size of mail
sent will be greater as this limit has no effect upon mail
headers. The size can be specified in units of m, k, b, c (MB,
KB, Bytes). If no unit is specified, it is assumed to be KB. A
limit of zero indicates that the output should not be truncated.
if A report is only sent if no if condition is specified or if the
specified if condition is true. The condition syntax allows for
the usual logical operators ("||", "&&", "!"), comparison
operators ("==", "!=", "<", "<=", ">", ">=") and basic
arithmetic operators ("+", "-"). Aside from counters defined by
the configuration (see the COMMAND OUTPUT section below), the
following variables may be used:
$exit If the command terminated normally, this is its exit
code. Otherwise, it is negative and indicates the signal
number having caused the command to terminate (e.g. -1
indicates signal number 1 caused the command to
terminate).
$size output size (in bytes), same as "$outsize + $errsize"
$outsize
size (in bytes) of standard output
$errsize
size (in bytes) of standard error
$lines number of lines output
$outlines
number of standard output lines
$errlines
number of standard error lines
$runtime
command run time (in seconds)
$utime user time used by the command
$stime system time used by the command
$tty 1 if shush is run from a terminal (e.g. interactively), 0
otherwise.
MAIL SUBJECTS
The "lockmsg", "timeoutmsg" and "subject" parameters may contain the
following tokens which are expanded as described below:
%% The "%" character
%h The hostname
%<digit>
or "%-<digit>"
A partial hostname: A positive digit indicates how many
components of the fully qualified hostname to keep; a
negative digit indicates how many trailing components of
the fully qualified hostname to trim.
%i The instance ID
%n The configuration name
%N The configuration name and instance ID
%r The report name
%t The elapsed time.
%u The username.
%U The userid.
If the "%" character is found in the "subject" parameter,
then the "hostprefix" and "userprefix" parameters are
ignored.
COMMAND OUTPUT
After the command terminates, shush will use the contents of the
name.stdout and name.stderr files (if they exist) to look at the output
produced by the command.
These files follow a simple format. Each line is composed of a single
character (the counter name) followed by a regular expression.
All counters are initialized to 0 (zero). Each line of output is
matched against these regular expressions until a match is found. If a
match is found, the associated counter is incremented by one. These
counters may then be used as part of the main configuration, in an "if"
configuration parameter, allowing the decision to send a mail report to
be based on how many times certain regular expressions have been
matched.
Finally, regular expressions may define sub-expressions which will be
rendered in bold in mail reports.
Lines starting with the character "#" are considered to be comments and
are ignored. By default, standard regular expressions are used, unless
the first line is "#pcre" in which case Perl compatible regular
expressions are used.
ENVIRONMENT VARIABLES
HOME If the -c option is not used, shush will look for configuration
files in $HOME/.shush.
SHUSH_SENDMAIL
If defined, this should point to the sendmail(1) binary. This
variable overrides the "sendmail" configuration setting and
should be used with care.
TMPDIR Directory where temporary files are created.
EXAMPLE
The following configuration runs "shush -c /etc/shush -u" daily at
9:00, updating the user (root) crontab:
command=shush -c /etc/shush -u
schedule=0 9 * * *
lock=notify=root root-logs,abort
timeout=5m,loop,notify=root root-logs,15m
stderr=first
format=text
Subject=Crontab Daily Update
[logs]
to=root-logs
[readers]
if=$exit != 0 || $outlines != 1 || $errsize > 0 || U
to=root
format=rich
The associated configuration for standard output is:
Oshush: crontab updated\.$
U^.+$
and for standard error:
U^(.+)$
A lock will be set while running the command, and mail sent to "root"
and "root-logs" if the lock is held by another process when shush
starts, in which case shush will abort. A mail will also be sent to
"root" and "root-logs" if "shush -c /etc/shush -u" runs for more than 5
minutes, and for every 15 minutes following the first 5 minutes.
Upon completion, the output will always be sent to "root-logs".
Additionally, the output will be sent to "root" if the condition "$exit
!= 0 || $outlines != 1 || $errsize > 0 || U" is true. For this
condition to be true, one of the following must be true: the exit code
is non zero, the command standard output was not a single line, there
was output on standard error or finally, the counter "U" is non zero.
For the counter "U" to be non zero, there must be output on standard
output other than the line "shush: crontab updated.". Finally, any
line of output produced on the standard error will be displayed in bold
in mails sent to "root".
SEE ALSO
crontab(1), pcre(3), regex(3), sendmail(1), sh(1).
AVAILABILITY
The latest official release of shush is available on the web. The home
page is http://web.taranis.org/shush/
AUTHOR
Christophe Kalt <kalt@taranis.org>
BUGS
The -C option does not allow specifying an ID.
For other bugs, send reports to ‘shush-bugs@taranis.org’.
$Date: 2007-09-30 23:38:23 $