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