mdw@git.distorted.org.uk Git - 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 .IR mode ,
  68 a mode specification acceptable to
  69 .BR chmod (1),
  70 though relative permissions will be applied to mode
  71 .B 600
  72 (i.e.,
  73 .BR u=rw,og= ).
  74 .TP
  75 .BI "\-u \fR[" user\fR][ : group\fR]
  76 Set the ownership and/or group of the logfile.  If the
  77 .I user
  78 is specified, then the file's owner is set; if the
  79 .I group
  80 is specified, the file's group is set.  (Some care is taken to ensure
  81 that the file is never available to members of the wrong group.)
  82 .SS Operation
  83 The given
  84 .I command
  85 is executed with the
  86 given
  87 .IR arguments ,
  88 with stdin redirected from
  89 .BR /dev/null ,
  90 and stdout and stderr redirected to separate pipes.  If it is available,
  91 .BR stdbuf (1)
  92 is used to ensure that the
  93 .IR command 's
  94 stdout is line-buffered.
  95 .PP
  96 The
  97 .IR command 's
  98 output is collected in a log file named
  99 .IB logdir / tag . date # seq
 100 where
 101 .TP
 102 .I logdir
 103 is the argument of the
 104 .B \-d
 105 option, or
 106 .B @logdir@
 107 by default;
 108 .TP
 109 .I tag
 110 is the
 111 .I tag
 112 string given to
 113 .B hush
 114 as a command-line argument;
 115 .TP
 116 .I date
 117 is the current date, in ISO8601 form (in local time); and
 118 .TP
 119 .I seq
 120 is a sequence number, chosen to ensure that log file names are distinct
 121 and sort in chronological order.
 122 .PP
 123 The log file begins with a header giving the exact start time (in local
 124 time, with an offset from UTC) and a brief summary of the log format; it
 125 ends with another timestamp and the
 126 .IR command 's
 127 exit status.  In between is the command's output.  Lines written to
 128 stdout begin with
 129 .RB ` | ';
 130 lines to stderr begin with
 131 .RB ` * '.
 132 The two are interleaved in an attempt to help the reader identify how
 133 much progress the
 134 .I command
 135 had made when it encountered an error; however, because the streams are
 136 read asynchronously, this isn't perfect, and lines may appear earlier or
 137 later than they ought to.
 138 .PP
 139 If the
 140 .I command
 141 succeeds, as mentioned,
 142 .B hush
 143 exits without printing anything.  If it fails, and the
 144 .B \-m
 145 option was given, the log file is mailed to the appropriate
 146 .I email-address
 147 with a subject line
 148 .IP
 149 .IB tag :
 150 .I command
 151 .B failed (status =
 152 .IB rc )
 153 .PP
 154 where
 155 .I rc
 156 is the
 157 .IR command 's
 158 exit status.  If no
 159 .B \-m
 160 option was given, this log is simply written to standard output.
 161 .SH BUGS
 162 The stream interleaving isn't quite right, but it's hard to see how to
 163 improve it.
 164 .PP
 165 Capturing the command's output involves making a fairly large number of
 166 auxiliary processes and file descriptors.  This is a bit ugly.
 167 .SH AUTHOR
 168 Mark Wooding, <mdw@distorted.org.uk>
 169 .SH SEE ALSO
 170 .BR cron (8).