Annotation of www/report.html, Revision 1.40
1.18 jufi 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1.4 deraadt 2: <html>
3: <head>
4: <title>OpenBSD problem reports</title>
1.18 jufi 5: <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
1.4 deraadt 6: <meta name="description" content="OpenBSD problem report page">
1.40 ! tj 7: <meta name="copyright" content="This document copyright 1998-2016 by OpenBSD.">
1.37 sthen 8: <link rel="canonical" href="http://www.openbsd.org/report.html">
1.4 deraadt 9: </head>
10:
11: <body bgcolor="#ffffff" text="#000000" link="#23238e">
1.17 jsyn 12: <a href="index.html"><img alt="[OpenBSD]" height="30" width="141" src="images/smalltitle.gif" border="0"></a>
1.5 deraadt 13: <p>
1.18 jufi 14: <h2><font color="#e00000">How to report a Problem</font></h2>
15: <hr>
1.5 deraadt 16:
1.18 jufi 17: <h3><font color="#0000e0">Released versions problem reports</font></h3>
1.4 deraadt 18:
1.40 ! tj 19: Before reporting bugs/problems with released versions, go through this
! 20: checklist:
! 21:
1.4 deraadt 22: <ol>
1.40 ! tj 23: <li>First, check for <a href="errata.html">patches and notes regarding the
! 24: release</a>.
! 25: <li>Next, find out if there is a <a href="orders.html">newer release</a>
! 26: available.
! 27: <li>Finally, check for <a href="plus.html">changes made between OpenBSD
! 28: versions</a>.
1.4 deraadt 29: </ol>
1.40 ! tj 30:
1.4 deraadt 31: <p>
1.9 chris 32: If nothing looks like it addresses your problem, then please become acquainted
1.40 ! tj 33: with <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=sendbug">
! 34: sendbug(1)</a> before submitting a bug report.
1.4 deraadt 35:
1.18 jufi 36: <h3><font color="#0000e0">Current version problem reports</font></h3>
1.9 chris 37:
1.40 ! tj 38: If your problem is with the <i>-current</i> source tree rather than
! 39: <i>-release</i> or <i>-stable</i>,
1.5 deraadt 40:
1.4 deraadt 41: <ol>
1.40 ! tj 42: <li>Test the problem at least twice, with source updated a few days apart.
! 43: <li>Do not report source tree compilation problems, unless they persist.
! 44: They are almost always your mistake, or they are being worked on as you
! 45: encounter them.
! 46: People working on the project are doing <a href="faq/faq5.html">
! 47: make build</a> at least once per day, and usually several times
! 48: per day with different architectures.
! 49: <li>Remember that the <a href="anoncvs.html">AnonCVS</a> servers are
! 50: updated a few hours behind the actual working source tree.
! 51: <li>Check for <a href="plus.html">changes made between OpenBSD versions</a>
! 52: to see if the problem has been addressed.
! 53: <li>Much care is made in creating snapshots.
! 54: Sometimes mistakes are made, and our apologies are extended.
! 55: Reading or writing to the mailing lists is more appropriate than sending
! 56: in a bug report.
1.4 deraadt 57: </ol>
1.5 deraadt 58:
1.18 jufi 59: <h3><font color="#0000e0">How to create a problem report</font></h3>
1.8 chris 60:
61: <b>Always provide as much information as possible</b>.
1.40 ! tj 62: Try to pinpoint the exact problem.
1.34 lum 63: Give clear instructions on how to reproduce the problem.
1.40 ! tj 64: Try to describe it with as much accuracy and non-confusing terminology
! 65: as possible, especially if it is not easy to reproduce.
! 66: Describing problems by saying "it crashes" or "I get strange interrupt issues
! 67: on this one box that I built" are of no use.
! 68: Communicate with others (on the mailing lists or any other forum where
! 69: knowledgeable users congregate) to confirm that the problem is new and
! 70: preferably repeatable.
! 71: Please try to make sure it is not a local problem created by using broken
! 72: or unsupported hardware, or by using unsupported build options or software.
! 73:
! 74: <p>
! 75: Please don't start fixing problems that require significant work until you
! 76: are sure you understand them, especially during our release periods when we
! 77: must not change major sections of code.
! 78: If you are going to write significant amounts of code, mention it on the
! 79: mailing lists to make sure no one else is already working on the problem
1.9 chris 80: (saving duplication of effort).
1.40 ! tj 81:
1.25 david 82: <p>
1.8 chris 83: The following items should be contained in every bug report:
1.40 ! tj 84:
1.8 chris 85: <ol>
1.40 ! tj 86: <li>The exact sequence of steps from startup necessary to reproduce
! 87: the problem.
! 88: This should be self-contained; it is not enough to send in a bare
! 89: command without the arguments and other data you supplied to it.
1.8 chris 90: If a bug requires a particular sequence of events, please list those.
91: You are encouraged to minimize the size of your example, but this is
1.40 ! tj 92: not absolutely necessary.
! 93: If the bug is reproducible, we'll find it either way.
1.8 chris 94: <p>
1.40 ! tj 95: <li>The output you got.
! 96: Please do not just say that it "didn't work" or "failed."
! 97: If there is an error message, show it, even if you don't understand it.
! 98: If OpenBSD panics with a particular error, say which.
! 99: If nothing at all happens, say so.
! 100: Even if the result of your test case is a program crash or otherwise
! 101: obvious, it might not happen in our testing.
! 102: The easiest thing is to copy the output from the terminal, if possible.
! 103: <p>
! 104: Note: In case of fatal errors, the error message provided might not
! 105: contain all the information available.
! 106: In that case, also look at the output in the system log files, such
! 107: as those stored in /var/log.
! 108: Also, if you are dealing with an application that has its own log files,
! 109: such as httpd, check for errors where it keeps its logs.
! 110: <p>
! 111: <li>The OpenBSD kernel output.
! 112: You can get this with the dmesg command, but it is possible that your
! 113: dmesg output does not contain all the information that is captured in
! 114: <tt>/var/run/dmesg.boot</tt>.
! 115: If this is the case, include information from both.
! 116: <b>Please include this in all bug reports.</b>
! 117: <p>
! 118: <li>If you run third party software which has to do with your bug, say so,
! 119: including what version.
! 120: If you are talking about a snapshot, mention that, including its date
! 121: and time.
! 122: <p>
! 123: <li>A traceback from your kernel panic.
! 124: If your kernel panicked and you are at a
! 125: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=ddb">ddb</a>
! 126: prompt, please provide the panic message, as well as the output of
! 127: the <tt>trace</tt> and <tt>ps</tt> commands in your bug report as
! 128: advised.
! 129: If the machine hangs, try enabling <tt>sysctl ddb.console=1</tt>
! 130: prior to the hang and getting in DDB via Ctl+Alt+Esc on the keyboard
! 131: (must be outside of X), or sending BREAK if using a serial console.
! 132: If, for some reason, the panic message is not visible, you can get it
! 133: again with the <tt>show panic</tt> command.
! 134: <b>This is essential whenever possible.
! 135: Panic reports without the panic message, traceback and ps output are
! 136: useless</b>.
! 137: The output of <tt>show registers</tt> might be of interest as well.
! 138: You might then want to reboot with <tt>boot dump</tt> so that a kernel
! 139: image could be saved by
! 140: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=savecore">
! 141: savecore(8)</a> for further post-mortem debugging, as described in the
! 142: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=crash">crash(8)</a>
! 143: man page.
1.20 matthieu 144: <p>
1.40 ! tj 145: <li>If you're reporting a problem with the X Window System on an
1.30 matthieu 146: architecture that uses the X.Org server, please include the full
147: <tt>/var/log/Xorg.0.log</tt> file in your report in addition
1.40 ! tj 148: to the <tt>dmesg.boot</tt> information.
! 149: </ol>
1.20 matthieu 150:
1.8 chris 151: <p>
1.40 ! tj 152: Do not be afraid if your bug report becomes rather lengthy.
! 153: That is a fact of life.
! 154: It's better to report everything the first time than us having to squeeze
! 155: the facts out of you.
! 156: On the other hand, if your input files are huge, it is fair to ask first
! 157: whether somebody is interested in looking into it.
1.8 chris 158:
1.10 jufi 159: <a name="bugtypes"></a>
1.18 jufi 160: <h3><font color="#0000e0">Sending in bug reports</font></h3>
1.40 ! tj 161:
! 162: If possible, use the
! 163: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=sendbug">sendbug(1)</a>
! 164: command to help generate your bug report.
! 165: It will automatically include some useful information about your hardware
! 166: that helps diagnose many issues.
! 167: This tool requires that your system can properly send email.
! 168: If you cannot use sendbug on a functional OpenBSD machine, please send your
! 169: bug report to <a href="mailto:bugs@openbsd.org">bugs@openbsd.org</a>.
! 170:
1.25 david 171: <p>
1.9 chris 172: Perhaps what you are sending in is a feature request, not necessarily a bug.
1.40 ! tj 173: New features are accepted, especially with code that implements your suggested
! 174: new feature.
1.1 deraadt 175:
1.4 deraadt 176: <p>
1.40 ! tj 177: For debugging some problems, we must have the hardware that has the problem.
! 178: Please remember that the OpenBSD project's resources are limited.
! 179: You could <a href="want.html">donate some hardware</a>.
1.1 deraadt 180:
1.4 deraadt 181: </body>
182: </html>
![[BACK]](/icons/back.gif){kind=icon}
Return to report.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / www