--- /dev/null
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 39. Reporting Bugs</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"><link rel="start" href="index.html" title="The Official Samba-3 HOWTO and Reference Guide"><link rel="up" href="troubleshooting.html" title="Part V. Troubleshooting"><link rel="prev" href="problems.html" title="Chapter 38. Analyzing and Solving Samba Problems"><link rel="next" href="Appendix.html" title="Part VI. Reference Section"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 39. Reporting Bugs</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="problems.html">Prev</a> </td><th width="60%" align="center">Part V. Troubleshooting</th><td width="20%" align="right"> <a accesskey="n" href="Appendix.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="bugreport"></a>Chapter 39. Reporting Bugs</h2></div><div><div class="author"><h3 class="author"><span class="firstname">John</span> <span class="othername">H.</span> <span class="surname">Terpstra</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><code class="email"><<a href="mailto:jht@samba.org">jht@samba.org</a>></code></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Jelmer</span> <span class="othername">R.</span> <span class="surname">Vernooij</span></h3><div class="affiliation"><span class="orgname">The Samba Team<br></span><div class="address"><p><code class="email"><<a href="mailto:jelmer@samba.org">jelmer@samba.org</a>></code></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Andrew</span> <span class="surname">Tridgell</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><code class="email"><<a href="mailto:tridge@samba.org">tridge@samba.org</a>></code></p></div></div></div></div><div><p class="pubdate"> 27 June 1997 </p></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="bugreport.html#id2652358">Introduction</a></span></dt><dt><span class="sect1"><a href="bugreport.html#id2652448">General Information</a></span></dt><dt><span class="sect1"><a href="bugreport.html#dbglvl">Debug Levels</a></span></dt><dd><dl><dt><span class="sect2"><a href="bugreport.html#id2652667">Debugging-Specific Operations</a></span></dt></dl></dd><dt><span class="sect1"><a href="bugreport.html#id2652873">Internal Errors</a></span></dt><dt><span class="sect1"><a href="bugreport.html#id2653006">Attaching to a Running Process</a></span></dt><dt><span class="sect1"><a href="bugreport.html#id2653131">Patches</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2652358"></a>Introduction</h2></div></div></div><p>
+<a class="indexterm" name="id2652366"></a>
+<a class="indexterm" name="id2652373"></a>
+Please report bugs using Samba's <a href="https://bugzilla.samba.org/" target="_top">Bugzilla</a> facilities and take
+the time to read this file before you submit a bug report. Also, check to see if it has changed between
+releases, as we may be changing the bug reporting mechanism at some point.
+</p><p>
+Please do as much as you can yourself to help track down the
+bug. Samba is maintained by a dedicated group of people who volunteer
+their time, skills, and efforts. We receive far more mail than
+we can possibly answer, so you have a much higher chance of a response
+and a fix if you send us a “<span class="quote">developer-friendly</span>” bug report that lets
+us fix it fast.
+</p><p>
+<a class="indexterm" name="id2652406"></a>
+<a class="indexterm" name="id2652412"></a>
+<a class="indexterm" name="id2652419"></a>
+If you post the bug to the comp.protocols.smb
+newsgroup or the mailing list, do not assume that we will read it. If you suspect that your
+problem is not a bug but a configuration problem, it is better to send
+it to the Samba mailing list, as there are thousands of other users on
+that list who may be able to help you.
+</p><p>
+You may also like to look though the recent mailing list archives,
+which are conveniently accessible on the Samba Web pages
+at <a href="http://samba.org/samba/" target="_top">http://samba.org/samba/</a>.
+</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2652448"></a>General Information</h2></div></div></div><p>
+Before submitting a bug report, check your config for silly
+errors. Look in your log files for obvious messages that tell
+you've misconfigured something. Run testparm to check your config
+file for correct syntax.
+</p><p>
+Have you looked through <a href="diagnosis.html" title="Chapter 37. The Samba Checklist">The Samba Checklist</a>? This is extremely important.
+</p><p>
+If you include part of a log file with your bug report, then be sure to
+annotate it with exactly what you were doing on the client at the
+time and exactly what the results were.
+</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dbglvl"></a>Debug Levels</h2></div></div></div><p>
+If the bug has anything to do with Samba behaving incorrectly as a
+server (like refusing to open a file), then the log files will probably
+be quite useful. Depending on the problem, a log level of between 3 and
+10 showing the problem may be appropriate. A higher level gives more
+detail but may use too much disk space.
+</p><p>
+<a class="indexterm" name="id2652499"></a>
+<a class="indexterm" name="id2652506"></a>
+To set the debug level, use the <a class="indexterm" name="id2652513"></a>log level in your
+<code class="filename">smb.conf</code>. You may also find it useful to set the log
+level higher for just one machine and keep separate logs for each machine.
+To do this, add the following lines to your main <code class="filename">smb.conf</code> file:
+</p><table class="simplelist" border="0" summary="Simple list"><tr><td><a class="indexterm" name="id2652542"></a><em class="parameter"><code>log level = 10</code></em></td></tr><tr><td><a class="indexterm" name="id2652554"></a><em class="parameter"><code>log file = /usr/local/samba/lib/log.%m</code></em></td></tr><tr><td><a class="indexterm" name="id2652567"></a><em class="parameter"><code>include = /usr/local/samba/lib/smb.conf.%m</code></em></td></tr></table><p>
+and create a file <code class="filename">/usr/local/samba/lib/smb.conf.<em class="replaceable"><code>machine</code></em></code> where
+<em class="replaceable"><code>machine</code></em> is the name of the client you wish to debug. In that file put any
+<code class="filename">smb.conf</code> commands you want; for example, <a class="indexterm" name="id2652603"></a>log level may be useful. This also allows
+you to experiment with different security systems, protocol levels, and so on, on just one machine.
+</p><p>
+The <code class="filename">smb.conf</code> entry <a class="indexterm" name="id2652622"></a>log level is synonymous with the parameter <a class="indexterm" name="id2652629"></a>debuglevel that has been used in older versions of Samba and is being retained for backward
+compatibility of <code class="filename">smb.conf</code> files.
+</p><p>
+As the <a class="indexterm" name="id2652648"></a>log level value is increased, you will record a significantly greater level of
+debugging information. For most debugging operations, you may not need a setting higher than
+<code class="constant">3</code>. Nearly all bugs can be tracked at a setting of <code class="constant">10</code>, but be
+prepared for a large volume of log data.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2652667"></a>Debugging-Specific Operations</h3></div></div></div><p>
+<a class="indexterm" name="id2652675"></a>
+<a class="indexterm" name="id2652682"></a>
+<a class="indexterm" name="id2652688"></a>
+<a class="indexterm" name="id2652696"></a>
+ Samba-3.x permits debugging (logging) of specific functional components without unnecessarily
+ cluttering the log files with detailed logs for all operations. An example configuration to
+ achieve this is shown in:
+ </p><p>
+</p><table class="simplelist" border="0" summary="Simple list"><tr><td><a class="indexterm" name="id2652715"></a><em class="parameter"><code>log level = 0 tdb:3 passdb:5 auth:4 vfs:2</code></em></td></tr><tr><td><a class="indexterm" name="id2652728"></a><em class="parameter"><code>max log size = 0</code></em></td></tr><tr><td><a class="indexterm" name="id2652741"></a><em class="parameter"><code>log file = /var/log/samba/%U.%m.log</code></em></td></tr></table><p>
+</p><p>
+ This will cause the level of detail to be expanded to the debug class (log level) passed to
+ each functional area per the value shown above. The first value passed to the <em class="parameter"><code>log level</code></em>
+ of <code class="constant">0</code> means turn off all unnecessary debugging except the debug classes set for
+ the functional areas as specified. The table shown in <a href="bugreport.html#dbgclass" title="Table 39.1. Debuggable Functions">Debuggable Functions</a>
+ may be used to attain very precise analysis of each SMB operation Samba is conducting.
+ </p><div class="table"><a name="dbgclass"></a><p class="title"><b>Table 39.1. Debuggable Functions</b></p><table summary="Debuggable Functions" border="1"><colgroup><col><col></colgroup><thead><tr><th align="center">Function Name</th><th align="center">Function Name</th></tr></thead><tbody><tr><td align="center">all</td><td align="center">passdb</td></tr><tr><td align="center">tdb</td><td align="center">sam</td></tr><tr><td align="center">printdrivers</td><td align="center">auth</td></tr><tr><td align="center">lanman</td><td align="center">winbind</td></tr><tr><td align="center">smb</td><td align="center">vfs</td></tr><tr><td align="center">rpc_parse</td><td align="center">idmap</td></tr><tr><td align="center">rpc_srv</td><td align="center">quota</td></tr><tr><td align="center">rpc_cli</td><td align="center">acls</td></tr></tbody></table></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2652873"></a>Internal Errors</h2></div></div></div><p>
+If you get the message “<span class="quote"><span class="errorname">INTERNAL ERROR</span></span>” in your log files,
+it means that Samba got an unexpected signal while running. It is probably a
+segmentation fault and almost certainly means a bug in Samba (unless
+you have faulty hardware or system software).
+</p><p>
+If the message came from smbd, it will probably be accompanied by
+a message that details the last SMB message received by smbd. This
+information is often useful in tracking down the problem, so please
+include it in your bug report.
+</p><p>
+You should also detail how to reproduce the problem, if
+possible. Please make this reasonably detailed.
+</p><p>
+<a class="indexterm" name="id2652905"></a>
+You may also find that a core file appeared in a <code class="filename">corefiles</code>
+subdirectory of the directory where you keep your Samba log
+files. This file is the most useful tool for tracking down the bug. To
+use it, you do this:
+<a class="indexterm" name="id2652921"></a>
+<a class="indexterm" name="id2652928"></a>
+</p><pre class="screen">
+<code class="prompt">$ </code><strong class="userinput"><code>gdb smbd core</code></strong>
+</pre><p>
+</p><p>
+<a class="indexterm" name="id2652954"></a>
+<a class="indexterm" name="id2652960"></a>
+adding appropriate paths to smbd and core so gdb can find them. If you
+do not have gdb, try <strong class="userinput"><code>dbx</code></strong>. Then within the debugger,
+use the command <span><strong class="command">where</strong></span> to give a stack trace of where the
+problem occurred. Include this in your report.
+</p><p>
+<a class="indexterm" name="id2652985"></a>
+If you know any assembly language, do a <span><strong class="command">disass</strong></span> of the routine
+where the problem occurred (if it's in a library routine, then
+disassemble the routine that called it) and try to work out exactly
+where the problem is by looking at the surrounding code. Even if you
+do not know assembly, including this information in the bug report can be
+useful.
+</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2653006"></a>Attaching to a Running Process</h2></div></div></div><p>
+<a class="indexterm" name="id2653014"></a>
+<a class="indexterm" name="id2653021"></a>
+<a class="indexterm" name="id2653027"></a>
+Unfortunately, some UNIXes (in particular some recent Linux kernels)
+refuse to dump a core file if the task has changed UID (which smbd
+does often). To debug with this sort of system, you could try to attach
+to the running process using
+<strong class="userinput"><code>gdb smbd <em class="replaceable"><code>PID</code></em></code></strong>, where you get
+<em class="replaceable"><code>PID</code></em> from <span class="application">smbstatus</span>.
+Then use <span><strong class="command">c</strong></span> to continue and try to cause the core dump
+using the client. The debugger should catch the fault and tell you
+where it occurred.
+</p><p>
+Sometimes it is necessary to build Samba binary files that have debugging
+symbols so as to make it possible to capture enough information from a crashed
+operation to permit the Samba Team to fix the problem.
+</p><p>
+Compile with <code class="constant">-g</code> to ensure you have symbols in place.
+Add the following line to the <code class="filename">smb.conf</code> file global section:
+</p><pre class="screen">
+panic action = "/bin/sleep 90000"
+</pre><p>
+to catch any panics. If <span><strong class="command">smbd</strong></span> seems to be frozen, look for any sleep
+processes. If it is not, and appears to be spinning, find the PID
+of the spinning process and type:
+</p><pre class="screen">
+<code class="prompt">root# </code> gdb /usr/local/samba/sbin/smbd
+</pre><p>
+<a class="indexterm" name="id2653112"></a>
+then “<span class="quote">attach `pid'</span>” (of the spinning process), then type “<span class="quote">bt</span>” to
+get a backtrace to see where the smbd is in the call path.
+</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2653131"></a>Patches</h2></div></div></div><p>
+<a class="indexterm" name="id2653138"></a>
+<a class="indexterm" name="id2653145"></a>
+The best sort of bug report is one that includes a fix! If you send us
+patches, please use <strong class="userinput"><code>diff -u</code></strong> format if your version of
+diff supports it; otherwise, use <strong class="userinput"><code>diff -c4</code></strong>. Make sure
+you do the diff against a clean version of the source and let me know
+exactly what version you used.
+</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="problems.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="troubleshooting.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Appendix.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 38. Analyzing and Solving Samba Problems </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Part VI. Reference Section</td></tr></table></div></body></html>
projects / samba / blobdiff