syncing up docs, examples, & packaging from 3.0

(This used to be commit dd1348c566b4700ea01bd89639e2d3330c878167)

1 files changed, 154 insertions, 96 deletions

diff --git a/docs/docbook/projdoc/UNIX_INSTALL.xml b/docs/docbook/projdoc/UNIX_INSTALL.xml
index 6a38e60c0e..65a26702c4 100644
--- a/docs/docbook/projdoc/UNIX_INSTALL.xml
+++ b/docs/docbook/projdoc/UNIX_INSTALL.xml
@@ -3,7 +3,8 @@
 	&author.tridge;
 	&author.jelmer;
 	&author.jht;
-	<author><firstname>Karl</firstname><surname>Auer</surname></author>
+	&author.kauer;
+	&author.danshearer;
 	<!-- Isn't some of this written by others as well? -->
 
 </chapterinfo>
@@ -11,52 +12,89 @@
 <title>How to Install and Test SAMBA</title>
 
 <sect1>
-	<title>Obtaining and installing samba</title>
+	<title>Obtaining and Installing Samba</title>
 
 	<para>
-	Binary packages of samba are included in almost any Linux or
+	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 homepage</ulink>.
+	<ulink url="http://samba.org/">the Samba homepage</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">the chapter about compiling samba from scratch</link>.</para>
-
-	<para>If you have already installed samba, or if your operating system
-	was pre-installed with samba, then you may not need to bother with this
-	chapter. On the other hand, you may want to read this chapter anyhow
-	for information about updating samba.</para>
+	<para>If you need to compile Samba from source, check 
+	<link linkend="compiling"></link>.</para>
 
 </sect1>
 
 <sect1>
-	<title>Configuring samba (smb.conf)</title>
+	<title>Configuring Samba (smb.conf)</title>
 
 	<para>
-	Samba's configuration is stored in the &smb.conf; file, 
-	that usually resides in <filename>/etc/samba/smb.conf</filename> 
+	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.
+	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 seperated by an 
+	equality sign (=). The file is just a plain-text file, so you can 
+	open and edit it with your favorite editing tool.</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><link linkend="smbconfminimal"/> contains a very minimal &smb.conf;.
+	<indexterm><primary>minimal configuration</primary></indexterm>
+</para>
+
+	<smbconfexample id="smbconfminimal">
+		<title>A minimal smb.conf</title>
+
+		<smbconfsection>[global]</smbconfsection>
+		<smbconfoption><name>workgroup</name><value>WKG</value></smbconfoption>
+		<smbconfoption><name>netbios name</name><value>MYNAME</value></smbconfoption>
+		<smbconfsection>[share1]</smbconfsection>
+		<smbconfoption><name>path</name><value>/tmp</value></smbconfoption>
+
+		<smbconfsection>[share2]</smbconfsection>
+		<smbconfoption><name>path</name><value>/my_shared_folder</value></smbconfoption>
+		<smbconfoption><name>comment</name><value>Some random files</value></smbconfoption>
+	</smbconfexample>
+
+</sect2>
 	
 <sect2>
 	<title>Example Configuration</title>
 	
 	<para>
 	There are sample configuration files in the examples subdirectory in the
-	distribution. I suggest you read them carefully so you can see how the options
-	go together in practice. See the man page for all the options.
+	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.
 	</para>
 
 	<para>
-	The simplest useful configuration file would be something like this:
+	The simplest useful configuration file would contain something like shown in
+	<link linkend="simple-example"></link>.
 	</para>
 
 	<para>
-	<smbconfexample>
-		<title>Simplest possible smb.conf file</title>
+	<indexterm><primary>simple configuration</primary></indexterm>
+	<smbconfexample id="simple-example">
+		<title>Another simple smb.conf File</title>
 <smbconfsection>[global]</smbconfsection>
 <smbconfoption><name>workgroup</name><value>&example.workgroup;</value></smbconfoption>
 
@@ -68,36 +106,41 @@
 	
 	<para>
 	This will allow connections by anyone with an account on the server, using either
-	their login name or <smbconfsection>homes</smbconfsection>" as the service name.
-	(Note that the workgroup that Samba must also be set.)
+	their login name or <smbconfsection>homes</smbconfsection> as the service name.
+	(Note: The workgroup that Samba should appear in must also be set. The default
+	workgroup name is WORKGROUP.)
 	</para>
 	
 	<para>
