freebsd/libexec/bugfiler/bugfiler.8

.\" Copyright (c) 1983, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)bugfiler.8	8.2 (Berkeley) 12/11/93
.\"
.Dd December 11, 1993
.Dt BUGFILER 8
.Os BSD 4.2
.Sh NAME
.Nm bugfiler
.Nd file bug reports in folders automatically
.Sh SYNOPSIS
.Nm bugfiler
.Op Fl ar
.Op Fl v Ar version
.Sh DESCRIPTION
.Nm Bugfiler
is a program to automatically intercept, acknowledge,
redistribute and store bug reports.
.Nm Bugfiler
is normally invoked
by the mail delivery program with a line similar to the following in
.Pa /etc/aliases .
.Bd -literal -offset indent
bugs:	"|bugfiler"
.Ed
.Pp
It should be noted that the login
.Dq bugs
must exist for the bugfiler
to run.  Unless otherwise noted all paths used by
.Nm bugfiler
are
relative to the home directory of this login.
.Nm Bugfiler
also
expects all of its files and directories to be owned by
.Dq bugs .
.Pp
Available options.
.Bl -tag -width Ds
.It Fl a
Do not send automatic mail acknowledgement to the bug report filer.
(The default is to send the acknowledgement with the file
.Pa ~bugs/version/bug:ack
appended).
.It Fl r
Do not redistribute.
.It Fl v Ar version
Override the
.Ar version
provided within the bug report itself.
.El
.Pp
For the bug report to be correctly filed, it must contain a line
in the following format:
.Pp
.Bd -filled -offset indent -compact
.Bl -column Index folder
.It Index: Ta Em folder Ta Ar version
.El
.Ed
.Pp
The directories
.Pa ~bugs/ Ns Ar version
and
.Pa ~bugs/ Ns Ar version/ Ns Em folder
must exist before
.Nm bugfiler
attempts to store the bug report.  Bug
reports will be stored in files named by the concatenation of
.Ar version ,
.Em folder ,
and sequential numbers, i.e. if
.Ar version
is
.Dq 4.3 Tn BSD
and
.Em folder
is
.Dq ucb
the first bug report will be placed in
.Pa ~bugs/4.3BSD/ucb/1 .
If
.Em folder
contains more than one component only
the first one will be used, e.g. if
.Em folder
is
.Dq bin/from.c
or
.Dq bin/adb/con.c
it will be treated as if it were simply
.Dq bin .
.Pp
.Pp
If the
.Fl r
flag is not supplied, redistribution of the bug reports
is done as specified in the file
.Pa ~bugs/version/bug:redist .
This file
is in the format of the
.Xr aliases 5
file, including comments and
entries requiring multiple lines, with the single exception that the
.Em folder
component of the
.Dq Index:
line replaces the name to alias.
The special folder
.Dq all:
receives a redistribution of all bug reports
sent to this
.Ar version .
For example, the
.Pa bug:redist
file
.Pp
.Bd -literal -offset indent -compact
#	bigbug gets a copy of everything
all:	bigbug
#	ucb folder redistribution list
ucb:	karels, kjd@coke.berkeley.edu
	ra@beno.css.gov
.Ed
.Pp
will send copies of all bug reports with
.Dq ucb
as the
.Em folder
to bigbug, karels, kjd, and ra.
.Pp
Reports that cannot be filed, due to an invalid
.Dq Index:
line or
some other error, are placed in the directory
.Pa ~bugs/errors .
The
.Nm bugfiler
maintainer should correct these bug reports and then
run
.Nm bugfiler ,
with the corrected report as its standard input,
as bug reports with errors are neither acknowledged or redistributed.
All reports that
.Nm bugfiler
handles are logged in
.Pa ~bugs/log.
.Pp
Valid bugs are also logged in the file
.Pa ~bugs/version/summary.
This file has an entry for each bug report for
.Ar version
in the
format:
.Pp
.Bd -literal -offset indent -compact
Filename	Date
     Subject:
     Index:
     Owner:	Bugs Bunny
     Status:	Received
.Ed
.Pp
.Li Filename
is the concatenation of
.Ar version ,
.Em folder ,
and a number
as described above.
.Xr Date
is the date as reported by the system
clock, using
.Xr ctime 3 .
The
.Li Subject:
and
.Li Index:
lines are
copies of the
.Dq Subject:
and
.Dq index:
lines contained in the bug
report.  The
.Li Owner
and
.Li Status
fields are intended to provide a
rudimentary method of tracking the status of bug reports.
.Pp
The file
.Pa ~bugs/bug:lock
is the focus of all locking for
.Nm bugfiler .
If you wish to manipulate any of the log or error files, rename or remove
it and
.Nm bugfiler
will treat all bug reports that it receives as if
they were incorrectly formatted, i.e. it will place them in the directory
.Pa ~bugs/errors ,
for later recovery by the
.Nm bugfiler
maintainer.
Obviously, this file must be created when you first install
.Nm bugfiler .
.Pp
All errors that occur before
.Pa ~bugs/log
is found are logged into the system
log file, using
.Xr syslog 8 .
.Sh FILES
.Bl -tag -width /usr/share/misc/bugformatxx -compact
.It Pa ~bugs/bug:ack
the acknowledgement message
.It Pa ~bugs/bug:redist
the redistribution list
.It Pa ~bugs/bug:lock
the locking file
.It Pa ~bugs/errors/BUG_??????
bug reports with format errors
.It Pa ~bugs/log
the log file
.It Pa ~bugs/folder/summary
the summary files
.It Pa /usr/sbin/sendmail
the mail delivery program
.It Pa /usr/share/misc/bugformat
a sample bug report format
.El
.Sh SEE ALSO
.Xr sendbug 1 ,
.Xr aliases 5 ,
.Xr syslog 8
.Sh BUGS
Since mail can be forwarded in a number of different ways,
.Nm bugfiler
does not recognize forwarded mail and will acknowledge to the forwarder
instead of the original sender unless there is a
.Dq Reply-To
field in the
header.
.Pp
This version of
.Nm bugfiler
is not compatible with the version
released with
.Bx 4.3
in that it doesn't complain to the sender about
incorrectly formatted bug reports.
Frankly, we got tired of the profanity, not to mention the extended
conversations
.Nm bugfiler
was holding with
.Xr vacation 1 .
.Sh HISTORY
The
.Nm
command appeared in
.Bx 4.2 .