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:
or:
or:
or finally:
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'.
