Large number of small fixes to the layout and the build system.

(This used to be commit 73fac0653c774a8ed8654b064fd63d4e486f6b0f)

1 files changed, 382 insertions, 0 deletions

diff --git a/docs/Samba3-HOWTO/TOSHARG-Install.xml b/docs/Samba3-HOWTO/TOSHARG-Install.xml
new file mode 100644
index 0000000000..1cec899cdd
--- /dev/null
+++ b/docs/Samba3-HOWTO/TOSHARG-Install.xml
@@ -0,0 +1,382 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+<chapter id="install">
+<chapterinfo>
+	&author.tridge;
+	&author.jelmer;
+	&author.jht;
+	&author.kauer;
+	&author.danshearer;
+	<!-- Isn't some of this written by others as well? -->
+
+</chapterinfo>
+
+<title>How to Install and Test SAMBA</title>
+
+<sect1>
+	<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.
+	</para>
+
+	<para>If you need to compile Samba from source, check 
+	<link linkend="compiling">How to compile Samba.</link>
+	</para>
+
+</sect1>
+
+<sect1>
+	<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.
+	</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 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">Following example</link> contains a very minimal &smb.conf;.
+	<indexterm><primary>minimal configuration</primary></indexterm>
+</para>
+
+	<smbconfexample id="smbconfminimal">
+		<title>A minimal smb.conf</title>
+
+		<smbconfsection name="[global]"/>
+		<smbconfoption name="workgroup">WKG</smbconfoption>
+		<smbconfoption name="netbios name">MYNAME</smbconfoption>
+		<smbconfsection name="[share1]"/>
+		<smbconfoption name="path">/tmp</smbconfoption>
+
+		<smbconfsection name="[share2]"/>
+		<smbconfoption name="path">/my_shared_folder</smbconfoption>
+		<smbconfoption name="comment">Some random files</smbconfoption>
+	</smbconfexample>
+
+</sect2>
+
+<sect2>
+	<title>Starting Samba</title>
+
+	<para>
+	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.
+	</para>
+
+	<para>
+	The Samba server is made up of the following daemons:
+	</para>
+
+	<variablelist>
+		<varlistentry><term>nmbd</term>
+			<listitem><para>
+			<indexterm><primary>smbd</primary></indexterm>
+			<indexterm><primary>starting samba</primary><secondary>smbd</secondary></indexterm>
+			This daemon handles all name registration and resolution requests. It is the primary vehicle involved
+			in network browsing. It handles all UDP based protocols. The <command>nmbd</command> daemon should
+			be the first command started as part of the Samba start-up process.
+			</para></listitem>
+		</varlistentry>
+
+		<varlistentry><term>smbd</term>
+			<listitem><para>
+			<indexterm><primary>nmbd</primary></indexterm>
+			<indexterm><primary>starting samba</primary><secondary>nmbd</secondary></indexterm>
+			This daemon handles all TCP/IP based connection services for file and print based operations. It also
+			manages local authentication. It should be started immediately following the start-up of <command>nmbd</command>.
+			</para></listitem>
+		</varlistentry>
+
+		<varlistentry><term>winbindd</term>
+			<listitem><para>
+			<indexterm><primary>winbindd</primary></indexterm>
+			<indexterm><primary>starting samba</primary><secondary>winbindd</secondary></indexterm>
+			This daemon should be started when Samba is a member of a Windows NT4 or ADS Domain. It is also needed when
+			Samba has trust relationships with another Domain. The <command>winbindd</command> daemon will check the
+			&smb.conf; file for the presence of the <parameter>idmap uid</parameter> and <parameter>idmap gid</parameter>
+			parameters. If they are not found <command>winbindd</command> will bail-out and refuse to start.
+			</para></listitem>
+		</varlistentry>
+	</variablelist>
+
+	<para>
+	When Samba has been packaged by an operating system vendor the start-up 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 start-up.
+	</para>
+
+</sect2>
+	
+<sect2>
+	<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.
+	</para>
+
+	<para>
+	The simplest useful configuration file would contain something like shown in
+	<link linkend="simple-example">the next example</link>.
+	</para>
+
+	<para>
+	<indexterm><primary>simple configuration</primary></indexterm>
+	<smbconfexample id="simple-example">
+		<title>Another simple smb.conf File</title>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">&example.workgroup;</smbconfoption>
+
+<smbconfsection name="[homes]"/>
+<smbconfoption name="guest ok">no</smbconfoption>
+<smbconfoption name="read only">no</smbconfoption>
+	</smbconfexample>
+	</para>
+	
+	<para>
+	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
+	workgroup name is WORKGROUP.)
+	</para>
+	
+	<para>
+	Make sure you put the &smb.conf; file in the correct place.
+	</para>
+
+	<para>
+	For more information about security settings for the 
+	<smbconfsection name="[homes]"/> share please refer to 
+	<link linkend="securing-samba">Securing Samba</link> chapter.
+	</para>
+
+<sect3>
+	<title>Test Your Config File with <command>testparm</command></title>
+
+	<para>
+	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>
+
+	
+
+	<para>
+	Always run testparm again whenever the &smb.conf; file is changed!
+	</para>
+
+</sect3>
+</sect2>
+
+<sect2>
+	<title>SWAT</title>
+
+	<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.
+	</para>
+
+	<para>
+	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>
+	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">corresponding chapter</link>.</para>
+
+</sect2>
+
+</sect1>
+
+<sect1>
+	<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 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>Connect with a UNIX Client</title>
+	
+	<para>
+	Enter the following command:
+<screen>
+&prompt;<userinput>smbclient <replaceable> //yourhostname/aservice</replaceable></userinput>
+</screen></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 name="[homes]"/> section in the &smb.conf; file.</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>
+</screen></para>
+</sect1>
+
+<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>Try printing, e.g.</para>
+
+	<para>
+<screen>
+&dosprompt;<userinput>net use lpt1:	\\servername\spoolservice</userinput>
+</screen></para>
+
+<para>
+<screen>&dosprompt;<userinput>print filename</userinput>
+</screen></para>
+</sect1>
+
+<sect1>
+	<title>What If Things Don't Work?</title>
+	
+	<para>You might want to read <link linkend="diagnosis">The Samba Checklist</link>.
+	If you are still stuck, refer to <link linkend="problems">Analyzing and Solving Samba Problems</link> chapter.
+	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>
+
+<sect1>
+<title>Common Errors</title>
+
+<para>
+The following questions and issues are raised repeatedly on the Samba mailing list.
+</para>
+
+<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>
+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>
+&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>
+		<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><quote><errorname>The network name cannot be found</errorname></quote></title>
+
+		<para>
+		This error can be caused by one of these mis-configurations:
+		</para>
+
+		<itemizedlist>
+			<listitem><para>You specified an non-existing 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 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>
+
+	</sect2>
+</sect1>
+
+</chapter>