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