You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

495 lines
17 KiB

.TH reportbug 1
.SH NAME
reportbug \- reports a bug to a debbugs server
.SH SYNOPSIS
.B reportbug
.I "[options] <package | pseudo-package | absolute-pathname>"
.SH DESCRIPTION
.B reportbug
is primarily designed to report bugs in the Debian distribution; by
default, it creates an email to the Debian bug tracking system at
.I submit@bugs.debian.org
with information about the bug you've found, and makes a carbon copy
of the report for you as well.
.PP
Using the
.B \-\-bts
option, you can also report bugs to other servers that use the Debian
bug tracking system, \fBdebbugs\fP.
.PP
You may specify either a package name or an absolute filename; if you
use a filename, it must begin with a \fB/\fP to be recognized. If you
want \fBreportbug\fP to search the system for a filename, see the
\fB\-\-file\fP option, below.
.PP
You can also specify a \fBpseudo-package\fP; these are used in the
Debian bug tracking system to track issues that are not related to one
specific package. Run \fBreportbug\fP without any arguments, then
enter \fBother\fP at the package prompt, to see a list of the most
commonly-used pseudo-packages.
.SH OPTIONS
The program follows the usual GNU command line syntax, with long
options starting with two dashes (`\-\-').
A summary of options are included below.
.TP
.B \-h, \-\-help
Show summary of options.
.TP
.B \-v, \-\-version
Show the version of
.B reportbug
and exit.
.TP
.B \-a, \-\-af
Instead of spawning an editor to revise the bug report, use the
.B af
mail reader to edit and send it.
.TP
.B \-A FILENAME, \-\-attach=FILENAME
Attach a file to the bug report; both text and binary files are
acceptable. This routine will create a MIME attachment with the file
included; in some cases (usually text files), it is probably better to
use \-\-include. (Please note that Debian's bug tracking system has
limited support for MIME attachments.)
.TP
.B \-b, \-\-no\-query\-bts
Don't check the Debian bug tracking system to see if this problem has
already been reported; useful for offline use or if you're
.B really
sure it's a bug.
.TP
.B \-\-query\-bts
Check the Debian bug tracking system to see if this problem has
already been reported (default).
.TP
.B \-B SYSTEM, \-\-bts=SYSTEM
Instead of the Debian bug server (or the bug server specified in
\fB/etc/reportbug.conf\fP, use the server specified by
.B SYSTEM.
You can specify
.B help
to get a list of supported servers.
.TP
.B \-\-body=BODY
Use the specified BODY as the body of the message. The body text will be
wrapped at 70 columns, and the normal reportbug headers and footers
will be added as appropriate. The editor prompt and any "special"
prompting will be bypassed.
.TP
.B \-\-body-file=BODYFILE
The contents of the (assumed to be) text file BODYFILE will be used as
the message body. This file is assumed to be properly formatted
(i.e. reasonable line lengths, etc.). The usual headers and footers
will be added, and the editor step and "special" prompts will be
skipped. (BODYFILE may also be a named pipe; using a device special
file may lead to unusual results.)
.TP
.B \-c, \-\-no\-config\-files
Omit configuration files from the bug report without asking. By
default, you are asked if you want to include them; in some cases,
doing so may cause sensitive information to be sent via email.
.TP
.B \-\-configure
Rerun the
.B reportbug
first time configuration routine, and write a new .reportbugrc file.
This will erase any pre-existing settings in the file; however, a
backup will be written as .reportbugrc~.
.TP
.B \-\-check\-available
Check for newer releases of the package at packages.debian.org (default).
.TP
.B \-\-no\-check\-available
Do not check for newer releases of the package at packages.debian.org.
.TP
.B \-d, \-\-debug
Don't send a real bug report to Debian; send it to yourself instead.
This is primarily used for testing by the maintainer.
.TP
.B \-e EDITOR, \-\-editor=EDITOR
Specify the editor to use, overriding any EDITOR or VISUAL environment
variable setting.
.TP
.B \-\-email=ADDRESS
Set the email address your report should appear to be sent from
(i.e. the address that appears in the \fBFrom:\fP header). This
should be the actual Internet email address on its own (i.e. without a
real name or comment part). This setting will override the EMAIL and
DEBEMAIL environment variables, but not REPORTBUGEMAIL.
.TP
.B \-\-exit\-prompt
Display a prompt before exiting; this is useful if reportbug is run in
a transient terminal (i.e. from its Debian menu entry).
.TP
.B \-f FILENAME, \-\-filename=FILENAME
Report a bug in the package containing
.I FILENAME
so you don't have to figure out what package the file belongs to. The
path will be searched for an exact path for FILENAME before attempting
to broaden the search to all files.
.TP
.B \-\-path
If the \-f option is also specified, only search the path for the
specified FILENAME. Specifying an absolute path with the \-f option
(i.e. one beginning with a /) overrides this behavior.
.TP
19 years ago
.B \-g, \-\-gnupg, \-\-gpg
Attach a digital signature to the bug report using
.B GnuPG
(the GNU Privacy Guard). (This argument will be ignored if you are
using an MUA to edit and send your report.)
.TP
.B \-G, \-\-gnus
Use the GNUS mail and news reader to send your report, rather than
using the editor.
.TP
.B \-H HEADER, \-\-header=HEADER
Add a custom RFC 2822 header to your email; for example, to send a
carbon copy of the report to
.I debian-68k@lists.linux-m68k.org
you could use
.I \-H 'X\-Debbugs\-CC: debian\-68k@lists.linux\-m68k.org'
.TP
.B \-i FILE, \-\-include=FILE
Include the specified file as part of the body of the message to be
edited. Can be used multiple times to add multiple files; text-only
please! From a suggestion by Michael Alan Dorman in the
.B bug
bug list. (See also the \-\-attach option.)
.TP
.B \-I, \-\-no\-check\-installed
Do not check whether the package is installed before filing a report.
This is generally only useful when filing a report on a package you
know is not installed on your system.
.TP
.B \-\-check\-installed
Check if the specified package is installed when filing reports. (This
is the default behavior of reportbug.)
.TP
19 years ago
.B \-j JUSTIFICATION, \-\-justification=JUSTIFICATION
Bugs in Debian that have "serious", "grave", or "critical" severities
must meet certain criteria to be classified as such. This option
allows you to specify the justification for a release-critical bug,
instead of being prompted for it.
.TP
.B \-k, \-\-kudos
Send appreciative email to the recorded maintainer address, rather
than filing a bug report. (You can also send kudos to
\fIpackagename\fP@packages.debian.org, for packages in the Debian
archive; however, this option uses the Maintainer address from the
control file, so it works with other package sources too.)
.TP
19 years ago
.B \-K KEYID, \-\-keyid=KEYID
Private key to use for PGP/GnuPG signatures. If not specified, the
first key in the secret keyring that matches your email address will
be used.
.TP
.B \-\-license
Show \fBreportbug\fP's copyright and license information on standard
output.
.TP
.B \-\-list\-cc=ADDRESS
Send a carbon copy of the report to the specified list after a report
number is assigned; this is the equivalent to the option
.I \-H 'X\-Debbugs\-CC: ADDRESS'.
This option will only work as intended with debbugs systems.
.TP
.B \-m, \-\-maintonly
Only send the bug to the package maintainer; the bug tracking system
will not send a copy to the bug report distribution lists.
.TP
.B \-\-mode=MODE
Set the operating mode for \fBreportbug\fP.
.B reportbug
currently has four operating modes: \fBnovice\fP (the
default), \fBstandard\fP, \fBadvanced\fP, and \fBexpert\fP.
.B novice
mode is designed to minimize prompting about things that "ordinary
users" would be unlikely to know or care about, shifting the triage
19 years ago
burden onto the maintainer. Checking for new versions is only done
for the stable distribution in this mode. It is currently the default
mode.
.B standard
mode is more-or-less equivalent to the prompting that was provided by
reportbug 1.50 and earlier; it includes a relatively large number of
prompts and tries to encourage users to not file frivolous or
duplicate bug reports.
.B advanced
mode is like \fBstandard\fP mode, but may include shortcuts suitable
for more advanced users of Debian, without being as close to the metal
(and potential flamage) as \fBexpert\fP mode. (Currently, the only
differences from \fBstandard\fP mode are that it assumes familiarity
with the "incoming" queue; it allows the reporting of bugs on
"dependency" packages; and it does not prompt where to insert the
report text in the editor.)
.B expert
mode is designed to minimize prompts that are designed to discourage
frivolous or unnecessary bug reports, "severity inflation," and the
like. In expert mode,
.B reportbug
assumes the user is thoroughly familiar with Debian policies. In
practice, this means that reporters are no longer required to justify
setting a high severity on a bug report, and certain automated
cleanups of the message are bypassed. Individuals who do not
regularly contribute to the Debian project are \fIhighly\fP
discouraged from using expert mode, as it can lead to flamage from
maintainers when used improperly.
.TP
.B \-M, \-\-mutt
Instead of spawning an editor to revise the bug report, use the
.B mutt
mail reader to edit and send it.
.TP
.B \-\-mta='<MTA>'
Specify an alternate MTA, instead of
.B /usr/sbin/sendmail
(the default). Any
.B smtphost
setting will override this one.
.TP
.B \-\-mua='<MUA> <option>'
Instead of spawning an editor to revise the bug report, use the
specified MUA (mail user agent) to edit and send it. The
.B option
should be used to tell your mail reader to interpret the report as a
draft message. For examples of how this works, see how the
.B --mutt, --nmh
and
.B --af
options are processed.
.TP
.B \-n, \-\-nmh, \-\-mh
Instead of spawning an editor to revise the bug report, use the
.B comp
command (part of the
.B nmh
and
.B mh
mail systems) to edit and send it.
.TP
.B \-o FILE, \-\-output=FILE
Instead of sending an email, redirect it to the specified filename.
.TP
.B \-O, \-\-offline
Disable all external queries. Currently has the same effect as
\fB\-\-no\-check\-available \-\-no\-query\-bts\fP.
.TP
.B \-p, \-\-print
Instead of sending an email, print the bug report to standard output,
so you can redirect it to a file or pipe it to another program.
This option only outputs a template for a bug report; you will need to
fill in the long description.
.TP
.B \-\-paranoid
Show the contents of the message before it is sent, including all
headers. Automatically disabled if in template mode.
.TP
.B \-\-no\-paranoid
Don't show the full contents of the message before it is sent (default).
.TP
.B \-\-pgp
Attach a digital signature to the bug report using
.B PGP
(Pretty Good Privacy). Please note, however, that the Debian project
is phasing out the use of PGP in favor of GnuPG. (This argument will
be ignored if using an MUA to edit and send your report.)
.TP
.B \-\-proxy=PROXY, \-\-http_proxy=PROXY
Specify the WWW proxy server to use to handle the query of the bug
tracking system. You should only need this parameter if you are
behind a firewall. The PROXY argument should be formatted as a valid
HTTP URL, including (if necessary) a port number; for example,
\fBhttp://192.168.1.1:3128/\fP.
.TP
.B \-q, \-\-quiet
Suppress diagnostic messages to standard error.
.TP
.B \-Q, \-\-query\-only
Do not submit a bug report; just query the BTS. Option ignored if you
specify \-\-no\-bts\-query.
.TP
.B \-\-query\-source
Query on all binary packages built by the same source, not just the
binary package specified. (Default behavior as of reportbug 2.0)
.TP
.B \-\-no\-query\-source
Only query on the binary package specified on the command line.
.TP
.B \-\-realname=NAME
Set the real name (human-readable name) to use for your report.
.TP
.B \-\-report\-quiet
Register the bug in the bug tracking system, but don't send a report
to the package maintainer or anyone else. Don't do this unless you're
the maintainer of the package in question, or you really know what you
are doing.
.TP
.B \-\-reply-to=ADDRESS, \-\-replyto=ADDRESS
Set the
.B Reply-To
address header in your report.
.TP
.B \-s SUBJECT, \-\-subject=SUBJECT
Set the subject of the bug report (i.e. a brief explanation of the
problem, less than 60 characters). If you do not specify this switch,
you will be prompted for a subject.
.TP
.B \-S SEVERITY, \-\-severity=SEVERITY
Specify a severity level, from critical, grave, serious, important,
normal, minor, and wishlist.
.TP
.B \-\-smtphost=HOST[:PORT]
Use the mail transport agent (MTA) at
.B HOST
to send your report, instead of your local
.B /usr/sbin/sendmail
program. This should generally be your ISP's outgoing mail server;
you can also use 'localhost' if you have a working mail server running
on your machine. If the
.B PORT
is omitted, the standard port for SMTP, port 25, is used.
.TP
.B \-\-tls
If using SMTP, use Transport Layer Security (TLS) encryption to secure
the connection to the mail server. Some SMTP servers may require this
option.
.TP
.B \-\-smtpuser=USERNAME
If using SMTP, use the specified
.B USERNAME
for authentication.
.TP
.B \-\-smtppasswd=PASSWORD
If using SMTP, use the specified
.B PASSWORD
for authentication. If the password isn't specified on the command
line or in the configuration file, a prompt will be displayed asking
for it.
Use of this option is insecure on multiuser systems. Instead, you
should set this option in .reportbugrc and ensure it is only readable
by your user (e.g. with chmod 600 $HOME/.reportbugrc).
.TP
.B \-t TYPE, \-\-type=TYPE
Specify the type of report to be submitted; currently accepts either
gnats or debbugs.
.TP
.B \-T TAG, \-\-tag=TAG
Specify a tag to be filed on this report, for example \fB\-\-tag=patch\fP.
Multiple tags can be specified using multiple \-T or \-\-tag
arguments.
Alternatively, you can specify the 'tag'
.B none
to bypass the tags prompt without specifying any tags; this will also
ignore any tags specified on the command line.
.TP
.B \-\-template
Output a template report to standard output.
.TP
.B \-v, \-\-verify
Verify the integrity of the package (if installed) using debsums
before reporting.
.TP
.B \-V VERSION, \-\-package\-version=VERSION
Specify the version of the package the problem was found in. This is
probably most useful if you are reporting a bug in a package that is
not installable or installed on a different system.
.TP
.B \-x, \-\-no\-cc
Don't send a blind carbon copy (BCC) of the bug report to the
submitter (i.e. yourself).
.TP
.B \-z, \-\-no\-compress
Don't compress configuration files by removing comments and blank
lines.
.SH EXAMPLES
.TP
.B reportbug lynx-ssl
Report a bug in the lynx-ssl package.
.TP
.B reportbug \-\-path \-\-file=ls
Report a bug in the installed package that includes a program in your
path called \fBls\fP.
.SH CONFIGURATION FILES
From version 0.22 on,
.B reportbug
has supported a simple run control file syntax. Commands are read from
.B /etc/reportbug.conf
and
.B $HOME/.reportbugrc
with commands in the latter overriding those in the former. Commands
are not case sensitive, and currently take 0 or 1 arguments; arguments
containing whitespace must be enclosed in quotes. Any line starting
with # is taken to be a comment and will be ignored.
Generally, options corresponding to the GNU long options for
.B reportbug
are supported, without leading \-\- sequences. See the default
.B /etc/reportbug.conf
for all acceptable options.
.SH ENVIRONMENT
.TP
.B VISUAL
Editor to use for editing your bug report.
.TP
.B EDITOR
Editor to use for editing the bug report (overridden by VISUAL).
.TP
.B EMAIL, REPORTBUGEMAIL, DEBEMAIL
Email address to use as your from address; default is taken from your
user name and /etc/mailname.
.TP
.B DEBFULLNAME, DEBNAME, NAME
Real name to use; default is taken from /etc/passwd.
.TP
.B REPLYTO
Address for Reply-To header in outgoing mail.
.TP
.B MAILCC
Use the specified CC address on your email. Note you can also use the
.B -H
option for this (and for Bcc's too).
.TP
.B MAILBCC
Use the specified BCC address, instead of your email address. (CC and
BCC based on suggestions from Herbert Thielen in the
.B bug
wishlist).
.TP
.B http_proxy
Provides the address of a proxy server to handle the BTS query. This
should be a valid
.B http
URL for a proxy server, including any required port number (simply
specifying a hostname, or omitting a port other than 80, WILL NOT WORK).
.SH NOTES
Python's getopt module is pickier than GNU getopt() about the order of
command line arguments; all switches must be specified before the
package name.
.B reportbug
should probably be compatible with other bug tracking systems, like
.B bugzilla
(used by the GNOME and Mozilla projects) and
.B jitterbug
(used by Samba, AbiSource and FreeCiv) but it isn't.
.SH "SEE ALSO"
http://www.debian.org/Bugs/Developer#tags for available tags, querybts(1)
.SH AUTHOR
Chris Lawrence <lawrencc@debian.org>.
\" LocalWords: reportbug debbugs pathname Debian bts fBdebbugs fP filename fB
\" LocalWords: af Debian's BODYFILE config reportbugrc pre DEBEMAIL gnupg gpg
\" LocalWords: REPORTBUGEMAIL GnuPG MUA debian Dorman severities KEYID keyid
\" LocalWords: PGP maintonly mta MTA smtphost mua nmh mh pgp http realname
\" LocalWords: replyto wishlist ISP's localhost SMTP tls smtpuser USERNAME
\" LocalWords: smtppasswd multiuser chmod debsums uninstallable BCC ssl Bcc's
\" LocalWords: whitespace DEBFULLNAME DEBNAME MAILCC MAILBCC Thielen hostname
\" LocalWords: getopt bugzilla Mozilla AbiSource FreeCiv querybts