More updates.

(This used to be commit 20f8bde1d0a2b2e42efedcdac21778fe34c0ab79)

1 files changed, 1791 insertions, 0 deletions

diff --git a/docs/Samba-HOWTO-Collection/TOSHARG-Passdb.xml b/docs/Samba-HOWTO-Collection/TOSHARG-Passdb.xml
new file mode 100644
index 0000000000..2ee109db01
--- /dev/null
+++ b/docs/Samba-HOWTO-Collection/TOSHARG-Passdb.xml
@@ -0,0 +1,1791 @@
+<?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="passdb">
+<chapterinfo>
+	&author.jelmer;
+	&author.jht;
+	&author.jerry;
+	&author.jeremy;
+	<author>&person.gd;<contrib>LDAP updates</contrib></author>
+	<author>
+		<firstname>Olivier (lem)</firstname><surname>Lemaire</surname>
+		<affiliation>
+			<orgname>IDEALX</orgname>
+			<address><email>olem@IDEALX.org</email></address>
+		</affiliation>
+	</author>
+	
+	<pubdate>May 24, 2003</pubdate>
+</chapterinfo>
+<title>Account Information Databases</title>
+
+<para>
+Samba-3 implements a new capability to work concurrently with multiple account backends.
+The possible new combinations of password backends allows Samba-3 a degree of flexibility
+and scalability that previously could be achieved only with MS Windows Active Directory.
+This chapter describes the new functionality and how to get the most out of it.
+</para>
+
+<sect1>
+<title>Features and Benefits</title>
+
+<para>
+Samba-3 provides for complete backward compatibility with Samba-2.2.x functionality
+as follows:
+<indexterm><primary>SAM backend</primary><secondary>smbpasswd</secondary></indexterm>
+<indexterm><primary>SAM backend</primary><secondary>ldapsam_compat</secondary></indexterm>
+<indexterm><primary>encrypted passwords</primary></indexterm>
+</para>
+
+<?latex \newpage ?>
+
+<sect2>
+	<title>Backward Compatibility Backends</title>
+
+<variablelist>
+	<varlistentry><term>Plain Text</term>
+		<listitem>
+			<para>
+			This isn't really a backend at all, but is listed here for simplicity.  Samba can be
+			configured to pass plaintext authentication requests to the traditional UNIX/Linux
+			<filename>/etc/passwd</filename> and <filename>/etc/shadow</filename>
+			style subsystems.  On systems that have Pluggable Authentication Modules (PAM)
+			support, all PAM modules are supported. The behavior is just as it was with
+			Samba-2.2.x, and the protocol limitations imposed by MS Windows clients
+			apply likewise. Please refer to <link linkend="passdbtech">Technical Information</link> for more information
+			regarding the limitations of Plain Text password usage.
+			</para>
+		</listitem>
+	</varlistentry>
+
+	<varlistentry><term>smbpasswd</term>
+		<listitem>
+			<para>
+			This option allows continued use of the <filename>smbpasswd</filename>
+			file that maintains a plain ASCII (text) layout that includes the MS Windows
+			LanMan and NT encrypted passwords as well as a field that stores some
+			account information. This form of password backend does not store any of
+			the MS Windows NT/200x SAM (Security Account Manager) information required to
+			provide the extended controls that are needed for more comprehensive 
+			inter-operation with MS Windows NT4/200x servers.
+			</para>
+
+			<para>
+			This backend should be used only for backward compatibility with older
+			versions of Samba. It may be deprecated in future releases.
+			</para>
+		</listitem>
+	</varlistentry>
+
+	<varlistentry><term>ldapsam_compat (Samba-2.2 LDAP Compatibility)</term>
+		<listitem>
+			<para>
+			There is a password backend option that allows continued operation with
+			an existing OpenLDAP backend that uses the Samba-2.2.x LDAP schema extension.
+			This option is provided primarily as a migration tool, although there is
+			no reason to force migration at this time. This tool will eventually
+			be deprecated.
+			</para>
+		</listitem>
+	</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>New Backends</title>
+
+<para>
+Samba-3 introduces a number of new password backend capabilities.
+<indexterm><primary>SAM backend</primary><secondary>tdbsam</secondary></indexterm>
+<indexterm><primary>SAM backend</primary><secondary>ldapsam</secondary></indexterm>
+<indexterm><primary>SAM backend</primary><secondary>mysqlsam</secondary></indexterm>
+<indexterm><primary>SAM backend</primary><secondary>xmlsam</secondary></indexterm>
+</para>
+
+<variablelist>
+	<varlistentry><term>tdbsam</term>
+		<listitem>
+			<para>
+			This backend provides a rich database backend for local servers. This
+			backend is not suitable for multiple Domain Controllers (i.e., PDC + one
+			or more BDC) installations.
+			</para>
+
+			<para>
+			The <emphasis>tdbsam</emphasis> password backend stores the old <emphasis>
+			smbpasswd</emphasis> information plus the extended MS Windows NT / 200x
+			SAM information into a binary format TDB (trivial database) file.
+			The inclusion of the extended information makes it possible for Samba-3
+			to implement the same account and system access controls that are possible
+			with MS Windows NT4/200x-based systems.
+			</para>
+
+			<para>
+			The inclusion of the <emphasis>tdbsam</emphasis> capability is a direct
+			response to user requests to allow simple site operation without the overhead
+			of the complexities of running OpenLDAP. It is recommended to use this only
+			for sites that have fewer than 250 users. For larger sites or implementations,
+			the use of OpenLDAP or of Active Directory integration is strongly recommended.
+			</para>
+		</listitem>
+	</varlistentry>
+
+	<varlistentry><term>ldapsam</term>
+		<listitem>
+			<para>
+			This provides a rich directory backend for distributed account installation.	
+			</para>
+
+			<para>
+			Samba-3 has a new and extended LDAP implementation that requires configuration
+			of OpenLDAP with a new format Samba schema. The new format schema file is
+			included in the <filename class="directory">examples/LDAP</filename> directory of the Samba distribution.
+			</para>
+
+			<para>
+			The new LDAP implementation significantly expands the control abilities that
+			were possible with prior versions of Samba. It is now possible to specify
+			<quote>per user</quote> profile settings, home directories, account access controls, and
+			much more. Corporate sites will see that the Samba Team has listened to their
+			requests both for capability and to allow greater scalability.
+			</para>
+		</listitem>
+	</varlistentry>
+
+	<varlistentry><term>mysqlsam (MySQL based backend)</term>
+		<listitem>
+			<para>
+			It is expected that the MySQL-based SAM will be very popular in some corners.
+			This database backend will be of considerable interest to sites that want to
+			leverage existing MySQL technology.
+			</para>
+		</listitem>
+	</varlistentry>
+
+	<varlistentry><term>pgsqlsam (PostGreSQL based backend)</term>
+		<listitem>
+			<para>
+				Stores user information in a PostgreSQL database.
+				This backend is largely undocumented at 
+				the moment, though it's configuration is very similar to 
+				that of the mysqlsam backend.
+			</para>
+		</listitem>
+	</varlistentry>
+
+	<varlistentry><term>xmlsam (XML based datafile)</term>
+		<listitem>
+			<para>
+<indexterm><primary>pdbedit</primary></indexterm>
+			Allows the account and password data to be stored in an XML format
+			data file. This backend cannot be used for normal operation, it can only 
+			be used in conjunction with <command>pdbedit</command>'s pdb2pdb 
+			functionality. The DTD that is used might be subject to changes in the future.
+			</para>
+
+			<para>
+			The <parameter>xmlsam</parameter> option can be useful for account migration between database
+			backends or backups. Use of this tool will allow the data to be edited before migration
+			into another backend format.
+			</para>
+		</listitem>
+	</varlistentry>
+
+</variablelist>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="passdbtech">
+	<title>Technical Information</title>
+
+	<para>
+	Old Windows clients send plain text passwords over the wire. Samba can check these
+	passwords by encrypting them and comparing them to the hash stored in the UNIX user database.
+	</para>
+
+	<para>
+<indexterm><primary>encrypted passwords</primary></indexterm>	
+	Newer Windows clients send encrypted passwords (so-called LanMan and NT hashes) over 
+	the wire, instead of plain text passwords. The newest clients will send only encrypted
+	passwords and refuse to send plain text passwords, unless their registry is tweaked.
+	</para>
+
+	<para>
+	These passwords can't be converted to UNIX-style encrypted passwords. Because of that,
+	you can't use the standard UNIX user database, and you have to store the LanMan and NT
+	hashes somewhere else.
+	</para>
+	
+	<para>
+	In addition to differently encrypted passwords, Windows also stores certain data for each
+	user that is not stored in a UNIX user database. For example, workstations the user may logon from,
+	the location where the user's profile is stored, and so on. Samba retrieves and stores this
+	information using a <smbconfoption name="passdb backend"/>. Commonly available backends are LDAP, plain text
+	file, and MySQL. For more information, see the man page for &smb.conf; regarding the 
+	<smbconfoption name="passdb backend"/> parameter.
+	</para>
+
+
+	<image id="idmap-sid2uid">
+		<imagedescription>IDMAP: Resolution of SIDs to UIDs.</imagedescription>
+		<imagefile scale="50">idmap-sid2uid</imagefile>
+	</image>
+
+	<para>
+<indexterm><primary>SID</primary></indexterm>
+	The resolution of SIDs to UIDs is fundamental to correct operation of Samba. In both cases shown, if winbindd is not running, or cannot
+	be contacted, then only local SID/UID resolution is possible. See <link linkend="idmap-sid2uid">resolution of SIDs to UIDs</link> and
+	<link linkend="idmap-uid2sid">resolution of UIDs to SIDs</link> diagrams.
+	</para>
+
+	<image id="idmap-uid2sid">
+		<imagedescription>IDMAP: Resolution of UIDs to SIDs.</imagedescription>
+		<imagefile scale="50">idmap-uid2sid</imagefile>
+	</image>
+
+	<sect2>
+	<title>Important Notes About Security</title>
+		
+		<para>
+		The UNIX and SMB password encryption techniques seem similar on the surface. This
+		similarity is, however, only skin deep. The UNIX scheme typically sends clear-text
+		passwords over the network when logging in. This is bad. The SMB encryption scheme
+		never sends the clear-text password over the network but it does store the 16 byte 
+		hashed values on disk. This is also bad. Why? Because the 16 byte hashed values
+		are a <quote>password equivalent.</quote> You cannot derive the user's password from them, but
+		they could potentially be used in a modified client to gain access to a server.
+		This would require considerable technical knowledge on behalf of the attacker but
+		is perfectly possible. You should thus treat the data stored in whatever passdb
+		backend you use (smbpasswd file, LDAP, MYSQL) as though it contained the clear-text
+		passwords of all your users. Its contents must be kept secret and the file should
+		be protected accordingly.
+		</para>
+		
+		<para>
+		Ideally, we would like a password scheme that involves neither plain text passwords
+		on the network nor on disk. Unfortunately, this is not available as Samba is stuck with
+		having to be compatible with other SMB systems (Windows NT, Windows for Workgroups, Windows 9x/Me).
+		</para>
+
+		<para>
+		Windows NT 4.0 Service Pack 3 changed the default setting so plaintext passwords
+		are disabled from being sent over the wire. This mandates either the use of encrypted
+		password support or editing the Windows NT registry to re-enable plaintext passwords.
+		</para>
+		
+		<para>
+		The following versions of Microsoft Windows do not support full domain security protocols,
+		although they may log onto a domain environment:
+		</para>
+
+		<itemizedlist>
+			<listitem><para>MS DOS Network client 3.0 with the basic network redirector installed.</para></listitem>
+			<listitem><para>Windows 95 with the network redirector update installed.</para></listitem>
+			<listitem><para>Windows 98 [Second Edition].</para></listitem>
+			<listitem><para>Windows Me.</para></listitem>
+		</itemizedlist>
+
+		<note>
+		<para>
+ 		MS Windows XP Home does not have facilities to become a Domain Member and it cannot participate in domain logons.
+		</para>
+		</note>
+
+		<para>
+		The following versions of MS Windows fully support domain security protocols.
+		</para>
+
+		<itemizedlist>
+			<listitem><para>Windows NT 3.5x.</para></listitem>
+			<listitem><para>Windows NT 4.0.</para></listitem>
+			<listitem><para>Windows 2000 Professional.</para></listitem>
+			<listitem><para>Windows 200x Server/Advanced Server.</para></listitem>
+			<listitem><para>Windows XP Professional.</para></listitem>
+		</itemizedlist>
+			
+		<para>
+		All current releases of Microsoft SMB/CIFS clients support authentication via the
+		SMB Challenge/Response mechanism described here. Enabling clear-text authentication
+		does not disable the ability of the client to participate in encrypted authentication.
+		Instead, it allows the client to negotiate either plain text or encrypted password
+		handling.
+		</para>
+
+		<para>
+		MS Windows clients will cache the encrypted password alone. Where plain text passwords
+		are re-enabled through the appropriate registry change, the plain text password is never
+		cached. This means that in the event that a network connections should become disconnected
+		(broken), only the cached (encrypted) password will be sent to the resource server to
+		effect an auto-reconnect. If the resource server does not support encrypted passwords the
+		auto-reconnect will fail. Use of encrypted passwords is strongly advised.
+		</para>
+
+		<sect3>
+		<title>Advantages of Encrypted Passwords</title>
+
+			<itemizedlist>
+				<listitem><para>Plaintext passwords are not passed across 
+				the network. Someone using a network sniffer cannot just 
+				record passwords going to the SMB server.</para></listitem>
+
+				<listitem><para>Plaintext passwords are not stored anywhere in
+				memory or on disk.</para></listitem>
+			 
+				<listitem><para>Windows NT does not like talking to a server 
+				that does not support encrypted passwords. It will refuse 
+				to browse the server if the server is also in User Level 
+				security mode. It will insist on prompting the user for the 
+				password on each connection, which is very annoying. The
+				only things you can do to stop this is to use SMB encryption.
+				</para></listitem>
+
+				<listitem><para>Encrypted password support allows automatic share
+				(resource) reconnects.</para></listitem>
+
+				<listitem><para>Encrypted passwords are essential for PDC/BDC
+				operation.</para></listitem>
+			</itemizedlist>
+		</sect3>
+
+
+		<sect3>
+		<title>Advantages of Non-Encrypted Passwords</title>
+
+			<itemizedlist>
+				<listitem><para>Plaintext passwords are not kept 
+				on disk, and are not cached in memory. </para></listitem>
+				
+				<listitem><para>Uses same password file as other UNIX 
+				services such as Login and FTP.</para></listitem>
+				
+				<listitem><para>Use of other services (such as Telnet and FTP) that
+				send plain text passwords over the network, so sending them for SMB
+				is not such a big deal.</para></listitem>
+			</itemizedlist>
+		</sect3>
+	</sect2>
+
+	<sect2>
+	<title>Mapping User Identifiers between MS Windows and UNIX</title>
+
+	<para>
+	Every operation in UNIX/Linux requires a user identifier (UID), just as in
+	MS Windows NT4/200x this requires a Security Identifier (SID). Samba provides
+	two means for mapping an MS Windows user to a UNIX/Linux UID.
+	</para>
+
+	<para>
+	First, all Samba SAM (Security Account Manager database) accounts require
+	a UNIX/Linux UID that the account will map to. As users are added to the account
+	information database, Samba will call the <smbconfoption name="add user script"/>
+	interface to add the account to the Samba host OS. In essence all accounts in
+	the local SAM require a local user account.
+	</para>
+
+	<para>
+	<indexterm><primary>idmap uid</primary></indexterm>
+	<indexterm><primary>idmap gid</primary></indexterm>
+	The second way to effect Windows SID to UNIX UID mapping is via the
+	<emphasis>idmap uid</emphasis> and <emphasis>idmap gid</emphasis> parameters in &smb.conf;.
+	Please refer to the man page for information about these parameters.
+	These parameters are essential when mapping users from a remote SAM server.
+	</para>
+
+	</sect2>
+
+	<sect2 id="idmapbackend">
+	<title>Mapping Common UIDs/GIDs on Distributed Machines</title>
+
+	<para>
+	Samba-3 has a special facility that makes it possible to maintain identical UIDs and GIDs
+	on all servers in a distributed network. A distributed network is one where there exists
+	a PDC, one or more BDCs and/or one or more Domain Member servers. Why is this important?
+	This is important if files are being shared over more than one protocol (e.g., NFS) and where
+	users are copying files across UNIX/Linux systems using tools such as <command>rsync</command>.
+	</para>
+
+	<para>
+	<indexterm><primary>idmap backend</primary></indexterm>
+	The special facility is enabled using a parameter called <parameter>idmap backend</parameter>.
+	The default setting for this parameter is an empty string. Technically it is possible to use
+	an LDAP based idmap backend for UIDs and GIDs, but it makes most sense when this is done for
+	network configurations that also use LDAP for the SAM backend. Following
+	<link linkend="idmapbackendexample">example</link> shows that.
+	</para>
+
+	<para>
+<indexterm><primary>SAM backend</primary><secondary>ldapsam</secondary></indexterm>
+<smbconfexample id="idmapbackendexample">
+<title>Example configuration with the LDAP idmap backend</title>
+<smbconfsection name="[global]"/>
+<smbconfoption name="idmap backend">ldap:ldap://ldap-server.quenya.org:636</smbconfoption>
+<smbconfcomment>Alternately, this could be specified as:</smbconfcomment>
+<smbconfoption name="idmap backend">ldap:ldaps://ldap-server.quenya.org</smbconfoption>
+</smbconfexample>
+	</para>
+
+	<para>
+	A network administrator who wants to make significant use of LDAP backends will sooner or later be
+	exposed to the excellent work done by PADL Software. PADL <ulink url="http://www.padl.com"/> have
+	produced and released to open source an array of tools that might be of interest. These tools include:
+	</para>
+
+	<itemizedlist>
+		<listitem>
+		<para>
+		<emphasis>nss_ldap:</emphasis> An LDAP Name Service Switch module to provide native
+		name service support for AIX, Linux, Solaris, and other operating systems. This tool
+		can be used for centralized storage and retrieval of UIDs/GIDs.
+		</para>
+		</listitem>
+
+		<listitem>
+		<para>
+		<emphasis>pam_ldap:</emphasis> A PAM module that provides LDAP integration for UNIX/Linux
+		system access authentication.
+		</para>
+		</listitem>
+		<listitem>
+		<para>
+		<emphasis>idmap_ad:</emphasis> An IDMAP backend that supports the Microsoft Services for
+		UNIX RFC 2307 schema available from the PADL web 
+		<ulink url="http://www.padl.com/download/xad_oss_plugins.tar.gz">site</ulink>.
+		</para>
+		</listitem>
+	</itemizedlist>
+
+	</sect2>
+
+	<sect2>
+	<title>Regarding LDAP Directories and Windows Computer Accounts</title>
+
+		<para>
+		Samba doesn't provide a turnkey solution to LDAP. It is best to deal with the design and configuration
+		of an LDAP directory prior to integration with Samba. A working knowledge of LDAP makes Samba integration
+		easy and the lack of a working knowledge of LDAP can make it one a frustrating experience.
+		</para>
+
+		<para>
+		Computer (machine) accounts can be placed where ever you like in an LDAP directory subject to some
+		constraints that are described in this chapter.
+		</para>
+
+		<para>
+		The POSIX and SambaSAMAccount components of computer (machine) accounts are both used by Samba.
+		i.e.: Machine  accounts are treated inside Samba in the same way that Windows NT4/200X treats
+		them. A user account and a machine account are indistinquishable from each other, except that
+		the machine account ends in a '$' character, as do trust accounts.
+		</para>
+
+		<para>
+		The need for Windows user, group, machine, trust, etc. accounts to be tied to a valid UNIX uid
+		is a design decision that was made a long way back in the history of Samba development. It is
+		unlikely that this decision will be reversed of changed during the remaining life of the
+		Samba-3.x series.
+		</para>
+
+		<para>
+		The resolution of a UID from the Windows SID is achieved within Samba through a mechanism that
+		must refer back to the host operating system on which Samba is running. The Name Service
+		Switcher (NSS) is the preferred mechanism that shields applications (like Samba) from the
+		need to know everything about every host OS it runs on.
+		</para>
+
+		<para>
+		Samba asks the host OS to provide a UID via the <quote>passwd</quote>, <quote>shadow</quote>
+		and <quote>group</quote> facilities in the NSS control (configuration) file. The best tool
+		for achieving this is left up to the UNIX administrator to determine. It is not imposed by
+		Samba. Samba provides winbindd together with its support libraries as one method. It is
+		possible to do this via LDAP - and for that Samba provides the appropriate hooks so that
+		all account entities can be located in an LDAP directory.
+		</para>
+
+		<para>
+		For many the weapon of choice is to use the PADL nss_ldap utility. This utility must
+		be configured so that computer accounts can be resolved to a POSIX/UNIX account UID. That
+		is fundamentally an LDAP design question.  The information provided on the Samba list and
+		in the documentation is directed at providing working examples only. The design
+		of an LDAP directory is a complex subject that is beyond the scope of this documentation.
+		</para>
+
+	</sect2>
+
+</sect1>
+
+<sect1 id="acctmgmttools">
+<title>Account Management Tools</title>
+
+<para>
+<indexterm><primary>pdbedit</primary></indexterm>
+Samba provides two tools for management of user and machine accounts. These tools are
+called <command>smbpasswd</command> and <command>pdbedit</command>. 
+</para>
+	<sect2>
+	<title>The <emphasis>smbpasswd</emphasis> Command</title>
+	
+		<para>
+		The smbpasswd utility is similar to the <command>passwd</command>
+		or <command>yppasswd</command> programs. It maintains the two 32 byte password
+		fields in the passdb backend.
+		</para>
+
+		<para>
+		<command>smbpasswd</command> works in a client-server mode where it contacts the
+		local smbd to change the user's password on its behalf. This has enormous benefits.
+		</para>
+
+		<para>
+		<command>smbpasswd</command> has the capability to change passwords on Windows NT
+		servers (this only works when the request is sent to the NT Primary Domain Controller
+		if changing an NT Domain user's password).
+		</para>
+
+		<para>
+		<command>smbpasswd</command> can be used to:
+<indexterm><primary>User Management</primary></indexterm>
+<indexterm><primary>User Accounts</primary><secondary>Adding/Deleting</secondary></indexterm>
+		
+		</para>
+
+		<itemizedlist>
+			<listitem><para><emphasis>add</emphasis> user or machine accounts.</para></listitem>
+			<listitem><para><emphasis>delete</emphasis> user or machine accounts.</para></listitem>
+			<listitem><para><emphasis>enable</emphasis> user or machine accounts.</para></listitem>
+			<listitem><para><emphasis>disable</emphasis> user or machine accounts.</para></listitem>
+			<listitem><para><emphasis>set to NULL</emphasis> user passwords.</para></listitem>
+			<listitem><para><emphasis>manage interdomain trust accounts.</emphasis></para></listitem>
+		</itemizedlist>
+		
+		<para>
+		To run smbpasswd as a normal user just type:
+		</para>
+		
+		<para>
+<screen>
+&prompt;<userinput>smbpasswd</userinput>
+<prompt>Old SMB password: </prompt><userinput><replaceable>secret</replaceable></userinput>
+</screen>
+		For <replaceable>secret</replaceable>, type old value here or press return if
+		there is no old password.
+<screen>
+<prompt>New SMB Password: </prompt><userinput><replaceable>new secret</replaceable></userinput>
+<prompt>Repeat New SMB Password: </prompt><userinput><replaceable>new secret</replaceable></userinput>
+</screen>
+		</para>
+		
+		<para>
+		If the old value does not match the current value stored for that user, or the two
+		new values do not match each other, then the password will not be changed.
+		</para>
+		
+		<para>
+		When invoked by an ordinary user, the command will only allow the user to change his or her own
+		SMB password.
+		</para>
+		
+		<para>
+		When run by root, <command>smbpasswd</command> may take an optional argument specifying
+		the user name whose SMB password you wish to change. When run as root, <command>smbpasswd</command>
+		does not prompt for or check the old password value, thus allowing root to set passwords 
+		for users who have forgotten their passwords.
+		</para>
+		
+		<para>
+		<command>smbpasswd</command> is designed to work in the way familiar to UNIX
+		users who use the <command>passwd</command> or <command>yppasswd</command> commands.
+		While designed for administrative use, this tool provides essential User Level
+		password change capabilities.
+		</para>
+
+		<para>
+		For more details on using <command>smbpasswd</command>, refer to the man page (the
+		definitive reference).
+		</para>
+	</sect2>
+
+	<sect2 id="pdbeditthing">
+	<title>The <emphasis>pdbedit</emphasis> Command</title>
+
+		<para>
+<indexterm><primary>pdbedit</primary></indexterm>
+		<command>pdbedit</command> is a tool that can be used only by root. It is used to
+		manage the passdb backend. <command>pdbedit</command> can be used to:
+<indexterm><primary>User Management</primary></indexterm>
+<indexterm><primary>User Accounts</primary><secondary>Adding/Deleting</secondary></indexterm>
+
+		</para>
+
+		<itemizedlist>
+			<listitem><para>add, remove or modify user accounts.</para></listitem>
+			<listitem><para>list user accounts.</para></listitem>
+			<listitem><para>migrate user accounts.</para></listitem>
+		</itemizedlist>
+
+		<para>
+<indexterm><primary>pdbedit</primary></indexterm>
+		The <command>pdbedit</command> tool is the only one that can manage the account
+		security and policy settings. It is capable of all operations that smbpasswd can
+		do as well as a super set of them.
+		</para>
+
+		<para>
+<indexterm><primary>pdbedit</primary></indexterm>
+		One particularly important purpose of the <command>pdbedit</command> is to allow
+		the migration of account information from one passdb backend to another. See the
+		<link linkend="XMLpassdb">XML</link> password backend section of this chapter.
+		</para>
+
+		<para>
+		The following is an example of the user account information that is stored in
+		a tdbsam password backend. This listing was produced by running:
+		</para>
+
+<screen>
+&prompt;<userinput>pdbedit -Lv met</userinput>
+UNIX username:        met
+NT username:
+Account Flags:        [UX         ]
+User SID:             S-1-5-21-1449123459-1407424037-3116680435-2004
+Primary Group SID:    S-1-5-21-1449123459-1407424037-3116680435-1201
+Full Name:            Melissa E Terpstra
+Home Directory:       \\frodo\met\Win9Profile
+HomeDir Drive:        H:
+Logon Script:         scripts\logon.bat
+Profile Path:         \\frodo\Profiles\met
+Domain:               &example.workgroup;
+Account desc:
+Workstations:         melbelle
+Munged dial:
+Logon time:           0
+Logoff time:          Mon, 18 Jan 2038 20:14:07 GMT
+Kickoff time:         Mon, 18 Jan 2038 20:14:07 GMT
+Password last set:    Sat, 14 Dec 2002 14:37:03 GMT
+Password can change:  Sat, 14 Dec 2002 14:37:03 GMT
+Password must change: Mon, 18 Jan 2038 20:14:07 GMT
+</screen>
+
+		<para>
+<indexterm><primary>pdbedit</primary></indexterm>
+		The <command>pdbedit</command> tool allows migration of authentication (account)
+		databases from one backend to another. For example: To migrate accounts from an
+		old <filename>smbpasswd</filename> database to a <parameter>tdbsam</parameter>
+		backend:
+		</para>
+
+		<procedure>
+			<step><para>
+			Set the <smbconfoption name="passdb backend">tdbsam, smbpasswd</smbconfoption>.
+			</para></step>
+
+			<step><para>
+			Execute:
+<screen>
+&rootprompt;<userinput>pdbedit -i smbpasswd -e tdbsam</userinput>
+</screen>
+			</para></step>
+
+			<step><para>
+			Now remove the <parameter>smbpasswd</parameter> from the passdb backend
+			configuration in &smb.conf;.
+			</para></step>
+		</procedure>
+
+	</sect2>
+</sect1>
+
+<sect1>
+<title>Password Backends</title>
+
+<para>
+Samba offers the greatest flexibility in backend account database design of any SMB/CIFS server
+technology available today. The flexibility is immediately obvious as one begins to explore this
+capability.
+</para>
+
+<para>
+It is possible to specify not only multiple different password backends, but even multiple
+backends of the same type. For example, to use two different tdbsam databases:
+</para>
+
+<para>
+<smbconfblock>
+	<smbconfoption name="passdb backend">tdbsam:/etc/samba/passdb.tdb tdbsam:/etc/samba/old-passdb.tdb</smbconfoption>
+</smbconfblock>
+</para>
+
+
+	<sect2>
+	<title>Plaintext</title>
+
+		<para>
+		Older versions of Samba retrieved user information from the UNIX user database 
+		and eventually some other fields from the file <filename>/etc/samba/smbpasswd</filename>
+		or <filename>/etc/smbpasswd</filename>. When password encryption is disabled, no 
+		SMB specific data is stored at all. Instead all operations are conducted via the way
+		that the Samba host OS will access its <filename>/etc/passwd</filename> database.
+		Linux systems For example, all operations are done via PAM.
+		</para>
+
+	</sect2>
+
+	<sect2>
+	<title>smbpasswd &smbmdash; Encrypted Password Database</title>
+
+		<para>
+<indexterm><primary>SAM backend</primary><secondary>smbpasswd</secondary></indexterm>
+		Traditionally, when configuring <smbconfoption name="encrypt passwords">yes</smbconfoption> in Samba's &smb.conf; file, user account
+		information such as username, LM/NT password hashes, password change times, and account
+		flags have been stored in the <filename>smbpasswd(5)</filename> file. There are several
+		disadvantages to this approach for sites with large numbers of users (counted
+		in the thousands).
+		</para>
+
+		<itemizedlist>
+		<listitem><para>
+		The first problem is that all lookups must be performed sequentially. Given that
+		there are approximately two lookups per domain logon (one for a normal
+		session connection such as when mapping a network drive or printer), this
+		is a performance bottleneck for large sites. What is needed is an indexed approach
+		such as used in databases.
+		</para></listitem>
+
+		<listitem><para>
+		The second problem is that administrators who desire to replicate a smbpasswd file
+		to more than one Samba server were left to use external tools such as
+		<command>rsync(1)</command> and <command>ssh(1)</command> and wrote custom,
+		in-house scripts.
+		</para></listitem>
+
+		<listitem><para>
+		Finally, the amount of information that is stored in an smbpasswd entry leaves
+		no room for additional attributes such as a home directory, password expiration time,
+		or even a Relative Identifier (RID).
+		</para></listitem>
+		</itemizedlist>
+
+		<para>
+		As a result of these deficiencies, a more robust means of storing user attributes
+		used by smbd was developed. The API which defines access to user accounts
+		is commonly referred to as the samdb interface (previously this was called the passdb
+		API, and is still so named in the Samba CVS trees). 
+		</para>
+
+		<para>
+		Samba provides an enhanced set of passdb backends that overcome the deficiencies
+		of the smbpasswd plain text database. These are tdbsam, ldapsam and xmlsam.
+		Of these, ldapsam will be of most interest to large corporate or enterprise sites.
+		</para>
+
+	</sect2>
+
+	<sect2>
+	<title>tdbsam</title>
+
+	<para>
+<indexterm><primary>SAM backend</primary><secondary>tdbsam</secondary></indexterm>
+		Samba can store user and machine account data in a <quote>TDB</quote> (Trivial Database).
+		Using this backend does not require any additional configuration. This backend is
+		recommended for new installations that do not require LDAP.
+		</para>
+
+		<para>
+		As a general guide, the Samba Team does not recommend using the tdbsam backend for sites
+		that have 250 or more users. Additionally, tdbsam is not capable of scaling for use
+		in sites that require PDB/BDC implementations that require replication of the account
+		database. Clearly, for reason of scalability, the use of ldapsam should be encouraged.
+		</para>
+
+		<para>
+		The recommendation of a 250 user limit is purely based on the notion that this
+		would generally involve a site that has routed networks, possibly spread across
+		more than one physical location. The Samba Team has not at this time established
+		the performance based scalability limits of the tdbsam architecture.
+		</para>
+
+	</sect2>
+
+	<sect2>
+	<title>ldapsam</title>
+
+		<para>
+<indexterm><primary>SAM backend</primary><secondary>ldapsam</secondary></indexterm>
+		There are a few points to stress that the ldapsam does not provide. The LDAP
+		support referred to in this documentation does not include:
+		</para>
+
+		<itemizedlist>
+			<listitem><para>A means of retrieving user account information from
+			an Windows 200x Active Directory server.</para></listitem>
+			<listitem><para>A means of replacing /etc/passwd.</para></listitem>
+		</itemizedlist>
+
+		<para>
+		The second item can be accomplished by using LDAP NSS and PAM modules. LGPL
+		versions of these libraries can be obtained from 
+		<ulink url="http://www.padl.com/">PADL Software</ulink>.
+		More information about the configuration of these packages may be found at
+		<ulink url="http://safari.oreilly.com/?XmlId=1-56592-491-6">
+		<emphasis>LDAP, System Administration</emphasis>; Gerald Carter by O'Reilly; Chapter 6: Replacing NIS."</ulink>
+		</para>
+
+		<para>
+		This document describes how to use an LDAP directory for storing Samba user
+		account information traditionally stored in the smbpasswd(5) file. It is
+		assumed that the reader already has a basic understanding of LDAP concepts
+		and has a working directory server already installed. For more information
+		on LDAP architectures and directories, please refer to the following sites:
+		</para>
+
+		<itemizedlist>
+			<listitem><para><ulink url="http://www.openldap.org/">OpenLDAP</ulink></para></listitem>
+			<listitem><para><ulink url="http://iplanet.netscape.com/directory">Sun iPlanet Directory Server</ulink></para></listitem>
+		</itemizedlist>
+
+		<para>
+		Two additional Samba resources which may prove to be helpful are:
+		</para>
+
+		<itemizedlist>
+			<listitem><para>The <ulink url="http://www.unav.es/cti/ldap-smb/ldap-smb-3-howto.html">Samba-PDC-LDAP-HOWTO</ulink>
+			maintained by Ignacio Coupeau.</para></listitem>
+
+			<listitem><para>The NT migration scripts from <ulink url="http://samba.idealx.org/">IDEALX</ulink> that are
+			geared to manage users and group in such a Samba-LDAP Domain Controller configuration.
+			</para></listitem>
+		</itemizedlist>
+
+		<sect3>
+		<title>Supported LDAP Servers</title>
+
+			<para>
+			The LDAP ldapsam code has been developed and tested using the OpenLDAP 2.0 and 2.1 server and
+			client libraries. The same code should work with Netscape's Directory Server and client SDK.
+			However, there are bound to be compile errors and bugs. These should not be hard to fix.
+			Please submit fixes via the process outlined in <link linkend="bugreport">Reporting Bugs</link> chapter.
+			</para>
+
+		</sect3>
+
+		<sect3>
+		<title>Schema and Relationship to the RFC 2307 posixAccount</title>
+
+
+			<para>
+			Samba-3.0 includes the necessary schema file for OpenLDAP 2.0 in
+			<filename>examples/LDAP/samba.schema</filename>. The sambaSamAccount ObjectClass is given here:
+			</para>
+
+<para>
+<programlisting>
+ObjectClass (1.3.6.1.4.1.7165.2.2.6 NAME 'sambaSamAccount' SUP top AUXILIARY
+    DESC 'Samba-3.0 Auxiliary SAM Account'
+    MUST ( uid $ sambaSID )
+    MAY  ( cn $ sambaLMPassword $ sambaNTPassword $ sambaPwdLastSet $
+          sambaLogonTime $ sambaLogoffTime $ sambaKickoffTime $
+          sambaPwdCanChange $ sambaPwdMustChange $ sambaAcctFlags $
+          displayName $ sambaHomePath $ sambaHomeDrive $ sambaLogonScript $
+          sambaProfilePath $ description $ sambaUserWorkstations $
+          sambaPrimaryGroupSID $ sambaDomainName ))
+</programlisting>
+</para>
+
+			<para>
+			The <filename>samba.schema</filename> file has been formatted for OpenLDAP 2.0/2.1.
+			The Samba Team owns the OID space used by the above schema and recommends its use.
+			If you translate the schema to be used with Netscape DS, please submit the modified
+			schema file as a patch to <ulink url="mailto:jerry@samba.org">jerry@samba.org</ulink>.
+			</para>
+
+			<para>
+			Just as the smbpasswd file is meant to store information that provides information additional to  a
+			user's <filename>/etc/passwd</filename> entry, so is the sambaSamAccount object
+			meant to supplement the UNIX user account information. A sambaSamAccount is a
+			<constant>AUXILIARY</constant> ObjectClass so it can be used to augment existing
+			user account information in the LDAP directory, thus providing information needed
+			for Samba account handling. However, there are several fields (e.g., uid) that overlap
+			with the posixAccount ObjectClass outlined in RFC2307. This is by design.
+			</para>
+
+			<!--olem: we should perhaps have a note about shadowAccounts too as many
+			systems use them, isn'it ? -->
+
+			<para>
+			In order to store all user account information (UNIX and Samba) in the directory,
+			it is necessary to use the sambaSamAccount and posixAccount ObjectClass es in
+			combination. However, smbd will still obtain the user's UNIX account
+			information via the standard C library calls (e.g., getpwnam(), et al).
+			This means that the Samba server must also have the LDAP NSS library installed
+			and functioning correctly. This division of information makes it possible to
+			store all Samba account information in LDAP, but still maintain UNIX account
+			information in NIS while the network is transitioning to a full LDAP infrastructure.
+			</para>
+		</sect3>
+
+		<sect3>
+		<title>OpenLDAP Configuration</title>
+
+			<para>
+			To include support for the sambaSamAccount object in an OpenLDAP directory
+			server, first copy the samba.schema file to slapd's configuration directory.
+			The samba.schema file can be found in the directory <filename>examples/LDAP</filename>
+			in the Samba source distribution.
+			</para>
+
+<para>
+<screen>
+&rootprompt;<userinput>cp samba.schema /etc/openldap/schema/</userinput>
+</screen>
+</para>
+
+			<para>
+			Next, include the <filename>samba.schema</filename> file in <filename>slapd.conf</filename>.
+			The sambaSamAccount object contains two attributes that depend on other schema
+			files. The <parameter>uid</parameter> attribute is defined in <filename>cosine.schema</filename> and
+			the <parameter>displayName</parameter> attribute is defined in the <filename>inetorgperson.schema</filename>
+			file. Both of these must be included before the <filename>samba.schema</filename> file.
+			</para>
+
+<para>
+<programlisting>
+## /etc/openldap/slapd.conf
+
+## schema files (core.schema is required by default)
+include	           /etc/openldap/schema/core.schema
+
+## needed for sambaSamAccount
+include            /etc/openldap/schema/cosine.schema
+include            /etc/openldap/schema/inetorgperson.schema
+include            /etc/openldap/schema/nis.schema
+include            /etc/openldap/schema/samba.schema
+....
+</programlisting>
+</para>
+
+		<para>
+		It is recommended that you maintain some indices on some of the most useful attributes,
+		as in the following example, to speed up searches made on sambaSamAccount objectclasses
+		(and possibly posixAccount and posixGroup as well):
+		</para>
+
+<para>
+<programlisting>
+# Indices to maintain
+## required by OpenLDAP
+index objectclass             eq
+
+index cn                      pres,sub,eq
+index sn                      pres,sub,eq
+## required to support pdb_getsampwnam
+index uid                     pres,sub,eq
+## required to support pdb_getsambapwrid()
+index displayName             pres,sub,eq
+
+## uncomment these if you are storing posixAccount and
+## posixGroup entries in the directory as well
+##index uidNumber               eq
+##index gidNumber               eq
+##index memberUid               eq
+
+index   sambaSID              eq
+index   sambaPrimaryGroupSID  eq
+index   sambaDomainName       eq
+index   default               sub
+</programlisting>
+</para>
+
+		<para>
+		Create the new index by executing:
+		</para>
+
+<para>
+<screen>
+&rootprompt;./sbin/slapindex -f slapd.conf
+</screen>
+</para>
+
+		<para>
+		Remember to restart slapd after making these changes:
+		</para>
+
+<para>
+<screen>
+&rootprompt;<userinput>/etc/init.d/slapd restart</userinput>
+</screen>
+</para>
+
+		</sect3>
+
+		<sect3>
+		<title>Initialize the LDAP Database</title>
+
+		<para>
+		Before you can add accounts to the LDAP database you must create the account containers
+		that they will be stored in. The following LDIF file should be modified to match your
+		needs (DNS entries, and so on):
+		</para>
+		
+<para>
+	<smbfile name="samba.ldif.example">
+<programlisting>
+# Organization for Samba Base
+dn: dc=quenya,dc=org
+objectclass: dcObject
+objectclass: organization
+dc: quenya
+o: Quenya Org Network
+description: The Samba-3 Network LDAP Example
+
+# Organizational Role for Directory Management
+dn: cn=Manager,dc=quenya,dc=org
+objectclass: organizationalRole
+cn: Manager
+description: Directory Manager
+
+# Setting up container for users
+dn: ou=People,dc=quenya,dc=org
+objectclass: top
+objectclass: organizationalUnit
+ou: People
+
+# Setting up admin handle for People OU
+dn: cn=admin,ou=People,dc=quenya,dc=org
+cn: admin
+objectclass: top
+objectclass: organizationalRole
+objectclass: simpleSecurityObject
+userPassword: {SSHA}c3ZM9tBaBo9autm1dL3waDS21+JSfQVz
+
+# Setting up container for groups
+dn: ou=Groups,dc=quenya,dc=org
+objectclass: top
+objectclass: organizationalUnit
+ou: Groups
+
+# Setting up admin handle for Groups OU
+dn: cn=admin,ou=Groups,dc=quenya,dc=org
+cn: admin
+objectclass: top
+objectclass: organizationalRole
+objectclass: simpleSecurityObject
+userPassword: {SSHA}c3ZM9tBaBo9autm1dL3waDS21+JSfQVz
+
+# Setting up container for computers
+dn: ou=Computers,dc=quenya,dc=org
+objectclass: top
+objectclass: organizationalUnit
+ou: Computers
+
+# Setting up admin handle for Computers OU
+dn: cn=admin,ou=Computers,dc=quenya,dc=org
+cn: admin
+objectclass: top
+objectclass: organizationalRole
+objectclass: simpleSecurityObject
+userPassword: {SSHA}c3ZM9tBaBo9autm1dL3waDS21+JSfQVz
+</programlisting>
+</smbfile>
+</para>
+
+		<para>
+		The userPassword shown above should be generated using <command>slappasswd</command>.
+		</para>
+
+		<para>
+		The following command will then load the contents of the LDIF file into the LDAP
+		database.
+		</para>
+
+<para>
+<screen>
+&prompt;<userinput>slapadd -v -l initldap.dif</userinput>
+</screen>
+</para>
+
+		<para>
+		Do not forget to secure your LDAP server with an adequate access control list
+		as well as an admin password.
+		</para>
+
+		<note>
+		<para>
+		Before Samba can access the LDAP server you need to store the LDAP admin password
+		into the Samba-3 <filename>secrets.tdb</filename> database by:
+<screen>
+&rootprompt;<userinput>smbpasswd -w <replaceable>secret</replaceable></userinput>
+</screen>
+		</para>
+		</note>
+
+		</sect3>
+
+		<sect3>
+		<title>Configuring Samba</title>
+
+			<para>
+			The following parameters are available in smb.conf only if your
+			version of Samba was built with LDAP support. Samba automatically builds with LDAP support if the
+			LDAP libraries are found.
+			</para>
+
+			<para>LDAP related smb.conf options: 
+			<smbconfoption name="passdb backend">ldapsam:url</smbconfoption>,
+			<smbconfoption name="ldap admin dn"/>,
+			<smbconfoption name="ldap delete dn"/>,
+			<smbconfoption name="ldap filter"/>,
+			<smbconfoption name="ldap group suffix"/>,
+			<smbconfoption name="ldap idmap suffix"/>,
+			<smbconfoption name="ldap machine suffix"/>,
+			<smbconfoption name="ldap passwd sync"/>,
+			<smbconfoption name="ldap ssl"/>,
+			<smbconfoption name="ldap suffix"/>,
+			<smbconfoption name="ldap user suffix"/>,
+		</para>
+
+			<para>
+			These are described in the &smb.conf; man
+			page and so will not be repeated here. However, a <link linkend="confldapex">sample &smb.conf; file</link> for
+			use with an LDAP directory could appear as shown below.
+			</para>
+
+<para>
+<smbconfexample id="confldapex">
+<title>Configuration with LDAP</title>
+<smbconfsection name="[global]"/>
+<smbconfoption name="security">user</smbconfoption>
+<smbconfoption name="encrypt passwords">yes</smbconfoption>
+<smbconfoption name="netbios name">MORIA</smbconfoption>
+<smbconfoption name="workgroup">NOLDOR</smbconfoption>
+
+<smbconfcomment>ldap related parameters</smbconfcomment>
+
+<smbconfcomment>define the DN to use when binding to the directory servers</smbconfcomment>
+<smbconfcomment>The password for this DN is not stored in smb.conf. Rather it</smbconfcomment>
+<smbconfcomment>must be set by using 'smbpasswd -w secretpw' to store the</smbconfcomment>
+<smbconfcomment>passphrase in the secrets.tdb file. If the "ldap admin dn" values</smbconfcomment>
+<smbconfcomment>change, this password will need to be reset.</smbconfcomment>
+<smbconfoption name="ldap admin dn">"cn=Manager,dc=quenya,dc=org"</smbconfoption>
+
+<smbconfcomment>Define the SSL option when connecting to the directory</smbconfcomment>
+<smbconfcomment>('off', 'start tls', or 'on' (default))</smbconfcomment>
+<smbconfoption name="ldap ssl">start tls</smbconfoption>
+
+<smbconfcomment>syntax: passdb backend = ldapsam:ldap://server-name[:port]</smbconfcomment>
+<smbconfoption name="passdb backend">ldapsam:ldap://frodo.quenya.org</smbconfoption>
+
+<smbconfcomment>smbpasswd -x delete the entire dn-entry</smbconfcomment>
+<smbconfoption name="ldap delete dn">no</smbconfoption>
+
+<smbconfcomment>the machine and user suffix added to the base suffix</smbconfcomment>
+<smbconfcomment>wrote WITHOUT quotes. NULL suffixes by default</smbconfcomment>
+<smbconfoption name="ldap user suffix">ou=People</smbconfoption>
+<smbconfoption name="ldap group suffix">ou=Groups</smbconfoption>
+<smbconfoption name="ldap machine suffix">ou=Computers</smbconfoption>
+
+<smbconfcomment>Trust UNIX account information in LDAP</smbconfcomment>
+<smbconfcomment> (see the smb.conf man page for details)</smbconfcomment>
+
+<smbconfcomment> specify the base DN to use when searching the directory</smbconfcomment>
+<smbconfoption name="ldap suffix">dc=quenya,dc=org</smbconfoption>
+
+<smbconfcomment> generally the default ldap search filter is ok</smbconfcomment>
+<smbconfoption name="ldap filter">(uid=%u)</smbconfoption>
+</smbconfexample>
+</para>
+
+		</sect3>
+
+		<sect3>
+		<title>Accounts and Groups Management</title>
+
+			<para>
+<indexterm><primary>User Management</primary></indexterm>
+<indexterm><primary>User Accounts</primary><secondary>Adding/Deleting</secondary></indexterm>
+
+			As user accounts are managed through the sambaSamAccount objectclass, you should
+			modify your existing administration tools to deal with sambaSamAccount attributes.
+			</para>
+
+			<para>
+			Machine accounts are managed with the sambaSamAccount objectclass, just
+			like users accounts. However, it is up to you to store those accounts
+			in a different tree of your LDAP namespace. You should use
+			<quote>ou=Groups,dc=quenya,dc=org</quote> to store groups and
+			<quote>ou=People,dc=quenya,dc=org</quote> to store users. Just configure your
+			NSS and PAM accordingly (usually, in the <filename>/etc/openldap/sldap.conf</filename>
+			configuration file).
+			</para>
+
+			<para>
+			In Samba-3, the group management system is based on POSIX
+			groups. This means that Samba makes use of the posixGroup objectclass.
+			For now, there is no NT-like group system management (global and local
+			groups). Samba-3 knows only about <constant>Domain Groups</constant>
+			and, unlike MS Windows 2000 and Active Directory, Samba-3 does not
+			support nested groups. 
+			</para>
+
+		</sect3>
+
+		<sect3>
+		<title>Security and sambaSamAccount</title>
+
+
+			<para>
+			There are two important points to remember when discussing the security
+			of sambaSamAccount entries in the directory.
+			</para>
+
+			<itemizedlist>
+				<listitem><para><emphasis>Never</emphasis> retrieve the SambaLMPassword or
+				SambaNTPassword attribute values over an unencrypted LDAP session.</para></listitem>
+				<listitem><para><emphasis>Never</emphasis> allow non-admin users to
+				view the SambaLMPassword or SambaNTPassword attribute values.</para></listitem>
+			</itemizedlist>
+
+			<para>
+			These password hashes are clear-text equivalents and can be used to impersonate
+			the user without deriving the original clear-text strings. For more information
+			on the details of LM/NT password hashes, refer to the
+			<link linkend="passdb">Account Information Database</link> section of this chapter.
+			</para>
+
+			<para>
+			To remedy the first security issue, the <smbconfoption name="ldap ssl"/> &smb.conf; parameter defaults
+			to require an encrypted session (<smbconfoption name="ldap ssl">on</smbconfoption>) using
+			the default port of <constant>636</constant>
+			when contacting the directory server. When using an OpenLDAP server, it
+			is possible to use the StartTLS LDAP extended  operation in the place of
+			LDAPS. In either case, you are strongly discouraged to disable this security
+			(<smbconfoption name="ldap ssl">off</smbconfoption>).
+			</para>
+
+			<para>
+			Note that the LDAPS protocol is deprecated in favor of the LDAPv3 StartTLS
+			extended operation. However, the OpenLDAP library still provides support for
+			the older method of securing communication between clients and servers.
+			</para>
+
+			<para>
+			The second security precaution is to prevent non-administrative users from
+			harvesting password hashes from the directory. This can be done using the
+			following ACL in <filename>slapd.conf</filename>:
+			</para>
+
+<para>
+<programlisting>
+## allow the "ldap admin dn" access, but deny everyone else
+access to attrs=SambaLMPassword,SambaNTPassword
+     by dn="cn=Samba Admin,ou=People,dc=quenya,dc=org" write
+     by * none
+</programlisting>
+</para>
+
+		</sect3>
+
+		<sect3>
+		<title>LDAP Special Attributes for sambaSamAccounts</title>
+
+			<para> The sambaSamAccount objectclass is composed of the attributes shown in next tables: <link
+			linkend="attribobjclPartA">Part A</link>, and <link linkend="attribobjclPartB">Part B</link>. 
+			</para>
+
+			<para>
+			<table frame="all" id="attribobjclPartA">
+				<title>Attributes in the sambaSamAccount objectclass (LDAP) &smbmdash; Part A</title>
+			<tgroup cols="2" align="justify">
+					<colspec align="left"/>
+					<colspec align="justify" colwidth="1*"/>
+			<tbody>
+				<row><entry><constant>sambaLMPassword</constant></entry><entry>The LANMAN password 16-byte hash stored as a character
+						representation of a hexadecimal string.</entry></row>
+				<row><entry><constant>sambaNTPassword</constant></entry><entry>The NT password hash 16-byte stored as a character
+						representation of a hexadecimal string.</entry></row>
+				<row><entry><constant>sambaPwdLastSet</constant></entry><entry>The integer time in seconds since 1970 when the
+						<constant>sambaLMPassword</constant> and <constant>sambaNTPassword</constant> attributes were last set.
+				</entry></row>
+
+				<row><entry><constant>sambaAcctFlags</constant></entry><entry>String of 11 characters surrounded by square brackets []
+						representing account flags such as U (user), W (workstation), X (no password expiration),
+						I (Domain trust account), H (Home dir required), S (Server trust account),
+						and D (disabled).</entry></row>
+
+				<row><entry><constant>sambaLogonTime</constant></entry><entry>Integer value currently unused</entry></row>
+
+				<row><entry><constant>sambaLogoffTime</constant></entry><entry>Integer value currently unused</entry></row>
+
+				<row><entry><constant>sambaKickoffTime</constant></entry><entry>Specifies the time (UNIX time format) when the user
+				will be locked down and cannot login any longer. If this attribute is omitted, then the account will never expire.
+				If you use this attribute together with `shadowExpire' of the `shadowAccount' objectClass, will enable accounts to	
+				expire completely on an exact date.</entry></row>
+
+				<row><entry><constant>sambaPwdCanChange</constant></entry><entry>Specifies the time (UNIX time format) from which on the user is allowed to
+				change his password. If attribute is not set, the user will be free to change his password whenever he wants.</entry></row>
+
+				<row><entry><constant>sambaPwdMustChange</constant></entry><entry>Specifies the time (UNIX time format) since when the user is
+				forced to change his password. If this value is set to `0', the user will have to change his password at first login.
+				If this attribute is not set, then the password will never expire.</entry></row>
+
+				<row><entry><constant>sambaHomeDrive</constant></entry><entry>Specifies the drive letter to which to map the
+				UNC path specified by sambaHomePath. The drive letter must be specified in the form <quote>X:</quote>
+				where X is the letter of the drive to map. Refer to the <quote>logon drive</quote> parameter in the
+				smb.conf(5) man page for more information.</entry></row>
+
+				<row><entry><constant>sambaLogonScript</constant></entry><entry>The sambaLogonScript property specifies the path of
+				the user's logon script, .CMD, .EXE, or .BAT file. The string can be null. The path
+				is relative to the netlogon share. Refer to the <smbconfoption name="logon script"/> parameter in the
+				&smb.conf; man page for more information.</entry></row>
+
+				<row><entry><constant>sambaProfilePath</constant></entry><entry>Specifies a path to the user's profile.
+				This value can be a null string, a local absolute path, or a UNC path. Refer to the
+				<smbconfoption name="logon path"/> parameter in the &smb.conf; man page for more information.</entry></row>
+
+				<row><entry><constant>sambaHomePath</constant></entry><entry>The sambaHomePath property specifies the path of
+				the home directory for the user. The string can be null. If sambaHomeDrive is set and specifies
+				a drive letter, sambaHomePath should be a UNC path. The path must be a network
+				UNC path of the form <filename>\\server\share\directory</filename>. This value can be a null string.
+				Refer to the <command>logon home</command> parameter in the &smb.conf; man page for more information.
+				</entry></row>
+			</tbody>
+			</tgroup></table>
+			</para>
+			<para>
+			<table frame="all" id="attribobjclPartB">
+				<title>Attributes in the sambaSamAccount objectclass (LDAP) &smbmdash; Part B</title>
+			<tgroup cols="2" align="justify">
+					<colspec align="left"/>
+					<colspec align="justify" colwidth="1*"/>
+			<tbody>
+				<row><entry><constant>sambaUserWorkstations</constant></entry><entry>Here you can give a comma-separated list of machines
+				on which the user is allowed to login. You may observe problems when you try to connect to an Samba Domain Member.
+				Because Domain Members are not in this list, the Domain Controllers will reject them. Where this attribute is omitted,
+				the default implies no restrictions.
+				</entry></row>
+
+				<row><entry><constant>sambaSID</constant></entry><entry>The security identifier(SID) of the user.
+				The Windows equivalent of UNIX UIDs.</entry></row>
+
+				<row><entry><constant>sambaPrimaryGroupSID</constant></entry><entry>The Security IDentifier (SID) of the primary group
+				of the user.</entry></row>
+
+				<row><entry><constant>sambaDomainName</constant></entry><entry>Domain the user is part of.</entry></row>
+			</tbody>
+			</tgroup></table>
+			</para>
+
+			<para>
+			The majority of these parameters are only used when Samba is acting as a PDC of
+			a domain (refer to <link linkend="samba-pdc">Domain Control</link>, for details on
+			how to configure Samba as a Primary Domain Controller). The following four attributes
+			are only stored with the sambaSamAccount entry if the values are non-default values:
+			</para>
+
+			<itemizedlist>
+				<listitem><para>sambaHomePath</para></listitem>
+				<listitem><para>sambaLogonScript</para></listitem>
+				<listitem><para>sambaProfilePath</para></listitem>
+				<listitem><para>sambaHomeDrive</para></listitem>
+			</itemizedlist>
+
+			<para>
+			These attributes are only stored with the sambaSamAccount entry if
+			the values are non-default values. For example, assume MORIA has now been
+			configured as a PDC and that <smbconfoption name="logon home">\\%L\%u</smbconfoption> was defined in
+			its &smb.conf; file. When a user named <quote>becky</quote> logons to the domain,
+			the <smbconfoption name="logon home"/> string is expanded to \\MORIA\becky.
+			If the smbHome attribute exists in the entry <quote>uid=becky,ou=People,dc=samba,dc=org</quote>,
+			this value is used. However, if this attribute does not exist, then the value
+			of the <smbconfoption name="logon home"/> parameter is used in its place. Samba
+			will only write the attribute value to the directory entry if the value is
+			something other than the default (e.g., <filename>\\MOBY\becky</filename>).
+			</para>
+
+		</sect3>
+
+		<sect3>
+		<title>Example LDIF Entries for a sambaSamAccount</title>
+
+			<para>
+			The following is a working LDIF that demonstrates the use of the SambaSamAccount objectclass:
+			</para>
+
+	<para>
+		<smbfile name="samba.ldif.example2">
+	<programlisting>
+	dn: uid=guest2, ou=People,dc=quenya,dc=org
+	sambaLMPassword: 878D8014606CDA29677A44EFA1353FC7
+	sambaPwdMustChange: 2147483647
+	sambaPrimaryGroupSID: S-1-5-21-2447931902-1787058256-3961074038-513
+	sambaNTPassword: 552902031BEDE9EFAAD3B435B51404EE
+	sambaPwdLastSet: 1010179124
+	sambaLogonTime: 0
+	objectClass: sambaSamAccount
+	uid: guest2
+	sambaKickoffTime: 2147483647
+	sambaAcctFlags: [UX         ]
+	sambaLogoffTime: 2147483647
+	sambaSID: S-1-5-21-2447931902-1787058256-3961074038-5006
+	sambaPwdCanChange: 0
+</programlisting>
+</smbfile>
+	</para>
+
+			<para>
+			The following is an LDIF entry for using both the sambaSamAccount and
+			posixAccount objectclasses:
+			</para>
+
+			<para>
+				<smbfile name="samba.ldif.example3">
+	<programlisting>
+	dn: uid=gcarter, ou=People,dc=quenya,dc=org
+	sambaLogonTime: 0
+	displayName: Gerald Carter
+	sambaLMPassword: 552902031BEDE9EFAAD3B435B51404EE
+	sambaPrimaryGroupSID: S-1-5-21-2447931902-1787058256-3961074038-1201
+	objectClass: posixAccount
+	objectClass: sambaSamAccount
+	sambaAcctFlags: [UX         ]
+	userPassword: {crypt}BpM2ej8Rkzogo
+	uid: gcarter
+	uidNumber: 9000
+	cn: Gerald Carter
+	loginShell: /bin/bash
+	logoffTime: 2147483647
+	gidNumber: 100
+	sambaKickoffTime: 2147483647
+	sambaPwdLastSet: 1010179230
+	sambaSID: S-1-5-21-2447931902-1787058256-3961074038-5004
+	homeDirectory: /home/moria/gcarter
+	sambaPwdCanChange: 0
+	sambaPwdMustChange: 2147483647
+	sambaNTPassword: 878D8014606CDA29677A44EFA1353FC7
+</programlisting>
+</smbfile>
+	</para>
+
+		</sect3>
+
+		<sect3>
+		<title>Password Synchronization</title>
+
+		<para>
+		Samba-3 and later can update the non-samba (LDAP) password stored with an account. When
+		using pam_ldap, this allows changing both UNIX and Windows passwords at once.
+		</para>
+
+		<para>The <smbconfoption name="ldap passwd sync"/> options can have the  values shown in
+		<link linkend="ldappwsync">the next table</link>.</para>
+
+		<table frame="all" id="ldappwsync">
+			<title>Possible <emphasis>ldap passwd sync</emphasis> values</title>
+		<tgroup cols="2">
+			<colspec align="left" colwidth="1*"/>
+			<colspec align="justify" colwidth="4*"/>
+		<thead>
+			<row><entry align="left">Value</entry><entry align="center">Description</entry></row>
+		</thead>
+		<tbody>
+		<row><entry>yes</entry><entry><para>When the user changes his password, update
+			       <constant>SambaNTPassword</constant>, <constant>SambaLMPassword</constant>
+			       and the <constant>password</constant> fields.</para></entry></row>
+
+		<row><entry>no</entry><entry><para>Only update <constant>SambaNTPassword</constant> and <constant>SambaLMPassword</constant>.</para></entry></row>
+
+		<row><entry>only</entry><entry><para>Only update the LDAP password and let the LDAP server worry about the other fields.
+			This option is only available on some LDAP servers. Only when the LDAP server
+			supports LDAP_EXOP_X_MODIFY_PASSWD.</para></entry></row>
+		</tbody>
+		</tgroup>
+		</table>
+
+
+		<para>More information can be found in the &smb.conf; man page.</para>
+
+		</sect3>
+
+	</sect2>
+
+	<sect2>
+	<title>MySQL</title>
+
+	<para>
+<indexterm><primary>SAM backend</primary><secondary>mysqlsam</secondary></indexterm>
+	Every so often someone will come along with a great new idea. Storing user accounts in a
+	SQL backend is one of them. Those who want to do this are in the best position to know what the
+	specific benefits are to them. This may sound like a cop-out, but in truth we cannot attempt
+	to document every little detail why certain things of marginal utility to the bulk of
+	Samba users might make sense to the rest. In any case, the following instructions should help
+	the determined SQL user to implement a working system.
+	</para>
+
+		<sect3>
+		<title>Creating the Database</title>
+
+			<para>
+			You can set up your own table and specify the field names to pdb_mysql (see below
+			for the column names) or use the default table. The file <filename>examples/pdb/mysql/mysql.dump</filename> 
+			contains the correct queries to create the required tables. Use the command:
+
+<screen>
+&prompt;<userinput>mysql -u<replaceable>username</replaceable> -h<replaceable>hostname</replaceable> -p<replaceable>password</replaceable> \
+	<replaceable>databasename</replaceable> &lt; <filename>/path/to/samba/examples/pdb/mysql/mysql.dump</filename></userinput>
+</screen>
+			</para>
+		</sect3>
+
+		<sect3>
+		<title>Configuring</title>
+
+			<para>This plug-in lacks some good documentation, but here is some brief information. Add the following to the
+			<smbconfoption name="passdb backend"/> variable in your &smb.conf;:
+<smbconfblock>
+<smbconfoption name="passdb backend">[other-plugins] mysql:identifier [other-plugins]</smbconfoption>
+</smbconfblock>
+			</para>
+
+			<para>The identifier can be any string you like, as long as it does not collide with 
+			the identifiers of other plugins or other instances of pdb_mysql. If you 
+			specify multiple pdb_mysql.so entries in <smbconfoption name="passdb backend"/>, you also need to 
+			use different identifiers.
+			</para>
+
+			<para>
+			Additional options can be given through the &smb.conf; file in the <smbconfsection name="[global]"/> section.
+			Refer to <link linkend="mysqlpbe">the following table</link>.
+			</para>
+
+			<table frame="all" id="mysqlpbe">
+				<title>Basic smb.conf options for MySQL passdb backend</title>
+				<tgroup cols="2">
+					<colspec align="left"/>
+					<colspec align="justify" colwidth="1*"/>
+				<thead>
+					<row><entry>Field</entry><entry>Contents</entry></row>
+				</thead>
+				<tbody>
+					<row><entry>mysql host</entry><entry>Host name, defaults to `localhost'</entry></row>
+					<row><entry>mysql password</entry><entry></entry></row>
+					<row><entry>mysql user</entry><entry>Defaults to `samba'</entry></row>
+					<row><entry>mysql database</entry><entry>Defaults to `samba'</entry></row>
+					<row><entry>mysql port</entry><entry>Defaults to 3306</entry></row>
+					<row><entry>table</entry><entry>Name of the table containing the users</entry></row>
+				</tbody>
+				</tgroup>
+			</table>
+
+			<warning>
+			<para>
+			Since the password for the MySQL user is stored in the &smb.conf; file, you should make the &smb.conf; file 
+			readable only to the user who runs Samba. This is considered a security bug and will soon be fixed.
+			</para>
+			</warning>
+
+			<para>Names of the columns are given in <link linkend="moremysqlpdbe">the next table</link>. 
+			The default column names can be found in the example table dump.
+			 </para>
+
+		<para>
+			<table frame="all" id="moremysqlpdbe">
+				<title>MySQL field names for MySQL passdb backend</title>
+				<tgroup cols="3" align="justify">
+					<colspec align="left"/>
+					<colspec align="left"/>
+					<colspec align="justify" colwidth="1*"/>
+			<thead>		
+				<row><entry>Field</entry><entry>Type</entry><entry>Contents</entry></row>
+			</thead>
+			<tbody>
+				<row><entry>logon time column</entry><entry>int(9)</entry><entry>UNIX time stamp of last logon of user</entry></row>
+				<row><entry>logoff time column</entry><entry>int(9)</entry><entry>UNIX time stamp of last logoff of user</entry></row>
+				<row><entry>kickoff time column</entry><entry>int(9)</entry><entry>UNIX time stamp of moment user should be kicked off workstation (not enforced)</entry></row>
+				<row><entry>pass last set time column</entry><entry>int(9)</entry><entry>UNIX time stamp of moment password was last set</entry></row>
+				<row><entry>pass can change time column</entry><entry>int(9)</entry><entry>UNIX time stamp of moment from which password can be changed</entry></row>
+				<row><entry>pass must change time column</entry><entry>int(9)</entry><entry>UNIX time stamp of moment on which password must be changed</entry></row>
+				<row><entry>username column</entry><entry>varchar(255)</entry><entry>UNIX username</entry></row>
+				<row><entry>domain column</entry><entry>varchar(255)</entry><entry>NT domain user belongs to</entry></row>
+				<row><entry>nt username column</entry><entry>varchar(255)</entry><entry>NT username</entry></row>
+				<row><entry>fullname column</entry><entry>varchar(255)</entry><entry>Full name of user</entry></row>
+				<row><entry>home dir column</entry><entry>varchar(255)</entry><entry>UNIX homedir path (equivalent of the <smbconfoption name="logon home"/> parameter.</entry></row>
+				<row><entry>dir drive column</entry><entry>varchar(2)</entry><entry>Directory drive path (e.g., <quote>H:</quote>)</entry></row>
+				<row><entry>logon script column</entry><entry>varchar(255)</entry><entry>Batch file to run on client side when logging on</entry></row>
+				<row><entry>profile path column</entry><entry>varchar(255)</entry><entry>Path of profile</entry></row>
+				<row><entry>acct desc column</entry><entry>varchar(255)</entry><entry>Some ASCII NT user data</entry></row>
+				<row><entry>workstations column</entry><entry>varchar(255)</entry><entry>Workstations user can logon to (or NULL for all)</entry></row>
+				<row><entry>unknown string column</entry><entry>varchar(255)</entry><entry>Unknown string</entry></row>
+				<row><entry>munged dial column</entry><entry>varchar(255)</entry><entry>Unknown</entry></row>
+				<row><entry>user sid column</entry><entry>varchar(255)</entry><entry>NT user SID</entry></row>
+				<row><entry>group sid column</entry><entry>varchar(255)</entry><entry>NT group SID</entry></row>
+				<row><entry>lanman pass column</entry><entry>varchar(255)</entry><entry>Encrypted lanman password</entry></row>
+				<row><entry>nt pass column</entry><entry>varchar(255)</entry><entry>Encrypted nt passwd</entry></row>
+				<row><entry>plain pass column</entry><entry>varchar(255)</entry><entry>Plaintext password</entry></row>
+				<row><entry>acct ctrl column</entry><entry>int(9)</entry><entry>NT user data</entry></row>
+				<row><entry>unknown 3 column</entry><entry>int(9)</entry><entry>Unknown</entry></row>
+				<row><entry>logon divs column</entry><entry>int(9)</entry><entry>Unknown</entry></row>
+				<row><entry>hours len column</entry><entry>int(9)</entry><entry>Unknown</entry></row>
+				<row><entry>bad password count column</entry><entry>int(5)</entry><entry>Number of failed password tries before disabling an account</entry></row>
+				<row><entry>logon count column</entry><entry>int(5)</entry><entry>Number of logon attempts</entry></row>
+				<row><entry>unknown 6 column</entry><entry>int(9)</entry><entry>Unknown</entry></row>
+			</tbody></tgroup>
+		</table>
+		</para>
+
+			<para>
+			You can put a colon (:) after the name of each column, which 
+			should specify the column to update when updating the table. One can also specify nothing behind the colon, in which case the field data will not be updated. Setting a column name to <parameter>NULL</parameter> means the field should not be used.
+			</para>
+
+			<para><link linkend="mysqlsam">An example configuration</link> looks like:
+			</para>
+
+			<smbconfexample id="mysqlsam">
+				<title>Example configuration for the MySQL passdb backend</title>
+			<smbconfsection name="[global]"/>
+			<smbconfoption name="passdb backend">mysql:foo</smbconfoption>
+			<smbconfoption name="foo:mysql user">samba</smbconfoption>
+			<smbconfoption name="foo:mysql password">abmas</smbconfoption>
+			<smbconfoption name="foo:mysql database">samba</smbconfoption>
+			<smbconfcomment>domain name is static and can't be changed</smbconfcomment>
+			<smbconfoption name="foo:domain column">'MYWORKGROUP':</smbconfoption>
+			<smbconfcomment>The fullname column comes from several other columns</smbconfcomment>
+			<smbconfoption name="foo:fullname column">CONCAT(firstname,' ',surname):</smbconfoption>
+			<smbconfcomment>Samba should never write to the password columns</smbconfcomment>
+			<smbconfoption name="foo:lanman pass column">lm_pass:</smbconfoption>
+			<smbconfoption name="foo:nt pass column">nt_pass:</smbconfoption>
+			<smbconfcomment>The unknown 3 column is not stored</smbconfcomment>
+			<smbconfoption name="foo:unknown 3 column">NULL</smbconfoption>
+			</smbconfexample>
+		</sect3>
+
+		<sect3>
+		<title>Using Plaintext Passwords or Encrypted Password</title>
+
+			<para>
+<indexterm><primary>encrypted passwords</primary></indexterm>
+			I strongly discourage the use of plaintext passwords, however, you can use them.
+			</para>
+
+			<para>
+			If you would like to use plaintext passwords, set
+			`identifier:lanman pass column' and `identifier:nt pass column' to
+			`NULL' (without the quotes) and `identifier:plain pass column' to the
+			name of the column containing the plaintext passwords. 
+			</para>
+
+			<para>
+			If you use encrypted passwords, set the 'identifier:plain pass
+			column' to 'NULL' (without the quotes). This is the default.
+			</para>
+
+		</sect3>
+
+		<sect3>
+		<title>Getting Non-Column Data from the Table</title>
+
+			<para>
+			It is possible to have not all data in the database by making some `constant'.
+			</para>
+
+			<para>
+			For example, you can set `identifier:fullname column' to
+			something like <?latex \linebreak ?><command>CONCAT(Firstname,' ',Surname)</command>
+			</para>
+
+			<para>
+			Or, set `identifier:workstations column' to:
+			<command>NULL</command></para>
+
+			<para>See the MySQL documentation for more language constructs.</para>
+
+		</sect3>
+	</sect2>
+
+	<sect2 id="XMLpassdb">
+	<title>XML</title>
+
+	<para>
+<indexterm><primary>SAM backend</primary><secondary>xmlsam</secondary></indexterm>
+		This module requires libxml2 to be installed.</para>
+
+		<para>The usage of pdb_xml is fairly straightforward. To export data, use:
+		</para>
+
+		<para>
+<indexterm><primary>pdbedit</primary></indexterm>
+			<prompt>$ </prompt> <userinput>pdbedit -e xml:filename</userinput>
+		</para>
+
+		<para>
+		(where filename is the name of the file to put the data in)
+		</para>
+
+		<para>
+		To import data, use:
+		<prompt>$ </prompt> <userinput>pdbedit -i xml:filename</userinput>
+		</para>
+	</sect2>
+</sect1>
+
+<sect1>
+<title>Common Errors</title>
+
+	<sect2>
+		<title>Users Cannot Logon</title>
+
+		<para><quote>I've installed Samba, but now I can't log on with my UNIX account! </quote></para>
+
+		<para>Make sure your user has been added to the current Samba <smbconfoption name="passdb backend"/>. 
+		Read the section <link linkend="acctmgmttools">Account Management Tools</link> for details.</para>
+
+	</sect2>
+
+	<sect2>
+	<title>Users Being Added to the Wrong Backend Database</title>
+
+	<para>
+	A few complaints have been received from users that just moved to Samba-3. The following
+	&smb.conf; file entries were causing problems, new accounts were being added to the old
+	smbpasswd file, not to the tdbsam passdb.tdb file:
+	</para>
+
+	<para>
+	<smbconfblock>
+	<smbconfsection name="[global]"/>
+	<member>...</member>
+	<smbconfoption name="passdb backend">smbpasswd, tdbsam</smbconfoption>
+	<member>...</member>
+	</smbconfblock>
+	</para>
+
+	<para>
+	Samba will add new accounts to the first entry in the <emphasis>passdb backend</emphasis>
+	parameter entry. If you want to update to the tdbsam, then change the entry to:
+	</para>
+
+	<para>
+<smbconfblock>
+[globals]
+...
+<smbconfoption name="passdb backend">tdbsam, smbpasswd</smbconfoption>
+...
+</smbconfblock>
+	</para>
+
+	</sect2>
+
+	<sect2>
+	<title>Configuration of <parameter>auth methods</parameter></title>
+
+	<para>
+	When explicitly setting an <smbconfoption name="auth methods"/> parameter,
+	<parameter>guest</parameter> must be specified as the first entry on the line,
+	for example, <smbconfoption name="auth methods">guest sam</smbconfoption>.
+	</para>
+
+	</sect2>
+
+</sect1>
+
+</chapter>