chiark - git - mdw - misc/blob - hush.1.in

   1 .TH hush 1 "14 December 2011" "Edgeware tools"
   2 .SH NAME
   3 hush \- run a program, quietly unless it fails
   4 .SH SYNOPSIS
   5 .B hush
   6 .RB [ \-d
   7 .IR directory ]
   8 .RB [ \-m
   9 .IR email-address ]
  10 .RB [ \-n
  11 .IR maxlog ]
  12 .RB [ \-u
  13 .IR owner ][\fB: group ]
  14 .br
  15         \c
  16 .I tag
  17 .I command
  18 .IR arguments ...
  19 .SH DESCRIPTION
  20 The
  21 .B hush
  22 program runs a command.  The command's output (i.e., what it writes to
  23 its standard output and standard error file descriptors) is always
  24 logged to a file.  If the command succeeds,
  25 .B hush
  26 itself outputs nothing; if it fails, then
  27 .B hush
  28 either writes the command's output to its own stdout, or sends it via
  29 email.  It is intended to be used when running noisy programs via
  30 .BR cron (8),
  31 to reduce the amount of uninteresting mail (`cronspam') produced by an
  32 essentially working system.
  33 .PP
  34 The following command-line options are recognized.
  35 .TP
  36 .B \-h
  37 Write a help message describing
  38 .BR hush 's
  39 command line options and usage to standard output, and exit.
  40 .TP
  41 .B \-v
  42 Write
  43 .BR hush 's
  44 version number to standard output, and exit.
  45 .TP
  46 .BI "\-d " directory
  47 Write log files to
  48 .I directory
  49 rather than the default,
  50 .BR "@logdir@" .
  51 .TP
  52 .BI "\-m " email-address
  53 Rather than writing its output to stdout if the command fails, send the
  54 command's output to
  55 .IR email-address .
  56 and exit with status 0.  (This is perhaps a surprising choice, but it
  57 prevents the caller from taking additional action to report a problem
  58 which has already been escalated to a human.)
  59 .TP
  60 .BI "\-n " maxlog
  61 If necessary, delete old logfiles so that no more than
  62 .I maxlog
  63 log files are left.
  64 .TP
  65 .BI "\-p " mode
  66 Set the permissions on the logfile to
  67 .I mode ,
  68 a mode specification acceptable to
  69 .BR chmod (1), though relative permissions will be applied to mode
  70 .B 600
  71 (i.e.,
  72 .BR u=rw,og= ).
  73 .TP
  74 .BI "\-u \fR[" user\fR][ : group\fR]
  75 Set the ownership and/or group of the logfile.  If the
  76 .I user
  77 is specified, then the file's owner is set; if the
  78 .I group
  79 is specified, the file's group is set.  (Some care is taken to ensure
  80 that the file is never available to members of the wrong group.)
  81 .SS Operation
  82 The given
  83 .I command
  84 is executed with the
  85 given
  86 .IR arguments ,
  87 with stdin redirected from
  88 .BR /dev/null ,
  89 and stdout and stderr redirected to separate pipes.  If it is available,
  90 .BR stdbuf (1)
  91 is used to ensure that the
  92 .IR command 's
  93 stdout is line-buffered.
  94 .PP
  95 The
  96 .IR command 's
  97 output is collected in a log file named
  98 .IB logdir / tag . date # seq
  99 where
 100 .TP
 101 .I logdir
 102 is the argument of the
 103 .B \-d
 104 option, or
 105 .B @logdir@
 106 by default;
 107 .TP
 108 .I tag
 109 is the
 110 .I tag
 111 string given to
 112 .B hush
 113 as a command-line argument;
 114 .TP
 115 .I date
 116 is the current date, in ISO8601 form (in local time); and
 117 .TP
 118 .I seq
 119 is a sequence number, chosen to ensure that log file names are distinct
 120 and sort in chronological order.
 121 .PP
 122 The log file begins with a header giving the exact start time (in local
 123 time, with an offset from UTC) and a brief summary of the log format; it
 124 ends with another timestamp and the
 125 .IR command 's
 126 exit status.  In between is the command's output.  Lines written to
 127 stdout begin with
 128 .RB ` | ';
 129 lines to stderr begin with
 130 .RB ` * '.
 131 The two are interleaved in an attempt to help the reader identify how
 132 much progress the
 133 .I command
 134 had made when it encountered an error; however, because the streams are
 135 read asynchronously, this isn't perfect, and lines may appear earlier or
 136 later than they ought to.
 137 .PP
 138 If the
 139 .I command
 140 succeeds, as mentioned,
 141 .B hush
 142 exits without printing anything.  If it fails, and the
 143 .B \-m
 144 option was given, the log file is mailed to the appropriate
 145 .I email-address
 146 with a subject line
 147 .IP
 148 .IB tag :
 149 .I command
 150 .B failed (status =
 151 .IB rc )
 152 .PP
 153 where
 154 .I rc
 155 is the
 156 .IR command 's
 157 exit status.  If no
 158 .B \-m
 159 option was given, this log is simply written to standard output.
 160 .SH BUGS
 161 The stream interleaving isn't quite right, but it's hard to see how to
 162 improve it.
 163 .PP
 164 Capturing the command's output involves making a fairly large number of
 165 auxiliary processes and file descriptors.  This is a bit ugly.
 166 .SH AUTHOR
 167 Mark Wooding, <mdw@distorted.org.uk>
 168 .SH SEE ALSO
 169 .BR cron (8).