--- /dev/null
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 27. PAM-Based Distributed Authentication</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"><link rel="start" href="index.html" title="The Official Samba-3 HOWTO and Reference Guide"><link rel="up" href="optional.html" title="Part III. Advanced Configuration"><link rel="prev" href="ProfileMgmt.html" title="Chapter 26. Desktop Profile Management"><link rel="next" href="integrate-ms-networks.html" title="Chapter 28. Integrating MS Windows Networks with Samba"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 27. PAM-Based Distributed Authentication</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ProfileMgmt.html">Prev</a> </td><th width="60%" align="center">Part III. Advanced Configuration</th><td width="20%" align="right"> <a accesskey="n" href="integrate-ms-networks.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="pam"></a>Chapter 27. PAM-Based Distributed Authentication</h2></div><div><div class="author"><h3 class="author"><span class="firstname">John</span> <span class="othername">H.</span> <span class="surname">Terpstra</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><code class="email"><<a href="mailto:jht@samba.org">jht@samba.org</a>></code></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Stephen</span> <span class="surname">Langasek</span></h3><div class="affiliation"><div class="address"><p><code class="email"><<a href="mailto:vorlon@netexpress.net">vorlon@netexpress.net</a>></code></p></div></div></div></div><div><p class="pubdate">May 31, 2003</p></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="pam.html#id2631822">Features and Benefits</a></span></dt><dt><span class="sect1"><a href="pam.html#id2632453">Technical Discussion</a></span></dt><dd><dl><dt><span class="sect2"><a href="pam.html#id2632506">PAM Configuration Syntax</a></span></dt><dt><span class="sect2"><a href="pam.html#id2633504">Example System Configurations</a></span></dt><dt><span class="sect2"><a href="pam.html#id2633811"><code class="filename">smb.conf</code> PAM Configuration</a></span></dt><dt><span class="sect2"><a href="pam.html#id2633878">Remote CIFS Authentication Using <code class="filename">winbindd.so</code></a></span></dt><dt><span class="sect2"><a href="pam.html#id2633978">Password Synchronization Using <code class="filename">pam_smbpass.so</code></a></span></dt></dl></dd><dt><span class="sect1"><a href="pam.html#id2634372">Common Errors</a></span></dt><dd><dl><dt><span class="sect2"><a href="pam.html#id2634383">pam_winbind Problem</a></span></dt><dt><span class="sect2"><a href="pam.html#id2634481">Winbind Is Not Resolving Users and Groups</a></span></dt></dl></dd></dl></div><p>
+<a class="indexterm" name="id2631747"></a>
+<a class="indexterm" name="id2631753"></a>
+<a class="indexterm" name="id2631760"></a>
+<a class="indexterm" name="id2631767"></a>
+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.
+</p><p>
+<a class="indexterm" name="id2631784"></a>
+<a class="indexterm" name="id2631791"></a>
+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 <code class="filename">pam_smbpass.so</code> to your advantage.
+</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+The use of Winbind requires more than PAM configuration alone.
+Please refer to <a href="winbind.html" title="Chapter 23. Winbind: Use of Domain Accounts">Winbind: Use of Domain Accounts</a>, for further information regarding Winbind.
+</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2631822"></a>Features and Benefits</h2></div></div></div><p>
+<a class="indexterm" name="id2631830"></a>
+<a class="indexterm" name="id2631837"></a>
+<a class="indexterm" name="id2631844"></a>
+<a class="indexterm" name="id2631850"></a>
+<a class="indexterm" name="id2631860"></a>
+<a class="indexterm" name="id2631867"></a>
+<a class="indexterm" name="id2631873"></a>
+<a class="indexterm" name="id2631880"></a>
+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 (<code class="filename">/etc/passwd</code>)
+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 <span><strong class="command">login</strong></span>,
+<span><strong class="command">passwd</strong></span>, <span><strong class="command">chown</strong></span>, and so on.
+</p><p>
+<a class="indexterm" name="id2631922"></a>
+<a class="indexterm" name="id2631929"></a>
+<a class="indexterm" name="id2631936"></a>
+<a class="indexterm" name="id2631942"></a>
+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,
+<code class="filename">/etc/pam.conf</code> (Solaris), or by editing individual control files that are
+located in <code class="filename">/etc/pam.d</code>.
+</p><p>
+<a class="indexterm" name="id2631969"></a>
+<a class="indexterm" name="id2631976"></a>
+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.
+</p><p>
+PAM support modules are available for:
+</p><div class="variablelist"><dl><dt><span class="term"><code class="filename">/etc/passwd</code></span></dt><dd><p>
+<a class="indexterm" name="id2632006"></a>
+<a class="indexterm" name="id2632013"></a>
+<a class="indexterm" name="id2632020"></a>
+<a class="indexterm" name="id2632026"></a>
+<a class="indexterm" name="id2632033"></a>
+<a class="indexterm" name="id2632040"></a>
+ There are several PAM modules that interact with this standard UNIX user database. The most common are called
+ <code class="filename">pam_unix.so</code>, <code class="filename">pam_unix2.so</code>, <code class="filename">pam_pwdb.so</code> and
+ <code class="filename">pam_userdb.so</code>.
+ </p></dd><dt><span class="term">Kerberos</span></dt><dd><p>
+<a class="indexterm" name="id2632083"></a>
+<a class="indexterm" name="id2632089"></a>
+<a class="indexterm" name="id2632096"></a>
+<a class="indexterm" name="id2632103"></a>
+<a class="indexterm" name="id2632110"></a>
+ The <code class="filename">pam_krb5.so</code> 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).
+ </p></dd><dt><span class="term">LDAP</span></dt><dd><p>
+<a class="indexterm" name="id2632136"></a>
+<a class="indexterm" name="id2632142"></a>
+<a class="indexterm" name="id2632149"></a>
+<a class="indexterm" name="id2632156"></a>
+<a class="indexterm" name="id2632163"></a>
+<a class="indexterm" name="id2632170"></a>
+ The <code class="filename">pam_ldap.so</code> 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.
+ </p></dd><dt><span class="term">NetWare Bindery</span></dt><dd><p>
+<a class="indexterm" name="id2632197"></a>
+<a class="indexterm" name="id2632204"></a>
+<a class="indexterm" name="id2632211"></a>
+<a class="indexterm" name="id2632218"></a>
+ The <code class="filename">pam_ncp_auth.so</code> module allows authentication off any bindery-enabled
+ NetWare Core Protocol-based server.
+ </p></dd><dt><span class="term">SMB Password</span></dt><dd><p>
+<a class="indexterm" name="id2632243"></a>
+<a class="indexterm" name="id2632250"></a>
+<a class="indexterm" name="id2632257"></a>
+ This module, called <code class="filename">pam_smbpass.so</code>, allows user authentication of
+ the passdb backend that is configured in the Samba <code class="filename">smb.conf</code> file.
+ </p></dd><dt><span class="term">SMB Server</span></dt><dd><p>
+<a class="indexterm" name="id2632288"></a>
+<a class="indexterm" name="id2632294"></a>
+ The <code class="filename">pam_smb_auth.so</code> module is the original MS Windows networking authentication
+ tool. This module has been somewhat outdated by the Winbind module.
+ </p></dd><dt><span class="term">Winbind</span></dt><dd><p>
+<a class="indexterm" name="id2632320"></a>
+<a class="indexterm" name="id2632327"></a>
+<a class="indexterm" name="id2632334"></a>
+<a class="indexterm" name="id2632340"></a>
+ The <code class="filename">pam_winbind.so</code> 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.
+ </p></dd><dt><span class="term">RADIUS</span></dt><dd><p>
+<a class="indexterm" name="id2632367"></a>
+ 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.
+ </p></dd></dl></div><p>
+<a class="indexterm" name="id2632386"></a>
+<a class="indexterm" name="id2632393"></a>
+Of the modules listed, Samba provides the <code class="filename">pam_smbpasswd.so</code> and the
+<code class="filename">pam_winbind.so</code> modules alone.
+</p><p>
+<a class="indexterm" name="id2632416"></a>
+<a class="indexterm" name="id2632424"></a>
+<a class="indexterm" name="id2632431"></a>
+<a class="indexterm" name="id2632437"></a>
+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.
+</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2632453"></a>Technical Discussion</h2></div></div></div><p>
+<a class="indexterm" name="id2632461"></a>
+<a class="indexterm" name="id2632467"></a>
+<a class="indexterm" name="id2632475"></a>
+<a class="indexterm" name="id2632482"></a>
+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 <code class="filename">/etc/pam.conf</code> or the
+<code class="filename">/etc/pam.d/</code> directory.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2632506"></a>PAM Configuration Syntax</h3></div></div></div><p>
+<a class="indexterm" name="id2632514"></a>
+<a class="indexterm" name="id2632521"></a>
+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.
+</p><p>
+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 “<span class="quote">#</span>” and extend to the next end-of-line; also,
+module specification lines may be extended with a “<span class="quote">\</span>”-escaped newline.
+</p><p>
+<a class="indexterm" name="id2632553"></a>
+<a class="indexterm" name="id2632560"></a>
+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 <code class="filename">/lib/security</code>. If the module
+is located outside the default, then the path must be specified as:
+</p><pre class="programlisting">
+auth required /other_path/pam_strange_module.so
+</pre><p>
+</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2632585"></a>Anatomy of <code class="filename">/etc/pam.d</code> Entries</h4></div></div></div><p>
+The remaining information in this subsection was taken from the documentation of the Linux-PAM
+project. For more information on PAM, see
+<a href="http://ftp.kernel.org/pub/linux/libs/pam/" target="_top">the Official Linux-PAM home page</a>.
+</p><p>
+<a class="indexterm" name="id2632611"></a>
+A general configuration line of the <code class="filename">/etc/pam.conf</code> file has the following form:
+</p><pre class="programlisting">
+service-name module-type control-flag module-path args
+</pre><p>
+</p><p>
+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 <code class="filename">/etc/pam.d/</code> directory.
+Once we have explained the meaning of the tokens, we describe this method.
+</p><div class="variablelist"><dl><dt><span class="term">service-name</span></dt><dd><p>
+<a class="indexterm" name="id2632657"></a>
+<a class="indexterm" name="id2632663"></a>
+<a class="indexterm" name="id2632670"></a>
+ The name of the service associated with this entry. Frequently, the service-name is the conventional
+ name of the given application for example, <span><strong class="command">ftpd</strong></span>, <span><strong class="command">rlogind</strong></span> and
+ <span><strong class="command">su</strong></span>, and so on.
+ </p><p>
+ There is a special service-name reserved for defining a default authentication mechanism. It has
+ the name <em class="parameter"><code>OTHER</code></em> and may be specified in either lower- or uppercase characters.
+ Note, when there is a module specified for a named service, the <em class="parameter"><code>OTHER</code></em>
+ entries are ignored.
+ </p></dd><dt><span class="term">module-type</span></dt><dd><p>
+ One of (currently) four types of module. The four types are as follows:
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+<a class="indexterm" name="id2632738"></a>
+<a class="indexterm" name="id2632745"></a>
+ <em class="parameter"><code>auth:</code></em> 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 <code class="filename">/etc/groups</code> file)
+ or other privileges through its credential-granting properties.
+ </p></li><li><p>
+<a class="indexterm" name="id2632774"></a>
+<a class="indexterm" name="id2632781"></a>
+ <em class="parameter"><code>account:</code></em> 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 “<span class="quote">root</span>” login may be permitted only on the console.
+ </p></li><li><p>
+<a class="indexterm" name="id2632808"></a>
+ <em class="parameter"><code>session:</code></em> 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.
+ </p></li><li><p>
+<a class="indexterm" name="id2632830"></a>
+ <em class="parameter"><code>password:</code></em> This last module type is required for updating the authentication
+ token associated with the user. Typically, there is one module for each
+ “<span class="quote">challenge/response</span>” authentication <em class="parameter"><code>(auth)</code></em> module type.
+ </p></li></ul></div></dd><dt><span class="term">control-flag</span></dt><dd><p>
+ 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
+ <code class="filename">/etc/pam.conf</code> 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
+ <code class="filename">/etc/pam.conf</code> 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.
+ </p><p>
+<a class="indexterm" name="id2632894"></a>
+<a class="indexterm" name="id2632901"></a>
+<a class="indexterm" name="id2632908"></a>
+<a class="indexterm" name="id2632914"></a>
+ 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: <em class="parameter"><code>required</code></em>, <em class="parameter"><code>requisite</code></em>,
+ <em class="parameter"><code>sufficient</code></em>, and <em class="parameter"><code>optional</code></em>.
+ </p><p>
+ The Linux-PAM library interprets these keywords in the following manner:
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ <em class="parameter"><code>required:</code></em> 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.
+ </p></li><li><p>
+ <em class="parameter"><code>requisite:</code></em> 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.
+ </p></li><li><p>
+ <em class="parameter"><code>sufficient:</code></em> The success of this module is deemed <em class="parameter"><code>sufficient</code></em> 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 “<span class="quote">stacked</span>” 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.
+ </p></li><li><p>
+ <em class="parameter"><code>optional:</code></em> 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.
+ </p></li></ul></div><p>
+ 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 <em class="parameter"><code>value=action</code></em> tokens:
+ </p><pre class="programlisting">
+[value1=action1 value2=action2 ...]
+</pre><p>
+ Here, <em class="parameter"><code>value1</code></em> is one of the following return values:
+</p><pre class="screen">
+<em class="parameter"><code>success; open_err; symbol_err; service_err; system_err; buf_err;</code></em>
+<em class="parameter"><code>perm_denied; auth_err; cred_insufficient; authinfo_unavail;</code></em>
+<em class="parameter"><code>user_unknown; maxtries; new_authtok_reqd; acct_expired; session_err;</code></em>
+<em class="parameter"><code>cred_unavail; cred_expired; cred_err; no_module_data; conv_err;</code></em>
+<em class="parameter"><code>authtok_err; authtok_recover_err; authtok_lock_busy;</code></em>
+<em class="parameter"><code>authtok_disable_aging; try_again; ignore; abort; authtok_expired;</code></em>
+<em class="parameter"><code>module_unknown; bad_item;</code></em> and <em class="parameter"><code>default</code></em>.
+</pre><p>
+</p><p>
+ The last of these (<em class="parameter"><code>default</code></em>) can be used to set the action for those return values that are not explicitly defined.
+ </p><p>
+ The <em class="parameter"><code>action1</code></em> can be a positive integer or one of the following tokens:
+ <em class="parameter"><code>ignore</code></em>; <em class="parameter"><code>ok</code></em>; <em class="parameter"><code>done</code></em>;
+ <em class="parameter"><code>bad</code></em>; <em class="parameter"><code>die</code></em>; and <em class="parameter"><code>reset</code></em>.
+ 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.
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ <em class="parameter"><code>ignore:</code></em> When used with a stack of modules, the module's return status will not
+ contribute to the return code the application obtains.
+ </p></li><li><p>
+ <em class="parameter"><code>bad:</code></em> 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.
+ </p></li><li><p>
+ <em class="parameter"><code>die:</code></em> Equivalent to bad with the side effect of terminating the module stack and
+ PAM immediately returning to the application.
+ </p></li><li><p>
+ <em class="parameter"><code>ok:</code></em> 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 <em class="parameter"><code>ok</code></em> value will not be used to override that value.
+ </p></li><li><p>
+ <em class="parameter"><code>done:</code></em> Equivalent to <em class="parameter"><code>ok</code></em> with the side effect of terminating the module stack and
+ PAM immediately returning to the application.
+ </p></li><li><p>
+ <em class="parameter"><code>reset:</code></em> Clears all memory of the state of the module stack and starts again with
+ the next stacked module.
+ </p></li></ul></div><p>
+ Each of the four keywords, <em class="parameter"><code>required</code></em>; <em class="parameter"><code>requisite</code></em>;
+ <em class="parameter"><code>sufficient</code></em>; and <em class="parameter"><code>optional</code></em>, have an equivalent expression in terms
+ of the [...] syntax. They are as follows:
+ </p><p>
+ </p><div class="itemizedlist"><ul type="disc"><li><p>
+ <em class="parameter"><code>required</code></em> is equivalent to <em class="parameter"><code>[success=ok new_authtok_reqd=ok ignore=ignore default=bad]</code></em>.
+ </p></li><li><p>
+ <em class="parameter"><code>requisite</code></em> is equivalent to <em class="parameter"><code>[success=ok new_authtok_reqd=ok ignore=ignore default=die]</code></em>.
+ </p></li><li><p>
+ <em class="parameter"><code>sufficient</code></em> is equivalent to <em class="parameter"><code>[success=done new_authtok_reqd=done default=ignore]</code></em>.
+ </p></li><li><p>
+ <em class="parameter"><code>optional</code></em> is equivalent to <em class="parameter"><code>[success=ok new_authtok_reqd=ok default=ignore]</code></em>.
+ </p></li></ul></div><p>
+ </p><p>
+ 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
+ <em class="parameter"><code>[ ... value=action ... ]</code></em> 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.
+ </p></dd><dt><span class="term">module-path</span></dt><dd><p>
+ The pathname of the dynamically loadable object file; the pluggable module itself. If the first character of the
+ module path is “<span class="quote">/</span>”, 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: <code class="filename">/lib/security</code> (but see the previous notes).
+ </p><p>
+ 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.
+ </p><p>
+ If you wish to include spaces in an argument, you should surround that argument with square brackets. For example:
+ </p><pre class="programlisting">
+squid auth required pam_mysql.so user=passwd_query passwd=mada \
+db=eminence [query=select user_name from internet_service where \
+user_name=“<span class="quote">%u</span>” and password=PASSWORD(“<span class="quote">%p</span>”) and service=“<span class="quote">web_proxy</span>”]
+</pre><p>
+ When using this convention, you can include “<span class="quote">[</span>” characters inside the string, and if you wish to have a “<span class="quote">]</span>”
+ character inside the string that will survive the argument parsing, you should use “<span class="quote">\[</span>”. In other words,
+ </p><pre class="programlisting">
+[..[..\]..] --> ..[..]..
+</pre><p>
+ 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).
+ </p></dd></dl></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2633504"></a>Example System Configurations</h3></div></div></div><p>
+The following is an example <code class="filename">/etc/pam.d/login</code> 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 <code class="filename">pam_pwdb.so</code>.
+</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2633530"></a>PAM: Original Login Config</h4></div></div></div><p>
+ </p><pre class="programlisting">
+#%PAM-1.0
+# The PAM configuration file for the “<span class="quote">login</span>” 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
+</pre><p>
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2633558"></a>PAM: Login Using <code class="filename">pam_smbpass</code></h4></div></div></div><p>
+PAM allows use of replaceable modules. Those available on a sample system include:
+</p><p><code class="prompt">$</code><strong class="userinput"><code>/bin/ls /lib/security</code></strong>
+</p><pre class="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
+</pre><p>
+The following example for the login program replaces the use of
+the <code class="filename">pam_pwdb.so</code> module that uses the system
+password database (<code class="filename">/etc/passwd</code>,
+<code class="filename">/etc/shadow</code>, <code class="filename">/etc/group</code>) with
+the module <code class="filename">pam_smbpass.so</code>, which uses the Samba
+database containing the Microsoft MD4 encrypted password
+hashes. This database is stored either in
+<code class="filename">/usr/local/samba/private/smbpasswd</code>,
+<code class="filename">/etc/samba/smbpasswd</code> or in
+<code class="filename">/etc/samba.d/smbpasswd</code>, depending on the
+Samba implementation for your UNIX/Linux system. The
+<code class="filename">pam_smbpass.so</code> module is provided by
+Samba version 2.2.1 or later. It can be compiled by specifying the
+<code class="option">--with-pam_smbpass</code> options when running Samba's
+<span><strong class="command">configure</strong></span> script. For more information
+on the <code class="filename">pam_smbpass</code> module, see the documentation
+in the <code class="filename">source/pam_smbpass</code> directory of the Samba
+source distribution.
+</p><p>
+ </p><pre class="programlisting">
+#%PAM-1.0
+# The PAM configuration file for the “<span class="quote">login</span>” 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
+</pre><p>
+The following is the PAM configuration file for a particular
+Linux system. The default condition uses <code class="filename">pam_pwdb.so</code>.
+</p><p>
+ </p><pre class="programlisting">
+#%PAM-1.0
+# The PAM configuration file for the “<span class="quote">samba</span>” 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
+</pre><p>
+In the following example, the decision has been made to use the
+<span><strong class="command">smbpasswd</strong></span> database even for basic Samba authentication. Such a
+decision could also be made for the <span><strong class="command">passwd</strong></span> program and would
+thus allow the <span><strong class="command">smbpasswd</strong></span> passwords to be changed using the
+<span><strong class="command">passwd</strong></span> program:
+</p><p>
+ </p><pre class="programlisting">
+#%PAM-1.0
+# The PAM configuration file for the “<span class="quote">samba</span>” 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
+</pre><p>
+</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>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 <code class="filename">pam_stack.so</code> module that allows all
+authentication to be configured in a single central file. The
+<code class="filename">pam_stack.so</code> 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.
+</p></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2633811"></a><code class="filename">smb.conf</code> PAM Configuration</h3></div></div></div><p>
+There is an option in <code class="filename">smb.conf</code> called <a class="indexterm" name="id2633830"></a>obey pam restrictions.
+The following is from the online help for this option in SWAT:
+</p><div class="blockquote"><blockquote class="blockquote"><p>
+When Samba is configured to enable PAM support (i.e., <code class="option">--with-pam</code>), 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 <a class="indexterm" name="id2633853"></a>encrypt passwords = yes.
+The reason is that PAM modules cannot support the challenge/response authentication mechanism needed in the presence of SMB
+password encryption.
+</p><p>Default: <a class="indexterm" name="id2633867"></a>obey pam restrictions = no</p></blockquote></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2633878"></a>Remote CIFS Authentication Using <code class="filename">winbindd.so</code></h3></div></div></div><p>
+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 <code class="filename">/etc/passwd</code>.
+</p><p>
+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.
+</p><p>
+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.
+</p><p>
+The astute administrator will realize from this that the combination of <code class="filename">pam_smbpass.so</code>,
+<span><strong class="command">winbindd</strong></span>, and a distributed <a class="indexterm" name="id2633936"></a>passdb backend
+such as <em class="parameter"><code>ldap</code></em> 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.
+</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
+The RID to UNIX ID database is the only location where the user and group mappings are
+stored by <span><strong class="command">winbindd</strong></span>. If this file is deleted or corrupted, there is no way for <span><strong class="command">winbindd</strong></span>
+to determine which user and group IDs correspond to Windows NT user and group RIDs.
+</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2633978"></a>Password Synchronization Using <code class="filename">pam_smbpass.so</code></h3></div></div></div><p>
+<code class="filename">pam_smbpass</code> is a PAM module that can be used on conforming systems to
+keep the <code class="filename">smbpasswd</code> (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.
+</p><p>
+This module authenticates a local <code class="filename">smbpasswd</code> 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 <code class="filename">pam_winbind</code> instead.
+</p><p>
+Options recognized by this module are shown in <a href="pam.html#smbpassoptions" title="Table 27.1. Options recognized by pam_smbpass">next table</a>.
+</p><div class="table"><a name="smbpassoptions"></a><p class="title"><b>Table 27.1. Options recognized by <em class="parameter"><code>pam_smbpass</code></em></b></p><table summary="Options recognized by pam_smbpass" border="1"><colgroup><col align="left"><col align="justify"></colgroup><tbody><tr><td align="left">debug</td><td align="left">Log more debugging info.</td></tr><tr><td align="left">audit</td><td align="left">Like debug, but also logs unknown usernames.</td></tr><tr><td align="left">use_first_pass</td><td align="left">Do not prompt the user for passwords; take them from PAM_ items instead.</td></tr><tr><td align="left">try_first_pass</td><td align="left">Try to get the password from a previous PAM module; fall back to prompting the user.</td></tr><tr><td align="left">use_authtok</td><td align="left">Like try_first_pass, but *fail* if the new PAM_AUTHTOK has not been previously set (intended for stacking password modules only).</td></tr><tr><td align="left">not_set_pass</td><td align="left">Do not make passwords used by this module available to other modules.</td></tr><tr><td align="left">nodelay</td><td align="left">dDo not insert ~1-second delays on authentication failure.</td></tr><tr><td align="left">nullok</td><td align="left">Null passwords are allowed.</td></tr><tr><td align="left">nonull</td><td align="left">Null passwords are not allowed. Used to override the Samba configuration.</td></tr><tr><td align="left">migrate</td><td align="left">Only meaningful in an “<span class="quote">auth</span>” context; used to update smbpasswd file with a password used for successful authentication.</td></tr><tr><td align="left">smbconf=<em class="replaceable"><code>file</code></em></td><td align="left">Specify an alternate path to the <code class="filename">smb.conf</code> file.</td></tr></tbody></table></div><p>
+</p><p>
+The following are examples of the use of <code class="filename">pam_smbpass.so</code> in the format of the Linux
+<code class="filename">/etc/pam.d/</code> files structure. Those wishing to implement this
+tool on other platforms will need to adapt this appropriately.
+</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2634197"></a>Password Synchronization Configuration</h4></div></div></div><p>
+The following is a sample PAM configuration that shows the use of pam_smbpass to make
+sure <code class="filename">private/smbpasswd</code> is kept in sync when <code class="filename">/etc/passwd (/etc/shadow)</code>
+is changed. It is useful when an expired password might be changed by an
+application (such as <span><strong class="command">ssh</strong></span>).
+</p><p>
+ </p><pre class="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
+</pre></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2634243"></a>Password Migration Configuration</h4></div></div></div><p>
+The following PAM configuration shows the use of <code class="filename">pam_smbpass</code> 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 <span><strong class="command">ftp</strong></span> in, login using <span><strong class="command">ssh</strong></span>, pop
+their mail, and so on.
+</p><p>
+ </p><pre class="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
+</pre></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2634291"></a>Mature Password Configuration</h4></div></div></div><p>
+The following is a sample PAM configuration for a mature <code class="filename">smbpasswd</code> installation.
+<code class="filename">private/smbpasswd</code> is fully populated, and we consider it an error if
+the SMB password does not exist or does not match the UNIX password.
+</p><p>
+</p><pre class="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
+</pre></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2634331"></a>Kerberos Password Integration Configuration</h4></div></div></div><p>
+The following is a sample PAM configuration that shows <em class="parameter"><code>pam_smbpass</code></em> used together with
+<em class="parameter"><code>pam_krb5</code></em>. This could be useful on a Samba PDC that is also a member of
+a Kerberos realm.
+</p><p>
+ </p><pre class="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
+</pre></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2634372"></a>Common Errors</h2></div></div></div><p>
+PAM can be fickle and sensitive to configuration glitches. Here we look at a few cases from
+the Samba mailing list.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2634383"></a>pam_winbind Problem</h3></div></div></div><p>
+ A user reported, <span class="emphasis"><em>I have the following PAM configuration</em></span>:
+ </p><p>
+</p><pre class="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
+</pre><p>
+</p><p>
+ <span class="emphasis"><em>When I open a new console with [ctrl][alt][F1], I can't log in with my user “<span class="quote">pitie.</span>”
+ I have tried with user “<span class="quote">scienceu\pitie</span>” also.</em></span>
+ </p><p>
+ The problem may lie with the inclusion of <em class="parameter"><code>pam_stack.so
+ service=system-auth</code></em>. That file often contains a lot of stuff that may
+ duplicate what you are already doing. Try commenting out the <em class="parameter"><code>pam_stack</code></em> lines
+ for <em class="parameter"><code>auth</code></em> and <em class="parameter"><code>account</code></em> and see if things work. If they do, look at
+ <code class="filename">/etc/pam.d/system-auth</code> and copy only what you need from it into your
+ <code class="filename">/etc/pam.d/login</code> file. Alternatively, if you want all services to use
+ Winbind, you can put the Winbind-specific stuff in <code class="filename">/etc/pam.d/system-auth</code>.
+ </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2634481"></a>Winbind Is Not Resolving Users and Groups</h3></div></div></div><p>
+ “<span class="quote">
+ My <code class="filename">smb.conf</code> file is correctly configured. I have specified
+ <a class="indexterm" name="id2634499"></a>idmap uid = 12000
+ and <a class="indexterm" name="id2634506"></a>idmap gid = 3000-3500,
+ and <span><strong class="command">winbind</strong></span> is running. When I do the following it all works fine.
+ </span>”
+ </p><pre class="screen">
+<code class="prompt">root# </code><strong class="userinput"><code>wbinfo -u</code></strong>
+MIDEARTH\maryo
+MIDEARTH\jackb
+MIDEARTH\ameds
+...
+MIDEARTH\root
+
+<code class="prompt">root# </code><strong class="userinput"><code>wbinfo -g</code></strong>
+MIDEARTH\Domain Users
+MIDEARTH\Domain Admins
+MIDEARTH\Domain Guests
+...
+MIDEARTH\Accounts
+
+<code class="prompt">root# </code><strong class="userinput"><code>getent passwd</code></strong>
+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
+</pre><p>
+ “<span class="quote">
+ But this command fails:
+ </span>”
+</p><pre class="screen">
+<code class="prompt">root# </code><strong class="userinput"><code>chown maryo a_file</code></strong>
+chown: 'maryo': invalid user
+</pre><p>
+ “<span class="quote">This is driving me nuts! What can be wrong?</span>”
+ </p><p>
+ Your system is likely running <span><strong class="command">nscd</strong></span>, the name service
+ caching daemon. Shut it down, do not restart it! You will find your problem resolved.
+ </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ProfileMgmt.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="optional.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="integrate-ms-networks.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 26. Desktop Profile Management </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 28. Integrating MS Windows Networks with Samba</td></tr></table></div></body></html>
projects / samba / blobdiff