Debian Codegraph @

upstream/debian-unstable/man8/pam_unix.8

raw
1 '\" t
2 .\" Title: pam_unix
3 .\" Author: [see the "AUTHOR" section]
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 06/29/2025
6 .\" Manual: Linux-PAM Manual
7 .\" Source: Linux-PAM
8 .\" Language: English
9 .\"
10 .TH "PAM_UNIX" "8" "06/29/2025" "Linux\-PAM" "Linux\-PAM Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 pam_unix \- Module for traditional password authentication
32 .SH "SYNOPSIS"
33 .HP \w'\fBpam_unix\&.so\fR\ 'u
34 \fBpam_unix\&.so\fR [\&.\&.\&.]
35 .SH "DESCRIPTION"
36 .PP
37 This is the standard Unix authentication module\&. It uses standard calls from the system\*(Aqs libraries to retrieve and set account information as well as authentication\&. Usually this is obtained from the /etc/passwd and the /etc/shadow file as well if shadow is enabled\&.
38 .PP
39 The account component performs the task of establishing the status of the user\*(Aqs account and password based on the following
40 \fIshadow\fR
41 elements: expire, last_change, max_change, min_change, warn_change\&. In the case of the latter, it may offer advice to the user on changing their password or, through the
42 \fBPAM_AUTHTOKEN_REQD\fR
43 return, delay giving service to the user until they have established a new password\&. The entries listed above are documented in the
44 \fBshadow\fR(5)
45 manual page\&. Should the user\*(Aqs record not contain one or more of these entries, the corresponding
46 \fIshadow\fR
47 check is not performed\&.
48 .PP
49 The authentication component performs the task of checking the users credentials (password)\&. The default action of this module is to not permit the user access to a service if their official password is blank\&.
50 .PP
51 A helper binary,
52 \fBunix_chkpwd\fR(8), is provided to check the user\*(Aqs password when it is stored in a read protected database\&. This binary is very simple and will only check the password of the user invoking it\&. It is called transparently on behalf of the user by the authenticating component of this module\&. In this way it is possible for applications like
53 \fBxlock\fR(1)
54 to work without being setuid\-root\&. The module, by default, will temporarily turn off SIGCHLD handling for the duration of execution of the helper binary\&. This is generally the right thing to do, as many applications are not prepared to handle this signal from a child they didn\*(Aqt know was
55 \fBfork()\fRd\&. The
56 \fBnoreap\fR
57 module argument can be used to suppress this temporary shielding and may be needed for use with certain applications\&.
58 .PP
59 The maximum length of a password supported by the pam_unix module via the helper binary is
60 \fIPAM_MAX_RESP_SIZE\fR
61 \- currently 512 bytes\&. The rest of the password provided by the conversation function to the module will be ignored\&.
62 .PP
63 The password component of this module performs the task of updating the user\*(Aqs password\&. The default encryption hash is taken from the
64 \fBENCRYPT_METHOD\fR
65 variable from
66 \fI/etc/login\&.defs\fR
67 .PP
68 The session component of this module logs when a user logins or leave the system\&.
69 .PP
70 Remaining arguments, supported by others functions of this module, are silently ignored\&. Other arguments are logged as errors through
71 \fBsyslog\fR(3)\&.
72 .SH "OPTIONS"
73 .PP
74 debug
75 .RS 4
76 Turns on debugging via
77 \fBsyslog\fR(3)\&.
78 .RE
79 .PP
80 audit
81 .RS 4
82 A little more extreme than debug\&.
83 .RE
84 .PP
85 quiet
86 .RS 4
87 Turns off informational messages namely messages about session open and close via
88 \fBsyslog\fR(3)\&.
89 .RE
90 .PP
91 nullok
92 .RS 4
93 The default action of this module is to not permit the user access to a service if their official password is blank\&. The
94 \fBnullok\fR
95 argument overrides this default\&.
96 .RE
97 .PP
98 nullresetok
99 .RS 4
100 Allow users to authenticate with blank password if password reset is enforced even if
101 \fBnullok\fR
102 is not set\&. If password reset is not required and
103 \fBnullok\fR
104 is not set the authentication with blank password will be denied\&.
105 .RE
106 .PP
107 try_first_pass
108 .RS 4
109 Before prompting the user for their password, the module first tries the previous stacked module\*(Aqs password in case that satisfies this module as well\&.
110 .RE
111 .PP
112 use_first_pass
113 .RS 4
114 The argument
115 \fBuse_first_pass\fR
116 forces the module to use a previous stacked modules password and will never prompt the user \- if no password is available or the password is not appropriate, the user will be denied access\&.
117 .RE
118 .PP
119 nodelay
120 .RS 4
121 This argument can be used to discourage the authentication component from requesting a delay should the authentication as a whole fail\&. The default action is for the module to request a delay\-on\-failure of the order of two seconds\&.
122 .RE
123 .PP
124 use_authtok
125 .RS 4
126 When password changing enforce the module to set the new password to the one provided by a previously stacked
127 \fBpassword\fR
128 module (this is used in the example of the stacking of the
129 \fBpam_passwdqc\fR
130 module documented below)\&.
131 .RE
132 .PP
133 authtok_type=type
134 .RS 4
135 This argument can be used to modify the password prompt when changing passwords to include the type of the password\&. Empty by default\&.
136 .RE
137 .PP
138 nis
139 .RS 4
140 NIS RPC is used for setting new passwords\&.
141 .RE
142 .PP
143 remember=n
144 .RS 4
145 The last
146 \fIn\fR
147 passwords for each user are saved in
148 /etc/security/opasswd
149 in order to force password change history and keep the user from alternating between the same password too frequently\&. The MD5 password hash algorithm is used for storing the old passwords\&. Instead of this option the
150 \fBpam_pwhistory\fR
151 module should be used\&.
152 .RE
153 .PP
154 shadow
155 .RS 4
156 Try to maintain a shadow based system\&.
157 .RE
158 .PP
159 md5
160 .RS 4
161 When a user changes their password next, encrypt it with the MD5 algorithm\&.
162 .RE
163 .PP
164 bigcrypt
165 .RS 4
166 When a user changes their password next, encrypt it with the DEC C2 algorithm\&.
167 .RE
168 .PP
169 sha256
170 .RS 4
171 When a user changes their password next, encrypt it with the SHA256 algorithm\&. The SHA256 algorithm must be supported by the
172 \fBcrypt\fR(3)
173 function\&.
174 .RE
175 .PP
176 sha512
177 .RS 4
178 When a user changes their password next, encrypt it with the SHA512 algorithm\&. The SHA512 algorithm must be supported by the
179 \fBcrypt\fR(3)
180 function\&.
181 .RE
182 .PP
183 blowfish
184 .RS 4
185 When a user changes their password next, encrypt it with the blowfish algorithm\&. The blowfish algorithm must be supported by the
186 \fBcrypt\fR(3)
187 function\&.
188 .RE
189 .PP
190 gost_yescrypt
191 .RS 4
192 When a user changes their password next, encrypt it with the gost\-yescrypt algorithm\&. The gost\-yescrypt algorithm must be supported by the
193 \fBcrypt\fR(3)
194 function\&.
195 .RE
196 .PP
197 yescrypt
198 .RS 4
199 When a user changes their password next, encrypt it with the yescrypt algorithm\&. The yescrypt algorithm must be supported by the
200 \fBcrypt\fR(3)
201 function\&.
202 .RE
203 .PP
204 rounds=n
205 .RS 4
206 Set the optional number of rounds of the SHA256, SHA512, blowfish, gost\-yescrypt, and yescrypt password hashing algorithms to
207 \fIn\fR\&.
208 .RE
209 .PP
210 broken_shadow
211 .RS 4
212 Ignore errors reading shadow information for users in the account management module\&.
213 .RE
214 .PP
215 minlen=n
216 .RS 4
217 Set a minimum password length of
218 \fIn\fR
219 characters\&. The max\&. for DES crypt based passwords is 8 characters\&.
220 .RE
221 .PP
222 \fBobscure\fR
223 .RS 4
224 Enable some extra checks on password strength\&. These checks are based on the "obscure" checks in the original shadow package\&. The behavior is similar to the pam_cracklib module, but for non\-dictionary\-based checks\&. The following checks are implemented:
225 .PP
226 \fBPalindrome\fR
227 .RS 4
228 Verifies that the new password is not a palindrome of (i\&.e\&., the reverse of) the previous one\&.
229 .RE
230 .PP
231 \fBCase Change Only\fR
232 .RS 4
233 Verifies that the new password isn\*(Aqt the same as the old one with a change of case\&.
234 .RE
235 .PP
236 \fBSimilar\fR
237 .RS 4
238 Verifies that the new password isn\*(Aqt too much like the previous one\&.
239 .RE
240 .PP
241 \fBSimple\fR
242 .RS 4
243 Is the new password too simple? This is based on the length of the password and the number of different types of characters (alpha, numeric, etc\&.) used\&.
244 .RE
245 .PP
246 \fBRotated\fR
247 .RS 4
248 Is the new password a rotated version of the old password? (E\&.g\&., "billy" and "illyb")
249 .RE
250 .sp
251 .RE
252 .PP
253 no_pass_expiry
254 .RS 4
255 When set ignore password expiration as defined by the
256 \fIshadow\fR
257 entry of the user\&. The option has an effect only in case
258 \fIpam_unix\fR
259 was not used for the authentication or it returned authentication failure meaning that other authentication source or method succeeded\&. The example can be public key authentication in
260 \fIsshd\fR\&. The module will return
261 \fBPAM_SUCCESS\fR
262 instead of eventual
263 \fBPAM_NEW_AUTHTOK_REQD\fR
264 or
265 \fBPAM_AUTHTOK_EXPIRED\fR\&.
266 .RE
267 .PP
268 Invalid arguments are logged with
269 \fBsyslog\fR(3)\&.
270 .SH "MODULE TYPES PROVIDED"
271 .PP
272 All module types (\fBaccount\fR,
273 \fBauth\fR,
274 \fBpassword\fR
275 and
276 \fBsession\fR) are provided\&.
277 .SH "RETURN VALUES"
278 .PP
279 PAM_IGNORE
280 .RS 4
281 Ignore this module\&.
282 .RE
283 .SH "EXAMPLES"
284 .PP
285 An example usage for
286 /etc/pam\&.d/login
287 would be:
288 .sp
289 .if n \{\
290 .RS 4
291 .\}
292 .nf
293 # Authenticate the user
294 auth required pam_unix\&.so
295 # Ensure user\*(Aqs account and password are still active
296 account required pam_unix\&.so
297 # Change the user\*(Aqs password, but at first check the strength
298 # with pam_passwdqc(8)
299 password required pam_passwdqc\&.so config=/etc/passwdqc\&.conf
300 password required pam_unix\&.so use_authtok nullok yescrypt
301 session required pam_unix\&.so
302
303 .fi
304 .if n \{\
305 .RE
306 .\}
307 .sp
308 .SH "SEE ALSO"
309 .PP
310 \fBlogin.defs\fR(5),
311 \fBpam.conf\fR(5),
312 \fBpam.d\fR(5),
313 \fBpam\fR(7)
314 .SH "AUTHOR"
315 .PP
316 pam_unix was written by various people\&.