manpagez: man pages & more
man shush(1)
Home | html | info | man
shush(1)                                                              shush(1)




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 inter-
       rupting  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  run-
       ning 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 configura-
       tion, 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 com-
              pile 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 mul-
       tiple 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 con-
       figuration  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 param-
              eter.

       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 notifica-
              tion  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  min-
              utes.

       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  notifica-
              tion(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  configu-
              ration  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  speci-
              fied, it is assumed to be minutes.

       timeoutmsg
              If  set, this string will be used as subject for timeout notifi-
              cation(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 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  con-
              figuration  file  is  ignored.   When  using "errfirst" or "out-
              first", 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 head-
              ers.   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 opera-
              tors  ("==",  "!=",  "<",  "<=", ">", ">=") and basic arithmetic
              operators ("+", "-").  Aside from counters defined by  the  con-
              figuration (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 termi-
                     nate).

              $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>
                     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 expres-
       sions 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".   Addi-
       tionally,  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 out-
       put 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)

shush 1.2.3 - Generated Fri Aug 7 13:01:31 CDT 2009
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.