NAME
shush - Run a command and optionally report its output by
mail
SYNOPSIS
shush [ -h | -V ]
shush [ -c dir ] [ -S | -s facility ] [ -vfmk ] name
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 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 avail-
able configuration options, see the CONFIGURATION section
below.
Two additional configuration files may exist: name.stdout
and name.stderr. These files are used to analyze the stan-
dard output and standard error (respectively) produced by
the command. Configuration lines are composed of a single
character (a counter name) followed by a regular expression.
Each line of output is matched against this list until the
first match is found. When a match is found, the associated
counter is incremented by one. Counters may be used in con-
ditional expressions, allowing to base the decision to send
a mail report on how many times certain regular expressions
have been matched. Regular expressions may define sub-
expressions which will be will be rendered in bold in mail
reports. Lines starting with the character "#" are con-
sidered to be comments and are ignored. By default, stan-
dard regular expressions are used, unless the first line is
"#pcre" in which case Perl compatible regular expressions
are used.
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 confi-
gurations defined by the user. This may be done using one
of two ways. If a file named "schedule" exists in the con-
figuration directory, then it is read for scheduling infor-
mation. 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 char-
acter "*" to include all hosts, the configuration name and
finally, the scheduling information in the same format as is
used by the schedule option (see below). 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 option (see below). Files whose name starts with
the character "#" or ends 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's. The user must not already have a cron-
tab(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. Parame-
ters 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 optionally:
name@hostname=value
The second format will be ignored unless shush is running on
the specified hostname.
The following parameters may appear in the main section:
command
The actual command to run.
lock If set, this option instructs shush to obtain 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 ter-
minate 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 speci-
fied in units of w(eeks), d(ays), h(ours), m(inutes) or
s(econds). If not 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 option.
lockmsg
If set, this string will be used as subject for lock
notification(s) mail messages.
path shush does not modify the environment, except to set
the PATH variable if the path option is set.
randomdelay
If this option is set, shush will wait up 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 not 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 option 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 option.
stderr
This defines how the command's standard errors are cap-
tured and reported to the user: "first", "mixed" or
"last". When using "mixed", the name.stderr file is
ignored.
syslog
This option 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 supresses the use of
syslog.
timeout
This option 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 ter-
minate), a signal (either "SIGNAME" or "-SIGNUMBER")
that should be sent the command's process group, a sig-
nal (either "=SIGNAME" or "=SIGNUMBER") that should be
sent 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 com-
mand 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
not 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 following parameters may appear anywhere in the confi-
guration. 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.
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 option allows to cus-
tomize this prefix. A positive integer indicates how
many hostname components should be shown. With a nega-
tive integer, trailing components of the hostname are
shown. The integer zero indicates that the prefix
should be omitted.
userprefix
By default, specified subjects are prefixed with the
username between brackets. This option allows to dis-
able this prefix. Any non zero value indicates that
the username should be shown while zero causes the pre-
fix to be omitted.
format
Mail messages sending the output of the command may be
sent in three different format: "text" (the default),
"enriched" text or "html".
sizelimit
By default, the entire output of the command is sent in
mail reports. This option 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 trun-
cated.
if A report is only sent if no if condition is specified
or if the specified if condition is true. The condi-
tion syntax allows for the usual logical operators
("||", "&&", "!"), comparison operators ("==", "!=",
"<", "<=", ">", ">=") and basic arithmetic operators
("+", "-"). Asides from counters defined by the confi-
guration, the following variables may be used:
$exit
If the command terminated normally, this is its
exit code. Otherwise, it is negative and indi-
cates 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. interac-
tively), 0 otherwise.
ENVIRONMENT VARIABLES
HOME If the -c option is not used, shush will look for con-
figuration files in $HOME/.shush.
SHUSH_SENDMAIL
If defined, this should point to the sendmail(1)
binary. This variable overrides the "sendmail" confi-
guration 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,notify=root root-logs
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. A mail will also be sent to
"root" and "root-logs" if "shush -c /etc/shush -u" runs for
more than 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 || $out-
lines != 1 || $errsize > 0 || U" is true. For it to be
true, one of the following must be true: the exit code is
non zero, there was output on standard error or there was
output on standard output other than the line "shush: cron-
tab updated.". Any line of output other than "shush: cron-
tab updated." 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 <shush@taranis.org>
BUGS
Man(1) output converted with
man2html