Add all the source files from the old CVS tree,

add the 5 missing chapters from the HOWTO
and add jht's Samba by Example book.
(This used to be commit 9fb5bcb93e57c5162b3ee6f9c7d777dc0269d100)

1 files changed, 1100 insertions, 0 deletions

diff --git a/docs/guide/Chap10b-DomainAppsSupport.xml b/docs/guide/Chap10b-DomainAppsSupport.xml
new file mode 100644
index 0000000000..f5212e35bf
--- /dev/null
+++ b/docs/guide/Chap10b-DomainAppsSupport.xml
@@ -0,0 +1,1100 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
+  <!-- Stuff for xincludes -->
+  <!ENTITY % xinclude SYSTEM "../entities/xinclude.dtd">
+  %xinclude;
+
+  <!-- entities files to use -->
+  <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
+  %global_entities;
+
+]>
+
+<chapter id="DomApps">
+  <title>Integrating Additional Services</title>
+
+    <para><indexterm>
+	<primary>authentication</primary>
+      </indexterm><indexterm>
+	<primary>backends</primary>
+      </indexterm><indexterm>
+	<primary>smbpasswd</primary>
+      </indexterm><indexterm>
+	<primary>ldapsam</primary>
+      </indexterm><indexterm>
+	<primary>Active Directory</primary>
+      </indexterm>
+	You've come a long way now. You have pretty much mastered Samba-3 for 
+	most uses it can be put to. Up until now, you have cast Samba-3 in the leading 
+	role and where authentication was required, you have used one or another of 
+	Samba's many authentication backends (from flat text files with smbpasswd 
+	to LDAP directory integration with ldapsam). Now you can design a 
+	solution for a new Abmas business. This business is running Windows Server 
+	2003 and Active Directory, and these are to stay. It's time to master 
+	implementing Samba and Samba-supported services in a domain controlled by 
+	the latest Windows authentication technologies. Let's get started &smbmdash; this is 
+	leading edge.
+	</para>
+
+<sect1>
+	<title>Introduction</title>
+
+	<para>
+	Abmas has continued its miraculous growth; indeed, nothing seems to be able 
+	to stop its diversification into multiple (and seemingly unrelated) fields. 
+	Its latest acquisition is Abmas Snack Foods, a big player in the snack-food 
+	business.
+	</para>
+
+	<para>
+	With this acquisition comes new challenges for you and your team. Abmas Snack 
+	Foods is a well-developed business with a huge and heterogeneous network. They 
+	already have Windows, Netware, and Proprietary UNIX, but as yet no Samba or Linux. 
+	The network is mature and well established, and there is no question of their chosen 
+	user authentication scheme being changed for now. You need to take a wise new 
+	approach.
+	</para>
+
+	<para>
+	You have decided to set the ball rolling by introducing Samba-3 into the network 
+	gradually, taking over key services and easing the way to a full migration and, 
+	therefore, integration into Abmas's existing business later.
+	</para>
+
+	<sect2>
+		<title>Assignment Tasks</title>
+
+	<para><indexterm>
+	    <primary>web</primary>
+	    <secondary>proxying</secondary>
+	  </indexterm><indexterm>
+	    <primary>web</primary>
+	    <secondary>caching</secondary>
+	  </indexterm>
+	        You've promised the skeptical Abmas Snack Foods management team 
+		that you can show them how Samba can ease itself and other Open Source 
+		technologies into their existing infrastructure and deliver sound business 
+		advantages. Cost cutting is high on their agenda (a major promise of the 
+		acquisition). You have chosen Web proxying and caching as your proving ground.
+		</para>
+
+	<para><indexterm>
+	    <primary>bandwidth</primary>
+	  </indexterm><indexterm>
+	    <primary>Microsoft ISA</primary>
+	  </indexterm>
+		Abmas Snack Foods has several thousand users housed at their Head Office 
+		and multiple regional offices, plants, and warehouses. A high proportion of 
+		the business's work is done online, so Internet access for most of these 
+		users is essential. All Internet access, including all of their regional offices, 
+		is funneled through the head office and is the job of the (now your) networking 
+		team. The bandwidth requirements were horrific (comparable to a small ISP), and 
+		the team soon discovered proxying and caching. In fact, they became one of 
+		the earliest commercial users of Microsoft ISA.
+		</para>
+
+	<para><indexterm>
+	    <primary>Active Directory</primary>
+	  </indexterm><indexterm>
+	    <primary>authenticated</primary>
+	  </indexterm><indexterm>
+	    <primary>proxy</primary>
+	  </indexterm>
+		The team is not happy with ISA. Because it never lived up to its marketing promises, 
+		it under-performed and had reliability problems. You have pounced on the opportunity 
+		to show what Open Source can do. The one thing they do like, however, is ISA's 
+		integration with Active Directory. They like that their users, once logged on, 
+		are automatically authenticated against the proxy. If your alternative to ISA 
+		can operate completely seamlessly in their Active Directory Domain, it will be
+		approved.
+		</para>
+
+		<para>
+		This is a hands-on exercise. You build software applications so
+		that you obtain the functionality Abmas needs.
+		</para>
+
+	</sect2>
+</sect1>
+
+<sect1>
+	<title>Dissection and Discussion</title>
+
+	<para>
+	The key requirements in this business example are straightforward. You are not required 
+	to do anything new, just to replicate an existing system, not lose any existing features, 
+	and improve performance. The key points are:
+	</para>
+
+	<itemizedlist>
+		<listitem><para>
+		Internet access for most employees
+		</para></listitem>
+		<listitem><para>
+		Distributed system to accommodate load and geographical distribution of users
+		</para></listitem>
+		<listitem><para>
+		Seamless and transparent interoperability with the existing Active Directory domain
+		</para></listitem>
+	</itemizedlist>
+
+
+	<sect2>
+		<title>Technical Issues</title>
+
+	<para><indexterm>
+	    <primary>browsing</primary>
+	  </indexterm><indexterm>
+	    <primary>Squid</primary>
+	  </indexterm><indexterm>
+	    <primary>Squid proxy</primary>
+	  </indexterm><indexterm>
+	    <primary>proxy</primary>
+	  </indexterm><indexterm>
+	    <primary>authentication</primary>
+	  </indexterm><indexterm>
+	    <primary>Internet Explorer</primary>
+	  </indexterm><indexterm>
+	    <primary>winbind</primary>
+	  </indexterm><indexterm>
+	    <primary>NTLM</primary>
+	  </indexterm><indexterm>
+	    <primary>NTLM authentication daemon</primary>
+	  </indexterm><indexterm>
+	    <primary>authentication</primary>
+	  </indexterm><indexterm>
+	    <primary>daemon</primary>
+	  </indexterm><indexterm>
+	    <primary>Active Directory</primary>
+	  </indexterm><indexterm>
+	    <primary>domain</primary>
+	    <secondary>Active Directory</secondary>
+	  </indexterm><indexterm>
+	    <primary>Kerberos</primary>
+	  </indexterm><indexterm>
+	    <primary>token</primary>
+	  </indexterm>
+		Functionally, the user's Internet Explorer requests a browsing session with the 
+		Squid proxy, for which it offers its AD authentication token. Squid hands off 
+		the authentication request to the Samba-3 authentication helper application
+		called <command>ntlm_auth</command>. This helper is a hook into winbind, the 
+		Samba-3 NTLM authentication daemon. Winbind enables UNIX services to authenticate 
+		against Microsoft Windows Domains, including Active Directory domains. As Active 
+		Directory authentication is a modified Kerberos authentication, winbind is assisted 
+		in this by local Kerberos 5 libraries configured to check passwords with the Active 
+		Directory server. Once the token has been checked, a browsing session is established. 
+		This process is entirely transparent and seamless to the user.
+		</para>
+
+		<para>
+		Enabling this consists of:
+		</para>
+
+		<itemizedlist>
+			<listitem><para>
+			Preparing the necessary environment using preconfigured packages
+			</para></listitem>
+
+			<listitem><para>
+			Setting up raw Kerberos authentication against the Active Directory domain
+			</para></listitem>
+
+			<listitem><para>
+			Configuring, compiling, and then installing the supporting Samba-3 components
+			</para></listitem>
+
+			<listitem><para>
+			Tying it all together
+			</para></listitem>
+		</itemizedlist>
+
+	</sect2>
+
+
+	<sect2>
+		<title>Political Issues</title>
+
+		<para>
+		You are a stranger in a strange land and all eyes are upon you. Some would even like to see 
+		you fail. For you to gain the trust of your newly acquired IT people, it is essential that your 
+		solution does everything the old one did, but does it better in every way. Only then 
+		will the entrenched positions consider taking up your new way of doing things on a 
+		wider scale.
+		</para>
+
+	</sect2>
+
+</sect1>
+
+<sect1>
+	<title>Implementation</title>
+
+      <para><indexterm>
+	  <primary>Squid</primary>
+	</indexterm>
+	First, your system needs to be prepared and in a known good state to proceed. This consists 
+	of making sure that everything the system depends on is present and that everything that could 
+	interfere or conflict with the system is removed. You will be configuring the Squid and Samba-3 
+	packages and updating them if necessary. If conflicting packages of these programs are installed, 
+	they must be removed.
+	</para>
+
+      <para><indexterm>
+	  <primary>Red Hat Linux</primary>
+	</indexterm>
+	The following packages should be available on your Red Hat Linux system:
+	</para>
+
+	<itemizedlist>
+	<listitem><para><indexterm>
+	      <primary>krb5</primary>
+	    </indexterm><indexterm>
+	      <primary>Kerberos</primary>
+	    </indexterm>
+		krb5-libs
+		</para></listitem>
+
+		<listitem><para>
+		krb5-devel
+		</para></listitem>
+
+		<listitem><para>
+		krb5-workstation
+		</para></listitem>
+
+		<listitem><para>
+		krb5-server
+		</para></listitem>
+
+		<listitem><para>
+		pam_krb5
+		</para></listitem>
+	</itemizedlist>
+
+      <para><indexterm>
+	  <primary>SUSE Linux</primary>
+	</indexterm>
+	In the case of SUSE Linux, these packages are called:
+	</para>
+
+        <itemizedlist>
+                <listitem><para>
+                heimdal-lib
+                </para></listitem>
+
+                <listitem><para>
+                heimdal-devel
+                </para></listitem>
+
+	<listitem><para><indexterm>
+	      <primary>Heimdal</primary>
+	    </indexterm>
+                heimdal
+                </para></listitem>
+
+                <listitem><para>
+                pam_krb5
+                </para></listitem>
+        </itemizedlist>
+
+	<para>
+	If the required packages are not present on your system, you must install
+	them from the vendor's installation media. Follow the administrative guide
+	for your Linux system to ensure that the packages are correctly updated.
+	</para>
+
+      <note><para><indexterm>
+	    <primary>MS Windows Server 2003</primary>
+	  </indexterm><indexterm>
+	    <primary>Kerberos</primary>
+	  </indexterm><indexterm>
+	    <primary>MIT</primary>
+	  </indexterm>
+	If the requirement is for interoperation with MS Windows Server 2003, it
+	will be necessary to ensure that you are using MIT Kerberos version 1.3.1
+	or later. Red Hat Linux 9 ships with MIT Kerberos 1.2.7 and thus requires
+	updating.
+	</para>
+
+	<para><indexterm>
+	    <primary>Heimdal</primary>
+	  </indexterm><indexterm>
+	    <primary>SUSE Enterprise Linux Server</primary>
+	  </indexterm>
+	Heimdal 0.6 or later is required in the case of SUSE Linux. SUSE Enterprise
+	Linux Server 8 ships with Heimdal 0.4. SUSE 9 ships with the necessary version.
+	</para></note>
+
+	<sect2 id="ch10-one">
+	<title>Removal of Pre-existing Conflicting RPMs</title>
+
+	<para><indexterm>
+	    <primary>Squid</primary>
+	  </indexterm>
+	If Samba and/or Squid rpms are installed, they should be updated. You can 
+	build both from source.
+	</para>
+
+	<para><indexterm>
+	    <primary>rpm</primary>
+	  </indexterm><indexterm>
+	    <primary>samba</primary>
+	  </indexterm><indexterm>
+	    <primary>squid</primary>
+	  </indexterm>
+	Locating the packages to be uninstalled can be achieved by running:
+<screen>
+&rootprompt; rpm -qa | grep -i samba
+&rootprompt; rpm -qa | grep -i squid
+</screen>
+	The identified packages may be removed using:
+<screen>
+&rootprompt; rpm -e samba-common
+</screen>
+	</para>
+
+	<sect2>
+	<title>Kerberos Configuration</title>
+
+	<para><indexterm>
+	    <primary>Kerberos</primary>
+	  </indexterm><indexterm>
+	    <primary>Active Directory</primary>
+	    <secondary>server</secondary>
+	  </indexterm><indexterm>
+	    <primary>ADS</primary>
+	  </indexterm><indexterm>
+	    <primary>KDC</primary>
+	  </indexterm>
+	The systems Kerberos installation must be configured to communicate with 
+	your primary Active Directory server (ADS KDC).
+	</para>
+
+	<para>
+	Strictly speaking, MIT Kerberos version 1.3.1 currently gives the best results, 
+	although the current default Red Hat MIT version 1.2.7 gives acceptable results 
+	unless you are using Windows 2003 servers.
+	</para>
+
+	<para><indexterm>
+	    <primary>MIT</primary>
+	  </indexterm><indexterm>
+	    <primary>Heimdal</primary>
+	  </indexterm><indexterm>
+	    <primary>Kerberos</primary>
+	  </indexterm><indexterm>
+	    <primary>/etc/krb5.conf</primary>
+	  </indexterm><indexterm>
+	    <primary>DNS</primary>
+	    <secondary>SRV records</secondary>
+	  </indexterm><indexterm>
+	    <primary>KDC</primary>
+	  </indexterm><indexterm>
+	    <primary>DNS</primary>
+	    <secondary>lookup</secondary>
+	  </indexterm>
+	Officially, neither MIT (1.3.1) nor Heimdal (0.6) Kerberos needs an <filename>/etc/krb5.conf</filename> 
+	file in order to work correctly. All ADS domains automatically create SRV records in the 
+	DNS zone <constant>Kerberos.REALM.NAME</constant> for each KDC in the realm. Since both 
+	MIT and Heimdal, KRB5 libraries default to checking for these records, so they 
+	automatically find the KDCs. In addition, <filename>krb5.conf</filename> only allows 
+	specifying a single KDC, even there if there is more than one. Using the DNS lookup 
+	allows the KRB5 libraries to use whichever KDCs are available.
+	</para>
+
+	<procedure>
+	  <step><para><indexterm>
+		<primary>krb5.conf</primary>
+	      </indexterm>
+		If you find the need to manually configure the <filename>krb5.conf</filename>, you should edit it
+		to have the contents shown in <link linkend="ch10-krb5conf"/>. The final fully qualified path for this file 
+		should be <filename>/etc/krb5.conf</filename>.
+		</para></step>
+
+	  <step><para><indexterm>
+		<primary>Kerberos</primary>
+	      </indexterm><indexterm>
+		<primary>realm</primary>
+	      </indexterm><indexterm>
+		<primary>case-sensitive</primary>
+	      </indexterm><indexterm>
+		<primary>KDC</primary>
+	      </indexterm><indexterm>
+		<primary>synchronization</primary>
+	      </indexterm><indexterm>
+		<primary>initial credentials</primary>
+	      </indexterm><indexterm>
+		<primary>Clock skew</primary>
+	      </indexterm><indexterm>
+		<primary>NTP</primary>
+	      </indexterm><indexterm>
+		<primary>DNS</primary>
+		<secondary>lookup</secondary>
+	      </indexterm><indexterm>
+		<primary>reverse DNS</primary>
+	      </indexterm><indexterm>
+		<primary>NetBIOS name </primary>
+	      </indexterm><indexterm>
+		<primary>/etc/hosts</primary>
+	      </indexterm><indexterm>
+		<primary>mapping</primary>
+	      </indexterm>
+		The following gotchas often catch people out. Kerberos is case sensitive. Your realm must
+		be in UPPERCASE, or you will get an error: <quote>Cannot find KDC for requested realm while getting
+		initial credentials</quote>.  Kerberos is picky about time synchronization. The time
+		according to your participating servers must be within 5 minutes or you get an error
+		<quote>kinit(v5): Clock skew too great while getting initial credentials</quote>.
+		Clock skew limits are, in fact, configurable in the Kerberos protocols (the default is
+		5 minutes). A better solution is to implement NTP throughout your server network.
+		Kerberos needs to be able to do a reverse DNS lookup on the IP address of your KDC.
+		Also, the name that this reverse lookup maps to must either be the NetBIOS name of
+		the KDC (i.e., the hostname with no domain attached), or it can alternately be the
+		NetBIOS name followed by the realm. If all else fails, you can add a
+		<filename>/etc/hosts</filename> entry mapping the IP address of your KDC to its
+		NetBIOS name. If Kerberos cannot do this reverse lookup, you will get a local error
+		when you try to join the realm.
+		</para></step>
+
+	  <step><para><indexterm>
+		<primary>kinit</primary>
+	      </indexterm>
+		You are now ready to test your installation by issuing the command:
+<screen>
+&rootprompt; kinit [USERNAME@REALM]
+</screen> 
+		You are asked for your password, which you should enter. The following
+		is a typical console sequence:
+<screen>
+&rootprompt; kinit ADMINISTRATOR@LONDON.ABMAS.BIZ
+Password for ADMINISTRATOR@LONDON.ABMAS.BIZ: 
+</screen>
+		Make sure that your password is accepted by the Active Directory KDC.
+		</para></step>
+	</procedure>
+
+<example id="ch10-krb5conf">
+<title>Kerberos Configuration &smbmdash; File: <filename>/etc/krb5.conf</filename></title>
+<screen>
+[libdefaults]
+	default_realm = LONDON.ABMAS.BIZ
+
+[realms] 
+	LONDON.ABMAS.BIZ = {
+	kdc = w2k3s.london.abmas.biz
+	}
+</screen>
+</example>
+
+	<para><indexterm>
+	    <primary>klist</primary>
+	  </indexterm>
+	The command:
+<screen>
+&rootprompt; klist -e 
+</screen>
+	shows the Kerberos tickets cached by the system:
+	</para>
+
+	<sect3>
+	<title>Samba Configuration</title>
+
+	  <para><indexterm>
+	      <primary>Active Directory</primary>
+	    </indexterm>
+	Samba must be configured to correctly use Active Directory. Samba-3 must be used, as 
+	this has the necessary components to interface with Active Directory.
+	</para>
+
+	<procedure>
+	    <step><para><indexterm>
+		  <primary>Red Hat Linux</primary>
+		</indexterm><indexterm>
+		  <primary>Samba Tea</primary>
+		</indexterm><indexterm>
+		  <primary>Red Hat Fedora Linux</primary>
+		</indexterm><indexterm>
+		  <primary>MIT KRB5</primary>
+		</indexterm><indexterm>
+		  <primary>ntlm_auth</primary>
+		</indexterm>
+		Download the latest stable Samba-3 for Red Hat Linux from the official Samba Team
+		<ulink url="http://ftp.samba.org">FTP site.</ulink> The official Samba Team
+		RPMs for Red Hat Fedora Linux contain the <command>ntlm_auth</command> tool
+		needed, and are linked against MIT KRB5 version 1.3.1 and, therefore, are ready for use.
+		</para>
+
+	      <para><indexterm>
+		  <primary>SerNet</primary>
+		</indexterm><indexterm>
+		  <primary>RPMs</primary>
+		</indexterm>
+		The necessary, validated RPM packages for SUSE Linux may be obtained from
+		the <ulink url="ftp://ftp.sernet.de/pub/samba">SerNet</ulink> FTP site that
+		is located in Germany. All SerNet RPMs are validated, have the necessary
+		<command>ntlm_auth</command> tool, and are statically linked 
+		against suitably patched Heimdal 0.6 libraries.
+		</para></step>
+
+		<step><para>
+		Using your favorite editor, change the <filename>/etc/samba/smb.conf</filename>
+		file so it has contents similar to the example shown in <link linkend="ch10-smbconf"/>.
+		</para></step>
+
+	    <step><para><indexterm>
+		  <primary>computer account</primary>
+		</indexterm><indexterm>
+		  <primary>Active Directory</primary>
+		</indexterm><indexterm>
+		  <primary>net</primary>
+		  <secondary>ads</secondary>
+		  <tertiary>join</tertiary>
+		</indexterm><indexterm>
+		  <primary>Kerberos ticket</primary>
+		</indexterm><indexterm>
+		  <primary>ticket</primary>
+		</indexterm>
+		Next you need to create a computer account in the Active Directory. 
+		This sets up the trust relationship needed for other clients to 
+		authenticate to the Samba server with an Active Directory Kerberos ticket. 
+		This is done with the <quote>net ads join -U [Administrator%Password]</quote>
+		command, as follows:
+<screen>
+&rootprompt; net ads join -U administrator%vulcon
+</screen>
+		</para></step>
+
+	    <step><para><indexterm>
+		  <primary>smbd</primary>
+		</indexterm><indexterm>
+		  <primary>nmbd</primary>
+		</indexterm><indexterm>
+		  <primary>winbindd</primary>
+		</indexterm><indexterm>
+		  <primary>Active Directory</primary>
+		</indexterm><indexterm>
+		  <primary>Samba</primary>
+		</indexterm>
+		Your new Samba binaries must be started in the standard manner as is applicable
+		to the platform you are running on. Alternately, start your Active Directory 
+		enabled Samba with the following commands:
+<screen>
+&rootprompt; smbd -D
+&rootprompt; nmbd -D
+&rootprompt; winbindd -B
+</screen>
+		</para></step>
+
+	    <step><para><indexterm>
+		  <primary>winbind</primary>
+		</indexterm><indexterm>
+		  <primary>Active Directory</primary>
+		  <secondary>domain</secondary>
+		</indexterm><indexterm>
+		  <primary>wbinfo</primary>
+		</indexterm><indexterm>
+		  <primary>enumerating</primary>
+		</indexterm><indexterm>
+		  <primary>Active Directory</primary>
+		  <secondary>tree</secondary>
+		</indexterm>
+		We now need to test that Samba is communicating with the Active 
+		Directory domain; most specifically, we want to see whether winbind 
+		is enumerating users and groups. Issue the following commands:
+<screen>
+&rootprompt; wbinfo -t
+checking the trust secret via RPC calls succeeded
+</screen>
+		This tests whether we are authenticating against Active Directory:
+<screen>
+&rootprompt; wbinfo -u
+LONDON+Administrator
+LONDON+Guest
+LONDON+SUPPORT_388945a0
+LONDON+krbtgt
+LONDON+jht
+LONDON+xjht
+</screen>
+		This enumerates all the users in your Active Directory tree:
+<screen>
+&rootprompt; wbinfo -g
+LONDON+Domain Computers
+LONDON+Domain Controllers
+LONDON+Schema Admins
+LONDON+Enterprise Admins
+LONDON+Domain Admins
+LONDON+Domain Users
+LONDON+Domain Guests
+LONDON+Group Policy Creator Owners
+LONDON+DnsUpdateProxy
+</screen>
+		This enumerates all the groups in your Active Directory tree.
+		</para></step>
+
+	    <step><para><indexterm>
+		  <primary>Squid</primary>
+		</indexterm><indexterm>
+		  <primary>ntlm_auth</primary>
+		</indexterm>
+		Squid uses the <command>ntlm_auth</command> helper build with Samba-3.
+		You may test <command>ntlm_auth</command> with the command:
+<screen>
+&rootprompt; /usr/bin/ntlm_auth --username=jht
+password: XXXXXXXX
+</screen>
+		You are asked for your password, which you should enter. You are rewarded with:
+<screen>
+&rootprompt; NT_STATUS_OK: Success (0x0)
+</screen>
+		</para></step>
+
+		<step><para><indexterm>
+		  <primary>ntlm_auth</primary>
+		</indexterm><indexterm>
+		  <primary>authenticate</primary>
+		</indexterm><indexterm>
+		  <primary>winbind</primary>
+		</indexterm><indexterm>
+		  <primary>privileged pipe</primary>
+		</indexterm><indexterm>
+		  <primary>squid</primary>
+		</indexterm><indexterm>
+		  <primary>chgrp</primary>
+		</indexterm><indexterm>
+		  <primary>chmod</primary>
+		</indexterm><indexterm>
+		  <primary>failure</primary>
+		</indexterm>
+		The <command>ntlm_auth</command> helper, when run from a command line as the user 
+		<quote>root</quote>, authenticates against your Active Directory domain (with 
+		the aid of winbind). It manages this by reading from the winbind privileged pipe. 
+		Squid is running with the permissions of user <quote>squid</quote> and group 
+		<quote>squid</quote> and is not able to do this unless we make a vital change. 
+		Squid cannot read from the winbind privilege pipe unless you change the 
+		permissions of its directory. This is the single biggest cause of failure in the 
+		whole process. Remember to issue the following command (for Red Hat Linux):
+<screen>
+&rootprompt; chgrp squid /var/cache/samba/winbindd_privileged
+&rootprompt; chmod 755 /var/cache/samba/winbindd_privileged
+</screen>
+		For SUSE Linux 9, execute the following:
+<screen>
+&rootprompt; chgrp squid /var/lib/samba/winbindd_privileged
+&rootprompt; chmod 755 /var/lib/samba/winbindd_privileged
+</screen>
+		</para></step>
+
+	</procedure>
+	</sect3>
+
+	<sect3>
+	<title>NSS Configuration</title>
+
+	  <para><indexterm>
+	      <primary>NSS</primary>
+	    </indexterm><indexterm>
+	      <primary>winbind</primary>
+	    </indexterm><indexterm>
+	      <primary>authentication</primary>
+	    </indexterm>
+	For Squid to benefit from Samba-3, NSS must be updated to allow winbind as a valid route to user authentication.
+	</para>
+
+	<procedure>
+		<step><para>
+		Edit your <filename>/etc/nsswitch.conf</filename> file so it has the parameters shown
+		in <link linkend="ch10-etcnsscfg"/>.
+		</para></step>
+	</procedure>
+
+<smbconfexample id="ch10-smbconf">
+<title>Samba Configuration &smbmdash; File: <filename>/etc/samba/smb.conf</filename></title>
+<smbconfsection>[global]</smbconfsection>
+<smbconfoption><name>workgroup</name><value>LONDON</value></smbconfoption>
+<smbconfoption><name>netbios name</name><value>W2K3S</value></smbconfoption>
+<smbconfoption><name>realm</name><value>LONDON.ABMAS.BIZ</value></smbconfoption>
+<smbconfoption><name>security</name><value>ads</value></smbconfoption>
+<smbconfoption><name>encrypt passwords</name><value>yes</value></smbconfoption>
+<smbconfoption><name>password server</name><value>w2k3s.london.abmas.biz</value></smbconfoption>
+
+<smbconfcomment>separate domain and username with '/', like DOMAIN/username</smbconfcomment>
+<smbconfoption><name>winbind separator</name><value>/</value></smbconfoption>
+
+<smbconfcomment>use UIDs from 10000 to 20000 for domain users</smbconfcomment>
+<smbconfoption><name>idmap uid</name><value>10000-20000</value></smbconfoption>
+# use GIDs from 10000 to 20000 for domain groups
+<smbconfoption><name>idmap gid</name><value>10000-20000</value></smbconfoption>
+
+<smbconfcomment>allow enumeration of winbind users and groups</smbconfcomment>
+<smbconfoption><name>winbind enum users</name><value>yes</value></smbconfoption>
+<smbconfoption><name>winbind enum groups</name><value>yes</value></smbconfoption>
+<smbconfoption><name>winbind user default domain</name><value>yes</value></smbconfoption>
+</smbconfexample>
+
+<example id="ch10-etcnsscfg">
+<title>NSS Configuration File Extract &smbmdash; File: <filename>/etc/nsswitch.conf</filename></title>
+<screen>
+passwd: files winbind
+shadow: files
+group: files winbind
+</screen>
+</example>
+
+	</sect3>
+
+	<sect3>
+	<title>Squid Configuration</title>
+
+	  <para><indexterm>
+	      <primary>Squid</primary>
+	    </indexterm><indexterm>
+	      <primary>Active Directory</primary>
+	      <secondary>authentication</secondary>
+	    </indexterm>
+	Squid must be configured correctly to interact with the Samba-3 
+	components that handle Active Directory authentication.
+	</para>
+
+	</sect3>
+
+	</sect2>
+
+	<sect2>
+	<title>Configuration</title></sect2>
+
+	<procedure>
+	<step><para><indexterm>
+	      <primary>SUSE Linux</primary>
+	    </indexterm><indexterm>
+	      <primary>Squid</primary>
+	    </indexterm><indexterm>
+	      <primary>helper agent</primary>
+	    </indexterm>
+		If your Linux distribution is SUSE Linux 9, the version of Squid 
+		supplied is already enabled to use the winbind helper agent. You
+		can, therefore, omit the steps that would build the Squid binary
+		programs.
+		</para></step>
+
+	<step><para><indexterm>
+	      <primary>nobody</primary>
+	    </indexterm><indexterm>
+	      <primary>squid</primary>
+	    </indexterm><indexterm>
+	      <primary>rpms</primary>
+	    </indexterm><indexterm>
+	      <primary>/etc/passwd</primary>
+	    </indexterm><indexterm>
+	      <primary>/etc/group</primary>
+	    </indexterm>
+		Squid, by default, runs as the user <constant>nobody</constant>. You need to 
+		add a system user <constant>squid</constant> and a system group 
+		<constant>squid</constant> if they are not set up already (if the default 
+		Red Hat squid rpms were installed, they will be).  Set up a 
+		<constant>squid</constant> user in <filename>/etc/passwd</filename> 
+		and a <constant>squid</constant> group in <filename>/etc/group</filename> if these aren't there already.
+		</para></step>
+
+	<step><para><indexterm>
+	      <primary>permissions</primary>
+	    </indexterm><indexterm>
+	      <primary>chown</primary>
+	    </indexterm>
+		You now need to change the permissions on Squid's <constant>var</constant>
+		directory.  Enter the following command:
+<screen>
+&rootprompt; chown -R squid /var/cache/squid
+</screen>
+		</para></step>
+
+	<step><para><indexterm>
+	      <primary>logging</primary>
+	    </indexterm><indexterm>
+	      <primary>Squid</primary>
+	    </indexterm>
+		Squid must also have control over its logging. Enter the following commands:
+<screen>
+&rootprompt; chown -R chown squid:squid /var/log/squid
+&rootprompt; chmod 770 /var/log/squid
+</screen>
+		</para></step>
+
+		<step><para>
+		Finally, Squid must be able to write to its disk cache!
+		Enter the following commands:
+<screen>
+&rootprompt; chown -R chown squid:squid /var/cache/squid
+&rootprompt; chmod 770 /var/cache/squid
+</screen>
+		</para></step>
+
+	<step><para><indexterm>
+	      <primary>/etc/squid/squid.conf</primary>
+	    </indexterm>
+		The <filename>/etc/squid/squid.conf</filename> file must be edited to include the lines from 
+		<link linkend="etcsquidcfg"/> and <link linkend="etcsquid2"/>.
+		</para></step>
+
+	<step><para><indexterm>
+	      <primary>cache directories</primary>
+	    </indexterm>
+		You must create Squid's cache directories before it may be run.  Enter the following command: 
+<screen>
+&rootprompt; squid -z
+</screen>
+		</para></step>
+
+		<step><para>
+		Finally, start Squid and enjoy transparent Active Directory authentication.
+		Enter the following command:
+<screen>
+&rootprompt; squid
+</screen>
+		</para></step>
+	</procedure>
+
+<example id="etcsquidcfg">
+<title>Squid Configuration File Extract &smbmdash; <filename>/etc/squid.conf</filename> [ADMINISTRATIVE PARAMETERS Section]</title>
+<screen>
+	cache_effective_user squid
+	cache_effective_group squid
+</screen>
+</example>
+
+<example id="etcsquid2">
+<title>Squid Configuration File extract &smbmdash; File: <filename>/etc/squid.conf</filename> [AUTHENTICATION PARAMETERS Section]</title>
+<screen>
+	auth_param ntlm program /usr/bin/ntlm_auth \
+                                --helper-protocol=squid-2.5-ntlmssp
+	auth_param ntlm children 5
+	auth_param ntlm max_challenge_reuses 0
+	auth_param ntlm max_challenge_lifetime 2 minutes
+	auth_param basic program /usr/bin/ntlm_auth \
+                                --helper-protocol=squid-2.5-basic
+	auth_param basic children 5
+	auth_param basic realm Squid proxy-caching web server
+	auth_param basic credentialsttl 2 hours
+	acl AuthorizedUsers proxy_auth REQUIRED
+	http_access allow all AuthorizedUsers
+</screen>
+</example>
+
+	</sect2>
+
+	<sect2>
+		<title>Key Points Learned</title>
+
+	<para><indexterm>
+	    <primary>Web browsers</primary>
+	  </indexterm><indexterm>
+	    <primary>services</primary>
+	  </indexterm><indexterm>
+	    <primary>authentication protocols</primary>
+	  </indexterm><indexterm>
+	    <primary>Web</primary>
+	    <secondary>proxy</secondary>
+	    <tertiary>access</tertiary>
+	  </indexterm><indexterm>
+	    <primary>NTLMSSP</primary>
+	  </indexterm>
+		Microsoft Windows networking protocols permeate the spectrum of technologies that Microsoft
+		Windows clients use, even when accessing traditional services such as Web browsers. Depending 
+		on whom you discuss this with, this is either good or bad. No matter how you might evaluate this,
+		the use of NTLMSSP as the authentication protocol for Web proxy access has some advantages over
+		the cookie-based authentication regime used by all competing browsers. It is Samba's implementation
+		of NTLMSSP that makes it attractive to implement the solution that has been demonstrated in this chapter.
+		</para>
+
+	</sect2>
+
+</sect1>
+
+<sect1>
+	<title>Questions and Answers</title>
+
+      <para><indexterm>
+	  <primary>ntlm_auth</primary>
+	</indexterm><indexterm>
+	  <primary>SambaXP conference</primary>
+	</indexterm><indexterm>
+	  <primary>Goettingen</primary>
+	</indexterm><indexterm>
+	  <primary>Italian</primary>
+	</indexterm>
+	The development of the <command>ntlm_auth</command> module was first discussed in many Open Source circles
+	in 2002. At the SambaXP conference in Goettingen, Germany, Mr. Francesco Chemolli demonstrated the use of 
+	<command>ntlm_auth</command> during one of the late developer meetings that took place. Since that time, the 
+	adoption of <command>ntlm_auth</command> has spread considerably.
+	</para>
+
+	<para>
+	The largest report from a site that uses Squid with <command>ntlm_auth</command>-based authentication
+	support uses a dual processor server that has 2 GBytes of memory. It provides Web and FTP proxy services for 10,000
+	users. Approximately 2,000 of these users make heavy use of the proxy services. According to the source, who
+	wishes to remain anonymous, the sustained transaction load on this server hovers around 140 hits/sec. The following
+	comments were made with respect to questions regarding the performance of this installation:
+	</para>
+
+	<blockquote><para>
+	[In our] EXTREMELY optimized environment ... [the] performance impact is almost [nothing]. The <quote>almost</quote> 
+	part is due to the brain damage of the ntlm-over-http protocol definition. Suffice to say that its worst-case 
+	scenario triples the number of hits needed to perform the same transactions versus basic or digest auth[entication].
+	</para></blockquote>
+
+	<para>
+	You would be well advised to recognize the fact that all cache-intensive proxying solutions demand a lot of memory.
+	Make certain that your Squid proxy server is equipped with sufficient memory to permit all proxy operations to run 
+	out of memory without invoking the overheads involved in the use of memory that has to be swapped to disk.
+	</para>
+
+	<qandaset defaultlabel="chap10bqa" type="number">
+	<qandaentry>
+	<question>
+
+		<para>
+		What does Samba have to do with Web proxy serving?
+		</para>
+
+	</question>
+	<answer>
+
+	    <para><indexterm>
+		<secondary>transparent inter-operability</secondary>
+	      </indexterm><indexterm>
+		<primary>Windows clients</primary>
+	      </indexterm><indexterm>
+		<primary>network</primary>
+		<secondary>services</secondary>
+	      </indexterm><indexterm>
+		<primary>authentication</primary>
+	      </indexterm><indexterm>
+		<primary>wrapper</primary>
+	      </indexterm>
+		To provide transparent interoperability between Windows clients and the network services
+		that are used from them, Samba has had to develop tools and facilities that deliver that. The benefit
+		of Open Source software is that it can readily be reused. The current <command>ntlm_auth</command>
+		module is basically a wrapper around authentication code from the core of the Samba project.
+		</para>
+
+	    <para><indexterm>
+		<primary>plain-text</primary>
+	      </indexterm><indexterm>
+		<primary>authentication</primary>
+		<secondary>plain-text</secondary>
+	      </indexterm><indexterm>
+		<primary>Web</primary>
+		<secondary>proxy</secondary>
+	      </indexterm><indexterm>
+		<primary>FTP</primary>
+		<secondary>proxy</secondary>
+	      </indexterm><indexterm>
+		<primary>NTLMSSP</primary>
+	      </indexterm><indexterm>
+		<primary>logon credentials</primary>
+	      </indexterm><indexterm>
+		<primary>Windows explorer</primary>
+	      </indexterm><indexterm>
+		<primary>Internet Information Server</primary>
+	      </indexterm><indexterm>
+		<primary>Apache Web server</primary>
+	      </indexterm>
+		The <command>ntlm_auth</command> module supports basic plain-text authentication and NTLMSSP 
+		protocols. This module makes it possible for Web and FTP proxy requests to be authenticated without
+		the user being interrupted via his/her Windows logon credentials. This facility is available with
+		MS Windows explorer and is one of the key benefits claimed for Microsoft Internet Information Server.
+		There are a few open source initiatives to provide support for these protocols in the Apache Web server
+		also.
+		</para>
+
+	    <para><indexterm>
+		<primary>wrapper</primary>
+	      </indexterm>
+		The short answer is that by adding a wrapper around key authentication components of Samba, other
+		projects (like Squid) can benefit from the labors expended in meeting user interoperability needs.
+		</para>
+
+	</answer>
+	</qandaentry>
+
+	<qandaentry>
+	<question>
+
+		<para>
+		What other services does Samba provide?
+		</para>
+
+	</question>
+	<answer>
+
+	    <para><indexterm>
+		<primary>winbindd</primary>
+	      </indexterm><indexterm>
+		<primary>Identity resolver</primary>
+	      </indexterm><indexterm>
+		<primary>daemon</primary>
+	      </indexterm><indexterm>
+		<primary>smbd</primary>
+	      </indexterm><indexterm>
+		<primary>file and print server</primary>
+	      </indexterm>
+		Samba-3 is a file and print server. The core components that provide this functionality are <command>smbd</command>,
+		<command>nmbd</command>, and the Identity resolver daemon, <command>winbindd</command>.
+		</para>
+
+	    <para><indexterm>
+		<primary>SMB/CIFS</primary>
+	      </indexterm><indexterm>
+		<primary>smbclient</primary>
+	      </indexterm>
+		Samba-3 is an SMB/CIFS client. The core component that provides this is called <command>smbclient</command>.
+		</para>
+
+	    <para><indexterm>
+		<primary>modules</primary>
+	      </indexterm><indexterm>
+		<primary>utilities</primary>
+	      </indexterm><indexterm>
+		<primary>validation</primary>
+	      </indexterm><indexterm>
+		<primary>inter-operability</primary>
+	      </indexterm><indexterm>
+		<primary>authentication</primary>
+	      </indexterm>
+		Samba-3 includes a number of helper tools, plug-in modules, utilities, and test/validation facilities.
+		Samba-3 includes glue modules that help provide interoperability between MS Windows clients and UNIX/Linux
+		servers and client. It includes Winbind agents that make it possible to authenticate UNIX/Linux access attempts
+		as well as logins to an SMB/CIFS authentication server backend. Samba-3 includes name service switcher modules
+		to permit Identity resolution via SMB/CIFS servers (Windows NT4/200x, Samba, and a host of other commercial
+		server products).
+		</para>
+
+	</answer>
+	</qandaentry>
+
+	<qandaentry>
+	<question>
+
+		<para>
+		Does use of Samba (<command>ntlm_auth</command>) improve the performance of Squid?
+		</para>
+
+	</question>
+	<answer>
+
+		<para>
+		Not really. Samba's <command>ntlm_auth</command> module handles only authentication. It requires that
+		Squid make an external call to <command>ntlm_auth</command> and, therefore, actually incurs a
+		little more overhead. Compared with the benefit obtained, that overhead is well worth enduring. Since
+		Squid is a proxy server, and proxy servers tend to require lots of memory, it is good advice to provide
+		sufficient memory when using Squid. Just add a little more to accommodate <command>ntlm_auth</command>.
+		</para>
+
+	</answer>
+	</qandaentry>
+	</qandaset>
+
+</sect1>
+
+</chapter>
+