More changes.

(This used to be commit 82ac7a25ed5e95fa664f0bf73e8b8241bd7cb44c)

3 files changed, 337 insertions, 150 deletions

diff --git a/docs/Samba3-HOWTO/TOSHARG-Compiling.xml b/docs/Samba3-HOWTO/TOSHARG-Compiling.xml
index 80c9d9d1d6..f6536c8922 100644
--- a/docs/Samba3-HOWTO/TOSHARG-Compiling.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-Compiling.xml
@@ -392,7 +392,7 @@ example of what you would not want to see would be:
 			  
 </sect1>
 
-<sect1>
+<sect1 id="startingSamba">
 	<title>Starting the &smbd; &nmbd; and &winbindd;</title>
 
 
@@ -521,6 +521,73 @@ netbios-ns dgram udp wait root /usr/local/samba/bin/nmbd nmbd
 	into that system.
 	</para></note>
 
+	<sect3>
+	<title>Starting Samba for Red Hat Linux</title>
+
+	<para>
+	Red Hat Linux has not always included all Samba components in the standard installation.
+	So versions of Red Hat Linux do not install the winbind utility, even though it is present
+	on the installation CDROM media. Check to see if the <command>winbindd</command> is present
+	on the system:
+<screen>
+&rootprompt; ls /usr/sbin/winbindd
+/usr/sbin/winbindd
+</screen>
+	This means that the appropriate RPM package was installed. The following response means
+	that it is not installed:
+<screen>
+/bin/ls: /usr/sbin/winbind: No such file or directory
+</screen>
+	In this case it should be installed if you intend to use <command>winbindd</command>. Search
+	the CDROM installation media for the samba-winbind RPM and install it following Red Hat
+	guidelines.
+	</para>
+
+	<para>
+	The process for starting Samba will now be outlined. Be sure to configure Sambas' &smb.conf;
+	file before starting Samba. When configured, start Samba by executing:
+<screen>
+&rootprompt; service smb start
+&rootprompt; service winbind start
+</screen>
+	These steps will start &nmbd;, &smbd; and &winbindd;.
+	</para>
+
+	<para>
+	To ensure that these services will be automatically restarted when the system is rebooted
+	execute:
+<screen>
+&rootprompt; chkconfig smb on
+&rootprompt; chkconfig winbind on
+</screen>
+	Samba will be started automatically at every system reboot.
+	</para>
+
+	</sect3>
+
+	<sect3>
+	<title>Starting Samba for Novell SUSE Linux</title>
+
+	<para>
+	Novell SUSE Linux products automatically install all essential Samba components in a default installation.
+	Configure your &smb.conf; file, then execute the following to start Samba:
+<screen>
+&rootprompt; rcnmb start
+&rootprompt; rcsmb start
+&rootprompt; rcwinbind start
+</screen>
+	Now execute these commands so that Samba will be started automatically following a system
+	reboot:
+<screen>
+&rootprompt; chkconfig nmb on
+&rootprompt; chkconfig smb on
+&rootprompt; chkconfig winbind on
+</screen>
+	The Samba services will now be started automatically following a system reboot.
+	</para>
+
+	</sect3>
+
 	</sect2>
 
 </sect1>
diff --git a/docs/Samba3-HOWTO/TOSHARG-FastStart.xml b/docs/Samba3-HOWTO/TOSHARG-FastStart.xml
index 5d1df13111..b21fae4088 100644
--- a/docs/Samba3-HOWTO/TOSHARG-FastStart.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-FastStart.xml
@@ -59,37 +59,35 @@ the guilty, and any resemblance to unreal nonexistent sites is deliberate.
 <title>Description of Example Sites</title>
 
 <para>
-In the first set of configuration examples we consider the case of exceptionally simple
-system requirements. There is a real temptation to make something that should require
-little effort much too complex.
+In the first set of configuration examples we consider the case of exceptionally simple system requirements.
+There is a real temptation to make something that should require little effort much too complex.
 </para>
 
 <para>
-<link linkend="anon-ro"></link> documents the type of server that might be sufficient to serve CD-ROM
-images, or reference document files for network client use. This configuration is also discussed in 
-<link linkend="StandAloneServer"></link>, <link linkend="RefDocServer"></link>.
-The purpose for this configuration is to provide a shared volume that is read-only that anyone, even guests, can access.
+<link linkend="anon-ro"></link> documents the type of server that might be sufficient to serve CD-ROM images,
+or reference document files for network client use. This configuration is also discussed in <link
+linkend="StandAloneServer"></link>, <link linkend="RefDocServer"></link>.  The purpose for this configuration
+is to provide a shared volume that is read-only that anyone, even guests, can access.
 </para>
 
 <para>
