mirror of https://github.com/openbsd/www.git
188 lines
7.6 KiB
HTML
188 lines
7.6 KiB
HTML
<!doctype html>
|
|
<html lang=en>
|
|
<meta charset=utf-8>
|
|
|
|
<title>OpenBSD: Problem Reports</title>
|
|
<meta name="description" content="OpenBSD problem report page">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<link rel="stylesheet" type="text/css" href="openbsd.css">
|
|
<link rel="canonical" href="https://www.openbsd.org/report.html">
|
|
|
|
<style>
|
|
h3 {
|
|
color: var(--blue);
|
|
}
|
|
</style>
|
|
|
|
<h2 id=OpenBSD>
|
|
<a href="index.html">
|
|
<i>Open</i><b>BSD</b></a>
|
|
Problem Reports
|
|
</h2>
|
|
|
|
<hr>
|
|
|
|
<h3>Released versions problem reports</h3>
|
|
|
|
<p>
|
|
Before reporting bugs/problems with released versions, go through this
|
|
checklist:
|
|
|
|
<ol>
|
|
<li>First, check for <a href="errata.html">patches and notes regarding the
|
|
release</a>.
|
|
<li>Next, find out if there is a newer release available.
|
|
<li>Finally, check for <a href="plus.html">changes made between OpenBSD
|
|
versions</a>.
|
|
</ol>
|
|
|
|
<p>
|
|
If nothing looks like it addresses your problem, then please become acquainted
|
|
with <a href="https://man.openbsd.org/sendbug">sendbug(1)</a> before submitting
|
|
a bug report.
|
|
|
|
<h3>Current version problem reports</h3>
|
|
|
|
<p>
|
|
If your problem is with the -current source tree rather than
|
|
-release or -stable,
|
|
|
|
<ol>
|
|
<li>Test the problem at least twice, with source updated a few days apart.
|
|
<li>Do not report source tree compilation problems, unless they persist.
|
|
They are almost always your mistake, or they are being worked on as you
|
|
encounter them.
|
|
People working on the project are doing
|
|
<a href="faq/faq5.html">make build</a> at least once per day, and usually
|
|
several times per day with different architectures.
|
|
<li>Remember that the <a href="anoncvs.html">AnonCVS</a> servers are
|
|
updated a few hours behind the actual working source tree.
|
|
<li>Check for <a href="plus.html">changes made between OpenBSD versions</a>
|
|
to see if the problem has been addressed.
|
|
<li>Much care is made in creating snapshots.
|
|
Sometimes mistakes are made, and our apologies are extended.
|
|
Reading or writing to the mailing lists is more appropriate than sending
|
|
in a bug report.
|
|
</ol>
|
|
|
|
<h3>How to create a problem report</h3>
|
|
|
|
<p>
|
|
<strong>Always provide as much information as possible</strong>.
|
|
Try to pinpoint the exact problem.
|
|
Give clear instructions on how to reproduce the problem.
|
|
Try to describe it with as much accuracy and non-confusing terminology
|
|
as possible, especially if it is not easy to reproduce.
|
|
Describing problems by saying "it crashes" or "I get strange interrupt issues
|
|
on this one box that I built" is not helpful.
|
|
Communicate with others (on the mailing lists or any other forum where
|
|
knowledgeable users congregate) to confirm that the problem is new and
|
|
preferably repeatable.
|
|
Please try to make sure it is not a local problem created by using broken
|
|
or unsupported hardware, or by using unsupported build options or software.
|
|
|
|
<p>
|
|
Please don't start fixing problems that require significant work until you
|
|
are sure you understand them, especially during our release periods when we
|
|
must not change major sections of code.
|
|
If you are going to write significant amounts of code, mention it on the
|
|
mailing lists to make sure no one else is already working on the problem
|
|
(saving duplication of effort).
|
|
|
|
<p>
|
|
The following items should be contained in every bug report:
|
|
|
|
<ol>
|
|
<li>The exact sequence of steps from startup necessary to reproduce
|
|
the problem.
|
|
This should be self-contained; it is not enough to send in a bare
|
|
command without the arguments and other data you supplied to it.
|
|
If a bug requires a particular sequence of events, please list those.
|
|
You are encouraged to minimize the size of your example, but this is
|
|
not absolutely necessary.
|
|
If the bug is reproducible, we'll find it either way.
|
|
<p>
|
|
<li>The output you got.
|
|
Please do not just say that it "didn't work" or "failed."
|
|
If there is an error message, show it, even if you don't understand it.
|
|
If OpenBSD panics with a particular error, say which.
|
|
If nothing at all happens, say so.
|
|
Even if the result of your test case is a program crash or otherwise
|
|
obvious, it might not happen in our testing.
|
|
The easiest thing is to copy the output from the terminal, if possible.
|
|
<p>
|
|
Note: In case of fatal errors, the error message provided might not
|
|
contain all the information available.
|
|
In that case, also look at the output in the system log files, such
|
|
as those stored in <code>/var/log</code>.
|
|
Also, if you are dealing with an application that has its own log files,
|
|
such as httpd, check for errors where it keeps its logs.
|
|
<p>
|
|
<li>The OpenBSD kernel output.
|
|
You can get this with the dmesg command, but it is possible that your
|
|
dmesg output does not contain all the information that is captured in
|
|
<code>/var/run/dmesg.boot</code>.
|
|
If this is the case, include information from both.
|
|
<strong>Please include this in all bug reports.</strong>
|
|
<p>
|
|
<li>If you run third party software which has to do with your bug, say so,
|
|
including what version.
|
|
If you are talking about a snapshot, mention that, including its date
|
|
and time.
|
|
<p>
|
|
<li>A traceback from your kernel panic.
|
|
If your kernel panicked and you are at a
|
|
<a href="https://man.openbsd.org/ddb">ddb(4)</a>
|
|
prompt, please provide the panic message, as well as the output of
|
|
the <kbd>trace</kbd> and <kbd>ps</kbd> commands in your bug report as
|
|
advised.
|
|
If the machine hangs, try enabling <kbd>sysctl ddb.console=1</kbd>
|
|
prior to the hang and getting in DDB via Ctl+Alt+Esc on the keyboard
|
|
(must be outside of X), or sending BREAK if using a serial console.
|
|
If, for some reason, the panic message is not visible, you can get it
|
|
again with the <kbd>show panic</kbd> command.
|
|
<strong>This is essential whenever possible.
|
|
Panic reports without the panic message, traceback and ps output are
|
|
useless</strong>.
|
|
The output of <kbd>show registers</kbd> might be of interest as well.
|
|
You might then want to reboot with <kbd>boot dump</kbd> so that a kernel
|
|
image could be saved by
|
|
<a href="https://man.openbsd.org/savecore">savecore(8)</a> for further
|
|
post-mortem debugging, as described in the
|
|
<a href="https://man.openbsd.org/crash">crash(8)</a> man page.
|
|
<p>
|
|
<li>If you're reporting a problem with the X Window System on an
|
|
architecture that uses the X.Org server, please include the full
|
|
<code>/var/log/Xorg.0.log</code> file in your report in addition
|
|
to the <code>dmesg.boot</code> information.
|
|
</ol>
|
|
|
|
<p>
|
|
Do not be afraid if your bug report becomes rather lengthy.
|
|
That is a fact of life.
|
|
It's better to report everything the first time than us having to squeeze
|
|
the facts out of you.
|
|
On the other hand, if your input files are huge, it is fair to ask first
|
|
whether somebody is interested in looking into it.
|
|
|
|
<h3 id="bugtypes">Sending in bug reports</h3>
|
|
|
|
<p>
|
|
If possible, use the <a href="https://man.openbsd.org/sendbug">sendbug(1)</a>
|
|
command to help generate your bug report.
|
|
It will automatically include some useful information about your hardware
|
|
that helps diagnose many issues.
|
|
This tool requires that your system can properly send email.
|
|
If you cannot use sendbug on a functional OpenBSD machine, please send your
|
|
bug report to <a href="mailto:bugs@openbsd.org">bugs@openbsd.org</a>.
|
|
|
|
<p>
|
|
Perhaps what you are sending in is a feature request, not necessarily a bug.
|
|
New features are accepted, especially with code that implements your suggested
|
|
new feature.
|
|
|
|
<p>
|
|
For debugging some problems, we must have the hardware that has the problem.
|
|
Please remember that the OpenBSD project's resources are limited.
|
|
You could <a href="want.html">donate some hardware</a>.
|