Ubuntu Manpage: shush - Run a command and optionally report its output by mail

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 one 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".

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 $                          SHUSH(1)