-The second example shows a minimal configuration for a print server that anyone can print
-to as long as they have the correct printer drivers installed on their computer. This is a
-mirror of the system described in <link linkend="StandAloneServer"></link>, <link linkend="SimplePrintServer"></link>.
+The second example shows a minimal configuration for a print server that anyone can print to as long as they
+have the correct printer drivers installed on their computer. This is a mirror of the system described in
+<link linkend="StandAloneServer"></link>, <link linkend="SimplePrintServer"></link>.
 </para>
 
 <para>
-The next example is of a secure office file and print server that will be accessible only
-to users who have an account on the system. This server is meant to closely resemble a
-workgroup file and print server, but has to be more secure than an anonymous access machine.
-This type of system will typically suit the needs of a small office. The server provides no
-network logon facilities, offers no domain control; instead it is just a network-attached storage (NAS) device and a print server.
+The next example is of a secure office file and print server that will be accessible only to users who have an
+account on the system. This server is meant to closely resemble a workgroup file and print server, but has to
+be more secure than an anonymous access machine.  This type of system will typically suit the needs of a small
+office. The server provides no network logon facilities, offers no domain control; instead it is just a
+network-attached storage (NAS) device and a print server.
 </para>
 
 <para>
-Finally, we start looking at more complex systems that will either integrate into existing
-MS Windows networks or replace them entirely. The examples provided cover domain
-member servers as well as Samba domain control (PDC/BDC) and finally describes in detail
-a large distributed network with branch offices in remote locations.
+The later example consider more complex systems that will either integrate into existing MS Windows networks
+or replace them entirely. These cover domain member servers as well as Samba domain control (PDC/BDC) and
+finally describes in detail a large distributed network with branch offices in remote locations.
 </para>
 
 </sect1>
@@ -118,6 +116,11 @@ of the packages that are provided by the operating system vendor or through othe
 	server, or it can be a complex server that is a member of a domain security context.
 	</para>
 
+	<para>
+	As the examples are developed, every attempt is made to progress the system toward greater capability, just as
+	one might expect would happen in a real business office as that office grows in size and its needs change.
+	</para>
+
 		<sect3 id="anon-ro">
 		<title>Anonymous Read-Only Document Server</title>
 
@@ -129,35 +132,6 @@ of the packages that are provided by the operating system vendor or through othe
 		storage area.
 		</para>
 
-		<para>
-		As the examples are developed, every attempt is made to progress the
-		system toward greater capability, just as one might expect would happen
-		in a real business office as that office grows in size and its needs
-		change.
-		</para>
-
-		<para>
-		The configuration file is presented in <link linkend="anon-example">Anonymous Read-Only Server
-		Configuration</link>.
-		</para>
-
-		<example id="anon-example">
-		<title>Anonymous Read-Only Server Configuration</title>
-		<smbconfblock>
-		<smbconfcomment>Global parameters</smbconfcomment>
-		<smbconfsection name="[global]"/>
-		<smbconfoption name="workgroup">MIDEARTH</smbconfoption>
-		<smbconfoption name="netbios name">HOBBIT</smbconfoption>
-		<smbconfoption name="security">share</smbconfoption>
-
-		<smbconfsection name="[data]"/>
-		<smbconfoption name="comment">Data</smbconfoption>
-		<smbconfoption name="path">/export</smbconfoption>
-		<smbconfoption name="read only">Yes</smbconfoption>
-		<smbconfoption name="guest ok">Yes</smbconfoption>
-		</smbconfblock>
-		</example>
-
 		<itemizedlist>
 			<listitem><para>
 			The file system share point will be <filename>/export</filename>.
@@ -197,16 +171,42 @@ of the packages that are provided by the operating system vendor or through othe
 
 			<step><para>
 			Install the Samba configuration file (<filename>/etc/samba/smb.conf</filename>)
-			as shown.
+			as shown in <link linkend="anon-example">Anonymous Read-Only Server Configuration</link>.
 			</para></step>
 
