source: postlfs/security/linux-pam.xml

trunk
Last change on this file was 3dcc5df, checked in by Thomas Trepl <thomas@…>, 7 days ago

Upgrade Linux-PAM-1.6.1

  • Property mode set to 100644
File size: 19.2 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY linux-pam-download-http "https://github.com/linux-pam/linux-pam/releases/download/v&linux-pam-version;/Linux-PAM-&linux-pam-version;.tar.xz">
8 <!ENTITY linux-pam-download-ftp " ">
9 <!ENTITY linux-pam-md5sum "8ad1e72d1ff6480d8e0af658e2d7b768">
10 <!ENTITY linux-pam-size "1.0 MB">
11 <!ENTITY linux-pam-buildsize "39 MB (with tests)">
12 <!ENTITY linux-pam-time "0.4 SBU (with tests)">
13
14 <!ENTITY linux-pam-docs-download "https://github.com/linux-pam/linux-pam/releases/download/v&linux-pam-version;/Linux-PAM-&linux-pam-docs-version;-docs.tar.xz">
15 <!ENTITY linux-pam-docs-md5sum "46dc9f9a27ef73a2fbe3b667877e88da">
16 <!ENTITY linux-pam-docs-size "455 KB">
17 <!--
18 <!ENTITY debian-pam-docs "http://debian.securedservers.com/kernel/pub/linux/libs/pam">
19 -->
20]>
21
22<sect1 id="linux-pam" xreflabel="Linux-PAM-&linux-pam-version;">
23 <?dbhtml filename="linux-pam.html"?>
24
25
26 <title>Linux-PAM-&linux-pam-version;</title>
27
28 <indexterm zone="linux-pam">
29 <primary sortas="a-Linux-PAM">Linux-PAM</primary>
30 </indexterm>
31
32 <sect2 role="package">
33 <title>Introduction to Linux PAM</title>
34
35 <para>
36 The <application>Linux PAM</application> package contains
37 Pluggable Authentication Modules used by the local
38 system administrator to control how application programs authenticate
39 users.
40 </para>
41
42 &lfs121_checked;
43
44 <bridgehead renderas="sect3">Package Information</bridgehead>
45 <itemizedlist spacing="compact">
46 <listitem>
47 <para>
48 Download (HTTP): <ulink url="&linux-pam-download-http;"/>
49 </para>
50 </listitem>
51 <listitem>
52 <para>
53 Download (FTP): <ulink url="&linux-pam-download-ftp;"/>
54 </para>
55 </listitem>
56 <listitem>
57 <para>
58 Download MD5 sum: &linux-pam-md5sum;
59 </para>
60 </listitem>
61 <listitem>
62 <para>
63 Download size: &linux-pam-size;
64 </para>
65 </listitem>
66 <listitem>
67 <para>
68 Estimated disk space required: &linux-pam-buildsize;
69 </para>
70 </listitem>
71 <listitem>
72 <para>
73 Estimated build time: &linux-pam-time;
74 </para>
75 </listitem>
76 </itemizedlist>
77
78 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
79 <itemizedlist spacing="compact">
80 <title>Optional Documentation</title>
81 <listitem>
82 <para>
83 Download (HTTP): <ulink url="&linux-pam-docs-download;"/>
84 </para>
85 </listitem>
86 <listitem>
87 <para>
88 Download MD5 sum: &linux-pam-docs-md5sum;
89 </para>
90 </listitem>
91 <listitem>
92 <para>
93 Download size: &linux-pam-docs-size;
94 </para>
95 </listitem>
96 </itemizedlist>
97
98 <bridgehead renderas="sect3">Linux PAM Dependencies</bridgehead>
99
100 <bridgehead renderas="sect4">Optional</bridgehead>
101 <para role="optional">
102 <xref linkend="libnsl"/>,
103 <xref linkend="libtirpc"/>,
104 <xref linkend="rpcsvc-proto"/>,
105 &berkeley-db;,
106 <ulink url="https://github.com/linux-audit/audit-userspace">libaudit</ulink>,
107 <ulink url="https://github.com/openSUSE/libeconf">libeconf</ulink>, and
108 <ulink url="https://www.prelude-siem.org">Prelude</ulink>
109 </para>
110<!-- With 1.5.3, building the doc requires the namespaced version of
111 docbook-xsl, which is beyond BLFS.
112
113 <bridgehead renderas="sect4">Optional (To Rebuild the Documentation)</bridgehead>
114 <para role="optional">
115 <xref linkend="DocBook"/>,
116 <xref linkend="docbook-xsl"/>,
117 <xref linkend="fop"/>,
118 <xref linkend="libxslt"/> and either
119 <xref linkend="lynx"/> or
120 <ulink url="&w3m-url;">W3m</ulink>
121 </para>
122-->
123 <note>
124 <para role="required">
125 <xref role="runtime" linkend="shadow"/>
126 <phrase revision="systemd"> and <xref role="runtime" linkend="systemd"/>
127 must</phrase><phrase revision="sysv">must</phrase> be reinstalled
128 and reconfigured
129 after installing and configuring <application>Linux PAM</application>.
130 </para>
131
132 <para role="recommended">
133 With Linux-PAM-1.4.0 and higher, the pam_cracklib module is not
134 installed by default. Use <xref role="runtime" linkend="libpwquality"/>
135 to enforce strong passwords.
136 </para>
137 </note>
138
139 </sect2>
140
141 <sect2 role="kernel" id="linux-pam-kernel">
142 <title>Kernel Configuration</title>
143
144 <para>
145 For the PAM module <filename
146 class='libraryfile'>pam_loginuid.so</filename> (referred by
147 the PAM configuration file <filename>system-session</filename> if
148 <phrase revision='sysv'><xref linkend='elogind'/> is
149 built</phrase><phrase revision='systemd'><xref linkend='systemd'/> is
150 rebuilt with PAM support</phrase> later) to work,
151 a kernel configuration parameter need to be set or the module will
152 just do nothing:
153 </para>
154
155 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
156 href="linux-pam-kernel.xml"/>
157
158 <indexterm zone="linux-pam linux-pam-kernel">
159 <primary sortas="d-linux-pam">Linux-PAM</primary>
160 </indexterm>
161
162 </sect2>
163
164 <sect2 role="installation">
165 <title>Installation of Linux PAM</title>
166
167 <para revision="sysv">
168 First, prevent the installation of an unneeded systemd file:
169 </para>
170
171<screen revision="sysv"><userinput>sed -e /service_DATA/d \
172 -i modules/pam_namespace/Makefile.am &amp;&amp;
173autoreconf</userinput></screen>
174
175 <para>
176 If you downloaded the documentation, unpack the tarball by issuing
177 the following command.
178 </para>
179
180<screen><userinput>tar -xf ../Linux-PAM-&linux-pam-docs-version;-docs.tar.xz --strip-components=1</userinput></screen>
181<!--
182 <para>
183 If you want to regenerate the documentation yourself, fix the
184 <command>configure</command> script so it will detect lynx:
185 </para>
186
187<screen><userinput>sed -e 's/dummy elinks/dummy lynx/' \
188 -e 's/-no-numbering -no-references/-force-html -nonumbers -stdin/' \
189 -i configure</userinput></screen>
190-->
191 <para>
192 Compile and link <application>Linux PAM</application> by
193 running the following commands:
194 </para>
195
196<screen><userinput>./configure --prefix=/usr \
197 --sbindir=/usr/sbin \
198 --sysconfdir=/etc \
199 --libdir=/usr/lib \
200 --enable-securedir=/usr/lib/security \
201 --docdir=/usr/share/doc/Linux-PAM-&linux-pam-version; &amp;&amp;
202make</userinput></screen>
203
204 <para>
205 To test the results, a suitable <filename>/etc/pam.d/other</filename>
206 configuration file must exist.
207 </para>
208
209 <caution>
210 <title>Reinstallation or Upgrade of Linux PAM</title>
211 <para>
212 If you have a system with Linux PAM installed and working, be careful
213 when modifying the files in
214 <filename class="directory">/etc/pam.d</filename>, since your system
215 may become totally unusable. If you want to run the tests, you do not
216 need to create another <filename>/etc/pam.d/other</filename> file. The
217 existing file can be used for the tests.
218 </para>
219
220 <para>
221 You should also be aware that <command>make install</command>
222 overwrites the configuration files in
223 <filename class="directory">/etc/security</filename> as well as
224 <filename>/etc/environment</filename>. If you
225 have modified those files, be sure to back them up.
226 </para>
227 </caution>
228
229 <para>
230 For a first-time installation, create a configuration file by issuing the
231 following commands as the <systemitem class="username">root</systemitem>
232 user:
233 </para>
234
235<screen role="root"><userinput>install -v -m755 -d /etc/pam.d &amp;&amp;
236
237cat &gt; /etc/pam.d/other &lt;&lt; "EOF"
238<literal>auth required pam_deny.so
239account required pam_deny.so
240password required pam_deny.so
241session required pam_deny.so</literal>
242EOF</userinput></screen>
243
244 <para>
245 Now run the tests by issuing <command>make check</command>.
246 Be sure the tests produced no errors before continuing the
247 installation. Note that the tests are very long.
248 Redirect the output to a log file, so you can inspect it thoroughly.
249 </para>
250
251 <para>
252 For a first-time installation, remove the configuration file
253 created earlier by issuing the following command as the
254 <systemitem class="username">root</systemitem> user:
255 </para>
256
257<screen role="root"><userinput>rm -fv /etc/pam.d/other</userinput></screen>
258
259 <para>
260 Now, as the <systemitem class="username">root</systemitem>
261 user:
262 </para>
263
264<screen role="root"><userinput>make install &amp;&amp;
265chmod -v 4755 /usr/sbin/unix_chkpwd</userinput></screen>
266
267 </sect2>
268
269 <sect2 role="commands">
270 <title>Command Explanations</title>
271
272 <para>
273 <parameter>--enable-securedir=/usr/lib/security</parameter>:
274 This switch sets the installation location for the
275 <application>PAM</application> modules.
276 </para>
277<!--
278 <para>
279 <option>- -disable-regenerate-docu</option> : If the needed dependencies
280 (<xref linkend="DocBook"/>, <xref linkend="docbook-xsl"/>, <xref
281 linkend="libxslt"/>, and <xref linkend="lynx"/> or <ulink
282 url="&w3m-url;">W3m</ulink>) are installed, the manual pages, and the
283 html and text documentation files, are generated and installed.
284 Furthermore, if <xref linkend="fop"/> is installed, the PDF
285 documentation is generated and installed. Use this switch if you do not
286 want to rebuild the documentation.
287 </para>
288-->
289 <para>
290 <command>chmod -v 4755 /usr/sbin/unix_chkpwd</command>:
291 The setuid bit for the <command>unix_chkpwd</command> helper program must be
292 turned on, so that non-<systemitem class="username">root</systemitem>
293 processes can access the shadow file.
294 </para>
295
296 </sect2>
297
298 <sect2 role="configuration">
299 <title>Configuring Linux-PAM</title>
300
301 <sect3 id="pam-config">
302 <title>Configuration Files</title>
303
304 <para>
305 <filename>/etc/security/*</filename> and
306 <filename>/etc/pam.d/*</filename>
307 </para>
308
309 <indexterm zone="linux-pam pam-config">
310 <primary sortas="e-etc-security">/etc/security/*</primary>
311 </indexterm>
312
313 <indexterm zone="linux-pam pam-config">
314 <primary sortas="e-etc-pam.d">/etc/pam.d/*</primary>
315 </indexterm>
316
317 </sect3>
318
319 <sect3>
320 <title>Configuration Information</title>
321
322 <para>
323 Configuration information is placed in
324 <filename class="directory">/etc/pam.d/</filename>.
325 Here is a sample file:
326 </para>
327
328<screen><literal># Begin /etc/pam.d/other
329
330auth required pam_unix.so nullok
331account required pam_unix.so
332session required pam_unix.so
333password required pam_unix.so nullok
334
335# End /etc/pam.d/other</literal></screen>
336
337 <para>
338 Now create some generic configuration files. As the
339 <systemitem class="username">root</systemitem> user:
340 </para>
341
342<screen role="root"><userinput>install -vdm755 /etc/pam.d &amp;&amp;
343cat &gt; /etc/pam.d/system-account &lt;&lt; "EOF" &amp;&amp;
344<literal># Begin /etc/pam.d/system-account
345
346account required pam_unix.so
347
348# End /etc/pam.d/system-account</literal>
349EOF
350
351cat &gt; /etc/pam.d/system-auth &lt;&lt; "EOF" &amp;&amp;
352<literal># Begin /etc/pam.d/system-auth
353
354auth required pam_unix.so
355
356# End /etc/pam.d/system-auth</literal>
357EOF
358
359cat &gt; /etc/pam.d/system-session &lt;&lt; "EOF" &amp;&amp;
360<literal># Begin /etc/pam.d/system-session
361
362session required pam_unix.so
363
364# End /etc/pam.d/system-session</literal>
365EOF
366
367cat &gt; /etc/pam.d/system-password &lt;&lt; "EOF"
368<literal># Begin /etc/pam.d/system-password
369
370# use yescrypt hash for encryption, use shadow, and try to use any
371# previously defined authentication token (chosen password) set by any
372# prior module.
373password required pam_unix.so yescrypt shadow try_first_pass
374
375# End /etc/pam.d/system-password</literal>
376EOF
377</userinput></screen>
378
379 <para>
380 If you wish to enable strong password support, install
381 <xref linkend="libpwquality"/>, and follow the
382 instructions on that page to configure the pam_pwquality
383 PAM module with strong password support.
384 </para>
385
386 <para>
387 Next, add a restrictive <filename>/etc/pam.d/other</filename>
388 configuration file. With this file, programs that are PAM aware will
389 not run unless a configuration file specifically for that application
390 exists.
391 </para>
392
393<screen role="root"><userinput>cat &gt; /etc/pam.d/other &lt;&lt; "EOF"
394<literal># Begin /etc/pam.d/other
395
396auth required pam_warn.so
397auth required pam_deny.so
398account required pam_warn.so
399account required pam_deny.so
400password required pam_warn.so
401password required pam_deny.so
402session required pam_warn.so
403session required pam_deny.so
404
405# End /etc/pam.d/other</literal>
406EOF</userinput></screen>
407
408 <para>
409 The <application>PAM</application> man page (<command>man
410 pam</command>) provides a good starting point to learn
411 about the several fields, and allowable entries.
412 <!-- not accessible 2022-09-08 -->
413 <!-- it's available at a different address 2022-10-23-->
414 The
415 <ulink url="https://www.docs4dev.com/docs/en/linux-pam/1.1.2/reference/Linux-PAM_SAG.html">
416 Linux-PAM System Administrators' Guide
417 </ulink> is recommended for additional information.
418 </para>
419
420 <important>
421 <para>
422 You should now reinstall the <xref linkend="shadow"/>
423 <phrase revision="sysv">package</phrase>
424 <phrase revision="systemd"> and <xref linkend="systemd"/>
425 packages</phrase>.
426 </para>
427 </important>
428
429 </sect3>
430
431 </sect2>
432
433 <sect2 role="content">
434 <title>Contents</title>
435
436 <segmentedlist>
437 <segtitle>Installed Program</segtitle>
438 <segtitle>Installed Libraries</segtitle>
439 <segtitle>Installed Directories</segtitle>
440
441 <seglistitem>
442 <seg>
443 faillock, mkhomedir_helper, pam_namespace_helper,
444 pam_timestamp_check, pwhistory_helper, unix_chkpwd and
445 unix_update
446 </seg>
447 <seg>
448 libpam.so, libpamc.so and libpam_misc.so
449 </seg>
450 <seg>
451 /etc/security,
452 /usr/lib/security,
453 /usr/include/security and
454 /usr/share/doc/Linux-PAM-&linux-pam-version;
455 </seg>
456 </seglistitem>
457 </segmentedlist>
458
459 <variablelist>
460 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
461 <?dbfo list-presentation="list"?>
462 <?dbhtml list-presentation="table"?>
463
464 <varlistentry id="faillock">
465 <term><command>faillock</command></term>
466 <listitem>
467 <para>
468 displays and modifies the authentication failure record files
469 </para>
470 <indexterm zone="linux-pam faillock">
471 <primary sortas="b-faillock">faillock</primary>
472 </indexterm>
473 </listitem>
474 </varlistentry>
475
476 <varlistentry id="mkhomedir_helper">
477 <term><command>mkhomedir_helper</command></term>
478 <listitem>
479 <para>
480 is a helper binary that creates home directories
481 </para>
482 <indexterm zone="linux-pam mkhomedir_helper">
483 <primary sortas="b-mkhomedir_helper">mkhomedir_helper</primary>
484 </indexterm>
485 </listitem>
486 </varlistentry>
487
488 <varlistentry id="pam_namespace_helper">
489 <term><command>pam_namespace_helper</command></term>
490 <listitem>
491 <para>
492 is a helper program used to configure a private namespace for a
493 user session
494 </para>
495 <indexterm zone="linux-pam pam_namespace_helper">
496 <primary sortas="b-pam_namespace_helper">pam_namespace_helper</primary>
497 </indexterm>
498 </listitem>
499 </varlistentry>
500
501 <varlistentry id="pwhistory_helper">
502 <term><command>pwhistory_helper</command></term>
503 <listitem>
504 <para>
505 is a helper program that transfers password hashes from passwd or
506 shadow to opasswd
507 </para>
508 <indexterm zone="linux-pam pwhistory_helper">
509 <primary sortas="b-pwhistory_helper">pwhistory_helper</primary>
510 </indexterm>
511 </listitem>
512 </varlistentry>
513<!-- Removed with the removal of the pam_tally{,2} module
514 <varlistentry id="pam_tally">
515 <term><command>pam_tally</command></term>
516 <listitem>
517 <para>
518 is used to interrogate and manipulate the login counter file.
519 </para>
520 <indexterm zone="linux-pam pam_tally">
521 <primary sortas="b-pam_tally">pam_tally</primary>
522 </indexterm>
523 </listitem>
524 </varlistentry>
525
526 <varlistentry id="pam_tally2">
527 <term><command>pam_tally2</command></term>
528 <listitem>
529 <para>
530 is used to interrogate and manipulate the login counter file, but
531 does not have some limitations that <command>pam_tally</command>
532 does.
533 </para>
534 <indexterm zone="linux-pam pam_tally2">
535 <primary sortas="b-pam_tally2">pam_tally2</primary>
536 </indexterm>
537 </listitem>
538 </varlistentry>
539-->
540
541 <varlistentry id="pam_timestamp_check">
542 <term><command>pam_timestamp_check</command></term>
543 <listitem>
544 <para>
545 is used to check if the default timestamp is valid
546 </para>
547 <indexterm zone="linux-pam pam_timestamp_check">
548 <primary sortas="b-pam_timestamp_check">pam_timestamp_check</primary>
549 </indexterm>
550 </listitem>
551 </varlistentry>
552
553 <varlistentry id="unix_chkpwd">
554 <term><command>unix_chkpwd</command></term>
555 <listitem>
556 <para>
557 is a helper binary that verifies the password of the current user
558 </para>
559 <indexterm zone="linux-pam unix_chkpwd">
560 <primary sortas="b-unix_chkpwd">unix_chkpwd</primary>
561 </indexterm>
562 </listitem>
563 </varlistentry>
564
565 <varlistentry id="unix_update">
566 <term><command>unix_update</command></term>
567 <listitem>
568 <para>
569 is a helper binary that updates the password of a given user
570 </para>
571 <indexterm zone="linux-pam unix_update">
572 <primary sortas="b-unix_update">unix_update</primary>
573 </indexterm>
574 </listitem>
575 </varlistentry>
576
577 <varlistentry id="libpam">
578 <term><filename class="libraryfile">libpam.so</filename></term>
579 <listitem>
580 <para>
581 provides the interfaces between applications and the
582 PAM modules
583 </para>
584 <indexterm zone="linux-pam libpam">
585 <primary sortas="c-libpam">libpam.so</primary>
586 </indexterm>
587 </listitem>
588 </varlistentry>
589
590 </variablelist>
591
592 </sect2>
593
594</sect1>
Note: See TracBrowser for help on using the repository browser.