Provided by: shush_1.2.3-5_amd64 bug

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

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