diff options
Diffstat (limited to 'docs/docbook/projdoc/PAM-Authentication-And-Samba.xml')
| -rw-r--r-- | docs/docbook/projdoc/PAM-Authentication-And-Samba.xml | 891 |
1 files changed, 688 insertions, 203 deletions
diff --git a/docs/docbook/projdoc/PAM-Authentication-And-Samba.xml b/docs/docbook/projdoc/PAM-Authentication-And-Samba.xml index 4b5179acc7..c9fd510219 100644 --- a/docs/docbook/projdoc/PAM-Authentication-And-Samba.xml +++ b/docs/docbook/projdoc/PAM-Authentication-And-Samba.xml @@ -1,46 +1,462 @@ <chapter id="pam"> <chapterinfo> &author.jht; - <pubdate> (Jun 21 2001) </pubdate> + <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 Configuration for Centrally Managed Authentication</title> +<title>PAM based Distributed Authentication</title> + +<para> +This chapter you 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> +In addition to knowing how to configure winbind into PAM, you will learn generic PAM managment +possibilities and in particular how to deploy tools like pam_smbpass.so to your adavantage. +</para> + +<note><para> +The use of Winbind require more than PAM configuration alone. Please refer to: <link linkend="winbind"></link> +</para></note> <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>, +<title>Features and Benefits</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>. +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> +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 centralised on a +remote server. +</para> + +<para> +PAM support modules are available for: +</para> + +<variablelist> + <varlistentry><term><filename>/etc/passwd</filename></term><listitem><para>-</para> + <para> + There are several PAM modules that interact with this standard Unix user + database. The most common are called: pam_unix.so, pam_unix2.so, pam_pwdb.so + and pam_userdb.so. + </para> + </listitem></varlistentry> + + <varlistentry><term>Kerberos</term><listitem><para>-</para> + <para> + The pam_krb5.so 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>-</para> + <para> + The pam_ldap.so 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, Microsoft Active Directory. + </para> + </listitem></varlistentry> + + <varlistentry><term>NetWare Bindery</term><listitem><para>-</para> + <para> + The pam_ncp_auth.so module allows authentication off any bindery enabled + NetWare Core Protocol based server. + </para> + </listitem></varlistentry> + + <varlistentry><term>SMB Password</term><listitem><para>-</para> + <para> + This module, called pam_smbpass.so, will allow user authentication off + the passdb backend that is configured in the Samba &smb.conf; file. + </para> + </listitem></varlistentry> + + <varlistentry><term>SMB Server</term><listitem><para>-</para> + <para> + The pam_smb_auth.so 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>-</para> + <para> + The pam_winbind.so 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>-</para> + <para> + There is a PAM RADIUS (Remote Access Dial-In User Service) authentication + module. In most cases the administrator will 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> +Of the above, Samba provides the pam_smbpasswd.so and the pam_winbind.so modules alone. +</para> + +<para> +Once configured, these permit a remarkable level of flexibility in the location and use +of distributed samba domain controllers that can provide wide are 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> +PAM is designed to provide the system administrator 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, /etc/pam.conf; or the /etc/pam.d/ directory. +</para> + +<sect2> +<title>PAM Configuration Syntax</title> + +<para> +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 `#' and extend to the next end-of-line; also, +module specification lines may be extended with a `\' escaped newline. +</para> + +<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: +</para> + +<para> +<screen> +auth required /other_path/pam_strange_module.so +</screen> +</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/"> +http://ftp.kernel.org/pub/linux/libs/pam</ulink> The Official Linux-PAM home page. +</para> + +<para> +A general configuration line of the /etc/pam.conf file has the following form: +</para> + +<para> +<screen> +service-name module-type control-flag module-path args +</screen> +</para> + +<para> +Below, 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 above tokens, we will describe this method. +</para> + +<variablelist> + <varlistentry><term>service-name</term><listitem><para>-</para> + <para> + The name of the service associated with this entry. Frequently the service name is the conventional + name of the given application. For example, `ftpd', `rlogind' and `su', etc. . + </para> + + <para> + There is a special service-name, reserved for defining a default authentication mechanism. It has + the name `OTHER' and may be specified in either lower or upper case characters. Note, when there + is a module specified for a named service, the `OTHER' entries are ignored. + </para></listitem> + </varlistentry> + + <varlistentry><term>module-type</term><listitem><para>-</para> + <para> + One of (currently) four types of module. The four types are as follows: + </para> + + <itemizedlist> + <listitem><para> + <emphasis>auth:</emphasis> this module type provides two aspects of authenticating the user. + Firstly, it establishes that the user is who they claim to be, by instructing the application + to prompt the user for a password or other means of identification. Secondly, the module can + grant group membership (independently of the <filename>/etc/groups</filename> file discussed + above) or other privileges through its credential granting properties. + </para></listitem> + + <listitem><para> + <emphasis>account:</emphasis> 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 applicant + user `root' login only on the console. + </para></listitem> + + <listitem><para> + <emphasis>session:</emphasis> primarily, this module is associated with doing things that need + to be done for the user before/after they can be given service. Such things include the loggin + of information concerning the opening/closing of some data exchange with a user, mountin + directories, etc. + </para></listitem> + + <listitem><para> + <emphasis>password:</emphasis> this last module type is required for updating the authentication + token associated with the user. Typically, there is one module for each `challenge/response' + based authentication (auth) module-type. + </para></listitem> + </itemizedlist></listitem> + </varlistentry> + + <varlistentry><term>control-flag</term><listitem><para>-</para> + <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> + 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 + <emphasis>keywords: required, requisite, sufficient and optional</emphasis>. + </para> + + <para> + The Linux-PAM library interprets these keywords in the following manner: + </para> + + <itemizedlist> + <listitem><para> + <emphasis>required:</emphasis> 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> + <emphasis>requisite:</emphasis> like required, however, in the case that 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. Note, 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> + <emphasis>sufficient:</emphasis> the success of this module is deemed `sufficient' 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 `stacked' modules of this type are invoked. (Note, + 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> + <emphasis>optional:</emphasis> 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 delimeted with square brackets and + consists of a series of value=action tokens: + </para> + + <para><screen> + [value1=action1 value2=action2 ...] + </screen></para> + + <para> + Here, valueI is one of the following return values: success; open_err; symbol_err; service_err; + system_err; buf_err; perm_denied; auth_err; cred_insufficient; authinfo_unavail; user_unknown; maxtries; + new_authtok_reqd; acct_expired; session_err; cred_unavail; cred_expired; cred_err; no_module_data; conv_err; + authtok_err; authtok_recover_err; authtok_lock_busy; authtok_disable_aging; try_again; ignore; abort; + authtok_expired; module_unknown; bad_item; and default. The last of these (default) can be used to set + the action for those return values that are not explicitly defined. + </para> + + <para> + The actionI can be a positive integer or one of the following tokens: ignore; ok; done; bad; die; and reset. + 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> + <emphasis>ignore:</emphasis> 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> + <emphasis>bad:</emphasis> 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> + <emphasis>die:</emphasis> equivalent to bad with the side effect of terminating the module stack and + PAM immediately returning to the application. + </para></listitem> + + <listitem><para> + <emphasis>ok:</emphasis> 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 modules + failure, this 'ok' value will not be used to override that value. + </para></listitem> + + <listitem><para> + <emphasis>done:</emphasis> equivalent to ok with the side effect of terminating the module stack and + PAM immediately returning to the application. + </para></listitem> + + <listitem><para> + <emphasis>reset:</emphasis> clear all memory of the state of the module stack and start again with + the next stacked module. + </para></listitem> + </itemizedlist> + + <para> + Each of the four keywords: required; requisite; sufficient; and optional, have an equivalent expression in + terms of the [...] syntax. They are as follows: + </para> + + <para> + <itemizedlist> + <listitem><para> + required is equivalent to [success=ok new_authtok_reqd=ok ignore=ignore default=bad] + </para></listitem> + + <listitem><para> + requisite is equivalent to [success=ok new_authtok_reqd=ok ignore=ignore default=die] + </para></listitem> + + <listitem><para> + sufficient is equivalent to [success=done new_authtok_reqd=done default=ignore] + </para></listitem> + + <listitem><para> + optional is equivalent to [success=ok new_authtok_reqd=ok default=ignore] + </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 is something that makes it possible for PAM to support + machine-machine authentication using the transport protocol inherent to the client/server application. With the + <emphasis>[ ... value=action ... ]</emphasis> control syntax, it is possible for an application to be configured + to support binary prompts with compliant clients, but to gracefully fall over into an alternative authentication + mode for older, legacy, applications. + </para> + </listitem> + </varlistentry> + + <varlistentry><term>module-path</term><listitem><para>-</para> + <para> + The path-name of the dynamically loadable object file; the pluggable module itself. If the first character of the + module path is `/', 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 notes above). + </para> + + <para> + The args 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> + Note, if you wish to include spaces in an argument, you should surround that argument with square brackets. For example: + </para> + +<para><screen> +squid auth required pam_mysql.so user=passwd_query passwd=mada \ + db=eminence [query=select user_name from internet_service where \ + user_name='%u' and password=PASSWORD('%p') and \ + service='web_proxy'] +</screen></para> + + <para> + Note, when using this convention, you can include `[' characters inside the string, and if you wish to include a `]' + character inside the string that will survive the argument parsing, you should use `\['. In other words: + </para> + +<para><screen> +[..[..\]..] --> ..[..].. +</screen></para> + + <para> + Any line in (one of) the configuration file(s), 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. @@ -50,43 +466,50 @@ 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> +<sect3> +<title>PAM: original login config</title> + +<para><screen> +#%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 +</screen></para> + +</sect3> + +<sect3> +<title>PAM: login using pam_smbpass</title> <para> -PAM allows use of replacable modules. Those available on a -sample system include: +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> +<screen> +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 +</screen></para> <para> The following example for the login program replaces the use of @@ -102,37 +525,37 @@ hashes. This database is stored in either 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 +<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 `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><screen> +#%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 +</screen></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><screen> +#%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 +</screen></para> <para> In the following example the decision has been made to use the @@ -142,15 +565,15 @@ 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> +<para><screen> +#%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 +</screen></para> <note><para>PAM allows stacking of authentication mechanisms. It is also possible to pass information obtained within one PAM module through @@ -165,8 +588,12 @@ life though, every decision makes trade-offs, so you may want examine the PAM documentation for further helpful information. </para></note> +</sect3> + +</sect2> + <sect2> -<title>PAM Configuration in smb.conf</title> +<title>smb.conf PAM Configuration</title> <para> There is an option in smb.conf called <ulink @@ -175,8 +602,8 @@ 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 +When Samba-3 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 @@ -188,12 +615,53 @@ authentication mechanism needed in the presence of SMB password encryption. </para> -<para>Default: <command>obey pam restrictions = no</command></para> +<para>Default: <parameter>obey pam restrictions = no</parameter></para> </sect2> <sect2> -<title>Password Synchronisation using pam_smbpass.so</title> +<title>Remote CIFS Authentication using winbindd.so</title> + +<para> +All operating systems depend on the provision of users credentials accecptable to the platform. +Unix requires the provision of a user identifier (UID) as well as a group identifier (GID). +These are both simple integer type 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 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> + +<warning><para> +The rid to unix id database is the only location where the user and group mappings are +stored by winbindd. If this file is deleted or corrupted, there is no way for winbindd +to determine which user and group ids correspond to Windows NT user and group rids. +</para></warning> + +</sect2> + +<sect2> +<title>Password Synchronization using pam_smbpass.so</title> <para> pam_smbpass is a PAM module which can be used on conforming systems to @@ -204,62 +672,48 @@ 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> +<para> Options recognized by this module are as follows: +<table frame="all"> + <title>Options recognized by pam_smbpass</title> + <tgroup cols="2" align="left"> + <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>don't 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>don't make passwords used by this module available to other modules.</entry></row> + <row><entry>nodelay</entry><entry>don't 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 "auth" 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> - 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=< file > - specify an alternate path to the smb.conf - file. -</programlisting></para> - -<para><programlisting> +<para> Thanks go to the following people: +<simplelist> + <member><ulink url="mailto:morgan@transmeta.com">Andrew Morgan</ulink>, for providing the Linux-PAM + framework, without which none of this would have happened</member> - * Andrew Morgan < morgan@transmeta.com >, for providing the Linux-PAM - framework, without which none of this would have happened - - * Christian Gafton < gafton@redhat.com > and Andrew Morgan again, for the - pam_pwdb module upon which pam_smbpass was originally based + <member><ulink url="gafton@redhat.com">Christian Gafton</ulink> and Andrew Morgan again, for the + pam_pwdb module upon which pam_smbpass was originally based</member> - * Luke Leighton < lkcl@switchboard.net > for being receptive to the idea, + <member><ulink url="lkcl@switchboard.net">Luke Leighton</ulink> 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 - <http://www.samba.org/samba/team.html>, for creating a great product - and for giving this project a purpose - - --------------------- - Stephen Langasek < vorlon@netexpress.net > -</programlisting></para> + that keep me working on it :)</member> +</simplelist>. +</para> <para> The following are examples of the use of pam_smbpass.so in the format of Linux @@ -268,7 +722,7 @@ tool on other platforms will need to adapt this appropriately. </para> <sect3> -<title>Password Synchonisation Configuration</title> +<title>Password Synchronisation Configuration</title> <para> A sample PAM configuration that shows the use of pam_smbpass to make @@ -277,18 +731,18 @@ 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> +<para><screen> +#%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 +</screen></para> </sect3> <sect3> @@ -302,20 +756,20 @@ 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> +<para><screen> +#%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 +</screen></para> </sect3> <sect3> @@ -327,18 +781,18 @@ 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> +<para><screen> +#%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 +</screen></para> </sect3> <sect3> @@ -350,40 +804,71 @@ 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> +<para><screen> +#%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 +</screen></para> + </sect3> </sect2> + </sect1> <sect1> -<title>Distributed Authentication</title> +<title>Common Errors</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. +PAM can be a very 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> + I have the following PAM configuration: + </para> + +<para> +<screen> +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 +</screen> +</para> + + <para> + When I open a new console with [ctrl][alt][F1], then I cant log in with my user "pitie". + I've tried with user "scienceu+pitie" also. + </para> + + <para> + Answer: The problem may lie with your inclusion of <parameter>pam_stack.so + service=system-auth</parameter>. That file often contains a lot of stuff that may + duplicate what you're already doing. Try commenting out the pam_stack lines + for auth and account 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> + </sect1> </chapter> |