+<example id="anon-example">
+<title>Anonymous Read-Only Server Configuration</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">MIDEARTH</smbconfoption>
+<smbconfoption name="netbios name">HOBBIT</smbconfoption>
+<smbconfoption name="security">share</smbconfoption>
+
+<smbconfsection name="[data]"/>
+<smbconfoption name="comment">Data</smbconfoption>
+<smbconfoption name="path">/export</smbconfoption>
+<smbconfoption name="read only">Yes</smbconfoption>
+<smbconfoption name="guest ok">Yes</smbconfoption>
+</smbconfblock>
+</example>
+
 			<step><para>
-			Test the configuration file:
+			Test the configuration file by executing the following command:
 <screen>
 &rootprompt;<userinput>testparm</userinput>
 </screen>
+			Alternately, where you are operating from a master configuration file called
+			<filename>smb.conf.master</filename>, the following sequence of commands might prove
+			more appropriate:
+<screen>
+&rootprompt; cd /etc/samba
+&rootprompt; testparm -s smb.conf.master > smb.conf
+&rootprompt; testparm
+</screen>
 			Note any error messages that might be produced. Proceed only if error-free output has been
-			obtained. An example of the output with the following file will list the file.
+			obtained. An example of typical output that should be generated from the above configuration
+			file is shown here:
 <screen>
 Load smb config files from /etc/samba/smb.conf
 Processing section "[data]"
@@ -230,8 +230,9 @@ Press enter to see a dump of your service definitions
 			</para></step>
 
 			<step><para>
-			Start Samba using the method applicable to your operating system
-			platform.
+			Start Samba using the method applicable to your operating system platform. The method that
+			should be used is platform dependant. Refer to <link linkend="startingSamba">Starting Samba</link>
+			for further information regarding starting of Samba.
 			</para></step>
 
 			<step><para>
@@ -356,7 +357,16 @@ Added user jackb.
 
 		<para>
 		The above configuration is not ideal. It uses no smart features, and it deliberately
-		presents a less than elegant solution. But it is basic, and it does print.
+		presents a less than elegant solution. But it is basic, and it does print. Samba makes
+		use of the direct printing application program interface that is provided by CUPS.
+		When Samba has been compiled and linked with the CUPS libraries the default printing
+		system will be CUPS. By specifying that the printcap name is CUPS, Samba will use
+		the CUPS library API to communicate directly with CUPS for all printer functions.
+		It is possible to force the use of external printing commands by setting the value
+		of the <prarameter>printing</parameter> to either SYSV or BSD, and thus the value of
+		the parameter <parameter>printcap name</parameter> must be set to something other than
+		CUPS. In such case, it could be set to the name of any file that contains a list
+		of printers that should be made available to Windows clients.
 		</para>
 
 		<note><para>
@@ -382,7 +392,7 @@ Added user jackb.
 			Directory permissions should be set for public read-write with the
 			sticky bit set as shown:
 <screen>
-&rootprompt;<userinput>chmod a+trw TX /var/spool/samba</userinput>
+&rootprompt;<userinput>chmod a+twrx /var/spool/samba</userinput>
 </screen>
 		The purpose of setting the sticky bit is to prevent who does not own the temporary print file
 		from being able to take control of it with the potential for devious misuse.
@@ -434,7 +444,7 @@ Added user jackb.
 		encrypted passwords in a file called <filename>/etc/samba/smbpasswd</filename>.
 		The default &smb.conf; entry that makes this happen is
 		<smbconfoption name="passdb backend">smbpasswd, guest</smbconfoption>. Since this is the default,
-		it is not necessary to enter it into the configuration file. Note that guest backend is
+		it is not necessary to enter it into the configuration file. Note that the guest backend is
 		added to the list of active passdb backends no matter whether it specified directly in Samba configuration
 		file or not.
 		</para>
@@ -570,6 +580,12 @@ Workgroup            Master
 ---------            -------
 MIDEARTH             OLORIN
 </screen>
+			The following error message indicates that Samba was not running:
+<screen>
+&rootprompt; smbclient -L olorin -U%
+Error connecting to 192.168.1.40 (Connection refused)
+Connection to olorin failed
+</screen>
 			</para></step>
 
 			<step><para>
@@ -636,7 +652,7 @@ smb: \> <userinput>q</userinput>
 	The accounting department uses an accounting application called <emphasis>SpytFull</emphasis>
 	that must be run from a central application server. The software is licensed to run only off
 	one server, there are no workstation components, and it is run off a mapped share. The data
