Docbook XML conversion: projdoc

(This used to be commit f7c9df751459da2d4a996d5f0135334fb3f87f69)

1 files changed, 389 insertions, 0 deletions

diff --git a/docs/docbook/projdoc/PAM-Authentication-And-Samba.xml b/docs/docbook/projdoc/PAM-Authentication-And-Samba.xml
new file mode 100644
index 0000000000..4b5179acc7
--- /dev/null
+++ b/docs/docbook/projdoc/PAM-Authentication-And-Samba.xml
@@ -0,0 +1,389 @@
+<chapter id="pam">
+<chapterinfo>
+	&author.jht;
+    <pubdate> (Jun 21 2001) </pubdate>
+</chapterinfo>
+ 
+<title>PAM Configuration for Centrally Managed Authentication</title>
+
+<sect1>
+<title>Samba and PAM</title>
+
+<para>
+A number of Unix systems (eg: 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 such programs as: <command>login</command>, 
+<command>passwd</command>, <command>chown</command>, etc.
+</para>
+
+<para>
+PAM provides a mechanism that disconnects these security programs 
+from the underlying authentication/authorization infrastructure.
+PAM is configured either through one file <filename>/etc/pam.conf</filename> (Solaris), 
+or by editing individual files that are located in <filename>/etc/pam.d</filename>.
+</para>
+
+<note>
+	<para>
+	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>
+</note>
+
+<para>
+The following is an example <filename>/etc/pam.d/login</filename> configuration file. 
+This example had all options been uncommented is probably not usable 
+as 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>
+
+<para><programlisting>
+	#%PAM-1.0
+	# The PAM configuration file for the `login' 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>
+
+<para>
+PAM allows use of replacable 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 which 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 which contains the Microsoft MD4 encrypted password 
+hashes. This database is stored in either 
+<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 
+<command>--with-pam_smbpass</command> options when running Samba's
+<filename>configure</filename> 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 `login' 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 `samba' 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 
+smbpasswd database even for basic samba authentication. Such a 
+decision could also be made for the passwd program and would 
+thus allow the smbpasswd passwords to be changed using the passwd 
+program.
+</para>
+
+<para><programlisting>
+	#%PAM-1.0
+	# The PAM configuration file for the `samba' 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 implmentations 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 very devoted followers 
+on the basis that it allows for easier administration. As with all issues in 
+life though, every decision makes trade-offs, so you may want examine the 
+PAM documentation for further helpful information.
+</para></note>
+
+<sect2>
+<title>PAM Configuration in smb.conf</title>
+
+<para>
+There is an option in smb.conf called <ulink 
+url="smb.conf.5.html#OBEYPAMRESTRICTIONS">obey pam restrictions</ulink>. 
+The following is from the on-line help for this option in SWAT;
+</para>
+
+<para>
+When Samba is configured to enable PAM support (i.e. 
+<constant>--with-pam</constant>), 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. Note that Samba always 
+ignores PAM for authentication in the case of 
+<ulink url="smb.conf.5.html#ENCRYPTPASSWORDS">encrypt passwords = yes</ulink>. 
+The reason is that PAM modules cannot support the challenge/response 
+authentication mechanism needed in the presence of SMB 
+password encryption. 
+</para>
+
+<para>Default: <command>obey pam restrictions = no</command></para>
+
+</sect2>
+
+<sect2>
+<title>Password Synchronisation using pam_smbpass.so</title>
+
+<para>
+pam_smbpass is a PAM module which can be used on conforming systems to
+keep the smbpasswd (Samba password) database in sync with the unix
+password file. PAM (Pluggable Authentication Modules) is an API supported
+under some Unices, such as Solaris, HPUX and Linux, that provides a
+generic interface to authentication mechanisms.
+</para>
+
+<para>
+For more information on PAM, see http://ftp.kernel.org/pub/linux/libs/pam/
+</para>
+
+<para>
+This module authenticates a local smbpasswd user database.  If you require
+support for authenticating against a remote SMB server, or if you're
+concerned about the presence of suid root binaries on your system, it is
+recommended that you use pam_winbind instead.
+</para>
+
+<para><programlisting>
+Options recognized by this module are as follows:
+
+        debug           -       log more debugging info
+        audit           -       like debug, but also logs unknown usernames
+        use_first_pass  -       don't prompt the user for passwords;
+                                take them from PAM_ items instead
+        try_first_pass  -       try to get the password from a previous
+                                PAM module, fall back to prompting the user
+        use_authtok     -       like try_first_pass, but *fail* if the new
+                                PAM_AUTHTOK has not been previously set.
+                                (intended for stacking password modules only)
+        not_set_pass    -       don't make passwords used by this module
+                                available to other modules.
+        nodelay         -       don't insert ~1 second delays on authentication
+                                failure.
+        nullok          -       null passwords are allowed.
+        nonull          -       null passwords are not allowed. Used to
+                                override the Samba configuration.
+        migrate         -       only meaningful in an "auth" context;
+                                used to update smbpasswd file with a
+                                password used for successful authentication.
+        smbconf=&lt; file &gt;  -     specify an alternate path to the smb.conf
+                                file.
+</programlisting></para>
+
+<para><programlisting>
+Thanks go to the following people:
+
+	* Andrew Morgan &lt; morgan@transmeta.com &gt;, for providing the Linux-PAM
+	framework, without which none of this would have happened
+
+	* Christian Gafton &lt; gafton@redhat.com &gt; and Andrew Morgan again, for the
+	pam_pwdb module upon which pam_smbpass was originally based
+
+	* Luke Leighton &lt; lkcl@switchboard.net &gt; for being receptive to the idea,
+	and for the occasional good-natured complaint about the project's status
+	that keep me working on it :)
+
+	* and of course, all the other members of the Samba team
+	&lt;http://www.samba.org/samba/team.html&gt;, for creating a great product
+	and for giving this project a purpose
+
+	---------------------
+	Stephen Langasek &lt; vorlon@netexpress.net &gt;
+</programlisting></para>
+
+<para>
+The following are examples of the use of pam_smbpass.so in the format of 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 Synchonisation Configuration</title>
+
+<para>
+A sample PAM configuration that shows the use of pam_smbpass to make
+sure private/smbpasswd is kept in sync when /etc/passwd (/etc/shadow)
+is changed.  Useful when an expired password might be changed by an
+application (such as ssh).
+</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>
+A sample PAM configuration that shows the use of pam_smbpass 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 ftp in, login using ssh, pop
+their mail, etc.
+</para>
+
+<para><programlisting>
+	#%PAM-1.0
+	# password-migration
+	#
+	auth       requisite        pam_nologin.so
+	# pam_smbpass is called IFF 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>
+A sample PAM configuration for a 'mature' smbpasswd installation.
+private/smbpasswd is fully populated, and we consider it an error if
+the smbpasswd doesn't exist or doesn't 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>
+A sample PAM configuration that shows pam_smbpass used together with
+pam_krb5.  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>Distributed Authentication</title>
+
+<para>
+The astute administrator will realize from this that the 
+combination of <filename>pam_smbpass.so</filename>, 
+<command>winbindd</command>, and a distributed 
+passdb backend, such as ldap, will allow the establishment of a
+centrally managed, distributed 
+user/password database that can also be used by all 
+PAM (eg: Linux) aware programs and applications. This arrangement 
+can have particularly potent advantages compared with the 
+use of Microsoft Active Directory Service (ADS) in so far as 
+reduction of wide area network authentication traffic.
+</para>
+
+</sect1>
+
+</chapter>