Update.

(This used to be commit 04a1961b214a944bb6d489bfa335bf220b708939)

1 files changed, 34 insertions, 24 deletions

diff --git a/docs/Samba3-HOWTO/TOSHARG-Bugs.xml b/docs/Samba3-HOWTO/TOSHARG-Bugs.xml
index 1395d8893b..0ef2c5cc76 100644
--- a/docs/Samba3-HOWTO/TOSHARG-Bugs.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-Bugs.xml
@@ -14,11 +14,12 @@
 <sect1>
 <title>Introduction</title>
 
-<para>Please report bugs using Samba's
-<ulink url="https://bugzilla.samba.org/">Bugzilla</ulink> 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.
+<para>
+<indexterm><primary>Bugzilla</primary></indexterm>
+<indexterm><primary>bug reports</primary></indexterm>
+Please report bugs using Samba's <ulink url="https://bugzilla.samba.org/">Bugzilla</ulink> 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.
 </para>
 
 <para>
@@ -31,6 +32,9 @@ us fix it fast.
 </para>
 
 <para>
+<indexterm><primary>comp.protocols.smb</primary></indexterm>
+<indexterm><primary>newsgroup</primary></indexterm>
+<indexterm><primary>configuration problem</primary></indexterm>
 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 
@@ -80,40 +84,37 @@ detail but may use too much disk space.
 </para>
 
 <para>
+<indexterm><primary>debug level</primary></indexterm>
+<indexterm><primary>log level</primary></indexterm>
 To set the debug level, use the <smbconfoption name="log level"/> in your 
 &smb.conf;. 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 &smb.conf; file:
 </para>
 
-<para><smbconfblock>
+<smbconfblock>
 <smbconfoption name="log level">10</smbconfoption>
 <smbconfoption name="log file">/usr/local/samba/lib/log.%m</smbconfoption>
 <smbconfoption name="include">/usr/local/samba/lib/smb.conf.%m</smbconfoption>
-</smbconfblock></para>
+</smbconfblock>
 
 <para>
 and create a file <filename>/usr/local/samba/lib/smb.conf.<replaceable>machine</replaceable></filename> where
-<replaceable>machine</replaceable> is the name of the client you wish to debug. In that file
-put any &smb.conf; commands you want; for example, 
-<smbconfoption name="log level"/> may be useful. This also allows you to 
-experiment with different security systems, protocol levels, and so on, on just 
-one machine.
+<replaceable>machine</replaceable> is the name of the client you wish to debug. In that file put any
+&smb.conf; commands you want; for example, <smbconfoption name="log level"/> may be useful. This also allows
+you to experiment with different security systems, protocol levels, and so on, on just one machine.
 </para>
 
 <para>
-The &smb.conf; entry <smbconfoption name="log level"/> 
-is synonymous with the parameter <smbconfoption name="debuglevel"/> that has
-been used in older versions of Samba and is being retained for backward 
+The &smb.conf; entry <smbconfoption name="log level"/> is synonymous with the parameter <smbconfoption
+name="debuglevel"/> that has been used in older versions of Samba and is being retained for backward
 compatibility of &smb.conf; files.
 </para>
 
 <para>
-As the <smbconfoption name="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 
-<constant>3</constant>. Nearly 
-all bugs can be tracked at a setting of <constant>10</constant>, but be 
+As the <smbconfoption name="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
+<constant>3</constant>. Nearly all bugs can be tracked at a setting of <constant>10</constant>, but be
 prepared for a large volume of log data.
 </para>
 
@@ -121,6 +122,10 @@ prepared for a large volume of log data.
 	<title>Debugging-Specific Operations</title>
 
 	<para>
+<indexterm><primary>debugging</primary></indexterm>
+<indexterm><primary>logging</primary></indexterm>
+<indexterm><primary>functional components</primary></indexterm>
+<indexterm><primary>cluttering</primary></indexterm>
 	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:
@@ -196,14 +201,14 @@ files. This file is the most useful tool for tracking down the bug. To
 use it, you do this:
 <indexterm><primary>gdb</primary></indexterm>
 <indexterm><primary>debug</primary></indexterm>
-</para>
-
-
 <screen>
 &prompt;<userinput>gdb smbd core</userinput>
 </screen>
+</para>
 
 <para>
+<indexterm><primary>dbx</primary></indexterm>
+<indexterm><primary>stack trace</primary></indexterm>
 adding appropriate paths to smbd and core so gdb can find them. If you
 do not have gdb, try <userinput>dbx</userinput>. Then within the debugger,
 use the command <command>where</command> to give a stack trace of where the
@@ -211,6 +216,7 @@ problem occurred. Include this in your report.
 </para>
 
 <para>
+<indexterm><primary>disass</primary></indexterm>
 If you know any assembly language, do a <command>disass</command> 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
@@ -224,6 +230,9 @@ useful.
 <title>Attaching to a Running Process</title>
 
 <para>
+<indexterm><primary>PID</primary></indexterm>
+<indexterm><primary>gdb</primary></indexterm>
+<indexterm><primary>smbstatus</primary></indexterm>
 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
@@ -251,8 +260,9 @@ to catch any panics. If <command>smbd</command> seems to be frozen, look for any
 processes. If it is not, and appears to be spinning, find the PID
 of the spinning process and type:
 <screen>
-gdb /usr/local/samba/sbin/smbd
+&rootprompt; gdb /usr/local/samba/sbin/smbd
 </screen>
+<indexterm><primary>spinning process</primary></indexterm>
 then <quote>attach `pid'</quote> (of the spinning process), then type <quote>bt</quote> to
 get a backtrace to see where the smbd is in the call path.
 </para>