-	store is in a UNIX-based SQL backend. The UNIX gurus look after that, so it is not our
+	store is in a UNIX-based SQL backend. The UNIX gurus look after that, so this is not our
 	problem.
 	</para>
 
@@ -1061,7 +1077,7 @@ net groupmap add ntgroup="QA Team"   unixgroup=qateam    type=d
 			Idealx</ulink> Web site. They may also be obtained from the Samba tarball. Linux
 			distributions tend to install the Idealx scripts in the 
 			<filename>/usr/share/doc/packages/sambaXXXXXX/examples/LDAP/smbldap-tools</filename> directory.
-			Idealx scripts version <constant>smbldap-tools-0.8.7</constant> are known to work well.
+			Idealx scripts version <constant>smbldap-tools-0.9.1</constant> are known to work well.
 			</para>
 
 			<procedure>
@@ -1110,8 +1126,8 @@ index   default               sub
 				</para></step>
 
 				<step><para>
-				Create the following file <filename>samba-ldap-init.ldif</filename>:
-				<indexterm><primary>samba-ldap-init.ldif</primary></indexterm>
+				Create the following file <filename>initdb.ldif</filename>:
+				<indexterm><primary>initdb.ldif</primary></indexterm>
 <programlisting>
 # Organization for SambaXP Demo
 dn: dc=quenya,dc=org
@@ -1163,7 +1179,8 @@ userPassword: {SSHA}0jBHgQ1vp4EDX2rEMMfIudvRMJoGwjVb
 
 				<step><para>
 				The &smb.conf; file that drives this backend can be found in example <link
-				linkend="fast-ldap">LDAP backend smb.conf for PDC</link>.
+				linkend="fast-ldap">LDAP backend smb.conf for PDC</link>. Add additional stanzas
+				as required.
 				</para></step>
 
 <example id="fast-ldap">
@@ -1228,7 +1245,9 @@ userPassword: {SSHA}0jBHgQ1vp4EDX2rEMMfIudvRMJoGwjVb
 			<title>Backup Domain Controller</title>
 
 			<para>
-			<link linkend="fast-bdc"/> shows the example configuration for the BDC.
+			<link linkend="fast-bdc"/> shows the example configuration for the BDC. Note that
+			the &smb.conf; file does not specify the smbldap-tools scripts &smbmdash; they are
+			not needed on a BDC. Add additional stanzas for shares and printers as required.
 			</para>
 
 			<procedure>
diff --git a/docs/Samba3-HOWTO/TOSHARG-Install.xml b/docs/Samba3-HOWTO/TOSHARG-Install.xml
index 7ecc33bdce..344dfaaa90 100644
--- a/docs/Samba3-HOWTO/TOSHARG-Install.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-Install.xml
@@ -17,15 +17,15 @@
 	<title>Obtaining and Installing Samba</title>
 
 	<para>
-	Binary packages of Samba are included in almost any Linux or
-	UNIX distribution. There are also some packages available at 
-	<ulink url="http://samba.org/">the Samba home page</ulink>. Refer to 
-	the manual of your operating system for details on installing packages 
-	for your specific operating system.
+	<indexterm><primary>packages</primary></indexterm>
+	Binary packages of Samba are included in almost any Linux or UNIX distribution. There are also some
+	packages available at <ulink url="http://samba.org/">the Samba home page</ulink>. Refer to the manual of your
+	operating system for details on installing packages for your specific operating system.
 	</para>
 
-	<para>If you need to compile Samba from source, check 
-	<link linkend="compiling">How to Compile Samba.</link>
+	<para>
+	<indexterm><primary>compile</primary></indexterm>
+	If you need to compile Samba from source, check <link linkend="compiling">How to Compile Samba</link>.
 	</para>
 
 </sect1>
@@ -34,32 +34,56 @@
 	<title>Configuring Samba (smb.conf)</title>
 
 	<para>
-	Samba's configuration is stored in the &smb.conf; file, which
-	usually resides in <filename>/etc/samba/smb.conf</filename> 
-	or <filename>/usr/local/samba/lib/smb.conf</filename>. You can either 
-	edit this file yourself or do it using one of the many graphical 
-	tools that are available, such as the Web-based interface SWAT, that 
-	is included with Samba.
+	<indexterm><primary>/etc/samba/smb.conf</primary></indexterm>
+	<indexterm><primary>SWAT</primary></indexterm>
+	Samba's configuration is stored in the &smb.conf; file, which usually resides in
+	<filename>/etc/samba/smb.conf</filename> or <filename>/usr/local/samba/lib/smb.conf</filename>. You can either
+	edit this file yourself or do it using one of the many graphical tools that are available, such as the
+	Web-based interface SWAT, that is included with Samba.
 	</para>
 
 	<sect2>
 	<title>Configuration File Syntax</title>
 
