diff options
Diffstat (limited to 'docs/docbook/projdoc/Bugs.xml')
| -rw-r--r-- | docs/docbook/projdoc/Bugs.xml | 112 |
1 files changed, 54 insertions, 58 deletions
diff --git a/docs/docbook/projdoc/Bugs.xml b/docs/docbook/projdoc/Bugs.xml index 0688e23cf3..15bd14ac1a 100644 --- a/docs/docbook/projdoc/Bugs.xml +++ b/docs/docbook/projdoc/Bugs.xml @@ -1,8 +1,9 @@ <chapter id="bugreport"> <chapterinfo> + &author.jht; &author.jelmer; - &author.tridge; <!-- This is mostly a guess --> + &author.tridge; <pubdate> 27 June 1997 </pubdate> </chapterinfo> @@ -11,79 +12,76 @@ <sect1> <title>Introduction</title> -<para>Please report bugs using - <ulink url="https://bugzilla.samba.org/">bugzilla</ulink>.</para> - -<para> -Please take the time to read this file before you submit a bug -report. Also, please see if it has changed between releases, as we -may be changing the bug reporting mechanism at some time. +<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> <para> -Please also do as much as you can yourself to help track down the +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 about it than -we can possibly answer, so you have a much higher chance of an answer -and a fix if you send us a "developer friendly" bug report that lets +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 <quote>developer friendly</quote> bug report that lets us fix it fast. </para> <para> Do not assume that if you post the bug to the comp.protocols.smb newsgroup or the mailing list that we will read it. If you suspect that your -problem is not a bug but a configuration problem then it is better to send -it to the Samba mailing list, as there are (at last count) 5000 other users on -that list that may be able to help you. +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. </para> <para> You may also like to look though the recent mailing list archives, -which are conveniently accessible on the Samba web pages +which are conveniently accessible on the Samba Web pages at <ulink noescape="1" url="http://samba.org/samba/">http://samba.org/samba/</ulink>. </para> </sect1> <sect1> -<title>General info</title> +<title>General Information</title> <para> -Before submitting a bug report check your config for silly -errors. Look in your log files for obvious messages that tell you that -you've misconfigured something and run testparm to test your config +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. </para> <para> -Have you run through the <link linkend="diagnosis">diagnosis</link>? -This is very important. +Have you looked through <link linkend="diagnosis"/>? This is extremely important. </para> <para> -If you include part of a log file with your bug report then be sure to +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. +time and exactly what the results were. </para> </sect1> <sect1> -<title>Debug levels</title> +<title>Debug Levels</title> <para> 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 very useful. Depending on the problem a log level of between 3 and +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. </para> <para> -To set the debug level use the <smbconfoption><name>log level</name></smbconfoption> in your +To set the debug level, use the <smbconfoption><name>log level</name></smbconfoption> 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: +To do this, add the following lines to your main &smb.conf; file: </para> <para><smbconfblock> @@ -93,47 +91,46 @@ To do this add the following lines to your main &smb.conf; file: </smbconfblock></para> <para> -then create a file -<filename>/usr/local/samba/lib/smb.conf.<replaceable>machine</replaceable></filename> where +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</name></smbconfoption> may be useful. This also allows you to -experiment with different security systems, protocol levels etc on just +experiment with different security systems, protocol levels and so on, on just one machine. </para> <para> The &smb.conf; entry <smbconfoption><name>log level</name></smbconfoption> is synonymous with the parameter <smbconfoption><name>debuglevel</name></smbconfoption> that has -been used in older versions of Samba and is being retained for backwards +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</name></smbconfoption> value is increased you will record -a significantly increasing level of debugging information. For most -debugging operations you may not need a setting higher than +As the <smbconfoption><name>log level</name></smbconfoption> 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 VERY large volume of log data. +prepared for a large volume of log data. </para> </sect1> <sect1> -<title>Internal errors</title> +<title>Internal Errors</title> <para> -If you get a <errorname>INTERNAL ERROR</errorname> message in your log files +If you get the message <quote><errorname>INTERNAL ERROR</errorname></quote> 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). </para> <para> -If the message came from smbd then it will probably be accompanied by -a message which details the last SMB message received by smbd. This -info is often very useful in tracking down the problem so please +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. </para> @@ -142,17 +139,17 @@ You should also detail how to reproduce the problem, if possible. Please make this reasonably detailed. </para> -<indexterm><primary>core files</primary></indexterm> <para> +<indexterm><primary>core files</primary></indexterm> You may also find that a core file appeared in a <filename>corefiles</filename> -subdirectory of the directory where you keep your samba log +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: -</para> - +use it, you do this: <indexterm><primary>gdb</primary></indexterm> <indexterm><primary>debug</primary></indexterm> +</para> + <screen> &prompt;<userinput>gdb smbd core</userinput> @@ -160,29 +157,28 @@ use it you do this: <para> adding appropriate paths to smbd and core so gdb can find them. If you -don't have gdb then try <userinput>dbx</userinput>. Then within the debugger +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 problem occurred. Include this in your report. </para> <para> -If you know any assembly language then do a -<command>disass</command> of the routine -where the problem occurred (if its in a library routine then +If you know any assembly language, do a <command>disass</command> of the routine +where the problem occurred (if its 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 -don't know assembly, including this info in the bug report can be +do not know assembly, including this information in the bug report can be useful. </para> </sect1> <sect1> -<title>Attaching to a running process</title> +<title>Attaching to a Running Process</title> <para> -Unfortunately some unixes (in particular some recent linux kernels) +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 +does often). To debug with this sort of system, you could try to attach to the running process using <userinput>gdb smbd <replaceable>PID</replaceable></userinput> where you get <replaceable>PID</replaceable> from <application>smbstatus</application>. @@ -196,12 +192,12 @@ where it occurred. <sect1> <title>Patches</title> -<indexterm><primary>diff</primary></indexterm> -<indexterm><primary>patch</primary></indexterm> <para> +<indexterm><primary>diff</primary></indexterm> +<indexterm><primary>patch</primary></indexterm> The best sort of bug report is one that includes a fix! If you send us -patches please use <userinput>diff -u</userinput> format if your version of +patches, please use <userinput>diff -u</userinput> format if your version of diff supports it, otherwise use <userinput>diff -c4</userinput>. Make sure you do the diff against a clean version of the source and let me know exactly what version you used. |