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