-	<para>The &smb.conf; file uses the same syntax as the various old 
-	.ini files in Windows 3.1: Each file consists of various sections, 
-	which are started by putting the section name between brackets ([]) 
-	on a new line. Each contains zero or more key/value pairs separated by an 
-	equality sign (=). The file is just a plaintext file, so you can 
-	open and edit it with your favorite editing tool.</para>
+	<para>
+	<indexterm><primary>section name</primary></indexterm>
+	The &smb.conf; file uses the same syntax as the various old <filename>.ini</filename> files in Windows
+	3.1: Each file consists of various sections, which are started by putting the section name between brackets
+	(<literal>[]</literal>) on a new line. Each contains zero or more key/value pairs separated by an equality
+	sign (<literal>=</literal>). The file is just a plaintext file, so you can open and edit it with your favorite
+	editing tool.
+	</para>
+
+	<para>
+	<indexterm><primary>meta-service</primary></indexterm>
+	<indexterm><primary>print</primary><secondary>queue</secondary></indexterm>
+	<indexterm><primary>share</primary></indexterm>
+	<indexterm><primary>spooler.</primary></indexterm>
+	<indexterm><primary>print</primary><secondary>spooler</secondary></indexterm>
+	<indexterm><primary>spool</primary><secondary>directory</secondary></indexterm>
+	Each section in the &smb.conf; file represents either a share or a meta-service on the Samba server. The
+	section <literal>[global]</literal> is special, since it contains settings that apply to the whole Samba
+	server.  Samba supports a number of meta-services, each of which serves its own purpose. For example, the
+	<literal>[homes]</literal> share is a meta-service that causes Samba to provide a personal home share for
+	each user. The <literal>[printers]</literal> share is a meta-service that establishes print queue support
+	and that specifies the location of the intermediate spool directory into which print jobs are received
+	from Windows clients prior to being dispatched to the UNIX/Linux print spooler.
+	</para>
 
-	<para>Each section in the &smb.conf; file represents a share 
-	on the Samba server. The section <quote>global</quote> is special, since it 
-	contains settings that apply to the whole Samba server and not 
-	to one share in particular.</para>
+	<para>
+	<indexterm><primary>stanza</primary></indexterm>
+	Each section of the &smb.conf; file that specifies a share, or a meta-service, is called a stanza.
+	The <literal>global</literal> stanza specifies settings that affect all the other stanzas in the
+	&smb.conf; file. Configuration parameters are documented in the &smb.conf; man page. Some parameters
+	can be used only in the <literal>global</literal> stanza, some only in share or meta-service stanzas,
+	and some can be used globally or just within a share or meta-service stanza.
+	</para>
 
-<para><link linkend="smbconfminimal">A minimal smb.conf</link> contains a very minimal &smb.conf;.
+	<para>
+	<indexterm><primary>minimal</primary><secondary>configuration</secondary></indexterm>
+	<link linkend="smbconfminimal">A minimal smb.conf</link> contains a very minimal &smb.conf;.
 	<indexterm><primary>minimal configuration</primary></indexterm>
-</para>
+	</para>
 
 	<example id="smbconfminimal">
 		<title>A minimal smb.conf</title>
@@ -83,6 +107,7 @@
 	<title>Starting Samba</title>
 
 	<para>
+	<indexterm><primary>daemon</primary></indexterm>
 	Samba essentially consists of two or three daemons. A daemon is a UNIX application that runs in the background and provides services.
 	An example of a service is the Apache Web server for which the daemon is called <command>httpd</command>. In the case of Samba there
 	are three daemons, two of which are needed as a minimum.
@@ -125,6 +150,7 @@
 	</variablelist>
 
 	<para>
+	<indexterm><primary>startup</primary><secondary>process</secondary></indexterm>
 	When Samba has been packaged by an operating system vendor, the startup process is typically a custom feature of its
 	integration into the platform as a whole. Please refer to your operating system platform administration manuals for
 	specific information pertaining to correct management of Samba startup.