-	Make sure you put the &smb.conf; file in the correct place 
-	(usually in <filename>/etc/samba</filename>).
+	Make sure you put the &smb.conf; file in the correct place.
 	</para>
 
 	<para>
 	For more information about security settings for the 
 	<smbconfsection>[homes]</smbconfsection> share please refer to 
-	<link linkend="securing-samba">"Securing Samba"</link>.
+	<link linkend="securing-samba"></link>.
 	</para>
 
 <sect3>
-	<title>Test your config file with <command>testparm</command></title>
+	<title>Test Your Config File with <command>testparm</command></title>
 
 	<para>
-	It's important that you test the validity of your &smb.conf;
-	file using the &testparm; program. If testparm runs OK
-	then it will list the loaded services. If not it will give an error message.
+	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>
 
-	<para>
-	Make sure it runs OK and that the services look reasonable before proceeding.
-	</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>
+
+	
 
 	<para>
-	Always run testparm again when you change &smb.conf;!
+	Always run testparm again whenever the &smb.conf; file is changed!
 	</para>
 
 </sect3>
@@ -107,68 +150,68 @@
 	<title>SWAT</title>
 
 	<para>
-	SWAT is a web-based interface that helps you configure samba. 
-	SWAT might not be available in the samba package on your platform, 
-	but in a separate package. Please read the swat manpage 
-	on compiling, installing and configuring swat from source.
+	<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 manpage 
+	on compiling, installing and configuring SWAT from source.
 	</para>
 
 	<para>
-	To launch SWAT just run your favorite web browser and 
-	point it at <ulink url="http://localhost:901/" noescape="1">http://localhost:901/</ulink>. Replace
-	<replaceable>localhost</replaceable>
-	with the name of the computer you are running samba on if you 
-	are running samba on a different computer than your browser.
+	To launch SWAT, just run your favorite Web browser and point it to
+	<ulink url="http://localhost:901/" noescape="1">http://localhost:901/</ulink>.
+	Replace <replaceable>localhost</replaceable> with the name of the computer on which
+	Samba is running if that is a different computer than your browser.
 	</para>
 
 	<para>
-	Note that you can attach to SWAT from any IP connected 
-	machine but connecting from a remote machine leaves your 
-	connection open to password sniffing as passwords will be sent 
-	in the clear over the wire. 
+	SWAT can be used from a browser on any IP-connected machine, but be aware that connecting from a remote
+	machine leaves your connection open to password sniffing as passwords will be sent over the wire in the clear. 
 	</para>
+
+	<para>More information about SWAT can be found in <link linkend="SWAT"/>.</para>
+
 </sect2>
+
 </sect1>
 
 <sect1>
-	<title>Try listing the shares available on your 
-	server</title>
+	<title>List Shares Available on the Server</title>
+
+	<para>
+	To list shares that are available from the configured Samba server execute the
+	following command:
+	</para>
 
 <para><screen>
 &prompt;<userinput>smbclient -L <replaceable>yourhostname</replaceable></userinput>
 </screen></para>
 
-	<para>You should get back a list of shares available on 
-	your server. If you don't then something is incorrectly setup. 
-	Note that this method can also be used to see what shares 
-	are available on other LanManager clients (such as WfWg).</para>
-
-	<para>If you choose user level security then 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 -U% to the command line. This will not work 
-	with non-Samba servers)</para>
+	<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>
+
+	<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>
 </sect1>
 
 <sect1>
-	<title>Try connecting with the unix client</title>
+	<title>Connect with a UNIX Client</title>
 	
 	<para>
+	Enter the following command:
 <screen>
 &prompt;<userinput>smbclient <replaceable> //yourhostname/aservice</replaceable></userinput>
 </screen></para>
 	
-	<para>Typically the <replaceable>yourhostname</replaceable> 
-	would be the name of the host where you installed &smbd;. 
-	The <replaceable>aservice</replaceable> is 
-	any service you have defined in the &smb.conf;
-	file. Try your user name if you just have a <smbconfsection>[homes]</smbconfsection>
-	section
-	in &smb.conf;.</para>
+	<para>Typically <replaceable>yourhostname</replaceable> is the name of the host on which &smbd;
+	has been installed. The <replaceable>aservice</replaceable> is any service that has been defined in the &smb.conf;
+	file. Try your user name if you just have a <smbconfsection>[homes]</smbconfsection> section in the &smb.conf; file.</para>
 
