Add all the source files from the old CVS tree,

add the 5 missing chapters from the HOWTO
and add jht's Samba by Example book.
(This used to be commit 9fb5bcb93e57c5162b3ee6f9c7d777dc0269d100)

1 files changed, 557 insertions, 0 deletions

diff --git a/docs/howto/Diagnosis.xml b/docs/howto/Diagnosis.xml
new file mode 100644
index 0000000000..dc3b43972a
--- /dev/null
+++ b/docs/howto/Diagnosis.xml
@@ -0,0 +1,557 @@
+<chapter id="diagnosis">
+<chapterinfo>
+	&author.tridge;
+	&author.jelmer;
+	&author.danshearer;
+	<pubdate>Wed Jan 15</pubdate>
+</chapterinfo>
+
+<title>The Samba Checklist</title>
+
+<sect1>
+<title>Introduction</title>
+
+<para>
+This file contains a list of tests you can perform to validate your
+Samba server. It also tells you what the likely cause of the problem
+is if it fails any one of these steps. If it passes all these tests,
+then it is probably working fine.
+</para>
+
+<para>
+You should do all the tests, in the order shown. We have tried to
+carefully choose them so later tests only use capabilities verified in
+the earlier tests. However, do not stop at the first error as there
+have been some instances when continuing with the tests has helped
+to solve a problem.
+</para>
+
+<para>
+If you send one of the Samba mailing lists  an email saying, <quote>it does not work</quote>
+and you have not followed this test procedure, you should not be surprised
+if your email is ignored.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Assumptions</title>
+
+<para>
+In all of the tests, it is assumed you have a Samba server called 
+BIGSERVER and a PC called ACLIENT both in workgroup TESTGROUP.
+</para>
+
+<para>
+The procedure is similar for other types of clients.
+</para>
+
+<para>
+It is also assumed you know the name of an available share in your
+&smb.conf;. I will assume this share is called <smbconfsection>tmp</smbconfsection>.
+You can add a <smbconfsection>tmp</smbconfsection> share like this by adding the
+lines shown in <link linkend="tmpshare">the next example</link>.
+</para>
+
+<para><smbconfexample id="tmpshare">
+<title>smb.conf with [tmp] share</title>
+<smbconfsection>[tmp]</smbconfsection>
+<smbconfoption><name>comment</name><value>temporary files </value></smbconfoption>
+<smbconfoption><name>path</name><value>/tmp</value></smbconfoption>
+<smbconfoption><name>read only</name><value>yes</value></smbconfoption>
+</smbconfexample>
+</para>
+
+<note><para>
+These tests assume version 3.0.0 or later of the Samba suite.
+Some commands shown did not exist in earlier versions. 
+</para></note>
+
+<para>
+Please pay attention to the error messages you receive. If any error message
+reports that your server is being unfriendly, you should first check that your
+IP name resolution is correctly set up. Make sure your <filename>/etc/resolv.conf</filename>
+file points to name servers that really do exist.
+</para>
+
+<para>
+Also, if you do not have DNS server access for name resolution, please check
+that the settings for your &smb.conf; file results in <command>dns proxy = no</command>. The
+best way to check this is with <command>testparm smb.conf</command>.
+</para>
+
+
+<para>
+<indexterm><primary>log files</primary><secondary>monitoring</secondary></indexterm>
+It is helpful to monitor the log files during testing by using the
+<command>tail -F log_file_name</command> in a separate
+terminal console (use ctrl-alt-F1 through F6 or multiple terminals in X). 
+Relevant log files can be found (for default installations) in
+<filename>/usr/local/samba/var</filename>. Also, connection logs from
+machines can be found here or possibly in <filename>/var/log/samba</filename>,
+depending on how or if you specified logging in your &smb.conf; file.
+</para>
+
+<para>
+If you make changes to your &smb.conf; file while going through these test,
+remember to restart &smbd; and &nmbd;.
+</para>
+
+</sect1>
+
+<sect1>
+<title>The Tests</title>
+<procedure>
+<title>Diagnosing your Samba server</title>
+
+
+<step performance="required">
+<para>
+<indexterm><primary>testparm</primary></indexterm>
+In the directory in which you store your &smb.conf; file, run the command
+<command>testparm smb.conf</command>. If it reports any errors, then your &smb.conf;
+configuration file is faulty.
+</para>
+
+<note><para>
+Your &smb.conf; file may be located in: <filename>/etc/samba</filename>
+or in <filename>/usr/local/samba/lib</filename>.
+</para></note>
+</step>
+
+<step performance="required">
+<para>
+Run the command <command>ping BIGSERVER</command> from the PC and
+<command>ping ACLIENT</command> from the UNIX box. If you do not get a valid response,
+then your TCP/IP software is not correctly installed. 
+</para>
+
+<para>
+You will need to start a <quote>dos prompt</quote> window on the PC to run ping.
+</para>
+
+<para>
+If you get a message saying <quote><errorname>host not found</errorname></quote> or similar, then your DNS
+software or <filename>/etc/hosts</filename> file is not correctly setup.
+It is possible to run Samba without DNS entries for the server and client, but it is assumed
+you do have correct entries for the remainder of these tests. 
+</para>
+
+<para>
+Another reason why ping might fail is if your host is running firewall 
+software. You will need to relax the rules to let in the workstation
+in question, perhaps by allowing access from another subnet (on Linux
+this is done via the appropriate firewall maintenance commands <command>ipchains</command>
+or <command>iptables</command>).
+</para>
+
+<note>
+<para>
+Modern Linux distributions install ipchains/iptables by default. 
+This is a common problem that is often overlooked.
+</para>
+</note>
+
+<para>
+If you wish to check what firewall rules may be present in a system under test, simply run
+<command>iptables -L -v</command> or if <parameter>ipchains</parameter>-based firewall rules are in use,
+<command>ipchains -L -v</command>.
+</para>
+
+<para>
+Here is a sample listing from a system that has an external ethernet interface (eth1) on which Samba
+is not active, and an internal (private network) interface (eth0) on which Samba is active:
+<screen>
+frodo:~ # iptables -L -v
+Chain INPUT (policy DROP 98496 packets, 12M bytes)
+ pkts bytes target     prot opt in     out     source     destination
+ 187K  109M ACCEPT     all  --  lo     any     anywhere   anywhere
+ 892K  125M ACCEPT     all  --  eth0   any     anywhere   anywhere
+1399K 1380M ACCEPT     all  --  eth1   any     anywhere   anywhere  \
+					state RELATED,ESTABLISHED
+
+Chain FORWARD (policy DROP 0 packets, 0 bytes)
+ pkts bytes target     prot opt in     out     source     destination
+ 978K 1177M ACCEPT     all  --  eth1   eth0    anywhere   anywhere \
+					state RELATED,ESTABLISHED
+ 658K   40M ACCEPT     all  --  eth0   eth1    anywhere   anywhere
+    0     0 LOG        all  --  any    any     anywhere   anywhere \
+					LOG level warning
+
+Chain OUTPUT (policy ACCEPT 2875K packets, 1508M bytes)
+ pkts bytes target     prot opt in     out     source     destination
+
+Chain reject_func (0 references)
+ pkts bytes target     prot opt in     out     source     destination
+</screen>
+</para>
+
+</step>
+
+<step performance="required">
+<para>
+Run the command: <command>smbclient -L BIGSERVER</command>
+on the UNIX box. You should get back a list of available shares. 
+</para>
+
+<para>
+If you get an error message containing the string <quote>Bad password</quote>, then
+you probably have either an incorrect <parameter>hosts allow</parameter>, 
+<parameter>hosts deny</parameter> or <parameter>valid users</parameter> line in your 
+&smb.conf;, or your guest account is not valid. Check what your guest account is using &testparm; and
+temporarily remove any <parameter>hosts allow</parameter>, <parameter>hosts deny</parameter>,
+<parameter>valid users</parameter> or <parameter>invalid users</parameter> lines.
+</para>
+
+<para>
+If you get a message <quote><errorname>connection refused</errorname></quote> response, then the <command>smbd</command> server may
+not be running. If you installed it in <filename>inetd.conf</filename>, then you probably edited
+that file incorrectly. If you installed it as a daemon, then check that
+it is running, and check that the netbios-ssn port is in a LISTEN
+state using <command>netstat -a</command>.
+</para>
+
+<note><para>
+<indexterm><primary>inetd</primary></indexterm>
+<indexterm><primary>xinetd</primary><see>inetd</see></indexterm>
+Some UNIX/Linux systems use <command>xinetd</command> in place of
+<command>inetd</command>. Check your system documentation for the location
+of the control files for your particular system implementation of
+the network super daemon.
+</para></note>
+
+<para>
+If you get a message saying <quote><errorname>session request failed</errorname></quote>, the server refused the
+connection. If it says <quote>Your server software is being unfriendly</quote>, then
+it's probably because you have invalid command line parameters to &smbd;,
+or a similar fatal problem with the initial startup of &smbd;. Also
+check your config file (&smb.conf;) for syntax errors with &testparm;
+and that the various directories where Samba keeps its log and lock
+files exist.
+</para>
+
+<para>
+There are a number of reasons for which smbd may refuse or decline
+a session request. The most common of these involve one or more of
+the &smb.conf; file entries as shown in <link linkend="modif1">the next example</link>.
+</para>
+
+
+<para>
+<smbconfexample id="modif1">
+	<title>Configuration for only allowing connections from a certain subnet</title>
+<smbconfsection>[globals]</smbconfsection>
+<member>...</member>
+<smbconfoption><name>hosts deny</name><value>ALL</value></smbconfoption>
+<smbconfoption><name>hosts allow</name><value>xxx.xxx.xxx.xxx/yy</value></smbconfoption>
+<smbconfoption><name>interfaces</name><value>eth0</value></smbconfoption>
+<smbconfoption><name>bind interfaces only</name><value>Yes</value></smbconfoption>
+<member>...</member>
+</smbconfexample>
+</para>
+
+<para>
+In the above, no allowance has been made for any session requests that
+will automatically translate to the loopback adapter address 127.0.0.1.
+To solve this problem, change these lines as shown in <link linkend="modif2">the following example</link>.
+</para>
+
+<para>
+<smbconfexample id="modif2">
+	<title>Configuration for allowing connections from a certain subnet and localhost</title>
+<smbconfsection>[globals]</smbconfsection>
+<member>...</member>
+<smbconfoption><name>hosts deny</name><value>ALL</value></smbconfoption>
+<smbconfoption><name>hosts allow</name><value>xxx.xxx.xxx.xxx/yy 127.</value></smbconfoption>
+<smbconfoption><name>interfaces</name><value>eth0 lo</value></smbconfoption>
+<member>...</member>
+</smbconfexample>
+</para>
+
+<para>
+<indexterm><primary>inetd</primary></indexterm>
+Another common cause of these two errors is having something already running 
+<indexterm><primary>smbclient</primary></indexterm>
+on port <constant>139</constant>, such as Samba (&smbd; is running from <application>inetd</application> already) or
+something like Digital's Pathworks. Check your <filename>inetd.conf</filename> file before trying
+to start &smbd; as a daemon &smbmdash; it can avoid a lot of frustration!
+</para>
+
+<para>
+And yet another possible cause for failure of this test is when the subnet mask
+and/or broadcast address settings are incorrect. Please check that the
+network interface IP Address/Broadcast Address/Subnet Mask settings are
+correct and that Samba has correctly noted these in the <filename>log.nmbd</filename> file.
+</para>
+
+</step>
+
+<step performance="required">
+
+<para>
+Run the command: <command>nmblookup -B BIGSERVER __SAMBA__</command>.
+You should get back the IP address of your Samba server.
+</para>
+
+<para>
+If you do not, then nmbd is incorrectly installed. Check your <filename>inetd.conf</filename>
+if you run it from there, or that the daemon is running and listening to udp port 137.
+</para>
+
+<para>
+One common problem is that many inetd implementations can't take many
+parameters on the command line. If this is the case, then create a
+one-line script that contains the right parameters and run that from
+inetd.
+</para>
+
+</step>
+
+<step performance="required">
+
+<para>
+Run the command: <command>nmblookup -B ACLIENT `*'</command>
+</para>
+
+<para>
+You should get the PC's IP address back. If you do not then the client
+software on the PC isn't installed correctly, or isn't started, or you
+got the name of the PC wrong. 
+</para>
+
+<para>
+If ACLIENT does not resolve via DNS then use the IP address of the
+client in the above test.
+</para>
+
+</step>
+
+<step performance="required">
+
+<para>
+Run the command: <command>nmblookup -d 2 '*'</command>
+</para>
+
+<para>
+This time we are trying the same as the previous test but are trying
+it via a broadcast to the default broadcast address. A number of
+NetBIOS/TCP/IP hosts on the network should respond, although Samba may
+not catch all of the responses in the short time it listens. You
+should see the <quote><errorname>got a positive name query response</errorname></quote>
+messages from several hosts.
+</para>
+
+<para>
+If this does not give a similar result to the previous test, then
+nmblookup isn't correctly getting your broadcast address through its
+automatic mechanism. In this case you should experiment with the
+<smbconfoption><name>interfaces</name></smbconfoption> option in &smb.conf; to manually configure your IP
+address, broadcast and netmask. 
+</para>
+
+<para>
+If your PC and server aren't on the same subnet, then you will need to use the
+<option>-B</option> option to set the broadcast address to that of the PCs subnet.
+</para>
+
+<para>
+This test will probably fail if your subnet mask and broadcast address are
+not correct. (Refer to TEST 3 notes above).
+</para>
+
+</step>
+
+<step performance="required">
+
+
+<para>
+<indexterm><primary>smbclient</primary></indexterm>
+Run the command: <command>smbclient //BIGSERVER/TMP</command>. You should 
+then be prompted for a password. You should use the password of the account
+with which you are logged into the UNIX box. If you want to test with
+another account, then add the <option>-U accountname</option> option to the end of
+the command line. For example, <command>smbclient //bigserver/tmp -Ujohndoe</command>.
+</para>
+
+<note><para>
+It is possible to specify the password along with the username as follows:
+<command>smbclient //bigserver/tmp -Ujohndoe%secret</command>.
+</para></note>
+
+<para>
+Once you enter the password, you should get the <prompt>smb></prompt> prompt. If you
+do not, then look at the error message. If it says <quote><errorname>invalid network
+name</errorname></quote>, then the service <smbconfsection>tmp</smbconfsection> is not correctly setup in your &smb.conf;.
+</para>
+
+<para>
+If it says <quote><errorname>bad password</errorname></quote>, then the likely causes are:
+</para>
+
+<orderedlist>
+<listitem>
+	<para>
+	You have shadow passwords (or some other password system) but didn't
+	compile in support for them in &smbd;.
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	Your <smbconfoption><name>valid users</name></smbconfoption> configuration is incorrect.
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	You have a mixed case password and you haven't enabled the <smbconfoption><name>password level</name></smbconfoption> option at a high enough level.
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	The <smbconfoption><name>path</name></smbconfoption> line in &smb.conf; is incorrect. Check it with &testparm;.
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	You enabled password encryption but didn't map UNIX to Samba users. Run:
+	<command>smbpasswd -a username</command>
+	</para>
+</listitem>
+</orderedlist>
+
+<para>
+Once connected, you should be able to use the commands <command>dir</command>, <command>get</command>,
+<command>put</command> and so on. Type <command>help command</command> for instructions. You should
+especially check that the amount of free disk space shown is correct when you type <command>dir</command>.
+</para>
+
+</step>
+
+<step performance="required">
+
+<para>
+On the PC, type the command <command>net view \\BIGSERVER</command>. You will 
+need to do this from within a dos prompt window. You should get back a 
+list of shares available on the server.
+</para>
+
+<para>
+If you get a message <quote><errorname>network name not found</errorname></quote> or similar error, then netbios
+name resolution is not working. This is usually caused by a problem in <command>nmbd</command>.
+To overcome it, you could do one of the following (you only need to choose one of them):
+</para>
+
+<orderedlist>
+<listitem><para>
+	Fixup the &nmbd; installation.
+</para></listitem>
+
+<listitem><para>
+	Add the IP address of BIGSERVER to the <command>wins server</command> box in the
+	advanced TCP/IP setup on the PC.
+</para></listitem>
+
+<listitem><para>
+	Enable Windows name resolution via DNS in the advanced section of the TCP/IP setup.
+</para></listitem>
+
+<listitem><para>
+	Add BIGSERVER to your lmhosts file on the PC.
+</para></listitem>
+</orderedlist>
+
+<para>
+If you get a message <quote><errorname>invalid network name</errorname></quote> or 
+<quote><errorname>bad password error</errorname></quote>, then apply the
+same fixes as for the <command>smbclient -L</command> test above. In
+particular, make sure your <command>hosts allow</command> line is correct (see the man pages).
+</para>
+
+<para>
+Also, do not overlook that fact that when the workstation requests the
+connection to the Samba server, it will attempt to connect using the 
+name with which you logged onto your Windows machine. You need to make
+sure that an account exists on your Samba server with that exact same
+name and password.
+</para>
+
+<para>
+If you get a message <quote><errorname>specified computer is not receiving requests</errorname></quote> or similar,
+it probably means that the host is not contact-able via TCP services.
+Check to see if the host is running TCP wrappers, and if so add an entry in
+the <filename>hosts.allow</filename> file for your client (or subnet, and so on.)
+</para>
+
+</step>
+
+<step performance="required">
+
+<para>
+Run the command <command>net use x: \\BIGSERVER\TMP</command>. You should 
+be prompted for a password, then you should get a <computeroutput>command completed 
+successfully</computeroutput> message. If not, then your PC software is incorrectly 
+installed or your &smb.conf; is incorrect. Make sure your <parameter>hosts allow</parameter>
+and other config lines in &smb.conf; are correct.
+</para>
+
+<para>
+It's also possible that the server can't work out what user name to connect you as.
+To see if this is the problem, add the line
+<smbconfoption><name>user</name><value>username</value></smbconfoption> to the
+<smbconfsection>[tmp]</smbconfsection> section of 
+&smb.conf; where <parameter>username</parameter> is the
+username corresponding to the password you typed. If you find this
+fixes things, you may need the username mapping option. 
+</para>
+
+<para>
+It might also be the case that your client only sends encrypted passwords 
+and you have <smbconfoption><name>encrypt passwords</name><value>no</value></smbconfoption> in &smb.conf;.
+Change this to "yes" to fix this.
+</para>
+
+</step>
+
+<step performance="required">
+
+<para>
+Run the command <command>nmblookup -M <parameter>testgroup</parameter></command> where 
+<parameter>testgroup</parameter> is the name of the workgroup that your Samba server and 
+Windows PCs belong to. You should get back the IP address of the 
+master browser for that workgroup.
+</para>
+
+<para>
+If you do not, then the election process has failed. Wait a minute to
+see if it is just being slow, then try again. If it still fails after
+that, then look at the browsing options you have set in &smb.conf;. Make
+sure you have <smbconfoption><name>preferred master</name><value>yes</value></smbconfoption> to ensure that 
+an election is held at startup.
+</para>
+
+</step>
+
+<step performance="required">
+
+<para>
+>From file manager, try to browse the server. Your Samba server should
+appear in the browse list of your local workgroup (or the one you
+specified in &smb.conf;). You should be able to double click on the name
+of the server and get a list of shares. If you get the error message <quote>invalid password</quote>,
+ you are probably running Windows NT and it
+is refusing to browse a server that has no encrypted password
+capability and is in User Level Security mode. In this case, either set
+<smbconfoption><name>security</name><value>server</value></smbconfoption> and 
+<smbconfoption><name>password server</name><value>Windows_NT_Machine</value></smbconfoption> in your
+&smb.conf; file, or make sure <smbconfoption><name>encrypt passwords</name></smbconfoption> is
+set to <quote>yes</quote>.
+</para>
+
+</step>
+</procedure>
+</sect1>
+
+</chapter>