Debian Codegraph @

upstream/debian-unstable/man8/pam_listfile.8

raw
1 '\" t
2 .\" Title: pam_listfile
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_LISTFILE" "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_listfile \- deny or allow services based on an arbitrary file
32 .SH "SYNOPSIS"
33 .HP \w'\fBpam_listfile\&.so\fR\ 'u
34 \fBpam_listfile\&.so\fR item=[tty|user|rhost|ruser|group|shell] sense=[allow|deny] file=\fI/path/filename\fR onerr=[succeed|fail] [apply=[\fIuser\fR|\fI@group\fR]] [quiet]
35 .SH "DESCRIPTION"
36 .PP
37 pam_listfile is a PAM module which provides a way to deny or allow services based on an arbitrary file\&.
38 .PP
39 The module gets the
40 \fBitem\fR
41 of the type specified \-\-
42 \fIuser\fR
43 specifies the username,
44 \fIPAM_USER\fR;
45 \fItty\fR
46 specifies the name of the terminal (if any) over which the request has been made,
47 \fIPAM_TTY\fR;
48 \fIrhost\fR
49 specifies the name of the remote host (if any) from which the request was made,
50 \fIPAM_RHOST\fR; and
51 \fIruser\fR
52 specifies the name of the remote user (if available) who made the request,
53 \fIPAM_RUSER\fR
54 \-\- and looks for an instance of that item in the
55 \fBfile=\fR\fB\fIfilename\fR\fR\&.
56 filename
57 contains one line per item listed\&. If the item is found, then if
58 \fBsense=allow\fR,
59 \fIPAM_SUCCESS\fR
60 is returned, causing the authorization request to succeed; else if
61 \fBsense=deny\fR,
62 \fIPAM_AUTH_ERR\fR
63 is returned, causing the authorization request to fail\&.
64 .PP
65 If an error is encountered (for instance, if
66 filename
67 does not exist, or a poorly\-constructed argument is encountered), then if
68 \fBonerr=succeed\fR,
69 \fIPAM_SUCCESS\fR
70 is returned, otherwise if
71 \fBonerr=fail\fR,
72 \fIPAM_AUTH_ERR\fR
73 or
74 \fIPAM_SERVICE_ERR\fR
75 (as appropriate) will be returned\&.
76 .PP
77 An additional argument,
78 \fBapply=\fR, can be used to restrict the application of the above to a specific user (\fBapply=\fR\fB\fIusername\fR\fR) or a given group (\fBapply=\fR\fB\fI@groupname\fR\fR)\&. This added restriction is only meaningful when used with the
79 \fItty\fR,
80 \fIrhost\fR
81 and
82 \fIshell\fR
83 items\&.
84 .PP
85 Besides this last one, all arguments should be specified; do not count on any default behavior\&.
86 .PP
87 No credentials are awarded by this module\&.
88 .SH "OPTIONS"
89 .PP
90 .PP
91 item=[tty|user|rhost|ruser|group|shell]
92 .RS 4
93 What is listed in the file and should be checked for\&.
94 .RE
95 .PP
96 sense=[allow|deny]
97 .RS 4
98 Action to take if the item is found in the file\&. If the item is NOT found in the file, then the opposite action is requested\&.
99 .RE
100 .PP
101 file=/path/filename
102 .RS 4
103 File containing one item per line\&. The file needs to be a plain file and not world writable\&.
104 .RE
105 .PP
106 onerr=[succeed|fail]
107 .RS 4
108 What to do if something weird happens like being unable to open the file\&.
109 .RE
110 .PP
111 apply=[user|@group]
112 .RS 4
113 Restrict the user class for which the restriction apply\&. Note that with
114 \fBitem=[user|ruser|group]\fR
115 this does not make sense, but for
116 \fBitem=[tty|rhost|shell]\fR
117 it has a meaning\&.
118 .RE
119 .PP
120 quiet
121 .RS 4
122 Do not treat service refusals or missing list files as errors that need to be logged\&.
123 .RE
124 .SH "MODULE TYPES PROVIDED"
125 .PP
126 All module types (\fBauth\fR,
127 \fBaccount\fR,
128 \fBpassword\fR
129 and
130 \fBsession\fR) are provided\&.
131 .SH "RETURN VALUES"
132 .PP
133 .PP
134 PAM_AUTH_ERR
135 .RS 4
136 Authentication failure\&.
137 .RE
138 .PP
139 PAM_BUF_ERR
140 .RS 4
141 Memory buffer error\&.
142 .RE
143 .PP
144 PAM_IGNORE
145 .RS 4
146 The rule does not apply to the
147 \fBapply\fR
148 option\&.
149 .RE
150 .PP
151 PAM_SERVICE_ERR
152 .RS 4
153 Error in service module\&.
154 .RE
155 .PP
156 PAM_SUCCESS
157 .RS 4
158 Success\&.
159 .RE
160 .SH "EXAMPLES"
161 .PP
162 Classic \*(Aqftpusers\*(Aq authentication can be implemented with this entry in
163 /etc/pam\&.d/ftpd:
164 .sp
165 .if n \{\
166 .RS 4
167 .\}
168 .nf
169 #
170 # deny ftp\-access to users listed in the /etc/ftpusers file
171 #
172 auth required pam_listfile\&.so \e
173 onerr=succeed item=user sense=deny file=/etc/ftpusers
174
175 .fi
176 .if n \{\
177 .RE
178 .\}
179 .sp
180 Note, users listed in
181 /etc/ftpusers
182 file are (counterintuitively)
183 \fInot\fR
184 allowed access to the ftp service\&.
185 .PP
186 To allow login access only for certain users, you can use a
187 /etc/pam\&.d/login
188 entry like this:
189 .sp
190 .if n \{\
191 .RS 4
192 .\}
193 .nf
194 #
195 # permit login to users listed in /etc/loginusers
196 #
197 auth required pam_listfile\&.so \e
198 onerr=fail item=user sense=allow file=/etc/loginusers
199
200 .fi
201 .if n \{\
202 .RE
203 .\}
204 .sp
205 For this example to work, all users who are allowed to use the login service should be listed in the file
206 /etc/loginusers\&. Unless you are explicitly trying to lock out root, make sure that when you do this, you leave a way for root to log in, either by listing root in
207 /etc/loginusers, or by listing a user who is able to
208 \fIsu\fR
209 to the root account\&.
210 .SH "SEE ALSO"
211 .PP
212 \fBpam.conf\fR(5),
213 \fBpam.d\fR(5),
214 \fBpam\fR(7)
215 .SH "AUTHOR"
216 .PP
217 pam_listfile was written by Michael K\&. Johnson <johnsonm@redhat\&.com> and Elliot Lee <sopwith@cuc\&.edu>\&.