@@ -136,15 +162,19 @@
 	<title>Example Configuration</title>
 	
 	<para>
-	There are sample configuration files in the examples subdirectory in the
-	distribution. It is suggested you read them carefully so you can see how the options
-	go together in practice. See the man page for all the options. 
-	It might be worthwhile to start out with the smb.conf.default 
-	configuration file and adapt it to your needs. It contains plenty of 
-	comments.
+	<indexterm><primary>examples</primary></indexterm>
+	<indexterm><primary>source code</primary></indexterm>
+	<indexterm><primary>distribution</primary></indexterm>
+	<indexterm><primary>tarball</primary></indexterm>
+	<indexterm><primary>pacakge</primary></indexterm>
+	There are sample configuration files in the examples subdirectory in the source code distribution tarball
+	pacakge. It is suggested you read them carefully so you can see how the options go together in practice. See
+	the man page for all the options.  It might be worthwhile to start out with the
+	<filename>smb.conf.default</filename> configuration file and adapt it to your needs. It contains plenty of comments.
 	</para>
 
 	<para>
+	<indexterm><primary>simplest</primary><secondary>configuration</secondary></indexterm>
 	The simplest useful configuration file would contain something like that shown in
 	<link linkend="simple-example">Another simple smb.conf File</link>.
 	<indexterm><primary>simple configuration</primary></indexterm>
@@ -163,6 +193,10 @@
 </example>
 	
 	<para>
