Docbook XML conversion: projdoc

(This used to be commit f7c9df751459da2d4a996d5f0135334fb3f87f69)

1 files changed, 201 insertions, 0 deletions

diff --git a/docs/docbook/projdoc/Bugs.xml b/docs/docbook/projdoc/Bugs.xml
new file mode 100644
index 0000000000..d782920457
--- /dev/null
+++ b/docs/docbook/projdoc/Bugs.xml
@@ -0,0 +1,201 @@
+<chapter id="bugreport">
+
+<chapterinfo>
+	&author.jelmer;
+	<author>
+		<affiliation>
+			<orgname>Samba Team</orgname>
+		</affiliation>
+	</author>
+	<pubdate> 27 June 1997 </pubdate>
+</chapterinfo>
+
+<title>Reporting Bugs</title>
+
+<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>
+
+<para>
+Please also 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
+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.
+</para>
+
+<para>
+You may also like to look though the recent mailing list archives,
+which are conveniently accessible on the Samba web pages
+at <ulink url="http://samba.org/samba/">http://samba.org/samba/</ulink>.
+</para>
+
+</sect1>
+
+<sect1>
+<title>General info</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
+file for correct syntax.
+</para>
+
+<para>
+Have you run through the <link linkend="diagnosis">diagnosis</link>? 
+This is very important.
+</para>
+
+<para>
+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.
+</para>
+
+</sect1>
+
+<sect1>
+<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
+10 showing the problem may be appropriate. A higher level givesmore
+detail, but may use too much disk space.
+</para>
+
+<para>
+To set the debug level use <command>log level =</command> 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 use:
+</para>
+
+<para><programlisting>
+log level = 10
+log file = /usr/local/samba/lib/log.%m
+include = /usr/local/samba/lib/smb.conf.%m
+</programlisting></para>
+
+<para>
+then 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 
+<command>log level=</command> may be useful. This also allows you to 
+experiment with different security systems, protocol levels etc on just 
+one machine.
+</para>
+
+<para>
+The &smb.conf; entry <command>log level =</command> 
+is synonymous with the entry <command>debuglevel =</command> that has been 
+used in older versions of Samba and is being retained for backwards 
+compatibility of &smb.conf; files.
+</para>
+
+<para>
+As the <command>log level =</command> 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 3. Nearly 
+all bugs can be tracked at a setting of 10, but be prepared for a VERY 
+large volume of log data.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Internal errors</title>
+
+<para>
+If you get a "INTERNAL ERROR" message 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
+include it in your bug report.
+</para>
+
+<para>
+You should also detail how to reproduce the problem, if
+possible. Please make this reasonably detailed.
+</para>
+
+<para>
+You may also find that a core file appeared in a <filename>corefiles</filename>
+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>
+
+<para><command>gdb smbd core</command></para>
+
+<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 use the
+command <userinput>where</userinput> to give a stack trace of where the problem
+occurred. Include this in your mail.
+</para>
+
+<para>
+If you know any assembly language then do a <userinput>disass</userinput> 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 then incuding this info in the bug report can be
+useful. 
+</para>
+</sect1>
+
+<sect1>
+<title>Attaching to a running process</title>
+
+<para>
+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 <userinput>gdb smbd <replaceable>PID</replaceable></userinput> where you get <replaceable>PID</replaceable> from
+<application>smbstatus</application>. Then use <userinput>c</userinput> to continue and try to cause the core dump
+using the client. The debugger should catch the fault and tell you
+where it occurred.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Patches</title>
+
+<para>
+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 
+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. 
+</para>
+
+</sect1>
+</chapter>
+