docs/htmldocs/Bugs.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >Reporting Bugs</TITLE
   5 ><META
   6 NAME="GENERATOR"
   7 CONTENT="Modular DocBook HTML Stylesheet Version 1.57"></HEAD
   8 ><BODY
   9 CLASS="ARTICLE"
  10 BGCOLOR="#FFFFFF"
  11 TEXT="#000000"
  12 LINK="#0000FF"
  13 VLINK="#840084"
  14 ALINK="#0000FF"
  15 ><DIV
  16 CLASS="ARTICLE"
  17 ><DIV
  18 CLASS="TITLEPAGE"
  19 ><H1
  20 CLASS="TITLE"
  21 ><A
  22 NAME="BUGREPORT"
  23 >Reporting Bugs</A
  24 ></H1
  25 ><HR></DIV
  26 ><DIV
  27 CLASS="SECT1"
  28 ><H1
  29 CLASS="SECT1"
  30 ><A
  31 NAME="AEN3"
  32 >Introduction</A
  33 ></H1
  34 ><P
  35 >The email address for bug reports is samba@samba.org</P
  36 ><P
  37 >Please take the time to read this file before you submit a bug
  38 report. Also, please see if it has changed between releases, as we
  39 may be changing the bug reporting mechanism at some time.</P
  40 ><P
  41 >Please also do as much as you can yourself to help track down the
  42 bug. Samba is maintained by a dedicated group of people who volunteer
  43 their time, skills and efforts. We receive far more mail about it than
  44 we can possibly answer, so you have a much higher chance of an answer
  45 and a fix if you send us a "developer friendly" bug report that lets
  46 us fix it fast. </P
  47 ><P
  48 >Do not assume that if you post the bug to the comp.protocols.smb
  49 newsgroup or the mailing list that we will read it. If you suspect that your
  50 problem is not a bug but a configuration problem then it is better to send
  51 it to the Samba mailing list, as there are (at last count) 5000 other users on
  52 that list that may be able to help you.</P
  53 ><P
  54 >You may also like to look though the recent mailing list archives,
  55 which are conveniently accessible on the Samba web pages
  56 at http://samba.org/samba/ </P
  57 ></DIV
  58 ><DIV
  59 CLASS="SECT1"
  60 ><HR><H1
  61 CLASS="SECT1"
  62 ><A
  63 NAME="AEN10"
  64 >General info</A
  65 ></H1
  66 ><P
  67 >Before submitting a bug report check your config for silly
  68 errors. Look in your log files for obvious messages that tell you that
  69 you've misconfigured something and run testparm to test your config
  70 file for correct syntax.</P
  71 ><P
  72 >Have you run through the <A
  73 HREF="Diagnosis.html"
  74 TARGET="_top"
  75 >diagnosis</A
  76 >?
  77 This is very important.</P
  78 ><P
  79 >If you include part of a log file with your bug report then be sure to
  80 annotate it with exactly what you were doing on the client at the
  81 time, and exactly what the results were.</P
  82 ></DIV
  83 ><DIV
  84 CLASS="SECT1"
  85 ><HR><H1
  86 CLASS="SECT1"
  87 ><A
  88 NAME="AEN16"
  89 >Debug levels</A
  90 ></H1
  91 ><P
  92 >If the bug has anything to do with Samba behaving incorrectly as a
  93 server (like refusing to open a file) then the log files will probably
  94 be very useful. Depending on the problem a log level of between 3 and
  95 10 showing the problem may be appropriate. A higher level givesmore
  96 detail, but may use too much disk space.</P
  97 ><P
  98 >To set the debug level use <B
  99 CLASS="COMMAND"
 100 >log level =</B
 101 > in your
 102 <TT
 103 CLASS="FILENAME"
 104 >smb.conf</TT
 105 >. You may also find it useful to set the log
 106 level higher for just one machine and keep separate logs for each machine.
 107 To do this use:</P
 108 ><P
 109 ><PRE
 110 CLASS="PROGRAMLISTING"
 111 >log level = 10
 112 log file = /usr/local/samba/lib/log.%m
 113 include = /usr/local/samba/lib/smb.conf.%m</PRE
 114 ></P
 115 ><P
 116 >then create a file
 117 <TT
 118 CLASS="FILENAME"
 119 >/usr/local/samba/lib/smb.conf.machine</TT
 120 > where
 121 "machine" is the name of the client you wish to debug. In that file
 122 put any smb.conf commands you want, for example
 123 <B
 124 CLASS="COMMAND"
 125 >log level=</B
 126 > may be useful. This also allows you to
 127 experiment with different security systems, protocol levels etc on just
 128 one machine.</P
 129 ><P
 130 >The <TT
 131 CLASS="FILENAME"
 132 >smb.conf</TT
 133 > entry <B
 134 CLASS="COMMAND"
 135 >log level =</B
 136 >
 137 is synonymous with the entry <B
 138 CLASS="COMMAND"
 139 >debuglevel =</B
 140 > that has been
 141 used in older versions of Samba and is being retained for backwards
 142 compatibility of smb.conf files.</P
 143 ><P
 144 >As the <B
 145 CLASS="COMMAND"
 146 >log level =</B
 147 > value is increased you will record
 148 a significantly increasing level of debugging information. For most
 149 debugging operations you may not need a setting higher than 3. Nearly
 150 all bugs can be tracked at a setting of 10, but be prepared for a VERY
 151 large volume of log data.</P
 152 ></DIV
 153 ><DIV
 154 CLASS="SECT1"
 155 ><HR><H1
 156 CLASS="SECT1"
 157 ><A
 158 NAME="AEN33"
 159 >Internal errors</A
 160 ></H1
 161 ><P
 162 >If you get a "INTERNAL ERROR" message in your log files it means that
 163 Samba got an unexpected signal while running. It is probably a
 164 segmentation fault and almost certainly means a bug in Samba (unless
 165 you have faulty hardware or system software)</P
 166 ><P
 167 >If the message came from smbd then it will probably be accompanied by
 168 a message which details the last SMB message received by smbd. This
 169 info is often very useful in tracking down the problem so please
 170 include it in your bug report.</P
 171 ><P
 172 >You should also detail how to reproduce the problem, if
 173 possible. Please make this reasonably detailed.</P
 174 ><P
 175 >You may also find that a core file appeared in a "corefiles"
 176 subdirectory of the directory where you keep your samba log
 177 files. This file is the most useful tool for tracking down the bug. To
 178 use it you do this:</P
 179 ><P
 180 ><B
 181 CLASS="COMMAND"
 182 >gdb smbd core</B
 183 ></P
 184 ><P
 185 >adding appropriate paths to smbd and core so gdb can find them. If you
 186 don't have gdb then try "dbx". Then within the debugger use the
 187 command "where" to give a stack trace of where the problem
 188 occurred. Include this in your mail.</P
 189 ><P
 190 >If you known any assembly language then do a "disass" of the routine
 191 where the problem occurred (if its in a library routine then
 192 disassemble the routine that called it) and try to work out exactly
 193 where the problem is by looking at the surrounding code. Even if you
 194 don't know assembly then incuding this info in the bug report can be
 195 useful. </P
 196 ></DIV
 197 ><DIV
 198 CLASS="SECT1"
 199 ><HR><H1
 200 CLASS="SECT1"
 201 ><A
 202 NAME="AEN43"
 203 >Attaching to a running process</A
 204 ></H1
 205 ><P
 206 >Unfortunately some unixes (in particular some recent linux kernels)
 207 refuse to dump a core file if the task has changed uid (which smbd
 208 does often). To debug with this sort of system you could try to attach
 209 to the running process using "gdb smbd PID" where you get PID from
 210 smbstatus. Then use "c" to continue and try to cause the core dump
 211 using the client. The debugger should catch the fault and tell you
 212 where it occurred.</P
 213 ></DIV
 214 ><DIV
 215 CLASS="SECT1"
 216 ><HR><H1
 217 CLASS="SECT1"
 218 ><A
 219 NAME="AEN46"
 220 >Patches</A
 221 ></H1
 222 ><P
 223 >The best sort of bug report is one that includes a fix! If you send us
 224 patches please use <B
 225 CLASS="COMMAND"
 226 >diff -u</B
 227 > format if your version of
 228 diff supports it, otherwise use <B
 229 CLASS="COMMAND"
 230 >diff -c4</B
 231 >. Make sure
 232 your do the diff against a clean version of the source and let me know
 233 exactly what version you used. </P
 234 ></DIV
 235 ></DIV
 236 ></BODY
 237 ></HTML
 238 >