Moving docs tree to docs-xml to make room for generated docs in the release tarball.

(This used to be commit 9f672c26d63955f613088489c6efbdc08b5b2d14)

1 files changed, 1013 insertions, 0 deletions

diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-PAM.xml b/docs-xml/Samba3-HOWTO/TOSHARG-PAM.xml
new file mode 100644
index 0000000000..072e88a5ba
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-PAM.xml
@@ -0,0 +1,1013 @@
+<?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="pam">
+<chapterinfo>
+	&author.jht;
+	<author>
+		<firstname>Stephen</firstname><surname>Langasek</surname>
+		<affiliation>
+			<address><email>vorlon@netexpress.net</email></address>
+		</affiliation>
+	</author>
+    <pubdate>May 31, 2003</pubdate>
+</chapterinfo>
+ 
+<title>PAM-Based Distributed Authentication</title>
+
+<para>
+<indexterm><primary>PAM-enabled</primary></indexterm>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+<indexterm><primary>Winbind-based authentication</primary></indexterm>
+This chapter should help you to deploy Winbind-based authentication on any PAM-enabled
+UNIX/Linux system. Winbind can be used to enable user-level application access authentication
+from any MS Windows NT domain, MS Windows 200x Active Directory-based
+domain, or any Samba-based domain environment. It will also help you to configure PAM-based local host access
+controls that are appropriate to your Samba configuration.
+</para>
+
+<para>
+<indexterm><primary>PAM management</primary></indexterm>
+<indexterm><primary>pam_smbpass.so</primary></indexterm>
+In addition to knowing how to configure Winbind into PAM, you will learn generic PAM management
+possibilities and in particular how to deploy tools like <filename>pam_smbpass.so</filename> to your advantage.
+</para>
+
+<note><para>
+The use of Winbind requires more than PAM configuration alone.
+Please refer to <link linkend="winbind">Winbind: Use of Domain Accounts</link>, for further information regarding Winbind.
+</para></note>
+
+<sect1>
+<title>Features and Benefits</title>
+
+<para>
+<indexterm><primary>Sun Solaris</primary></indexterm>
+<indexterm><primary>xxxxBSD</primary></indexterm>
+<indexterm><primary>Linux</primary></indexterm>
+<indexterm><primary>Pluggable Authentication Modules</primary><see>PAM</see></indexterm>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>login</primary></indexterm>
+<indexterm><primary>passwd</primary></indexterm>
+<indexterm><primary>chown</primary></indexterm>
+A number of UNIX systems (e.g., Sun Solaris), as well as the xxxxBSD family and Linux,
+now utilize the Pluggable Authentication Modules (PAM) facility to provide all authentication, 
+authorization, and resource control services. Prior to the introduction of PAM, a decision
+to use an alternative to the system password database (<filename>/etc/passwd</filename>) 
+would require the provision of alternatives for all programs that provide security services.
+Such a choice would involve provision of alternatives to programs such as <command>login</command>, 
+<command>passwd</command>, <command>chown</command>, and so on.
+</para>
+
+<para>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>/etc/pam.conf</primary></indexterm>
+<indexterm><primary>Solaris</primary></indexterm>
+<indexterm><primary>/etc/pam.d</primary></indexterm>
+PAM provides a mechanism that disconnects these security programs from the underlying
+authentication/authorization infrastructure. PAM is configured by making appropriate modifications to one file,
+<filename>/etc/pam.conf</filename> (Solaris), or by editing individual control files that are
+located in <filename>/etc/pam.d</filename>.
+</para>
+
+<para>
+<indexterm><primary>PAM-enabled</primary></indexterm>
+<indexterm><primary>dynamically loadable library modules</primary></indexterm>
+On PAM-enabled UNIX/Linux systems, it is an easy matter to configure the system to use any
+authentication backend so long as the appropriate dynamically loadable library modules
+are available for it. The backend may be local to the system or may be centralized on a
+remote server.
+</para>
+
+<para>
+PAM support modules are available for:
+</para>
+
+<variablelist>
+	<varlistentry><term><filename>/etc/passwd</filename></term><listitem>
+		<para>
+<indexterm><primary>/etc/passwd</primary></indexterm>
+<indexterm><primary>PAM modules</primary></indexterm>
+<indexterm><primary>pam_unix.so</primary></indexterm>
+<indexterm><primary>pam_unix2.so</primary></indexterm>
+<indexterm><primary>pam_pwdb.so</primary></indexterm>
+<indexterm><primary>pam_userdb.so</primary></indexterm>
+		There are several PAM modules that interact with this standard UNIX user database. The most common are called
+		<filename>pam_unix.so</filename>, <filename>pam_unix2.so</filename>, <filename>pam_pwdb.so</filename> and
+		<filename>pam_userdb.so</filename>.
+		</para>
+	</listitem></varlistentry>
+
+	<varlistentry><term>Kerberos</term><listitem>
+		<para>
+<indexterm><primary>pam_krb5.so</primary></indexterm>
+<indexterm><primary>Kerberos</primary></indexterm>
+<indexterm><primary>Heimdal</primary></indexterm>
+<indexterm><primary>MIT Kerberos</primary></indexterm>
+<indexterm><primary>ADS</primary></indexterm>
+		The <filename>pam_krb5.so</filename> module allows the use of any Kerberos-compliant server.
+		This tool is used to access MIT Kerberos, Heimdal Kerberos, and potentially
+		Microsoft Active Directory (if enabled).
+		</para>
+	</listitem></varlistentry>
+
+	<varlistentry><term>LDAP</term><listitem>
+		<para>
+<indexterm><primary>LDAP</primary></indexterm>
+<indexterm><primary>pam_ldap.so</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>Sun ONE iDentity server</primary></indexterm>
+<indexterm><primary>Novell eDirectory server</primary></indexterm>
+<indexterm><primary>Microsoft Active Directory</primary></indexterm>
+		The <filename>pam_ldap.so</filename> module allows the use of any LDAP v2- or v3-compatible backend
+		server. Commonly used LDAP backend servers include OpenLDAP v2.0 and v2.1,
+		Sun ONE iDentity server, Novell eDirectory server, and Microsoft Active Directory.
+		</para>
+	</listitem></varlistentry>
+
+	<varlistentry><term>NetWare Bindery</term><listitem>
+		<para>
+<indexterm><primary>NetWare Bindery</primary></indexterm>
+<indexterm><primary>pam_ncp_auth.so</primary></indexterm>
+<indexterm><primary>bindery-enabled</primary></indexterm>
+<indexterm><primary>NetWare Core Protocol-based server</primary></indexterm>
+		The <filename>pam_ncp_auth.so</filename> module allows authentication off any bindery-enabled
+		NetWare Core Protocol-based server.
+		</para>
+	</listitem></varlistentry>
+
+	<varlistentry><term>SMB Password</term><listitem>
+		<para>
+<indexterm><primary>SMB Password</primary></indexterm>
+<indexterm><primary>pam_smbpass.so</primary></indexterm>
+<indexterm><primary>passdb backend</primary></indexterm>
+		This module, called <filename>pam_smbpass.so</filename>, allows user authentication of
+		the passdb backend that is configured in the Samba &smb.conf; file.
+		</para>
+	</listitem></varlistentry>
+
+	<varlistentry><term>SMB Server</term><listitem>
+		<para>
+<indexterm><primary>SMB Server</primary></indexterm>
+<indexterm><primary>pam_smb_auth.so</primary></indexterm>
+		The <filename>pam_smb_auth.so</filename> module is the original MS Windows networking authentication
+		tool. This module has been somewhat outdated by the Winbind module.
+		</para>
+	</listitem></varlistentry>
+
+	<varlistentry><term>Winbind</term><listitem>
+		<para>
+<indexterm><primary>Winbind</primary></indexterm>
+<indexterm><primary>pam_winbind.so</primary></indexterm>
+<indexterm><primary>domain controller</primary></indexterm>
+<indexterm><primary>authentication</primary></indexterm>
+		The <filename>pam_winbind.so</filename> module allows Samba to obtain authentication from any
+		MS Windows domain controller. It can just as easily be used to authenticate
+		users for access to any PAM-enabled application.
+		</para>
+	</listitem></varlistentry>
+
+	<varlistentry><term>RADIUS</term><listitem>
+		<para>
+<indexterm><primary>Remote Access Dial-In User Service</primary><see>RADIUS</see></indexterm>
+		There is a PAM RADIUS (Remote Access Dial-In User Service) authentication
+		module. In most cases, administrators need to locate the source code
+		for this tool and compile and install it themselves. RADIUS protocols are
+		used by many routers and terminal servers.
+		</para>
+	</listitem></varlistentry>
+</variablelist>
+
+<para>
+<indexterm><primary>pam_smbpasswd.so</primary></indexterm>
+<indexterm><primary>pam_winbind.so</primary></indexterm>
+Of the modules listed, Samba provides the <filename>pam_smbpasswd.so</filename> and the
+<filename>pam_winbind.so</filename> modules alone.
+</para>
+
+<para>
+<indexterm><primary>wide-area network bandwidth</primary></indexterm>
+<indexterm><primary>efficient authentication</primary></indexterm>
+<indexterm><primary>PAM-capable</primary></indexterm>
+<indexterm><primary>centrally managed</primary></indexterm>
+Once configured, these permit a remarkable level of flexibility in the location and use
+of distributed Samba domain controllers that can provide wide-area network bandwidth,
+efficient authentication services for PAM-capable systems. In effect, this allows the
+deployment of centrally managed and maintained distributed authentication from a
+single-user account database.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Technical Discussion</title>
+
+<para>
+<indexterm><primary>PAM</primary></indexterm>
+<indexterm><primary>privilege-granting applications</primary></indexterm>
+<indexterm><primary>/etc/pam.conf</primary></indexterm>
+<indexterm><primary>/etc/pam.d/</primary></indexterm>
+PAM is designed to provide system administrators with a great deal of flexibility in
+configuration of the privilege-granting applications of their system. The local
+configuration of system security controlled by PAM is contained in one of two places:
+either the single system file <filename>/etc/pam.conf</filename> or the
+<filename>/etc/pam.d/</filename> directory.
+</para>
+
+<sect2>
+<title>PAM Configuration Syntax</title>
+
+<para>
+<indexterm><primary>PAM-specific tokens</primary></indexterm>
+<indexterm><primary>case sensitivity</primary></indexterm>
+In this section we discuss the correct syntax of and generic options respected by entries to these files.
+PAM-specific tokens in the configuration file are case insensitive. The module paths, however, are case
+sensitive, since they indicate a file's name and reflect the case dependence of typical file systems.  The
+case sensitivity of the arguments to any given module is defined for each module in turn.
+</para>
+
+<para>
+In addition to the lines described below, there are two special characters provided for the convenience
+of the system administrator: comments are preceded by a <quote>#</quote> and extend to the next end-of-line; also,
+module specification lines may be extended with a <quote>\</quote>-escaped newline. 
+</para>
+
+<para>
+<indexterm><primary>PAM authentication module</primary></indexterm>
+<indexterm><primary>/lib/security</primary></indexterm>
+If the PAM authentication module (loadable link library file) is located in the
+default location, then it is not necessary to specify the path. In the case of
+Linux, the default location is <filename>/lib/security</filename>. If the module
+is located outside the default, then the path must be specified as:
+<programlisting>
+auth  required  /other_path/pam_strange_module.so
+</programlisting>
+</para>
+
+<sect3>
+<title>Anatomy of <filename>/etc/pam.d</filename> Entries</title>
+
+<para>
+The remaining information in this subsection was taken from the documentation of the Linux-PAM
+project. For more information on PAM, see 
+<ulink url="http://ftp.kernel.org/pub/linux/libs/pam/">the Official Linux-PAM home page</ulink>.
+</para>
+
+<para>
+<indexterm><primary>/etc/pam.conf</primary></indexterm>
+A general configuration line of the <filename>/etc/pam.conf</filename> file has the following form:
+<programlisting>
+service-name   module-type   control-flag   module-path   args
+</programlisting>
+</para>
+
+<para>
+We explain the meaning of each of these tokens. The second (and more recently adopted)
+way of configuring Linux-PAM is via the contents of the <filename>/etc/pam.d/</filename> directory.
+Once we have explained the meaning of the tokens, we describe this method.
+</para>
+
+<variablelist>
+	<varlistentry><term>service-name</term><listitem>
+		<para>
+<indexterm><primary>ftpd</primary></indexterm>
+<indexterm><primary>rlogind</primary></indexterm>
+<indexterm><primary>su</primary></indexterm>
+		The name of the service associated with this entry. Frequently, the service-name is the conventional
+		name of the given application &smbmdash; for example, <command>ftpd</command>, <command>rlogind</command> and
+		<command>su</command>, and so on.
+		</para>
+
+		<para>
+		There is a special service-name reserved for defining a default authentication mechanism. It has
+		the name <parameter>OTHER</parameter> and may be specified in either lower- or uppercase characters.
+		Note, when there is a module specified for a named service, the <parameter>OTHER</parameter>
+		entries are ignored.
+		</para>
+		</listitem>
+	</varlistentry>
+
+	<varlistentry><term>module-type</term><listitem>
+                <para>
+		One of (currently) four types of module. The four types are as follows:
+		</para>
+
+		<itemizedlist>
+			<listitem><para>
+<indexterm><primary>auth</primary></indexterm>
+<indexterm><primary>/etc/groups</primary></indexterm>
+			<parameter>auth:</parameter> This module type provides two aspects of authenticating the user.
+			It establishes that the user is who he or she claims to be by instructing the application
+			to prompt the user for a password or other means of identification. Second, the module can
+			grant group membership (independently of the <filename>/etc/groups</filename> file)
+			or other privileges through its credential-granting properties.
+			</para></listitem>
+
+			<listitem><para>
+<indexterm><primary>account</primary></indexterm>
+<indexterm><primary>non-authentication-based account management</primary></indexterm>
+			<parameter>account:</parameter> This module performs non-authentication-based account management.
+			It is typically used to restrict/permit access to a service based on the time of day, currently
+		 	available system resources (maximum number of users), or perhaps the location of the user 
+			login. For example, the <quote>root</quote> login may be permitted only on the console.
+			</para></listitem>
+
+			<listitem><para>
+<indexterm><primary>session</primary></indexterm>
+			<parameter>session:</parameter> Primarily, this module is associated with doing things that need
+			to be done for the user before and after he or she can be given service. Such things include logging
+			information concerning the opening and closing of some data exchange with a user, mounting
+			directories, and so on.
+			</para></listitem>
+
+			<listitem><para>
+<indexterm><primary>password</primary></indexterm>
+			<parameter>password:</parameter> This last module type is required for updating the authentication
+			token associated with the user. Typically, there is one module for each
+			<quote>challenge/response</quote> authentication <parameter>(auth)</parameter> module type.
+			</para></listitem>
+		</itemizedlist>
+		</listitem>
+	</varlistentry>
+
+	<varlistentry><term>control-flag</term><listitem>
+		<para>
+		The control-flag is used to indicate how the PAM library will react to the success or failure of the
+		module it is associated with. Since modules can be stacked (modules of the same type execute in series,
+		one after another), the control-flags determine the relative importance of each module. The application
+		is not made aware of the individual success or failure of modules listed in the
+		<filename>/etc/pam.conf</filename> file. Instead, it receives a summary success or fail response from
+		the Linux-PAM library. The order of execution of these modules is that of the entries in the
+		<filename>/etc/pam.conf</filename> file; earlier entries are executed before later ones.
+		As of Linux-PAM v0.60, this control-flag can be defined with one of two syntaxes.
+		</para>
+
+		<para>
+<indexterm><primary>required</primary></indexterm>
+<indexterm><primary>requisite</primary></indexterm>
+<indexterm><primary>sufficient</primary></indexterm>
+<indexterm><primary>optional</primary></indexterm>
+		The simpler (and historical) syntax for the control-flag is a single keyword defined to indicate the
+		severity of concern associated with the success or failure of a specific module. There are four such
+		keywords: <parameter>required</parameter>, <parameter>requisite</parameter>,
+		<parameter>sufficient</parameter>, and <parameter>optional</parameter>.
+		</para>
+
+		<para>
+		The Linux-PAM library interprets these keywords in the following manner:
+		</para>
+
+		<itemizedlist>
+			<listitem><para>
+			<parameter>required:</parameter> This indicates that the success of the module is required for the
+			module-type facility to succeed. Failure of this module will not be apparent to the user until all
+			of the remaining modules (of the same module-type) have been executed.
+			</para></listitem>
+
+			<listitem><para>
+			<parameter>requisite:</parameter> Like required, except that if such a module returns a
+			failure, control is directly returned to the application. The return value is that associated with
+			the first required or requisite module to fail. This flag can be used to protect against the
+			possibility of a user getting the opportunity to enter a password over an unsafe medium. It is
+			conceivable that such behavior might inform an attacker of valid accounts on a system. This
+			possibility should be weighed against the not insignificant concerns of exposing a sensitive
+			password in a hostile environment.
+			</para></listitem>
+
+			<listitem><para>
+			<parameter>sufficient:</parameter> The success of this module is deemed <parameter>sufficient</parameter> to satisfy
+			the Linux-PAM library that this module-type has succeeded in its purpose. In the event that no
+			previous required module has failed, no more <quote>stacked</quote> modules of this type are invoked.
+			(In this case, subsequent required modules are not invoked). A failure of this module is not deemed
+			as fatal to satisfying the application that this module-type has succeeded.
+			</para></listitem>
+
+            <listitem><para>
+            <parameter>optional:</parameter> As its name suggests, this control-flag marks the module as not
+			being critical to the success or failure of the user's application for service. In general,
+			Linux-PAM ignores such a module when determining if the module stack will succeed or fail.
+			However, in the absence of any definite successes or failures of previous or subsequent stacked
+			modules, this module will determine the nature of the response to the application. One example of
+			this latter case is when the other modules return something like PAM_IGNORE.
+			</para></listitem>
+		</itemizedlist>
+
+		<para>
+		The more elaborate (newer) syntax is much more specific and gives the administrator a great deal of control
+		over how the user is authenticated. This form of the control-flag is delimited with square brackets and
+		consists of a series of <parameter>value=action</parameter> tokens:
+		</para>
+
+<para><programlisting>
+[value1=action1 value2=action2 ...]
+</programlisting></para>
+
+		<para>
+		Here, <parameter>value1</parameter> is one of the following return values:
+<screen>
+<parameter>success; open_err; symbol_err; service_err; system_err; buf_err;</parameter>
+<parameter>perm_denied; auth_err; cred_insufficient; authinfo_unavail;</parameter>
+<parameter>user_unknown; maxtries; new_authtok_reqd; acct_expired; session_err;</parameter>
+<parameter>cred_unavail; cred_expired; cred_err; no_module_data; conv_err;</parameter>
+<parameter>authtok_err; authtok_recover_err; authtok_lock_busy;</parameter>
+<parameter>authtok_disable_aging; try_again; ignore; abort; authtok_expired;</parameter>
+<parameter>module_unknown; bad_item;</parameter> and <parameter>default</parameter>.
+</screen>
+</para>
+
+		<para>
+		The last of these (<parameter>default</parameter>) can be used to set the action for those return values that are not explicitly defined.
+		</para>
+
+		<para>
+		The <parameter>action1</parameter> can be a positive integer or one of the following tokens: 
+		<parameter>ignore</parameter>; <parameter>ok</parameter>; <parameter>done</parameter>;
+		<parameter>bad</parameter>; <parameter>die</parameter>; and <parameter>reset</parameter>.
+		A positive integer, J, when specified as the action, can be used to indicate that the next J modules of the
+		current module-type will be skipped. In this way, the administrator can develop a moderately sophisticated
+		stack of modules with a number of different paths of execution. Which path is taken can be determined by the
+		reactions of individual modules.
+		</para>
+
+		<itemizedlist>
+			<listitem><para>
+			<parameter>ignore:</parameter> When used with a stack of modules, the module's return status will not
+			contribute to the return code the application obtains.
+			</para></listitem>
+
+			<listitem><para>
+            <parameter>bad:</parameter> This action indicates that the return code should be thought of as indicative
+			of the module failing. If this module is the first in the stack to fail, its status value will be used
+			for that of the whole stack.
+			</para></listitem>
+
+            <listitem><para>
+            <parameter>die:</parameter> Equivalent to bad with the side effect of terminating the module stack and
+			PAM immediately returning to the application.
+			</para></listitem>
+
+           <listitem><para>
+           <parameter>ok:</parameter> This tells PAM that the administrator thinks this return code should
+			contribute directly to the return code of the full stack of modules. In other words, if the former
+			state of the stack would lead to a return of PAM_SUCCESS, the module's return code will override
+			this value. Note, if the former state of the stack holds some value that is indicative of a module's
+			failure, this <parameter>ok</parameter> value will not be used to override that value.
+			</para></listitem>
+
+            <listitem><para>
+            <parameter>done:</parameter> Equivalent to <parameter>ok</parameter> with the side effect of terminating the module stack and
+			PAM immediately returning to the application.
+                        </para></listitem>
+
+           <listitem><para>
+           <parameter>reset:</parameter> Clears all memory of the state of the module stack and starts again with
+			the next stacked module.
+			</para></listitem>
+		</itemizedlist>
+
+		<para>
+		Each of the four keywords, <parameter>required</parameter>; <parameter>requisite</parameter>;
+		<parameter>sufficient</parameter>; and <parameter>optional</parameter>, have an equivalent expression in terms
+		of the [...] syntax. They are as follows:
+		</para>
+
+		<para>
+		<itemizedlist>
+			<listitem><para>
+			<parameter>required</parameter> is equivalent to <parameter>[success=ok new_authtok_reqd=ok ignore=ignore default=bad]</parameter>.
+			</para></listitem>
+
+			<listitem><para>
+			<parameter>requisite</parameter> is equivalent to <parameter>[success=ok new_authtok_reqd=ok ignore=ignore default=die]</parameter>.
+			</para></listitem>
+
+			<listitem><para>
+			<parameter>sufficient</parameter> is equivalent to <parameter>[success=done  new_authtok_reqd=done  default=ignore]</parameter>.
+			</para></listitem>
+
+			<listitem><para>
+			<parameter>optional</parameter> is equivalent to <parameter>[success=ok new_authtok_reqd=ok default=ignore]</parameter>.
+			</para></listitem>
+		</itemizedlist>
+		</para>
+
+		<para>
+		Just to get a feel for the power of this new syntax, here is a taste of what you can do with it. With Linux-PAM-0.63,
+		the notion of client plug-in agents was introduced. This makes it possible for PAM to support
+		machine-machine authentication using the transport protocol inherent to the client/server application. With the
+		<parameter>[ ... value=action ... ]</parameter> control syntax, it is possible for an application to be configured
+		to support binary prompts with compliant clients, but to gracefully fail over into an alternative authentication
+		mode for legacy applications.
+		</para>
+		</listitem>
+	</varlistentry>
+
+	<varlistentry><term>module-path</term><listitem>
+		<para>
+		The pathname of the dynamically loadable object file; the pluggable module itself. If the first character of the
+		module path is <quote>/</quote>, it is assumed to be a complete path. If this is not the case, the given module path is appended
+		to the default module path: <filename>/lib/security</filename> (but see the previous notes).
+		</para>
+
+		<para>
+		The arguments are a list of tokens that are passed to the module when it is invoked, much like arguments to a typical
+		Linux shell command. Generally, valid arguments are optional and are specific to any given module. Invalid arguments
+		are ignored by a module; however, when encountering an invalid argument, the module is required to write an error
+		to syslog(3). For a list of generic options, see the next section.
+		</para>
+
+		<para>
+		If you wish to include spaces in an argument, you should surround that argument with square brackets. For example:
+		</para>
+
+<para><programlisting>
+squid auth required pam_mysql.so user=passwd_query passwd=mada \
+db=eminence [query=select user_name from internet_service where \
+user_name=<quote>%u</quote> and password=PASSWORD(<quote>%p</quote>) and service=<quote>web_proxy</quote>]
+</programlisting></para>
+
+		<para>
+		When using this convention, you can include <quote>[</quote> characters inside the string, and if you wish to have a <quote>]</quote>
+		character inside the string that will survive the argument parsing, you should use <quote>\[</quote>. In other words,
+		</para>
+
+<para><programlisting>
+[..[..\]..]    -->   ..[..]..
+</programlisting></para>
+
+		<para>
+		Any line in one of the configuration files that is not formatted correctly will generally tend (erring on the
+		side of caution) to make the authentication process fail. A corresponding error is written to the system log files
+		with a call to syslog(3). 
+		</para>
+		</listitem>
+	</varlistentry>
+</variablelist>
+
+</sect3>
+
+</sect2>
+
+<sect2>
+<title>Example System Configurations</title>
+
+<para>
+The following is an example <filename>/etc/pam.d/login</filename> configuration file. 
+This example had all options uncommented and is probably not usable 
+because it stacks many conditions before allowing successful completion 
+of the login process. Essentially, all conditions can be disabled 
+by commenting them out, except the calls to <filename>pam_pwdb.so</filename>.
+</para>
+
+<sect3>
+<title>PAM: Original Login Config</title>
+
+<para>
+	<programlisting>
+#%PAM-1.0
+# The PAM configuration file for the <quote>login</quote> service
+#
+auth         required    pam_securetty.so
+auth         required    pam_nologin.so
+# auth       required    pam_dialup.so
+# auth       optional    pam_mail.so
+auth         required    pam_pwdb.so shadow md5
+# account    requisite   pam_time.so
+account      required    pam_pwdb.so
+session      required    pam_pwdb.so
+# session    optional    pam_lastlog.so
+# password   required    pam_cracklib.so retry=3
+password     required    pam_pwdb.so shadow md5
+</programlisting>
+</para>
+
+</sect3>
+
+<sect3>
+<title>PAM: Login Using <filename>pam_smbpass</filename></title>
+
+<para>
+PAM allows use of replaceable modules. Those available on a sample system include:
+</para>
+
+<para><prompt>$</prompt><userinput>/bin/ls /lib/security</userinput>
+<programlisting>
+pam_access.so    pam_ftp.so          pam_limits.so     
+pam_ncp_auth.so  pam_rhosts_auth.so  pam_stress.so     
+pam_cracklib.so  pam_group.so        pam_listfile.so   
+pam_nologin.so   pam_rootok.so       pam_tally.so      
+pam_deny.so      pam_issue.so        pam_mail.so       
+pam_permit.so    pam_securetty.so    pam_time.so       
+pam_dialup.so    pam_lastlog.so      pam_mkhomedir.so  
+pam_pwdb.so      pam_shells.so       pam_unix.so       
+pam_env.so       pam_ldap.so         pam_motd.so       
+pam_radius.so    pam_smbpass.so      pam_unix_acct.so  
+pam_wheel.so     pam_unix_auth.so    pam_unix_passwd.so
+pam_userdb.so    pam_warn.so         pam_unix_session.so
+</programlisting></para>
+
+<para>
+The following example for the login program replaces the use of 
+the <filename>pam_pwdb.so</filename> module that uses the system 
+password database (<filename>/etc/passwd</filename>,
+<filename>/etc/shadow</filename>, <filename>/etc/group</filename>) with 
+the module <filename>pam_smbpass.so</filename>, which uses the Samba 
+database containing the Microsoft MD4 encrypted password 
+hashes. This database is stored either in 
+<filename>/usr/local/samba/private/smbpasswd</filename>, 
+<filename>/etc/samba/smbpasswd</filename> or in 
+<filename>/etc/samba.d/smbpasswd</filename>, depending on the 
+Samba implementation for your UNIX/Linux system. The 
+<filename>pam_smbpass.so</filename> module is provided by 
+Samba version 2.2.1 or later. It can be compiled by specifying the 
+<option>--with-pam_smbpass</option> options when running Samba's
+<command>configure</command> script. For more information
+on the <filename>pam_smbpass</filename> module, see the documentation
+in the <filename>source/pam_smbpass</filename> directory of the Samba 
+source distribution.
+</para>
+
+<para>
+	<programlisting>
+#%PAM-1.0
+# The PAM configuration file for the <quote>login</quote> service
+#
+auth        required    pam_smbpass.so nodelay
+account     required    pam_smbpass.so nodelay
+session     required    pam_smbpass.so nodelay
+password    required    pam_smbpass.so nodelay
+</programlisting></para>
+
+<para>
+The following is the PAM configuration file for a particular 
+Linux system. The default condition uses <filename>pam_pwdb.so</filename>.
+</para>
+
+<para>
+	<programlisting>
+#%PAM-1.0
+# The PAM configuration file for the <quote>samba</quote> service
+#
+auth       required     pam_pwdb.so nullok nodelay shadow audit
+account    required     pam_pwdb.so audit nodelay
+session    required     pam_pwdb.so nodelay
+password   required     pam_pwdb.so shadow md5
+</programlisting></para>
+
+<para>
+In the following example, the decision has been made to use the 
+<command>smbpasswd</command> database even for basic Samba authentication. Such a 
+decision could also be made for the <command>passwd</command> program and would 
+thus allow the <command>smbpasswd</command> passwords to be changed using the
+<command>passwd</command> program:
+</para>
+
+<para>
+		<programlisting>
+#%PAM-1.0
+# The PAM configuration file for the <quote>samba</quote> service
+#
+auth       required     pam_smbpass.so nodelay
+account    required     pam_pwdb.so audit nodelay
+session    required     pam_pwdb.so nodelay
+password   required     pam_smbpass.so nodelay smbconf=/etc/samba.d/smb.conf
+</programlisting>
+</para>
+
+<note><para>PAM allows stacking of authentication mechanisms. It is 
+also possible to pass information obtained within one PAM module through 
+to the next module in the PAM stack. Please refer to the documentation for 
+your particular system implementation for details regarding the specific 
+capabilities of PAM in this environment. Some Linux implementations also 
+provide the <filename>pam_stack.so</filename> module that allows all 
+authentication to be configured in a single central file. The 
+<filename>pam_stack.so</filename> method has some devoted followers 
+on the basis that it allows for easier administration. As with all issues in 
+life, though, every decision has trade-offs, so you may want to examine the 
+PAM documentation for further helpful information.
+</para></note>
+
+</sect3>
+
+</sect2>
+
+<sect2>
+<title>&smb.conf; PAM Configuration</title>
+
+<para>
+There is an option in &smb.conf; called <smbconfoption name="obey pam restrictions"/>.
+The following is from the online help for this option in SWAT:
+</para>
+
+<blockquote>
+<para>
+When Samba is configured to enable PAM support (i.e., <option>--with-pam</option>), this parameter will 
+control whether or not Samba should obey PAM's account and session management directives. The default behavior 
+is to use PAM for clear-text authentication only and to ignore any account or session management. Samba always 
+ignores PAM for authentication in the case of <smbconfoption name="encrypt passwords">yes</smbconfoption>. 
+The reason is that PAM modules cannot support the challenge/response authentication mechanism needed in the presence of SMB 
+password encryption. 
+</para>
+
+<para>Default: <smbconfoption name="obey pam restrictions">no</smbconfoption></para>
+</blockquote>
+
+</sect2>
+
+<sect2>
+<title>Remote CIFS Authentication Using <filename>winbindd.so</filename></title>
+
+<para>
+All operating systems depend on the provision of user credentials acceptable to the platform.
+UNIX requires the provision of a user identifier (UID) as well as a group identifier (GID).
+These are both simple integer numbers that are obtained from a password backend such
+as <filename>/etc/passwd</filename>.
+</para>
+
+<para>
+Users and groups on a Windows NT server are assigned a relative ID (RID) which is unique for
+the domain when the user or group is created. To convert the Windows NT user or group into
+a  UNIX user or group, a mapping between RIDs and UNIX user and group IDs is required. This
+is one of the jobs that winbind performs.
+</para>
+
+<para>
+As winbind users and groups are resolved from a server, user and group IDs are allocated
+from a specified range. This is done on a first come, first served basis, although all
+existing users and groups will be mapped as soon as a client performs a user or  group 
+enumeration command. The allocated UNIX IDs are stored in a database file under the Samba
+lock directory and will be remembered.
+</para>
+
+<para>
+The astute administrator will realize from this that the combination of <filename>pam_smbpass.so</filename>, 
+<command>winbindd</command>, and a distributed <smbconfoption name="passdb backend"></smbconfoption>
+such as <parameter>ldap</parameter> will allow the establishment of a centrally managed, distributed user/password
+database that can also be used by all PAM-aware (e.g., Linux) programs and applications. This arrangement can have
+particularly potent advantages compared with the use of Microsoft Active Directory Service (ADS) insofar as
+the reduction of wide-area network authentication traffic.
+</para>
+
+<warning><para>
+The RID to UNIX ID database is the only location where the user and group  mappings are 
+stored by <command>winbindd</command>. If this file is deleted or corrupted, there is no way for <command>winbindd</command>
+to determine which user and group IDs correspond to Windows NT user and group RIDs.
+</para></warning>
+
+</sect2>
+
+<sect2>
+<title>Password Synchronization Using <filename>pam_smbpass.so</filename></title>
+
+<para>
+<filename>pam_smbpass</filename> is a PAM module that can be used on conforming systems to
+keep the <filename>smbpasswd</filename> (Samba password) database in sync with the UNIX
+password file. PAM is an API supported
+under some UNIX operating systems, such as Solaris, HPUX, and Linux, that provides a
+generic interface to authentication mechanisms.
+</para>
+
+<para>
+This module authenticates a local <filename>smbpasswd</filename> user database. If you require
+support for authenticating against a remote SMB server, or if you are
+concerned about the presence of SUID root binaries on your system, it is
+recommended that you use <filename>pam_winbind</filename> instead.
+</para>
+
+<para>
+Options recognized by this module are shown in <link linkend="smbpassoptions">next table</link>.
+<table frame="all" id="smbpassoptions">
+	<title>Options recognized by <parameter>pam_smbpass</parameter></title>
+	<tgroup cols="2" align="left">
+		<colspec align="left"/>
+		<colspec align="justify" colwidth="1*"/>
+	<tbody>
+		<row><entry>debug</entry><entry>Log more debugging info.</entry></row>
+		<row><entry>audit</entry><entry>Like debug, but also logs unknown usernames.</entry></row>
+		<row><entry>use_first_pass</entry><entry>Do not prompt the user for passwords; take them from PAM_ items instead.</entry></row>
+		<row><entry>try_first_pass</entry><entry>Try to get the password from a previous PAM module; fall back to prompting the user.</entry></row>
+		<row><entry>use_authtok</entry>
+			<entry>Like try_first_pass, but *fail* if the new PAM_AUTHTOK has not been previously set (intended for stacking password modules only).</entry></row>
+		<row><entry>not_set_pass</entry><entry>Do not make passwords used by this module available to other modules.</entry></row>
+		<row><entry>nodelay</entry><entry>dDo not insert ~1-second delays on authentication failure.</entry></row>
+		<row><entry>nullok</entry><entry>Null passwords are allowed.</entry></row>
+		<row><entry>nonull</entry><entry>Null passwords are not allowed. Used to override the Samba configuration.</entry></row>
+		<row><entry>migrate</entry><entry>Only meaningful in an <quote>auth</quote> context; used to update smbpasswd file with a password used for successful authentication.</entry></row>
+		<row><entry>smbconf=<replaceable>file</replaceable></entry><entry>Specify an alternate path to the &smb.conf; file.</entry></row>
+	</tbody>
+</tgroup>
+</table>
+</para>
+
+<para>
+The following are examples of the use of <filename>pam_smbpass.so</filename> in the format of the Linux
+<filename>/etc/pam.d/</filename> files structure. Those wishing to implement this
+tool on other platforms will need to adapt this appropriately.
+</para>
+
+<sect3>
+<title>Password Synchronization Configuration</title>
+
+<para>
+The following is a sample PAM configuration that shows the use of pam_smbpass to make
+sure <filename>private/smbpasswd</filename> is kept in sync when <filename>/etc/passwd (/etc/shadow)</filename>
+is changed. It is useful when an expired password might be changed by an
+application (such as <command>ssh</command>).
+</para>
+
+<para>
+	<programlisting>
+#%PAM-1.0
+# password-sync
+#
+auth       requisite    pam_nologin.so
+auth       required     pam_unix.so
+account    required     pam_unix.so
+password   requisite    pam_cracklib.so retry=3
+password   requisite    pam_unix.so shadow md5 use_authtok try_first_pass
+password   required     pam_smbpass.so nullok use_authtok try_first_pass
+session    required     pam_unix.so
+</programlisting></para>
+</sect3>
+
+<sect3>
+<title>Password Migration Configuration</title>
+
+<para>
+The following PAM configuration shows the use of <filename>pam_smbpass</filename> to migrate
+from plaintext to encrypted passwords for Samba. Unlike other methods,
+this can be used for users who have never connected to Samba shares:
+password migration takes place when users <command>ftp</command> in, login using <command>ssh</command>, pop
+their mail, and so on.
+</para>
+
+<para>
+	<programlisting>
+#%PAM-1.0
+# password-migration
+#
+auth       requisite   pam_nologin.so
+# pam_smbpass is called IF pam_unix succeeds.
+auth       requisite   pam_unix.so
+auth       optional    pam_smbpass.so migrate
+account    required    pam_unix.so
+password   requisite   pam_cracklib.so retry=3
+password   requisite   pam_unix.so shadow md5 use_authtok try_first_pass
+password   optional    pam_smbpass.so nullok use_authtok try_first_pass
+session    required    pam_unix.so
+</programlisting></para>
+</sect3>
+
+<sect3>
+<title>Mature Password Configuration</title>
+
+<para>
+The following is a sample PAM configuration for a mature <filename>smbpasswd</filename> installation.
+<filename>private/smbpasswd</filename> is fully populated, and we consider it an error if
+the SMB password does not exist or does not match the UNIX password.
+</para>
+
+<para>
+<programlisting>
+#%PAM-1.0
+# password-mature
+#
+auth       requisite    pam_nologin.so
+auth       required     pam_unix.so
+account    required     pam_unix.so
+password   requisite    pam_cracklib.so retry=3
+password   requisite    pam_unix.so shadow md5 use_authtok try_first_pass
+password   required     pam_smbpass.so use_authtok use_first_pass
+session    required     pam_unix.so
+</programlisting></para>
+</sect3>
+
+<sect3>
+<title>Kerberos Password Integration Configuration</title>
+
+<para>
+The following is a sample PAM configuration that shows <parameter>pam_smbpass</parameter> used together with
+<parameter>pam_krb5</parameter>. This could be useful on a Samba PDC that is also a member of
+a Kerberos realm.
+</para>
+
+<para>
+		<programlisting>
+#%PAM-1.0
+# kdc-pdc
+#
+auth       requisite   pam_nologin.so
+auth       requisite   pam_krb5.so
+auth       optional    pam_smbpass.so migrate
+account    required    pam_krb5.so
+password   requisite   pam_cracklib.so retry=3
+password   optional    pam_smbpass.so nullok use_authtok try_first_pass
+password   required    pam_krb5.so use_authtok try_first_pass
+session    required    pam_krb5.so
+</programlisting></para>
+
+</sect3>
+
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>Common Errors</title>
+
+<para>
+PAM can be fickle and sensitive to configuration glitches. Here we look at a few cases from
+the Samba mailing list.
+</para>
+
+	<sect2>
+	<title>pam_winbind Problem</title>
+
+	<para>
+	A user reported, <emphasis>I have the following PAM configuration</emphasis>:
+	</para>
+
+<para>
+<programlisting>
+auth required /lib/security/pam_securetty.so
+auth sufficient /lib/security/pam_winbind.so
+auth sufficient /lib/security/pam_unix.so use_first_pass nullok
+auth required /lib/security/pam_stack.so service=system-auth
+auth required /lib/security/pam_nologin.so
+account required /lib/security/pam_stack.so service=system-auth
+account required /lib/security/pam_winbind.so
+password required /lib/security/pam_stack.so service=system-auth
+</programlisting>
+</para>
+
+	<para>
+	<emphasis>When I open a new console with [ctrl][alt][F1], I can't log in with my user <quote>pitie.</quote>
+	I have tried with user <quote>scienceu\pitie</quote> also.</emphasis>
+	</para>
+
+	<para>
+	The problem may lie with the inclusion of <parameter>pam_stack.so
+	service=system-auth</parameter>. That file often contains a lot of stuff that may
+	duplicate what you are already doing. Try commenting out the <parameter>pam_stack</parameter> lines
+	for <parameter>auth</parameter> and <parameter>account</parameter> and see if things work. If they do, look at
+	<filename>/etc/pam.d/system-auth</filename> and copy only what you need from it into your
+	<filename>/etc/pam.d/login</filename> file. Alternatively, if you want all services to use
+	Winbind, you can put the Winbind-specific stuff in <filename>/etc/pam.d/system-auth</filename>.
+	</para>
+
+	</sect2>
+
+	<sect2>
+	<title>Winbind Is Not Resolving Users and Groups</title>
+
+	<para>
+	<quote>
+	My &smb.conf; file is correctly configured. I have specified 
+	<smbconfoption name="idmap uid">12000</smbconfoption> 
+	and <smbconfoption name="idmap gid">3000-3500,</smbconfoption>
+	and <command>winbind</command> is running. When I do the following it all works fine.
+	</quote>
+	</para>
+
+<para><screen>
+&rootprompt;<userinput>wbinfo -u</userinput>
+MIDEARTH\maryo
+MIDEARTH\jackb
+MIDEARTH\ameds
+...
+MIDEARTH\root
+
+&rootprompt;<userinput>wbinfo -g</userinput>
+MIDEARTH\Domain Users
+MIDEARTH\Domain Admins
+MIDEARTH\Domain Guests
+...
+MIDEARTH\Accounts
+
+&rootprompt;<userinput>getent passwd</userinput>
+root:x:0:0:root:/root:/bin/bash
+bin:x:1:1:bin:/bin:/bin/bash
+...
+maryo:x:15000:15003:Mary Orville:/home/MIDEARTH/maryo:/bin/false
+</screen></para>
+
+	<para>
+	<quote>
+	But this command fails:
+	</quote>
+<screen>
+&rootprompt;<userinput>chown maryo a_file</userinput>
+chown: 'maryo': invalid user
+</screen>
+	<quote>This is driving me nuts! What can be wrong?</quote>
+	</para>
+
+	<para>
+	Your system is likely running <command>nscd</command>, the name service
+	caching daemon. Shut it down, do not restart it! You will find your problem resolved.
+	</para>
+
+	</sect2>
+</sect1>
+
+</chapter>