+	<indexterm><primary>connections</primary></indexterm>
+	<indexterm><primary>account</primary></indexterm>
+	<indexterm><primary>login name</primary></indexterm>
+	<indexterm><primary>service name</primary></indexterm>
 	This will allow connections by anyone with an account on the server, using either
 	their login name or <smbconfsection name="homes"/> as the service name.
 	(Note: The workgroup that Samba should appear in must also be set. The default
@@ -170,12 +204,18 @@
 	</para>
 	
 	<para>
-	Make sure you put the &smb.conf; file in the correct place.
+	<indexterm><primary>smbd</primary></indexterm>
+	Make sure you put the &smb.conf; file in the correct place. Note, the correct location of this file
+	depends on how the binary files were built. You can discover the correct location by executing from
+	the directory that contains the <command>smbd</command> command file:
+<screen>
+&rootprompt; smbd -b | grep smb.conf
+</screen>
 	</para>
 
 	<para>
-	For more information about security settings for the 
-	<smbconfsection name="[homes]"/> share, please refer to 
+	<indexterm><primary>security</primary><secondary>settings</secondary></indexterm>
+	For more information about security settings for the <smbconfsection name="[homes]"/> share, please refer to 
 	<link linkend="securing-samba">Securing Samba</link>.
 	</para>
 
@@ -183,24 +223,42 @@
 	<title>Test Your Config File with <command>testparm</command></title>
 
 	<para>
+	<indexterm><primary>validate</primary></indexterm>
+	<indexterm><primary>testparm</primary></indexterm>
+	<indexterm><primary>misconfigurations</primary></indexterm>
 	It's important to validate the contents of the &smb.conf; file using the &testparm; program.
 	If testparm runs correctly, it will list the loaded services. If not, it will give an error message.
 	Make sure it runs correctly and that the services look reasonable before proceeding. Enter the command: 
-	</para>
-
 	<screen>
 	&rootprompt; testparm /etc/samba/smb.conf
 	</screen>
-
-	<para>testparm will parse your configuration file and report 
-	any unknown parameters or incorrect syntax. </para>
-
-	
+	Testparm will parse your configuration file and report any unknown parameters or incorrect syntax.
+	It also performs a check for common misconfigurations and will issue a warning if one is found.
+	</para>
 
 	<para>
 	Always run testparm again whenever the &smb.conf; file is changed!
 	</para>
 
+	<para>
+	<indexterm><primary>smbd</primary></indexterm>
+	<indexterm><primary>nmbd</primary></indexterm>
+	<indexterm><primary>winbindd</primary></indexterm>
+	<indexterm><primary>configuration</primary><secondary>documentation</secondary></indexterm>
+	The &smb.conf; file is constantly checked by the Samba daemons <command>smbd</command> and every instance of
+	itself that it spawns, <command>nmbd</command> and <command>winbindd</command>. It is good practice to
+	keep this file as small as possible. Many administrators prefer to document Samba configuration settings
+	and thus the need to keep this file small goes against good documentation wisdom. One solution that may
+	be adopted is to do all documentation and configuration in a file that has another name, such as
+	<filename>smb.conf.master</filename>. The <command>testparm</command> utility can be used to generate a
+	fully optimized &smb.conf; file from this master configuration and documtenation file as shown here:
+<screen>
+&rootprompt; testparm -s smb.conf.master > smb.conf
+</screen>
+	This administrative method makes it possible to maitain detailed configuration change records while at
+	the same time keeping the working &smb.conf; file size to the minimum necessary.
+	</para>
+
 </sect3>
 </sect2>
 
@@ -209,10 +267,10 @@
 
 	<para>
 	<indexterm><primary>swat</primary></indexterm>
-	SWAT is a Web-based interface that can be used to facilitate the configuration of Samba. 
-	SWAT might not be available in the Samba package that shipped with your platform, 
-	but in a separate package. Please read the SWAT man page 
-	on compiling, installing, and configuring SWAT from source.
+	SWAT is a Web-based interface that can be used to facilitate the configuration of Samba.  SWAT might not
+	be available in the Samba package that shipped with your platform, but in a separate package. If it is
+	necesaary to built SWAT please read the SWAT man page regarding compilation, installation, and
+	configuration of SWAT from the source code.
 	</para>
 
 	<para>
@@ -227,7 +285,9 @@
 	machine leaves your connection open to password sniffing because passwords will be sent over the wire in the clear. 
 	</para>
 
-	<para>More information about SWAT can be found in <link linkend="SWAT"></link>.</para>
+	<para>
+	More information about SWAT can be found in <link linkend="SWAT">The Samba Web Administration Tool</link>.
+	</para>
 
 </sect2>
 
@@ -245,14 +305,18 @@
 &prompt;<userinput>smbclient -L <replaceable>yourhostname</replaceable></userinput>
 </screen></para>
 
-	<para>You should see a list of shares available on your server. If you do not, then
+	<para>
+	You should see a list of shares available on your server. If you do not, then
 	something is incorrectly configured. This method can also be used to see what shares 
-	are available on other SMB servers, such as Windows 2000.</para>
+	are available on other SMB servers, such as Windows 2000.
+	</para>
 
-	<para>If you choose user-level security, you may find that Samba requests a password
+	<para>
+	If you choose user-level security, you may find that Samba requests a password
 	before it will list the shares. See the <command>smbclient</command> man page for details.
 	You can force it to list the shares without a password by adding the option
-	<option>-N</option> to the command line. </para>
+	<option>-N</option> to the command line. 
+	</para>
 </sect1>
 
 <sect1>
@@ -279,31 +343,36 @@
 <sect1>
 	<title>Connect from a Remote SMB Client</title>
 
-	<para>Now that Samba is working correctly locally, you can try to 
-	access it from other clients. Within a few minutes, the Samba host 
-	should be listed in the Network Neighborhood on all Windows 
-	clients of its subnet. Try browsing the server from another client
-	or "mounting" it.</para>
-
-	<para>Mounting disks from a DOS, Windows, or OS/2 client can be done by running a command such as:</para>
-
-	<para><screen>
-&dosprompt;<userinput>net use d: \\servername\service</userinput>
-</screen></para>
+	<para>
+	Now that Samba is working correctly locally, you can try to access it from other clients. Within a few
+	minutes, the Samba host should be listed in the Network Neighborhood on all Windows clients of its subnet.
+	Try browsing the server from another client or "mounting" it.
+	</para>
 
-	<para>Try printing, for example,</para>
+	<para>
+	Mounting disks from a DOS, Windows, or OS/2 client can be done by running a command such as:
+<screen>
+&dosprompt;<userinput>net use m: \\servername\service</userinput>
+</screen>
+	Where the drive letter m: is any available drive letter. It is important to double-check that the
+	service (share) name that you used does actually exist.
+	</para>
 
 	<para>
+	Try printing, for example,
 <screen>
 &dosprompt;<userinput>net use lpt1:	\\servername\spoolservice</userinput>
-</screen></para>
+</screen>
+	The <literal>spoolservice</literal> is the name of the printer (actually the print queue) on the target
+	server. This will permit all print jobs that are captured by the lpt1: port on the Windows client to
+	be sent to the printer that owns the spoolservice that has been specified.
+	</para>
 
 <para>
 <screen>&dosprompt;<userinput>print filename</userinput>
 </screen></para>
-</sect1>
 
-<sect1>
+	<sect2>
 	<title>What If Things Don't Work?</title>
 	
 	<para>
@@ -314,6 +383,34 @@
 	problem and has found a way to overcome it.
 	</para>
 
+	<para>
+	If you are new to Samba, and particularly if you are new to Windows networking, or to UNIX/Linux,
+	the book <quote>Samba-3 by Example</quote> will help you to create a validated network environment.
+	Simply choose from the first five chapters the network design that most closely matches site needs,
+	then follow the simple step-by-step procedure to deploy it. Later, when you have a working network
+	you may well want to refer back to this book for further insight into opportunities for improvement.
+	</para>
+
+	</sect2>
+
+	<sect2>
+	<title>Still Stuck?</title>
+
+	<para>
+	The best advice under the stress of abject frustration is to cool down! That may be challenging
+	of itself, but while you are angry or annoyed your ability to seek out a solution is somewhat
+	undermined. A cool head clears the way to finding the answer you are looking for. Just remember,
+	every problem has a solution &smbmdash; there is a good chance that someone else has found it
+	even though you can't right now. That will change with time, patience and learning.
+	</para>
+
+	<para>
+	Now that you have cooled down a bit, please refer to <link linkend="diagnosis">the Samba Checklist</link>
+	for a process that can be followed to identify the cause of your problem.
+	</para>
+
+	</sect2>
+
 </sect1>
 
 <sect1>
@@ -326,38 +423,42 @@ The following questions and issues are raised repeatedly on the Samba mailing li
 <sect2>
 	<title>Large Number of smbd Processes</title>
 
-<para>
-Samba consists of three core programs: &nmbd;, &smbd;, and &winbindd;. &nmbd; is the name server message daemon,
-&smbd; is the server message daemon, and &winbindd; is the daemon that handles communication with domain controllers.
-</para>
+	<para>
+	Samba consists of three core programs: &nmbd;, &smbd;, and &winbindd;. &nmbd; is the name server message daemon,
+	&smbd; is the server message daemon, and &winbindd; is the daemon that handles communication with domain controllers.
+	</para>
 
-<para>
-If Samba is <emphasis>not</emphasis> running as a WINS server, then there will be one single instance of
- &nmbd; running on your system. If it is running as a WINS server, then there will be
-two instances &smbmdash; one to handle the WINS requests.
-</para>
+	<para>
+	If Samba is <emphasis>not</emphasis> running as a WINS server, then there will be one single instance of
+	 &nmbd; running on your system. If it is running as a WINS server, then there will be
+	two instances &smbmdash; one to handle the WINS requests.
+	</para>
 
-<para>
-&smbd; handles all connection requests. It spawns a new process for each client
-connection made. That is why you may see so many of them, one per client connection.
-</para>
+	<para>
+	&smbd; handles all connection requests. It spawns a new process for each client
+	connection made. That is why you may see so many of them, one per client connection.
+	</para>
 
-<para>
-&winbindd; will run as one or two daemons, depending on whether or not it is being
-run in <emphasis>split mode</emphasis> (in which case there will be two instances).
-</para>
+	<para>
+	&winbindd; will run as one or two daemons, depending on whether or not it is being
+	run in <emphasis>split mode</emphasis> (in which case there will be two instances).
+	</para>
 
-</sect2>
+	</sect2>
 
 	<sect2>
 		<title>Error Message: open_oplock_ipc</title>
 
-	<para>An error message is observed in the log files when &smbd; is started: <quote>open_oplock_ipc: Failed to get local UDP socket
-	for address 100007f. Error was Cannot assign requested.</quote></para>
+	<para>
+	An error message is observed in the log files when &smbd; is started: <quote>open_oplock_ipc: Failed to
+	get local UDP socket for address 100007f. Error was Cannot assign requested.</quote>
+	</para>
 
-	<para>Your loopback device isn't working correctly. Make sure it is configured correctly. The loopback
+	<para>
+	Your loopback device isn't working correctly. Make sure it is configured correctly. The loopback
 	device is an internal (virtual) network device with the IP address <emphasis>127.0.0.1</emphasis>.
-	Read your OS documentation for details on how to configure the loopback on your system.</para>
+	Read your OS documentation for details on how to configure the loopback on your system.
+	</para>
 
 	</sect2>