How to report a Problem
Released versions problem reports
Before reporting bugs/problems with released versions,
go through this checklist:
- First check for patches and notes regarding the
- Next find out if there is a newer release
- The last thing to check is for changes made between
If nothing looks like it addresses your problem, then please become acquainted
before submitting a bug report.
Read further down for the types of bug reports desired.
Current version problem reports
If your problem is with the current source tree rather than a release or
- Test the problem at least twice, with source updated a few days apart.
- 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 make build at least once per day, and usually several times
per day with different architectures.
- Remember that the anoncvs
servers are updated significantly behind the actual working source tree.
- Check for changes made between OpenBSD versions
to see if the problem has been addressed.
- Much care is made in creating snapshots. Sometimes mistakes are made,
and our apologies are extended. Reading/writing the e-mail lists
is more appropriate than sending in a bug report.
How to create a problem report
Always provide as much information as possible.
Try to pin-point the exact problem.
Give clear instructions on how to reproduce the problem.
Try to describe the problem with as much accuracy and
non-confusing terminology as possible,
especially if it is not easy to reproduce.
Describing problems like "it crashes" or "I get strange interrupt
issues on this one box that I built", are of no use.
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 broken/unsupported hardware,
or by using unsupported build options or software.
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, check various
forums to make sure that someone else is not working on the problem
(saving duplication of effort).
The following items should be contained in every bug report:
- 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
- The output you got. Please do not 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.
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 /var/log. 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 (in the case of httpd, this
- 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 /var/run/dmesg.boot. If this is the
case, include information from both. Please include this
in all bug reports.
- If you run third-party software which has to do with your bug, say so,
including any subversion that software may have. If you are talking about
a CVS or FTP snapshot, mention that, including its date and time.
- A traceback from your kernel panic. If your kernel panic'ed, and you
are at a ddb>
prompt, then please provide the panic message, as well as the output of
the trace and ps commands in your bug report as
advised. If the machine hangs, try enabling sysctl ddb.console=1
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 show panic command.
This is essential whenever possible. Panic reports without panic message,
traceback and ps output are useless.
The output of show registers might be of interest as well.
You might then want to reboot with boot dump so that a kernel
image could be saved by savecore(8)
for further post-mortem debugging as described in the
- If you're reporting a problem with the X Window System on an
architecture that uses the X.Org server, please include the full
/var/log/Xorg.0.log file in your report in addition
to the dmesg.boot information.
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
Sending in bug reports
If possible, use the sendbug(1) command to get the bug into our tracking system.
Sendbug requires that your system can properly send Internet email. If you
cannot use sendbug on a functional OpenBSD machine, please send your bug report
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.
If someone else writes code for your new feature, the chances are that
it will be misunderstood and created so that you will not recognize it.
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 donate some hardware.
Types of bug reports in order of desirability:
- Repeatable problems with source fixes are the best.
- Repeatable problems that are not specific to your hardware/software
- Repeatable problems specific to your software layout.
- Repeatable problems specific to your hardware layout.
- Non-repeatable problems -- or problems you do not wish to repeat.