1<?xml version="1.0" encoding="iso-8859-1"?> 2<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> 3<chapter id="bugreport"> 4 5<chapterinfo> 6 &author.jht; 7 &author.jelmer; 8 &author.tridge; 9 <pubdate> 27 June 1997 </pubdate> 10</chapterinfo> 11 12<title>Reporting Bugs</title> 13 14<sect1> 15<title>Introduction</title> 16 17<para> 18<indexterm><primary>Bugzilla</primary></indexterm> 19<indexterm><primary>bug reports</primary></indexterm> 20Please report bugs using Samba's <ulink url="https://bugzilla.samba.org/">Bugzilla</ulink> facilities and take 21the time to read this file before you submit a bug report. Also, check to see if it has changed between 22releases, as we may be changing the bug reporting mechanism at some point. 23</para> 24 25<para> 26Please do as much as you can yourself to help track down the 27bug. Samba is maintained by a dedicated group of people who volunteer 28their time, skills, and efforts. We receive far more mail than 29we can possibly answer, so you have a much higher chance of a response 30and a fix if you send us a <quote>developer-friendly</quote> bug report that lets 31us fix it fast. 32</para> 33 34<para> 35<indexterm><primary>comp.protocols.smb</primary></indexterm> 36<indexterm><primary>newsgroup</primary></indexterm> 37<indexterm><primary>configuration problem</primary></indexterm> 38If you post the bug to the comp.protocols.smb 39newsgroup or the mailing list, do not assume that we will read it. If you suspect that your 40problem is not a bug but a configuration problem, it is better to send 41it to the Samba mailing list, as there are thousands of other users on 42that list who may be able to help you. 43</para> 44 45<para> 46You may also like to look though the recent mailing list archives, 47which are conveniently accessible on the Samba Web pages 48at <ulink noescape="1" url="http://samba.org/samba/">http://samba.org/samba/</ulink>. 49</para> 50 51</sect1> 52 53<sect1> 54<title>General Information</title> 55 56<para> 57Before submitting a bug report, check your config for silly 58errors. Look in your log files for obvious messages that tell 59you've misconfigured something. Run testparm to check your config 60file for correct syntax. 61</para> 62 63<para> 64Have you looked through <link linkend="diagnosis">The Samba Checklist</link>? This is extremely important. 65</para> 66 67<para> 68If you include part of a log file with your bug report, then be sure to 69annotate it with exactly what you were doing on the client at the 70time and exactly what the results were. 71</para> 72 73</sect1> 74 75<sect1 id="dbglvl"> 76<title>Debug Levels</title> 77 78<para> 79If the bug has anything to do with Samba behaving incorrectly as a 80server (like refusing to open a file), then the log files will probably 81be quite useful. Depending on the problem, a log level of between 3 and 8210 showing the problem may be appropriate. A higher level gives more 83detail but may use too much disk space. 84</para> 85 86<para> 87<indexterm><primary>debug level</primary></indexterm> 88<indexterm><primary>log level</primary></indexterm> 89To set the debug level, use the <smbconfoption name="log level"/> in your 90&smb.conf;. You may also find it useful to set the log 91level higher for just one machine and keep separate logs for each machine. 92To do this, add the following lines to your main &smb.conf; file: 93</para> 94 95<smbconfblock> 96<smbconfoption name="log level">10</smbconfoption> 97<smbconfoption name="log file">/usr/local/samba/lib/log.%m</smbconfoption> 98<smbconfoption name="include">/usr/local/samba/lib/smb.conf.%m</smbconfoption> 99</smbconfblock> 100 101<para> 102and create a file <filename>/usr/local/samba/lib/smb.conf.<replaceable>machine</replaceable></filename> where 103<replaceable>machine</replaceable> is the name of the client you wish to debug. In that file put any 104&smb.conf; commands you want; for example, <smbconfoption name="log level"/> may be useful. This also allows 105you to experiment with different security systems, protocol levels, and so on, on just one machine. 106</para> 107 108<para> 109The &smb.conf; entry <smbconfoption name="log level"/> is synonymous with the parameter <smbconfoption 110name="debuglevel"/> that has been used in older versions of Samba and is being retained for backward 111compatibility of &smb.conf; files. 112</para> 113 114<para> 115As the <smbconfoption name="log level"/> value is increased, you will record a significantly greater level of 116debugging information. For most debugging operations, you may not need a setting higher than 117<constant>3</constant>. Nearly all bugs can be tracked at a setting of <constant>10</constant>, but be 118prepared for a large volume of log data. 119</para> 120 121 <sect2> 122 <title>Debugging-Specific Operations</title> 123 124 <para> 125<indexterm><primary>debugging</primary></indexterm> 126<indexterm><primary>logging</primary></indexterm> 127<indexterm><primary>functional components</primary></indexterm> 128<indexterm><primary>cluttering</primary></indexterm> 129 Samba-3.x permits debugging (logging) of specific functional components without unnecessarily 130 cluttering the log files with detailed logs for all operations. An example configuration to 131 achieve this is shown in: 132 </para> 133 134<para> 135<smbconfblock> 136<smbconfoption name="log level">0 tdb:3 passdb:5 auth:4 vfs:2</smbconfoption> 137<smbconfoption name="max log size">0</smbconfoption> 138<smbconfoption name="log file">/var/log/samba/%U.%m.log</smbconfoption> 139</smbconfblock> 140</para> 141 142 <para> 143 This will cause the level of detail to be expanded to the debug class (log level) passed to 144 each functional area per the value shown above. The first value passed to the <parameter>log level</parameter> 145 of <constant>0</constant> means turn off all unnecessary debugging except the debug classes set for 146 the functional areas as specified. The table shown in <link linkend="dbgclass">Debuggable Functions</link> 147 may be used to attain very precise analysis of each SMB operation Samba is conducting. 148 </para> 149 150 <table frame="all" id="dbgclass"> 151 <title>Debuggable Functions</title> 152 <tgroup cols="2" align="center"> 153 <thead> 154 <row><entry>Function Name</entry><entry>Function Name</entry></row> 155 </thead> 156 <tbody> 157 <row><entry>all</entry><entry>passdb</entry></row> 158 <row><entry>tdb</entry><entry>sam</entry></row> 159 <row><entry>printdrivers</entry><entry>auth</entry></row> 160 <row><entry>lanman</entry><entry>winbind</entry></row> 161 <row><entry>smb</entry><entry>vfs</entry></row> 162 <row><entry>rpc_parse</entry><entry>idmap</entry></row> 163 <row><entry>rpc_srv</entry><entry>quota</entry></row> 164 <row><entry>rpc_cli</entry><entry>acls</entry></row> 165 </tbody> 166 </tgroup> 167 </table> 168 169 </sect2> 170 171</sect1> 172 173<sect1> 174<title>Internal Errors</title> 175 176<para> 177If you get the message <quote><errorname>INTERNAL ERROR</errorname></quote> in your log files, 178it means that Samba got an unexpected signal while running. It is probably a 179segmentation fault and almost certainly means a bug in Samba (unless 180you have faulty hardware or system software). 181</para> 182 183<para> 184If the message came from smbd, it will probably be accompanied by 185a message that details the last SMB message received by smbd. This 186information is often useful in tracking down the problem, so please 187include it in your bug report. 188</para> 189 190<para> 191You should also detail how to reproduce the problem, if 192possible. Please make this reasonably detailed. 193</para> 194 195 196<para> 197<indexterm><primary>core files</primary></indexterm> 198You may also find that a core file appeared in a <filename>corefiles</filename> 199subdirectory of the directory where you keep your Samba log 200files. This file is the most useful tool for tracking down the bug. To 201use it, you do this: 202<indexterm><primary>gdb</primary></indexterm> 203<indexterm><primary>debug</primary></indexterm> 204<screen> 205&prompt;<userinput>gdb smbd core</userinput> 206</screen> 207</para> 208 209<para> 210<indexterm><primary>dbx</primary></indexterm> 211<indexterm><primary>stack trace</primary></indexterm> 212adding appropriate paths to smbd and core so gdb can find them. If you 213do not have gdb, try <userinput>dbx</userinput>. Then within the debugger, 214use the command <command>where</command> to give a stack trace of where the 215problem occurred. Include this in your report. 216</para> 217 218<para> 219<indexterm><primary>disass</primary></indexterm> 220If you know any assembly language, do a <command>disass</command> of the routine 221where the problem occurred (if it's in a library routine, then 222disassemble the routine that called it) and try to work out exactly 223where the problem is by looking at the surrounding code. Even if you 224do not know assembly, including this information in the bug report can be 225useful. 226</para> 227</sect1> 228 229<sect1> 230<title>Attaching to a Running Process</title> 231 232<para> 233<indexterm><primary>PID</primary></indexterm> 234<indexterm><primary>gdb</primary></indexterm> 235<indexterm><primary>smbstatus</primary></indexterm> 236Unfortunately, some UNIXes (in particular some recent Linux kernels) 237refuse to dump a core file if the task has changed UID (which smbd 238does often). To debug with this sort of system, you could try to attach 239to the running process using 240<userinput>gdb smbd <replaceable>PID</replaceable></userinput>, where you get 241<replaceable>PID</replaceable> from <application>smbstatus</application>. 242Then use <command>c</command> to continue and try to cause the core dump 243using the client. The debugger should catch the fault and tell you 244where it occurred. 245</para> 246 247<para> 248Sometimes it is necessary to build Samba binary files that have debugging 249symbols so as to make it possible to capture enough information from a crashed 250operation to permit the Samba Team to fix the problem. 251</para> 252 253<para> 254Compile with <constant>-g</constant> to ensure you have symbols in place. 255Add the following line to the &smb.conf; file global section: 256<screen> 257panic action = "/bin/sleep 90000" 258</screen> 259to catch any panics. If <command>smbd</command> seems to be frozen, look for any sleep 260processes. If it is not, and appears to be spinning, find the PID 261of the spinning process and type: 262<screen> 263&rootprompt; gdb /usr/local/samba/sbin/smbd 264</screen> 265<indexterm><primary>spinning process</primary></indexterm> 266then <quote>attach `pid'</quote> (of the spinning process), then type <quote>bt</quote> to 267get a backtrace to see where the smbd is in the call path. 268</para> 269 270</sect1> 271 272<sect1> 273<title>Patches</title> 274 275 276<para> 277<indexterm><primary>diff</primary></indexterm> 278<indexterm><primary>patch</primary></indexterm> 279The best sort of bug report is one that includes a fix! If you send us 280patches, please use <userinput>diff -u</userinput> format if your version of 281diff supports it; otherwise, use <userinput>diff -c4</userinput>. Make sure 282you do the diff against a clean version of the source and let me know 283exactly what version you used. 284</para> 285 286</sect1> 287</chapter> 288