Debian Codegraph @

upstream/opensuse-tumbleweed/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: 05/26/2026
6 .\" Manual: Linux-PAM Manual
7 .\" Source: Linux-PAM
8 .\" Language: English
9 .\"
10 .TH "PAM_UNIX" "8" "05/26/2026" "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 no_pass_expiry
223 .RS 4
224 When set ignore password expiration as defined by the
225 \fIshadow\fR
226 entry of the user\&. The option has an effect only in case
227 \fIpam_unix\fR
228 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
229 \fIsshd\fR\&. The module will return
230 \fBPAM_SUCCESS\fR
231 instead of eventual
232 \fBPAM_NEW_AUTHTOK_REQD\fR
233 or
234 \fBPAM_AUTHTOK_EXPIRED\fR\&.
235 .RE
236 .PP
237 Invalid arguments are logged with
238 \fBsyslog\fR(3)\&.
239 .SH "MODULE TYPES PROVIDED"
240 .PP
241 All module types (\fBaccount\fR,
242 \fBauth\fR,
243 \fBpassword\fR
244 and
245 \fBsession\fR) are provided\&.
246 .SH "RETURN VALUES"
247 .PP
248 PAM_IGNORE
249 .RS 4
250 Ignore this module\&.
251 .RE
252 .SH "EXAMPLES"
253 .PP
254 An example usage for
255 /etc/pam\&.d/login
256 would be:
257 .sp
258 .if n \{\
259 .RS 4
260 .\}
261 .nf
262 # Authenticate the user
263 auth required pam_unix\&.so
264 # Ensure user\*(Aqs account and password are still active
265 account required pam_unix\&.so
266 # Change the user\*(Aqs password, but at first check the strength
267 # with pam_passwdqc(8)
268 password required pam_passwdqc\&.so config=/etc/passwdqc\&.conf
269 password required pam_unix\&.so use_authtok nullok yescrypt
270 session required pam_unix\&.so
271
272 .fi
273 .if n \{\
274 .RE
275 .\}
276 .sp
277 .SH "SEE ALSO"
278 .PP
279 \fBlogin.defs\fR(5),
280 \fBpam.conf\fR(5),
281 \fBpam.d\fR(5),
282 \fBpam\fR(8)
283 .SH "AUTHOR"
284 .PP
285 pam_unix was written by various people\&.