aboutsummaryrefslogtreecommitdiff
path: root/doc/pam_fshadow.8in
blob: 2e91c10f1b636441c3a7bc3c25339fc47a4652d8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
.\" This file is part of PAM-Modules -*- nroff -*-
.\" Copyright (C) 2001-2022 Sergey Poznyakoff
.\"
.\" PAM-Modules is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" PAM-Modules is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with PAM-Modules.  If not, see <http://www.gnu.org/licenses/>.
.so config.so
.TH PAM_FSHADOW 8 "February 3, 2022" "PAM-MODULES" "Pam-Modules User Reference"
.SH NAME
pam_fshadow \- use alternative passwd and/or shadow files
.SH SYNOPSIS
.nh
.na
\fBpam_fshadow\fR\
 [\fBaudit\fR]\
 [\fBdebug\fR[\fB=\fINUMBER\fR]]\
 [\fBbasic\fR|\fBextended\fR]\
 [\fBdomain\-index=\fIN\fR]\
 [\fBignore\-case\fR|\fBicase\fR|\fBcase\fR]\
 [\fBnopasswd\fR]\
 [\fBnoshadow\fR]\
 [\fBregex=\fIEXPR\fR]\
 [\fBrevert\-index\fR]\
 [\fBskip\-password\fR]\
 [\fBsysconfdir=\fIDIR\fR]\
 [\fBuse_authtok\fR]\
 [\fBusername\-index=\fIN\fR]\
 [\fBwaitdebug\fR]
