[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
.I 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
	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).