4 <firstname>Stephen</firstname><surname>Langasek</surname>
6 <address><email>vorlon@netexpress.net</email></address>
10 <pubdate> (Jun 21 2001) </pubdate>
13 <title>PAM Configuration for Centrally Managed Authentication</title>
16 <title>Samba and PAM</title>
19 A number of Unix systems (eg: Sun Solaris), as well as the
20 xxxxBSD family and Linux, now utilize the Pluggable Authentication
21 Modules (PAM) facility to provide all authentication,
22 authorization and resource control services. Prior to the
23 introduction of PAM, a decision to use an alternative to
24 the system password database (<filename>/etc/passwd</filename>)
25 would require the provision of alternatives for all programs that provide
26 security services. Such a choice would involve provision of
27 alternatives to such programs as: <command>login</command>,
28 <command>passwd</command>, <command>chown</command>, etc.
32 PAM provides a mechanism that disconnects these security programs
33 from the underlying authentication/authorization infrastructure.
34 PAM is configured either through one file <filename>/etc/pam.conf</filename> (Solaris),
35 or by editing individual files that are located in <filename>/etc/pam.d</filename>.
40 If the PAM authentication module (loadable link library file) is located in the
41 default location then it is not necessary to specify the path. In the case of
42 Linux, the default location is <filename>/lib/security</filename>. If the module
43 is located outside the default then the path must be specified as:
46 auth required /other_path/pam_strange_module.so
52 The following is an example <filename>/etc/pam.d/login</filename> configuration file.
53 This example had all options been uncommented is probably not usable
54 as it stacks many conditions before allowing successful completion
55 of the login process. Essentially all conditions can be disabled
56 by commenting them out except the calls to <filename>pam_pwdb.so</filename>.
59 <para><programlisting>
61 # The PAM configuration file for the `login' service
63 auth required pam_securetty.so
64 auth required pam_nologin.so
65 # auth required pam_dialup.so
66 # auth optional pam_mail.so
67 auth required pam_pwdb.so shadow md5
68 # account requisite pam_time.so
69 account required pam_pwdb.so
70 session required pam_pwdb.so
71 # session optional pam_lastlog.so
72 # password required pam_cracklib.so retry=3
73 password required pam_pwdb.so shadow md5
74 </programlisting></para>
77 PAM allows use of replacable modules. Those available on a
78 sample system include:
81 <para><prompt>$</prompt><userinput>/bin/ls /lib/security</userinput>
83 pam_access.so pam_ftp.so pam_limits.so
84 pam_ncp_auth.so pam_rhosts_auth.so pam_stress.so
85 pam_cracklib.so pam_group.so pam_listfile.so
86 pam_nologin.so pam_rootok.so pam_tally.so
87 pam_deny.so pam_issue.so pam_mail.so
88 pam_permit.so pam_securetty.so pam_time.so
89 pam_dialup.so pam_lastlog.so pam_mkhomedir.so
90 pam_pwdb.so pam_shells.so pam_unix.so
91 pam_env.so pam_ldap.so pam_motd.so
92 pam_radius.so pam_smbpass.so pam_unix_acct.so
93 pam_wheel.so pam_unix_auth.so pam_unix_passwd.so
94 pam_userdb.so pam_warn.so pam_unix_session.so
95 </programlisting></para>
98 The following example for the login program replaces the use of
99 the <filename>pam_pwdb.so</filename> module which uses the system
100 password database (<filename>/etc/passwd</filename>,
101 <filename>/etc/shadow</filename>, <filename>/etc/group</filename>) with
102 the module <filename>pam_smbpass.so</filename> which uses the Samba
103 database which contains the Microsoft MD4 encrypted password
104 hashes. This database is stored in either
105 <filename>/usr/local/samba/private/smbpasswd</filename>,
106 <filename>/etc/samba/smbpasswd</filename>, or in
107 <filename>/etc/samba.d/smbpasswd</filename>, depending on the
108 Samba implementation for your Unix/Linux system. The
109 <filename>pam_smbpass.so</filename> module is provided by
110 Samba version 2.2.1 or later. It can be compiled by specifying the
111 <option>--with-pam_smbpass</option> options when running Samba's
112 <command>configure</command> script. For more information
113 on the <filename>pam_smbpass</filename> module, see the documentation
114 in the <filename>source/pam_smbpass</filename> directory of the Samba
118 <para><programlisting>
120 # The PAM configuration file for the `login' service
122 auth required pam_smbpass.so nodelay
123 account required pam_smbpass.so nodelay
124 session required pam_smbpass.so nodelay
125 password required pam_smbpass.so nodelay
126 </programlisting></para>
129 The following is the PAM configuration file for a particular
130 Linux system. The default condition uses <filename>pam_pwdb.so</filename>.
133 <para><programlisting>
135 # The PAM configuration file for the `samba' service
137 auth required pam_pwdb.so nullok nodelay shadow audit
138 account required pam_pwdb.so audit nodelay
139 session required pam_pwdb.so nodelay
140 password required pam_pwdb.so shadow md5
141 </programlisting></para>
144 In the following example the decision has been made to use the
145 smbpasswd database even for basic samba authentication. Such a
146 decision could also be made for the passwd program and would
147 thus allow the smbpasswd passwords to be changed using the passwd
151 <para><programlisting>
153 # The PAM configuration file for the `samba' service
155 auth required pam_smbpass.so nodelay
156 account required pam_pwdb.so audit nodelay
157 session required pam_pwdb.so nodelay
158 password required pam_smbpass.so nodelay smbconf=/etc/samba.d/smb.conf
159 </programlisting></para>
161 <note><para>PAM allows stacking of authentication mechanisms. It is
162 also possible to pass information obtained within one PAM module through
163 to the next module in the PAM stack. Please refer to the documentation for
164 your particular system implementation for details regarding the specific
165 capabilities of PAM in this environment. Some Linux implmentations also
166 provide the <filename>pam_stack.so</filename> module that allows all
167 authentication to be configured in a single central file. The
168 <filename>pam_stack.so</filename> method has some very devoted followers
169 on the basis that it allows for easier administration. As with all issues in
170 life though, every decision makes trade-offs, so you may want examine the
171 PAM documentation for further helpful information.
175 <title>PAM Configuration in smb.conf</title>
178 There is an option in smb.conf called <ulink
179 url="smb.conf.5.html#OBEYPAMRESTRICTIONS">obey pam restrictions</ulink>.
180 The following is from the on-line help for this option in SWAT;
184 When Samba is configured to enable PAM support (i.e.
185 <option>--with-pam</option>), this parameter will
186 control whether or not Samba should obey PAM's account
187 and session management directives. The default behavior
188 is to use PAM for clear text authentication only and to
189 ignore any account or session management. Note that Samba always
190 ignores PAM for authentication in the case of
191 <ulink url="smb.conf.5.html#ENCRYPTPASSWORDS">encrypt passwords = yes</ulink>.
192 The reason is that PAM modules cannot support the challenge/response
193 authentication mechanism needed in the presence of SMB
197 <para>Default: <parameter>obey pam restrictions = no</parameter></para>
202 <title>Password Synchronisation using pam_smbpass.so</title>
205 pam_smbpass is a PAM module which can be used on conforming systems to
206 keep the smbpasswd (Samba password) database in sync with the unix
207 password file. PAM (Pluggable Authentication Modules) is an API supported
208 under some Unices, such as Solaris, HPUX and Linux, that provides a
209 generic interface to authentication mechanisms.
213 For more information on PAM, see <ulink url="http://ftp.kernel.org/pub/linux/libs/pam/">The linux PAM homepage</ulink>.
217 This module authenticates a local smbpasswd user database. If you require
218 support for authenticating against a remote SMB server, or if you're
219 concerned about the presence of suid root binaries on your system, it is
220 recommended that you use pam_winbind instead.
224 Options recognized by this module are as follows:
226 <tgroup cols="2" align="left">
228 <row><entry>debug</entry><entry>log more debugging info</entry></row>
229 <row><entry>audit</entry><entry>like debug, but also logs unknown usernames</entry></row>
230 <row><entry>use_first_pass</entry><entry>don't prompt the user for passwords; take them from PAM_ items instead</entry></row>
231 <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>
232 <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>
233 <row><entry>not_set_pass</entry><entry>don't make passwords used by this module available to other modules.</entry></row>
234 <row><entry>nodelay</entry><entry>don't insert ~1 second delays on authentication failure.</entry></row>
235 <row><entry>nullok</entry><entry>null passwords are allowed.</entry></row>
236 <row><entry>nonull</entry><entry>null passwords are not allowed. Used to override the Samba configuration.</entry></row>
237 <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>
238 <row><entry>smbconf=<replaceable>file</replaceable></entry><entry>specify an alternate path to the &smb.conf; file.</entry></row>
245 Thanks go to the following people:
247 <member><ulink url="mailto:morgan@transmeta.com">Andrew Morgan</ulink>, for providing the Linux-PAM
248 framework, without which none of this would have happened</member>
250 <member><ulink url="gafton@redhat.com">Christian Gafton</ulink> and Andrew Morgan again, for the
251 pam_pwdb module upon which pam_smbpass was originally based</member>
253 <member><ulink url="lkcl@switchboard.net">Luke Leighton</ulink> for being receptive to the idea,
254 and for the occasional good-natured complaint about the project's status
255 that keep me working on it :)</member>
260 The following are examples of the use of pam_smbpass.so in the format of Linux
261 <filename>/etc/pam.d/</filename> files structure. Those wishing to implement this
262 tool on other platforms will need to adapt this appropriately.
266 <title>Password Synchonisation Configuration</title>
269 A sample PAM configuration that shows the use of pam_smbpass to make
270 sure private/smbpasswd is kept in sync when /etc/passwd (/etc/shadow)
271 is changed. Useful when an expired password might be changed by an
272 application (such as ssh).
275 <para><programlisting>
279 auth requisite pam_nologin.so
280 auth required pam_unix.so
281 account required pam_unix.so
282 password requisite pam_cracklib.so retry=3
283 password requisite pam_unix.so shadow md5 use_authtok try_first_pass
284 password required pam_smbpass.so nullok use_authtok try_first_pass
285 session required pam_unix.so
286 </programlisting></para>
290 <title>Password Migration Configuration</title>
293 A sample PAM configuration that shows the use of pam_smbpass to migrate
294 from plaintext to encrypted passwords for Samba. Unlike other methods,
295 this can be used for users who have never connected to Samba shares:
296 password migration takes place when users ftp in, login using ssh, pop
300 <para><programlisting>
304 auth requisite pam_nologin.so
305 # pam_smbpass is called IFF pam_unix succeeds.
306 auth requisite pam_unix.so
307 auth optional pam_smbpass.so migrate
308 account required pam_unix.so
309 password requisite pam_cracklib.so retry=3
310 password requisite pam_unix.so shadow md5 use_authtok try_first_pass
311 password optional pam_smbpass.so nullok use_authtok try_first_pass
312 session required pam_unix.so
313 </programlisting></para>
317 <title>Mature Password Configuration</title>
320 A sample PAM configuration for a 'mature' smbpasswd installation.
321 private/smbpasswd is fully populated, and we consider it an error if
322 the smbpasswd doesn't exist or doesn't match the Unix password.
325 <para><programlisting>
329 auth requisite pam_nologin.so
330 auth required pam_unix.so
331 account required pam_unix.so
332 password requisite pam_cracklib.so retry=3
333 password requisite pam_unix.so shadow md5 use_authtok try_first_pass
334 password required pam_smbpass.so use_authtok use_first_pass
335 session required pam_unix.so
336 </programlisting></para>
340 <title>Kerberos Password Integration Configuration</title>
343 A sample PAM configuration that shows pam_smbpass used together with
344 pam_krb5. This could be useful on a Samba PDC that is also a member of
348 <para><programlisting>
352 auth requisite pam_nologin.so
353 auth requisite pam_krb5.so
354 auth optional pam_smbpass.so migrate
355 account required pam_krb5.so
356 password requisite pam_cracklib.so retry=3
357 password optional pam_smbpass.so nullok use_authtok try_first_pass
358 password required pam_krb5.so use_authtok try_first_pass
359 session required pam_krb5.so
360 </programlisting></para>
367 <title>Distributed Authentication</title>
370 The astute administrator will realize from this that the
371 combination of <filename>pam_smbpass.so</filename>,
372 <command>winbindd</command>, and a distributed
373 passdb backend, such as ldap, will allow the establishment of a
374 centrally managed, distributed
375 user/password database that can also be used by all
376 PAM (eg: Linux) aware programs and applications. This arrangement
377 can have particularly potent advantages compared with the
378 use of Microsoft Active Directory Service (ADS) in so far as
379 reduction of wide area network authentication traffic.