Final Addition. Copy layout is next.

(This used to be commit 6e81f1b33945fb4271172ed91c18a2a164bc5dff)

3 files changed, 333 insertions, 4 deletions

diff --git a/docs/Samba3-HOWTO/TOSHARG-ConfigSmarts.xml b/docs/Samba3-HOWTO/TOSHARG-ConfigSmarts.xml
new file mode 100644
index 0000000000..7c9cfcbc04
--- /dev/null
+++ b/docs/Samba3-HOWTO/TOSHARG-ConfigSmarts.xml
@@ -0,0 +1,322 @@
+<?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="cfgsmarts">
+<chapterinfo>
+	&author.jht;
+	<pubdate>June 30, 2005</pubdate>
+</chapterinfo>
+<title>Advanced Configuration Techniques</title>
+
+<para>
+Since the release of the first edition of this book there have been repeated requests to better document
+configuration techniques that may help a network administrator to get more out of Samba. Some users have asked
+for documentation regarding the use of the <smbconfoption name="include">file-name</smbconfoption> parameter.
+</para>
+
+<para>
+Commencing around mid-2004 there has been increasing interest in the ability to host multiple Samba servers on
+one machine. There has also been an interest in the hosting of multiple Samba server personalities on one
+server.
+</para>
+
+<para>
+Feedback from technical reviewers made the inclusion of this chapter a necessity. So finally, here is an attempt
+to answer the questions that have to date not been adequately addressed. Additional user input is welcome as
+it will help this chapter to mature. What is presented here is just a small beginning.
+</para>
+
+<para>
+There are a number of ways in which multiple servers can be hosted on a single Samba server. Multiple server
+hosting makes it possible to host multiple domain controllers on one machine. Each such machine is
+independent, and each can be stopped or started without affecting another.
+</para>
+
+<para>
+Sometimes it is desirable to host multiple servers, each with its own security mode. For example, a single
+UNIX/Linux host may be a domain member server (DMS) as well as a generic anonymous print server. In this case,
+only domain member machines and domain users can access the DMS, but even guest users can access the generic
+print server. Another example of a situation where it may be beneficial to host a generic (anonymous) server
+is to host a CDROM server.
+</para>
+
+<para>
+Some environments dictate the need to have separate servers, each with their own resources, each of which are
+accessible only by certain users or groups. This is one of the simple, but highly effective, capabilities
+</para>
+
+<sect1>
+<title>Implementation</title>
+
+<para>
+</para>
+
+<sect2>
+<title>Multiple Server Hosting</title>
+
+<para>
+The use of multiple server hosting involves running multiple separate instances of Samba, each with it's own
+configuration file. This method is complicated by the fact that each instance of &nmbd;, &smbd; and &winbindd;
+must have write access to entirely separate TDB files. The ability to keep separate the TDB files used by
+&nmbd;, &smbd; and &winbindd; can be enabled either by recompiling Samba for each server hosted so each has its
+own default TDB directories, or by configuring these in the &smb.conf; file, in which case each instance of
+&nmbd;, &smbd; and &winbindd; must be told to start up with its own &smb.conf; configuration file.
+</para>
+
+<para>
+Each instance should operate on its own IP address (that independent IP address can be an IP Alias).
+Each instance of &nmbd;, &smbd; and &winbindd; should listen only on its own IP socket. This can be secured
+using the <smbconfoption name="socket address"/> parameter. Each instance of the Samba server will have its
+own SID also, this means that the servers are discrete and independent of each other.
+</para>
+
+<para>
+The user of multiple server hosting is non-trivial, and requires careful configuration of each aspect of
+process management and start up. The &smb.conf; parameters that must be carefully configured includes:
+<smbconfoption name="private dir"/>, <smbconfoption name="pid directory"/>,<smbconfoption name="lock
+directory"/>, <smbconfoption name="interfaces"/>, <smbconfoption name="bind interfaces only"/>, <smbconfoption
+name="netbios name"/>, <smbconfoption name="workgroup"/>, <smbconfoption name="socket address"/>.
+</para>
+
+<para>
+Those who elect to use this method of creating multiple Samba servers must have the ability to read and follow
+the Samba source code, and to modify it as needed. This mode of deployment is considered beyond the scope of
+this book. However, if someone will contribute more comprehensive documentation we will gladly review it, and
+if it is suitable extend this section of this chapter. Until such documentation becomes available the hosting
+of multiple samba servers on a single host is considered not supported for Samba-3 by the Samba Team.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Multiple Virtual Server Personalities</title>
+
+<para>
+Samba has the ability to host multiple virtual servers, each of which have their own personality.  This is
+achieved by configuring an &smb.conf; file that is common to all personalities hosted.  Each server
+personality is hosted using its own <smbconfoption name="netbios alias"/> name, and each has its own distinct
+<smbconfoption name="[global]"/> section. Each server may have its own stanzas for services and meta-services.
+</para>
+
+<para>
+When hosting multiple virtual servers, each with their own personality, each can be in a different workgroup.
+Only the primary server can be a domain member or a domain controller. The personality is defined by the
+combination of the <smbconfoption name="security"/> mode it is operating in, the <smbconfoption name="netbios
+alias"/> it has, and the <smbconfoption name="workgroup"/> that is defined for it.
+</para>
+
+<para>
+This configuration style can be used either with NetBIOS names, or using NetBIOS-less SMB over TCP services.
+If run using NetBIOS mode (the most common method) it is important that the parameter <smbconfoption name="smb
+ports">139</smbconfoption> should be specified in the primary &smb.conf; file. Failure to do this will result
+in Samba operating over TCP port 445 and problematic operation at best, and at worst only being able to obtain
+the functionality that is specified in the primary &smb.conf; file. The use of NetBIOS over TCP/IP using only
+TCP port 139 means that the use of the <literal>%L</literal> macro is fully enabled. If the <smbconfoption
+name="smb ports">139</smbconfoption> is not specified (the default is <parameter>445 139</parameter>, or if
+the value of this parameter is set at <parameter>139 445</parameter> then the <literal>%L</literal> parameter
+is not serviceable.
+</para>
+
+<para>
+It is possible to host multiple servers, each with their own personality, using port 445 (the NetBIOS-less SMB
+port), in which case the <literal>%i</literal> parameter can be used to provide separate server identities (by
+IP Address). Each can have its own <smbconfoption name="security"/> mode. It will be necessary to use the
+<smbconfoption name="interfaces"/>, <smbconfoption name="bind interfaces only"/> and IP aliases in addition to
+the <smbconfoption name="netbios name"/> parameters to create the virtual servers. This method is considerably
+more complex than that using NetBIOS names only using TCP port 139.
+</para>
+
+<para>
+Consider an example environment that consists of a standalone, user-mode security Samba server and a read-only
+Windows 95 file server that has to be replaced. Instead of replacing the Windows 95 machine with a new PC, it
+is possible to add this server as a read-only anonymous file server that is hosted on the Samba server. Here
+are some parameters:
+</para>
+
+<para>
+The Samba server is called <literal>ELASTIC</literal>, its workgroup name is <literal>ROBINSNEST</literal>.
+The CDROM server is called <literal>CDSERVER</literal> and its workgroup is <literal>ARTSDEPT</literal>. A
+possible implementation is shown here:
+</para>
+
+<para>
+The &smb.conf; file for the master server is shown in <link linkend="elastic">Elastic smb.conf File</link>.
+This file is placed in the <filename>/etc/samba</filename> directory. Only the &nmbd; and the &smbd; daemons
+are needed. When started the server will appear in Windows Network Neighborhood as the machine
+<literal>ELASTIC</literal> under the workgroup <literal>ROBINSNEST</literal>. It is helpful if the Windows
+clients that must access this server are also in the workgroup <literal>ROBINSNEST</literal> as this will make
+browsing much more reliable.
+</para>
+
+<example id="elastic">
+<title>Elastic smb.conf File</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">ROBINSNEST</smbconfoption>
+<smbconfoption name="netbios name">ELASTIC</smbconfoption>
+<smbconfoption name="netbios aliases">CDSERVER</smbconfoption>
+<smbconfoption name="smb ports">139</smbconfoption>
+<smbconfoption name="printcap name">cups</smbconfoption>
+<smbconfoption name="disable spoolss">Yes</smbconfoption>
+<smbconfoption name="show add printer wizard">No</smbconfoption>
+<smbconfoption name="printing">cups</smbconfoption>
+<smbconfoption name="include">/etc/samba/smb-%L.conf</smbconfoption>
+
+<smbconfsection name="[homes]"/>
+<smbconfoption name="comment">Home Directories</smbconfoption>
+<smbconfoption name="valid users">%S</smbconfoption>
+<smbconfoption name="read only">No</smbconfoption>
+<smbconfoption name="browseable">No</smbconfoption>
+
+<smbconfsection name="[office]"/>
+<smbconfoption name="comment">Data</smbconfoption>
+<smbconfoption name="path">/data</smbconfoption>
+<smbconfoption name="read only">No</smbconfoption>
+
+<smbconfsection name="[printers]"/>
+<smbconfoption name="comment">All Printers</smbconfoption>
+<smbconfoption name="path">/var/spool/samba</smbconfoption>
+<smbconfoption name="create mask">0600</smbconfoption>
+<smbconfoption name="guest ok">Yes</smbconfoption>
+<smbconfoption name="printable">Yes</smbconfoption>
+<smbconfoption name="use client driver">Yes</smbconfoption>
+<smbconfoption name="browseable">No</smbconfoption>
+</smbconfblock>
+</example>
+
+<para>
+The configuration file for the CDROM server is listed in <link linkend="cdserver">CDROM Server
+smb-cdserver.conf file</link>. This file is called <filename>smb-cdserver.conf</filename> and it should be
+located in the <filename>/etc/samba</filename> directory. Machines that are in the workgroup
+<literal>ARTSDEPT</literal> will be able to browse this server freely.
+</para>
+
+<example id="cdserver">
+<title>CDROM Server smb-cdserver.conf file</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">ARTSDEPT</smbconfoption>
+<smbconfoption name="netbios name">CDSERVER</smbconfoption>
+<smbconfoption name="map to guest">Bad User</smbconfoption>
+<smbconfoption name="guest ok">Yes</smbconfoption>
+
+<smbconfsection name="[carousel]"/>
+<smbconfoption name="comment">CDROM Share</smbconfoption>
+<smbconfoption name="path">/export/cddata</smbconfoption>
+<smbconfoption name="read only">Yes</smbconfoption>
+<smbconfoption name="guest ok">Yes</smbconfoption>
+</smbconfblock>
+</example>
+
+<para>
+The two servers have different resources and are in separate workgroups. The server <literal>ELASTIC</literal>
+can only be accessed by uses who have an appropriate account on the host server. All users will be able to
+access the CDROM data that is stored in the <filename>/export/cddata</filename> directory. File system
+permissions should set so that the <literal>others</literal> user has read-only access to the directory and its
+contents. The files can be owned by root (any user other than the nobody account).
+</para>
+
+</sect2>
+
+<sect2>
+<title>Multiple Virtual Server Hosting</title>
+
+<para>
+In this example, the requirement is for a primary domain controller for the domain called
+<literal>MIDEARTH</literal>. The PDC will be called <literal>MERLIN</literal>. An extra machine called
+<literal>SAURON</literal> is required. Each machine will have only its own shares. Both machines belong to the
+same domain/workgroup.
+</para>
+
+<para>
+The master &smb.conf; file is shown in <link linkend="mastersmbc">the Master smb.conf File Global Section</link>.
+The two files that specify the share information for each server are shown in <link linkend="merlinsmbc">the
+smb-merlin.conf File Share Section</link>, and <link linkend="sauronsmbc">the smb-sauron.conf File Share
+Section</link>. All three files are locate in the <filename>/etc/samba</filename> directory.
+</para>
+
+<example id="mastersmbc">
+<title>Master smb.conf File Global Section</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">MIDEARTH</smbconfoption>
+<smbconfoption name="netbios name">MERLIN</smbconfoption>
+<smbconfoption name="netbios aliases">SAURON</smbconfoption>
+<smbconfoption name="passdb backend">tdbsam</smbconfoption>
+<smbconfoption name="smb ports">139</smbconfoption>
+<smbconfoption name="syslog">0</smbconfoption>
+<smbconfoption name="printcap name">CUPS</smbconfoption>
+<smbconfoption name="show add printer wizard">No</smbconfoption>
+<smbconfoption name="add user script">/usr/sbin/useradd -m '%u'</smbconfoption>
+<smbconfoption name="delete user script">/usr/sbin/userdel -r '%u'</smbconfoption>
+<smbconfoption name="add group script">/usr/sbin/groupadd '%g'</smbconfoption>
+<smbconfoption name="delete group script">/usr/sbin/groupdel '%g'</smbconfoption>
+<smbconfoption name="add user to group script">/usr/sbin/usermod -G '%g' '%u'</smbconfoption>
+<smbconfoption name="add machine script">/usr/sbin/useradd -s /bin/false -d /var/lib/nobody '%u'</smbconfoption>
+<smbconfoption name="logon script">scripts\login.bat</smbconfoption>
+<smbconfoption name="logon path"> </smbconfoption>
+<smbconfoption name="logon drive">X:</smbconfoption>
+<smbconfoption name="domain logons">Yes</smbconfoption>
+<smbconfoption name="preferred master">Yes</smbconfoption>
+<smbconfoption name="wins support">Yes</smbconfoption>
+<smbconfoption name="printing">CUPS</smbconfoption>
+<smbconfoption name="include">/etc/samba/smb-%L.conf</smbconfoption>
+</smbconfblock>
+</example>
+
+<example id="merlinsmbc">
+<title>MERLIN smb-merlin.conf File Share Section</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">MIDEARTH</smbconfoption>
+<smbconfoption name="netbios name">MERLIN</smbconfoption>
+
+<smbconfsection name="[homes]"/>
+<smbconfoption name="comment">Home Directories</smbconfoption>
+<smbconfoption name="valid users">%S</smbconfoption>
+<smbconfoption name="read only">No</smbconfoption>
+<smbconfoption name="browseable">No</smbconfoption>
+
+<smbconfsection name="[office]"/>
+<smbconfoption name="comment">Data</smbconfoption>
+<smbconfoption name="path">/data</smbconfoption>
+<smbconfoption name="read only">No</smbconfoption>
+
+<smbconfsection name="[netlogon]"/>
+<smbconfoption name="comment">NETLOGON</smbconfoption>
+<smbconfoption name="path">/var/lib/samba/netlogon</smbconfoption>
+<smbconfoption name="read only">Yes</smbconfoption>
+<smbconfoption name="browseable">No</smbconfoption>
+
+<smbconfsection name="[printers]"/>
+<smbconfoption name="comment">All Printers</smbconfoption>
+<smbconfoption name="path">/var/spool/samba</smbconfoption>
+<smbconfoption name="printable">Yes</smbconfoption>
+<smbconfoption name="use client driver">Yes</smbconfoption>
+<smbconfoption name="browseable">No</smbconfoption>
+</smbconfblock>
+</example>
+
+<example id="sauronsmbc">
+<title>SAURON smb-sauron.conf File Share Section</title>
+<smbconfblock>
+<smbconfcomment>Global parameters</smbconfcomment>
+<smbconfsection name="[global]"/>
+<smbconfoption name="workgroup">MIDEARTH</smbconfoption>
+<smbconfoption name="netbios name">SAURON</smbconfoption>
+
+<smbconfsection name="[www]"/>
+<smbconfoption name="comment">Web Pages</smbconfoption>
+<smbconfoption name="path">/srv/www/htdocs</smbconfoption>
+<smbconfoption name="read only">No</smbconfoption>
+</smbconfblock>
+</example>
+
+</sect2>
+
+</sect1>
+
+</chapter>
diff --git a/docs/Samba3-HOWTO/conventions.xml b/docs/Samba3-HOWTO/conventions.xml
index d4bbde8f85..1b3848405c 100644
--- a/docs/Samba3-HOWTO/conventions.xml
+++ b/docs/Samba3-HOWTO/conventions.xml
@@ -11,9 +11,16 @@
     <itemizedlist>
       <listitem>
 	<para>
-	TOSHARG is used as an abbreviation for the book, <quote>The Official Samba-3
-	HOWTO and Reference Guide,</quote> Editors: John H. Terpstra and Jelmer R. Vernooij,
-	Publisher: Prentice Hall, ISBN: 0131453556.
+	TOSHARG2 is used as an abbreviation for the book, <quote>The Official Samba-3
+	HOWTO and Reference Guide, Second Edition</quote> Editors: John H. Terpstra and Jelmer R. Vernooij,
+	Publisher: Prentice Hall, ISBN: 0131882228.
+	</para>
+      </listitem>
+
+      <listitem>
+	<para>
+	S3bE2 is used as an abbreviation for the book, <quote>Samba-3 by Example, Second Edition</quote> 
+	Editors: John H. Terpstra, Publisher: Prentice Hall, ISBN: 013188221X.
 	</para>
       </listitem>
 
diff --git a/docs/Samba3-HOWTO/index.xml b/docs/Samba3-HOWTO/index.xml
index 5404639325..609f7b174e 100644
--- a/docs/Samba3-HOWTO/index.xml
+++ b/docs/Samba3-HOWTO/index.xml
@@ -128,7 +128,7 @@ The chapters in this part each cover specific Samba features.
 	<xi:include href="TOSHARG-Backup.xml"/>
 	<xi:include href="TOSHARG-HighAvailability.xml"/>
 	<xi:include href="TOSHARG-LargeFile.xml"/>
-	<!--	<xi:include href="TOSHARG-SecureLDAP.xml"/> -->
+	<xi:include href="TOSHARG-ConfigSmarts.xml"/>
 
 </part>