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

(This used to be commit 73fac0653c774a8ed8654b064fd63d4e486f6b0f)

1 files changed, 584 insertions, 0 deletions

diff --git a/docs/Samba3-ByExample/SBE-preface.xml b/docs/Samba3-ByExample/SBE-preface.xml
new file mode 100644
index 0000000000..8c99546a6c
--- /dev/null
+++ b/docs/Samba3-ByExample/SBE-preface.xml
@@ -0,0 +1,584 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE preface PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+<preface id="preface">
+  <title>Preface</title>
+
+	<para>
+	Network administrators live busy lives. We face distractions and pressures
+	that drive us to seek proven, working case scenarios that can be easily
+	implemented. Often this approach lands us in trouble. There is a 
+	saying that, geometrically speaking, the shortest distance between two 
+	points is a straight line, but practically we find that the quickest 
+	route to a stable network solution is the long way around.
+	</para>
+
+	<para>
+	This book is your means to the straight path. It provides step-by-step,
+	proven, working examples of Samba deployments.  If you want to deploy
+	Samba-3 with the least effort, or if you want to become an expert at deploying
+	Samba-3 without having to search through lots of documentation, this
+	book is the ticket to your destination.
+	</para>
+
+	<para>
+	Samba is software that can be run on a platform other than Microsoft Windows,
+	for example, UNIX, Linux, IBM System 390, OpenVMS, and other operating systems.
+	Samba uses the TCP/IP protocol that is installed on the host server. When
+	correctly configured, it allows that host to interact with a Microsoft Windows
+	client or server as if it is a Windows file and print server. This book
+	will help you to implement Windows-compatible file and print services.
+	</para>
+
+	<para>
+	The examples presented in this book are typical of various businesses and
+	reflect the problems and challenges they face. Care has been taken to preserve
+	attitudes, perceptions, practices, and demands from real network case studies.
+	The maximum benefit may be obtained from this book by working carefully through
+	each exercise. You may be in a hurry to satisfy a specific need, so feel
+	free to locate the example that most closely matches your need, copy it, and
+	innovate as much as you like. Above all, enjoy the process of learning the
+	secrets of MS Windows networking that is truly liberated by Samba.
+	</para>
+
+	<para>
+	The focus of attention in this book is Samba-3. Specific notes are made in
+	respect of how Samba may be made secure. This book does not attempt to provide
+	detailed information regarding secure operation and configuration of peripheral
+	services and applications such as OpenLDAP, DNS and DHCP, the need for which
+	can be met from other resources that are dedicated to the subject.
+	</para>
+
+  <sect1>
+	<title>Why Is This Book Necessary?</title>
+
+	<para>
+	This book is the result of observations and feedback. The feedback from
+	the Samba-HOWTO-Collection has been positive and complimentary. There
+	have been requests for far more worked examples, a
+	<quote>Samba Cookbook,</quote> and for training materials to
+	help kick-start the process of mastering Samba.
+	</para>
+
+	<para>
+	The Samba mailing lists users have asked for sample configuration files
+	that work. It is natural to question one's own ability to correctly
+	configure a complex tool such as Samba until a minimum necessary
+	knowledge level has been attained.
+	</para>
+
+	<para>
+	The Samba-HOWTO-Collection, as do <emphasis>The Official Samba-3 HOWTO and 
+	Reference Guide</emphasis>, document Samba features and functionality in
+	a topical context.  This book takes a completely different approach. It
+	walks through Samba network configurations that are working within particular
+	environmental contexts, providing documented step-by-step implementations.
+	All example case configuration files, scripts, and other tools are provided
+	on the CD-ROM. This book is descriptive, provides detailed diagrams, and
+	makes deployment of Samba-3 a breeze.
+	</para>
+
+	<sect2>
+	<title>Samba 3.0.20 Update Edition</title>
+
+	<para>
+	The Samba 3.0.x series has been remarkably popular. At the time this book first
+	went to print samba-3.0.2 was being released. There have been significant modifications
+	and enhancements between samba-3.0.2 and samba-3.0.14 (the current release) that
+	necessitate this documentation update. This update has the specific intent to
+	refocus this book so that its guidance can be followed for samba-3.0.20
+	and beyond. Further changes are expected as Samba-3 matures further and will 
+	be reflected in future updates.
+	</para>
+
+	<para>
+	The changes shown in <link linkend="pref-new"/> are incorporated in this update:
+	</para>
+
+	<table id="pref-new">
+		<title>Samba Changes &smbmdash; 3.0.2 to 3.0.20</title>
+		<tgroup cols="2">
+			<colspec align="left"/>
+			<colspec align="justify"/>
+			<thead>
+				<row>
+					<entry align="left">
+						<para>
+						New Feature
+						</para>
+					</entry>
+					<entry align="left">
+						<para>
+						Description
+						</para>
+					</entry>
+				</row>
+			</thead>
+			<tbody>
+				<row>
+					<entry>
+						<para>
+						Winbind Case Handling
+						</para>
+					</entry>
+					<entry>
+						<para>
+						User and group names returned by <command>winbindd</command> are now converted to lower case
+						for better consistency. Samba implementations that depend on the case of information returned
+						by winbind (such as %u and %U) must now convert the dependency to expecting lower case values.
+						This affects mail spool files, home directories, valid user lines in the &smb.conf; file, etc.
+						</para>
+					</entry>
+				</row>
+				<row>
+					<entry>
+						<para>
+						Schema Changes
+						</para>
+					</entry>
+					<entry>
+						<para>
+						Addition of code to handle password aging, password uniqueness controls, bad
+						password instances at logon time, have made necessary extensions to the SambaSAM
+						schema. This change affects all sites that use LDAP and means that the directory
+						schema must be updated. 
+						</para>
+					</entry>
+				</row>
+				<row>
+					<entry>
+						<para>
+						Username Map Handling
+						</para>
+					</entry>
+					<entry>
+						<para>
+						Samba-3.0.8 redefined the behavior: Local authentication results in a username map file
+						lookup before authenticating the connection. All authentication via an external domain
+						controller will result in the use of the fully qualified name (i.e.: DOMAIN\username)
+						after the user has been successfully authenticated.
+						</para>
+					</entry>
+				</row>
+				<row>
+					<entry>
+						<para>
+						UNIX extension handling
+						</para>
+					</entry>
+					<entry>
+						<para>
+						Symbolicly linked files and directories on the UNIX host to absolute paths will
+						now be followed. This can be turned off using <quote>wide links = No</quote> in
+						the share stanza in the &smb.conf; file. Turning off <quote>wide links</quote>
+						support will degrade server performance because each path must be checked.
+						</para>
+					</entry>
+				</row>
+				<row>
+					<entry>
+						<para>
+						Privileges Support
+						</para>
+					</entry>
+					<entry>
+						<para>
+						Versions of Samba prior to samba-3.0.11 required the use of the UNIX <constant>root</constant>
+						account from network Windows clients. The new <quote>enable privileges = Yes</quote> capability
+						means that functions such as adding machines to the domain, managing printers, etc. can now
+						be delegated to normal user accounts or to groups of users.
+						</para>
+					</entry>
+				</row>
+			</tbody>
+		</tgroup>
+	</table>
+	</sect2>
+
+  </sect1>
+
+  <sect1>
+  <title>Prerequisites</title>
+
+	<para>
+	This book is not a tutorial on UNIX or Linux administration. UNIX and Linux
+	training is best obtained from books dedicated to the subject. This book
+	assumes that you have at least the basic skill necessary to use these operating
+	systems, and that you can use a basic system editor to edit and configure files.
+	It has been written with the assumption that you have experience with Samba, 
+	have read <emphasis>The Official Samba-3 HOWTO and Reference Guide</emphasis> and
+	the Samba-HOWTO-Collection, or that you have familiarity with Microsoft Windows.
+	</para>
+
+	<para>
+	If you do not have this experience, you can follow the examples in this book but may
+	find yourself at times intimidated by assumptions made. In this situation, you
+	may need to refer to administrative guides or manuals for your operating system
+	platform to find what is the best method to achieve what the text of this book describes.
+	</para>
+
+  </sect1>
+
+  <sect1>
+	<title>Approach</title>
+
+	<para>
+	The first chapter deals with some rather thorny network analysis issues. Do not be
+	put off by this. The information you glean, even without a detailed understanding
+	of network protocol analysis, can help you understand how Windows networking functions.
+	</para>
+
+	<para>
+	Each following chapter of this book opens with the description of a networking solution
+	sought by a hypothetical site. Bob Jordan is a hypothetical decision maker
+	for an imaginary company, <constant>Abmas Biz NL</constant>. We will use the
+	non-existent domain name <constant>abmas.biz</constant>. All <emphasis>facts</emphasis> 
+	presented regarding this company are fictitious and have been drawn from a variety of real 
+	business scenarios over many years. Not one of these reveal the identify of the 
+	real-world company from which the scenario originated.
+	</para>
+
+	<para> 
+	In any case, Mr. Jordan likes to give all his staff nasty little assignments.
+	Stanley Saroka is one of his proteges; Christine Roberson is the network administrator 
+	Bob trusts. Jordan is inclined to treat other departments well because they finance 
+	Abmas IT operations.
+	</para>
+
+	<para>
+	Each chapter presents a summary of the network solution we have chosen to
+	demonstrate together with a rationale to help you to understand the
+	thought process that drove that solution. The chapter then documents in precise
+	detail all configuration files and steps that must be taken to implement the
+	example solution. Anyone wishing to gain serious value from this book will
+	do well to take note of the implications of points made, so watch out for the
+	<emphasis>this means that</emphasis> notations.
+	</para>
+
+	<para>
+	Each chapter has a set of questions and answers to help you to
+	to understand and digest key attributes of the solutions presented.
+	</para>
+
+  </sect1>
+
+  <sect1>
+	<title>Summary of Topics</title>
+
+	<para>
+	The contents of this second edition of <emphasis>Samba-3 by Example</emphasis>
+	have been rearranged based on feedback from purchasers of the first edition.
+	</para>
+
+	<para>
+	Clearly the first edition contained most of what was needed and that was missing
+	from other books that cover this difficult subject. The new arrangement adds
+	additional material to meet consumer requests and includes changes that originated
+	as suggestions for improvement.
+	</para>
+
+	<para>
+	Chapter 1 now dives directly into the heart of the implementation of Windows
+	file and print server networks that use Samba at the heart.
+	</para>
+
+	<variablelist>
+		<varlistentry>
+		<term>Chapter 1 &smbmdash; No Frills Samba Servers</term><listitem>
+		<para>
+		Here you design a solution for three different business scenarios, each for a 
+		company called Abmas. There are two simple networking problems and one slightly 
+		more complex networking challenge. In the first two cases, Abmas has a small 
+		simple office, and they want to replace a Windows 9x peer-to-peer network. The 
+		third example business uses Windows 2000 Professional. This must be simple, 
+		so let's see how far we can get. If successful, Abmas grows quickly and
+		soon needs to replace all servers and workstations.
+		</para>
+
+        	<para><emphasis>TechInfo</emphasis> &smbmdash; This chapter demands:
+			<itemizedlist>
+				<listitem><para>Case 1: The simplest &smb.conf; file that may
+					reasonably be used. Works with Samba-2.x also. This
+					configuration uses Share Mode security. Encrypted
+					passwords are not used, so there is no 
+					<filename>smbpasswd</filename> file.
+					</para></listitem>
+
+				<listitem><para>Case 2: Another simple &smb.conf; file that adds
+					WINS support and printing support. This case deals with
+					a special requirement that demonstrates how to deal with
+					purpose-built software that has a particular requirement
+					for certain share names and printing demands. This
+					configuration uses Share Mode security and also works with
+					Samba-2.x. Encrypted passwords are not used, so there is no
+					<filename>smbpasswd</filename> file.
+					</para></listitem>
+
+				<listitem><para>Case 3: This &smb.conf; configuration uses User Mode
+					security. The file share configuration demonstrates
+					the ability to provide master access to an administrator
+					while restricting all staff to their own work areas.
+					Encrypted passwords are used, so there is an implicit
+					<filename>smbpasswd</filename> file.
+					</para></listitem>
+			</itemizedlist>
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Chapter 2 &smbmdash; Small Office Networking</term><listitem>
+		<para>
+		Abmas is a successful company now. They have 50 network users
+		and want a little more varoom from the network. This is a typical
+		small office and they want better systems to help them to grow. This is
+		your chance to really give advanced users a bit more functionality and usefulness.
+		</para>
+
+		<para><emphasis>TechInfo</emphasis> &smbmdash; This &smb.conf; file
+		makes use of encrypted passwords, so there is an <filename>smbpasswd</filename>
+		file. It also demonstrates use of the <parameter>valid users</parameter> and
+		<parameter>valid groups</parameter> to restrict share access. The Windows
+		clients access the server as Domain members. Mobile users log onto
+		the Domain while in the office, but use a local machine account while on the
+		road. The result is an environment that answers mobile computing user needs.
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Chapter 3 &smbmdash; Secure Office Networking</term><listitem>
+		<para>
+		Abmas is growing rapidly now. Money is a little tight, but with 130
+		network users, security has become a concern. They have many new machines
+		to install and the old equipment will be retired. This time they want the
+		new network to scale and grow for at least two years. Start with a sufficient
+		system and allow room for growth. You are now implementing an Internet
+		connection and have a few reservations about user expectations.
+		</para>
+
+		<para><emphasis>TechInfo</emphasis> &smbmdash; This &smb.conf; file
+                makes use of encrypted passwords, and you can use a <filename>tdbsam</filename>
+                password backend. Domain logons are introduced. Applications are served from the central
+		server. Roaming profiles are mandated. Access to the server is tightened up
+		so that only domain members can access server resources. Mobile computing
+		needs still are catered to.
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Chapter 4 &smbmdash; The 500 User Office</term><listitem>
+		<para>
+		The two-year projections were met. Congratulations, you are a star.
+		Now Abmas needs to replace the network. Into the existing user base, they
+		need to merge a 280-user company they just acquired. It is time to build a serious
+		network. There are now three buildings on one campus and your assignment is 
+		to keep everyone working while a new network is rolled out. Oh, isn't it nice 
+		to roll out brand new clients and servers! Money is no longer tight, you get 
+		to buy and install what you ask for. You will install routers and a firewall.
+		This is exciting!
+		</para>
+
+		<para><emphasis>TechInfo</emphasis> &smbmdash; This &smb.conf; file
+                makes use of encrypted passwords, and a <filename>tdbsam</filename>
+		password backend is used. You are not ready to launch into LDAP yet, so you
+		accept the limitation of having one central Domain Controller with a Domain
+		Member server in two buildings on your campus. A number of clever techniques
+		are used to demonstrate some of the smart options built into Samba.
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Chapter 5 &smbmdash; Making Happy Users</term><listitem>
+		<para>
+		Congratulations again. Abmas is happy with your services and you have been given another raise.
+		Your users are becoming much more capable and are complaining about little
+		things that need to be fixed. Are you up to the task? Mary says it takes her 20 minutes
+		to log onto the network and it is killing her productivity. Email is a bit <emphasis>
+		unreliable</emphasis> &smbmdash; have you been sleeping on the job? We do not discuss the
+		technology of email but when the use of mail clients breaks because of networking
+		problems, you had better get on top of it. It's time for a change.
+		</para>
+
+		<para><emphasis>TechInfo</emphasis> &smbmdash; This &smb.conf; file
+                makes use of encrypted passwords; a distributed <filename>ldapsam</filename>
+                password backend is used. Roaming profiles are enabled. Desktop profile controls
+		are introduced. Check out the techniques that can improve the user experience 
+		of network performance. As a special bonus, this chapter documents how to configure
+		smart downloading of printer drivers for drag-and-drop printing support. And, yes,
+		the secret of configuring CUPS is clearly documented. Go for it; this one will
+		tease you, too.
+                </para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Chapter 6 &smbmdash; A Distributed 2000 User Network</term><listitem>
+		<para>
+		Only eight months have passed, and Abmas has acquired another company. You now need to expand
+		the network further. You have to deal with a network that spans several countries.
+		There are three new networks in addition to the original three buildings at the head-office 
+		campus. The head office is in New York and you have branch offices in Washington, Los Angeles, and 
+		London. Your desktop standard is Windows XP Professional. In many ways, everything has changed
+		and yet it must remain the same. Your team is primed for another roll-out. You know there are
+		further challenges ahead.
+		</para>
+
+		<para><emphasis>TechInfo</emphasis> &smbmdash; Slave LDAP servers are introduced. Samba is
+		configured to use multiple LDAP backends. This is a brief chapter; it assumes that the
+		technology has been mastered and gets right down to concepts and how to deploy them.
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Chapter 7 &smbmdash; Adding UNIX/Linux Servers and Clients</term><listitem>
+		<para>
+		Well done, Bob, your team has achieved much. Now help Abmas integrate the entire network.
+		You want central control and central support and you need to cut costs. How can you reduce administrative
+		overheads and yet get better control of the network?
+		</para>
+
+		<para>
+		This chapter has been contributed by Mark Taylor <email>mark.taylor@siriusit.co.uk</email>
+		and is based on a live site. For further information regarding this example case, 
+		please contact Mark directly.
+		</para>
+
+		<para><emphasis>TechInfo</emphasis> &smbmdash; It is time to consider how to add Samba servers
+		and UNIX and Linux network clients. Users who convert to Linux want to be able to log on
+		using Windows network accounts. You explore nss_ldap, pam_ldap, winbind, and a few neat
+		techniques for taking control. Are you ready for this?
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Chapter 8 &smbmdash; Updating Samba-3</term><listitem>
+		<para>
+		This chapter is the result of repeated requests for better documentation of the steps
+		that must be followed when updating or upgrading a Samba server. It attempts to cover
+		the entire subject in broad-brush but at the same time provides detailed background
+		information that is not covered elsewhere in the Samba documentation.
+		</para>
+
+		<para><emphasis>TechInfo</emphasis> &smbmdash; Samba stores a lot of essential network
+		information in a large and growing collection of files. This chapter documents the
+		essentials of where those files may be located and how to find them. It also provide
+		an insight into inter-related matters that affect a Samba installation.
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Chapter 9 &smbmdash; Migrating NT4 Domain to Samba-3</term><listitem>
+		<para>
+		Another six months have <?latex \linebreak ?>
+		 passed. Abmas has acquired yet another company. You will find a
+		way to migrate all users off the old network onto the existing network without loss
+		of passwords and will effect the change-over during one weekend. May the force (and caffeine) be with
+		you, may you keep your back to the wind and may the sun shine on your face.
+		</para>
+
+		<para><emphasis>TechInfo</emphasis> &smbmdash; This chapter demonstrates the use of
+		the <command>net rpc migrate</command> facility using an LDAP ldapsam backend, and also
+		using a tdbsam passdb backend. Both are much-asked-for examples of NT4 Domain migration.
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Chapter 10 &smbmdash; Migrating NetWare 4.11 Server to Samba</term><listitem>
+		<para>
+		Misty Stanley-Jones has contributed information that summarizes her experience at migration
+		from a NetWare server to Samba-3.
+		</para>
+
+		<para><emphasis>TechInfo</emphasis> &smbmdash; The documentation provided demonstrates
+		how one site migrated from NetWare to Samba. Some alternatives tools are mentioned. These
+		could be used to provide another pathway to a successful migration.
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Chapter 11 &smbmdash; Active Directory, Kerberos and Security</term><listitem>
+		<para>
+		Abmas has acquired another company that has just migrated to running Windows Server 2003 and 
+		Active Directory. One of your staff makes offhand comments that land you in hot water.
+		A network security auditor is hired by the head of the new business and files a damning 
+		report, and you must address the <emphasis>defects</emphasis> reported. You have hired new 
+		network engineers who want to replace Microsoft Active Directory with a pure Kerberos 
+		solution. How will you handle this? 
+		</para>
+
+		<para><emphasis>TechInfo</emphasis> &smbmdash; This chapter is your answer. Learn about
+		share access controls, proper use of UNIX/Linux file system access controls, and Windows
+		200x Access Control Lists. Follow these steps to beat the critics.
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+                <term>Chapter 12 &smbmdash; Integrating Additional Services</term><listitem>
+                <para>
+		The battle is almost over, Samba-3 has won the day. Your team are delighted and now you
+		find yourself at yet another cross-roads. Abmas have acquired a snack food business, you
+		made promises you must keep. IT costs must be reduced, you have new resistance, but you
+		will win again. This time you choose to install the Squid proxy server to validate the
+		fact that Samba is far more than just a file and print server. SPNEGO authentication 
+		support means that your Microsoft Windows clients gain transparent proxy access.
+		</para>
+
+		<para><emphasis>TechInfo</emphasis> &smbmdash; Samba provides the <command>ntlm_auth</command>
+		module that makes it possible for MS Windows Internet Explorer to connect via the Squid Web
+		and FTP proxy server. You will configure Samba-3 as well as Squid to deliver authenticated
+		access control using the Active Directory Domain user security credentials.
+                </para>
+                </listitem>
+                </varlistentry>
+
+		<varlistentry>
+		<term>Chapter 13 &smbmdash; Performance, Reliability and Availability</term><listitem>
+		<para>
+		Bob, are you sure the new Samba server is up to the load? Your network is serving many
+		users who risk becoming unproductive. What can you do to keep ahead of demand? Can you
+		keep the cost under control also? What can go wrong?
+		</para>
+
+		<para><emphasis>TechInfo</emphasis> &smbmdash; Hot tips that put chili into your
+		network. Avoid name resolution problems, identify potential causes of network collisions,
+		avoid Samba configuration options that will weigh the server down. MS distributed file
+		services to make your network fly and much more. This chapter contains a good deal of 
+		<quote>Did I tell you about this...?</quote> type of hints to help keep your name on the top
+		performers list.
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>Appendix B &smbmdash; Windows Networking Primer</term><listitem>
+		<para>
+		Here we cover practical exercises to help us to understand how MS Windows
+		network protocols function. A network protocol analyzer helps you to
+		appreciate the fact that Windows networking is highly dependent on broadcast
+		messaging. Additionally, you can look into network packets that a Windows
+		client sends to a network server to set up a network connection. On completion,
+		you should have a basic understanding of how network browsing functions and
+		have seen some of the information a Windows client sends to
+		a file and print server to create a connection over which file and print
+		operations may take place.
+		</para>
+		</listitem>
+		</varlistentry>
+
+	</variablelist>
+
+  </sect1>
+
+  <!-- the conventions used in this book -->
+  <xi:include href="conventions.xml" xmlns:xi="http://www.w3.org/2003/XInclude" />
+
+</preface>
+