.ad
.hy
.SH DESCRIPTION
Authenticates the user against alternative \fBpasswd\fR and
\fBshadow\fR files.  There are two operation modes:
\fBplain\fR mode, in which the module uses only
one \fBpasswd\fR,\fBshadow\fR pair, and \fBvirtual domain\fR mode,
which selects the pair to use based depending on the authentication
token (the user name).
.PP
In plain mode, \fBpam_fshadow\fR checks the supplied user name and
authentication token against the \fBpasswd\fR and \fBshadow\fR files
located in the system configuration directory.  The latter is set when
configuring the package and defaults to \fB\*(ET\fR.  Its
location can be changed using the \fBsysconfdir\fR command line
parameter.
.PP
The command line options \fBnopasswd\fR and \fBnoshadow\fR are
provided to disable reading of either file.  E.g. if \fBnoshadow\fR is
given, the module will expect all authentication information to be
stored in the \fBpasswd\fR file.
.PP
The \fBvirtual domain\fR mode selects the \fBpasswd\fR,\fBshadow\fR
pair to use depending on the user name.  To that effect, the user name
is first split into the \fBlocal\fR and \fBauthentication domain\fR
parts using a regular expression supplied with the \fBregex\fR option.
The configuration directory name is then constructed by concatenating the
system configuration directory, a directory separator character (\fB/\fR),
and the name of the authentication domain.   The authentication then
proceeds as described above for the plain mode.  If the supplied user name
does not match the regular expression, \fBpam_fshadow\fR refuses access.
.SH OPTIONS
.TP
\fBbasic\fR
The argument to the \fBregex\fR option is a basic regular expression. 
.TP
\fBextended\fR
The argument to the \fBregex\fR option is a POSIX extended regular
expression.  This is the default.
.TP
\fBignore\-case\fR, \fBicase\fR
Use case-insensitive regex matching.
.TP
Use case-sensitive regex matching (default).
.TP
\fBnopasswd\fR
Use only \fBshadow\fR file for authentication.
.TP
\fBnoshadow\fR
Use only \fBpasswd\fR file for authentication.
.TP
\fBregex=\fIEXPR\fR
Defines a regular expression for splitting user name into the proper
name and authentication domain.  The expression must contain at least two
parentesized groups.  If it matches, the group 1 will be used to
extract local user name and the group 2 will select the authentication
domain.  These default group indices can be changed using the
\fBusername\-index\fR and \fBdomain\-index\fR options.  Additionally the
\fBrevert\-index\fR option swaps the meaning of the two indices.  For example:
.RS
.EX
regex=(.*)@(.*)
.EE
.RE

This regular expression will match user names like \fBsmith@domain\fR.
.TP
.B skip\-password
Disable password verification.  With this flag, the module only checks
whether the user is listed in the password and shadow files and
whether the user's account has not expired.  Use of either file
can be disabled using \fBnopasswd\fR or \fBnoshadow\fR (but not both).
.TP
\fBusername\-index=\fIN\fR
Use \fIN\fRth parenthesized group of the regular expression as the
user name.  Default is 1.
.TP
\fBdomain\-index=\fIN\fR
Use \fIN\fRth parenthesized group of the regular expression as the
group name.  Default is 2.
.TP
\fBrevert\-index\fR
Swap indices of the username and domain part parenthesized groups in
the regexp.
.TP
\fBsysconfdir=\fIDIR\fR
Use \fIDIR\fR as the system configuration directory, instead of the
default \fB\*(ET\fR.
.TP
\fBuse_authtok\fR
Do not prompt the user for password, take it from the saved
authentication tokens.
.TP
\fBdebug\fR\fB=\fINUMBER\fR]
Set debugging level (0 <= \fINUMBER\fR <= 100).
.TP
\fBwaitdebug\fR
Wait for \fIN\fR seconds before starting up.  This option is intended
to facilitate attaching to the module with
.BR gdb (1).
It is available only if the package was configured with
the \fB\-\-enable\-debug\fR option.
.TP
\fBaudit\fR
Log full debugging information (equivalent to \fBdebug=100\fR).
.SH MODULE TYPES PROVIDED
.BR auth ,
.BR session ,
.BR account .
.SH RETURN VALUES
.TP
.B PAM_SUCCESS
Successful return.
.TP
.B PAM_AUTH_ERR
Authentication failed.
.TP
.B PAM_AUTHINFO_UNAVAIL
The input information is not sufficient.
.TP
.B PAM_AUTHTOK_RECOVER_ERR
Failed to obtain stored authentication token.  This code can be
returned if \fBuse_authtok\fR was used.
.TP
.B PAM_SERVICE_ERR
Can't open \fBpasswd\fR or \fBshadow\fR file, or get username or
password.
.TP
.B PAM_USER_UNKNOWN
Supplied username not found.
.TP
.B PAM_SYSTEM_ERR
Out of memory.
.SH EXAMPLES
.nr step 1 1
.IP \n[step].
Plain mode.  Use the file \fB/etc/ftpauth/shadow\fR for authentication.
.PP
.EX
auth required pam_fshadow.so sysconfdir=/etc/ftpauth nopasswd
.EE
.IP \n+[step].
Authenticate against files located in \fB/etc/authdomain\fR.  E.g. if the
supplied user name were \fBsmith@ftp\fR, it would use the files
.B /etc/authdomain/ftp/passwd
and
.BR /etc/authdomain/ftp/shadow :
.PP
auth required pam_fshadow.so sysconfdir=/etc/authdomain regex=(.*)@(.*) 
.PP
.EX
.EE
.SH NOTE
This manpage is a short description of \fBpam_fshadow\fR.  For a detailed
discussion, including examples and usage recommendations, refer to the
\fBPAM-modules Manual\fR available in texinfo format.  If the \fBinfo\fR
reader and the tar documentation are properly installed on your
system, the command
.PP
.RS +4
.B info pam-modules
.RE
.PP
should give you access to the complete manual.
.PP
You can also view the manual using the info mode in
.BR emacs (1),
or find it in various formats online at
.PP
.RS +4
.B http://www.gnu.org.ua/software/pam-modules/manual
.RE
.PP
If any discrepancies occur between this manpage and the
\fBPAM-modules Manual\fR, the later shall be considered the authoritative
source.
.SH "SEE ALSO"
.BR pam.conf (5),
.BR pam.d (5),
.BR pam (8),
.BR regex (7).
.SH AUTHORS
Sergey Poznyakoff <gray@gnu.org>
.SH "BUG REPORTS"
Report bugs to <bug\-pam\-modules@gnu.org.ua>.
.SH COPYRIGHT
Copyright \(co 2001-2022 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:

Return to:

Send suggestions and report system problems to the System administrator.