[misc] / hush.1.in

.TH hush 1 "14 December 2011" "Edgeware tools"
.SH NAME
hush \- run a program, quietly unless it fails
.SH SYNOPSIS
.B hush
.RB [ \-d
.IR directory ]
.RB [ \-m
.IR email-address ]
.RB [ \-n
.IR maxlog ]
.RB [ \-u
.IR owner ][\fB: group ]
.br
	\c
.I tag
.I command
.IR arguments ...
.SH DESCRIPTION
The
.B hush
program runs a command.  The command's output (i.e., what it writes to
its standard output and standard error file descriptors) is always
logged to a file.  If the command succeeds,
.B hush
itself outputs nothing; if it fails, then
.B hush
either writes the command's output to its own stdout, or sends it via
email.  It is intended to be used when running noisy programs via
.BR cron (8),
to reduce the amount of uninteresting mail (`cronspam') produced by an
essentially working system.
.PP
The following command-line options are recognized.
.TP
.B \-h
Write a help message describing
.BR hush 's
command line options and usage to standard output, and exit.
.TP
.B \-v
Write
.BR hush 's
version number to standard output, and exit.
.TP
.BI "\-d " directory
Write log files to
.I directory
rather than the default,
.BR "@logdir@" .
.TP
.BI "\-m " email-address
Rather than writing its output to stdout if the command fails, send the
command's output to
.IR email-address .
and exit with status 0.  (This is perhaps a surprising choice, but it
prevents the caller from taking additional action to report a problem
which has already been escalated to a human.)
.TP
.BI "\-n " maxlog
If necessary, delete old logfiles so that no more than
.I maxlog
log files are left.
.TP
.BI "\-p " mode
Set the permissions on the logfile to
.IR mode ,
a mode specification acceptable to
.BR chmod (1),
though relative permissions will be applied to mode
.B 600
(i.e.,
.BR u=rw,og= ).
.TP
.BI "\-u \fR[" user\fR][ : group\fR]
Set the ownership and/or group of the logfile.  If the
.I user
is specified, then the file's owner is set; if the
.I group
is specified, the file's group is set.  (Some care is taken to ensure
that the file is never available to members of the wrong group.)
.SS Operation
The given
.I command
is executed with the
given
.IR arguments ,
with stdin redirected from
.BR /dev/null ,
and stdout and stderr redirected to separate pipes.  If it is available,
.BR stdbuf (1)
is used to ensure that the
.IR command 's
stdout is line-buffered.
.PP
The
.IR command 's
output is collected in a log file named
.IB logdir / tag . date # seq
where
.TP
.I logdir
is the argument of the
.B \-d
option, or
.B @logdir@
by default;
.TP
.I tag
is the
.I tag
string given to
.B hush
as a command-line argument;
.TP
.I date
is the current date, in ISO8601 form (in local time); and
.TP
.I seq
is a sequence number, chosen to ensure that log file names are distinct
and sort in chronological order.
.PP
The log file begins with a header giving the exact start time (in local
time, with an offset from UTC) and a brief summary of the log format; it
ends with another timestamp and the
.IR command 's
exit status.  In between is the command's output.  Lines written to
stdout begin with
.RB ` | ';
lines to stderr begin with
.RB ` * '.
The two are interleaved in an attempt to help the reader identify how
much progress the
.I command
had made when it encountered an error; however, because the streams are
read asynchronously, this isn't perfect, and lines may appear earlier or
later than they ought to.
.PP
If the
.I command
succeeds, as mentioned,
.B hush
exits without printing anything.  If it fails, and the
.B \-m
option was given, the log file is mailed to the appropriate
.I email-address
with a subject line
.IP
.IB tag :
.I command
.B failed (status =
.IB rc )
.PP
where
.I rc
is the
.IR command 's
exit status.  If no
.B \-m
option was given, this log is simply written to standard output.
.SH BUGS
The stream interleaving isn't quite right, but it's hard to see how to
improve it.
.PP
Capturing the command's output involves making a fairly large number of
auxiliary processes and file descriptors.  This is a bit ugly.
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
.SH SEE ALSO
.BR cron (8).
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
fd048815	49	rather than the default,
c818aced MW	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),
3ca52a3b MW	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).