-	<para>For example if your unix host is <replaceable>bambi</replaceable>
-	and your login name is <replaceable>fred</replaceable> you would type:</para>
+	<para>Example: If the UNIX host is called <replaceable>bambi</replaceable> and a valid login name
+	is <replaceable>fred</replaceable>, you would type:</para>
 
 <para><screen>
 &prompt;<userinput>smbclient //<replaceable>bambi</replaceable>/<replaceable>fred</replaceable></userinput>
@@ -176,15 +219,21 @@
 </sect1>
 
 <sect1>
-	<title>Try connecting from another SMB client</title>
+	<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>Try mounting disks. from a DOS, Windows or OS/2 client, eg:</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>Try printing. eg:</para>
+	<para>Try printing, e.g.</para>
 
 	<para>
 <screen>
@@ -199,10 +248,12 @@
 <sect1>
 	<title>What If Things Don't Work?</title>
 	
-	<para>Then you might read the file chapter <link linkend="diagnosis">diagnosis</link>
-	and the FAQ. If you are still stuck then refer to <link linkend="problems">"Analysing and solving problems"</link>.
-	Samba has been successfully installed at thousands of sites worldwide,
-	so maybe someone else has hit your problem and has overcome it.</para>
+	<para>You might want to read <link linkend="diagnosis"></link>.
+	If you are still stuck, refer to <link linkend="problems"></link>.
+	Samba has been successfully installed at thousands of sites worldwide.
+	It is unlikely that your particular problem is unique, so it might be
+	productive to perform an Internet search to see if someone else has encountered
+	your problem and has found a way to overcome it.</para>
 
 </sect1>
 
@@ -210,55 +261,62 @@
 <title>Common Errors</title>
 
 <para>
-The following questions and issues get raised on the samba mailing list over and over again.
+The following questions and issues are raised repeatedly on the Samba mailing list.
 </para>
 
 <sect2>
-	<title>Large number of smbd processes</title>
+	<title>Large Number of smbd Processes</title>
 
 <para>
-Samba consists on three core programs:
-&nmbd;, &smbd;, &winbindd;. &nmbd; is the name server message daemon,
-&smbd; is the server message daemon, &winbindd; is the daemon that
-handles communication with Domain Controllers.
+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 your system is NOT running as a WINS server, then there will be one (1) single instance of
+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 (2) instances - one to handle the WINS requests.
+two instances &smbmdash; one to handle the WINS requests.
 </para>
 
 <para>
-&smbd; handles ALL connection requests and then spawns a new process for each client
-connection made. That is why you are seeing so many of them, one (1) per client connection.
+&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 "split mode" (in which case there will be two instances).
+run in <emphasis>split mode</emphasis> (in which case there will be two instances).
 </para>
 
 </sect2>
 
 	<sect2>
-		<title>"open_oplock_ipc: Failed to get local UDP socket for address 100007f. Error was Cannot assign requested"</title>
-	<para>Your loopback device isn't working correctly. Make sure it's configured properly. The loopback device is an internal (virtual) network device with 
-		the ip address 127.0.0.1. Read your OS documentation for details 
-	on how to configure the loopback on your system.</para>
+		<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>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>
+
 	</sect2>
 
 	<sect2>
-		<title>"<errorname>The network name cannot be found</errorname>"</title>
+		<title><quote><errorname>The network name cannot be found</errorname></quote></title>
 
 		<para>
-			This error can be caused by one of these misconfigurations:
+		This error can be caused by one of these misconfigurations:
 		</para>
 
 		<itemizedlist>
-			<listitem><para>You specified an nonexisting <smbconfoption><name>path</name></smbconfoption> for the share in &smb.conf; </para></listitem>
+			<listitem><para>You specified an nonexisting path
+			for the share in &smb.conf;.</para></listitem>
+
 			<listitem><para>The user you are trying to access the share with does not 
-					have sufficient permissions to access the <smbconfoption><name>path</name></smbconfoption> for the share. Both read (r) and access (x) should be possible.</para></listitem>
+			have sufficient permissions to access the path for
+			the share. Both read (r) and access (x) should be possible.</para></listitem>
+
 			<listitem><para>The share you are trying to access does not exist.</para></listitem>
 	</itemizedlist>