summaryrefslogtreecommitdiff
path: root/docs/docbook/projdoc/PAM-Authentication-And-Samba.xml
diff options
context:
space:
mode:
Diffstat (limited to 'docs/docbook/projdoc/PAM-Authentication-And-Samba.xml')
-rw-r--r--docs/docbook/projdoc/PAM-Authentication-And-Samba.xml389
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>