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