Commit | Line | Data |
---|---|---|
c818aced MW |
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 | |
3ca52a3b | 67 | .IR mode , |
c818aced | 68 | a mode specification acceptable to |
3ca52a3b MW |
69 | .BR chmod (1), |
70 | though relative permissions will be applied to mode | |
c818aced MW |
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). |