xref: /freebsd-src/contrib/openpam/doc/man/pam.conf.5 (revision 3ba4c8c81a28de3e00ccf6d7f92c6f8e58bef456)
1556dce83SDag-Erling Smørgrav.\"-
249e56509SDag-Erling Smørgrav.\" Copyright (c) 2005-2017 Dag-Erling Smørgrav
3556dce83SDag-Erling Smørgrav.\" All rights reserved.
4556dce83SDag-Erling Smørgrav.\"
5556dce83SDag-Erling Smørgrav.\" Redistribution and use in source and binary forms, with or without
6556dce83SDag-Erling Smørgrav.\" modification, are permitted provided that the following conditions
7556dce83SDag-Erling Smørgrav.\" are met:
8556dce83SDag-Erling Smørgrav.\" 1. Redistributions of source code must retain the above copyright
9556dce83SDag-Erling Smørgrav.\"    notice, this list of conditions and the following disclaimer.
10556dce83SDag-Erling Smørgrav.\" 2. Redistributions in binary form must reproduce the above copyright
11556dce83SDag-Erling Smørgrav.\"    notice, this list of conditions and the following disclaimer in the
12556dce83SDag-Erling Smørgrav.\"    documentation and/or other materials provided with the distribution.
13556dce83SDag-Erling Smørgrav.\" 3. The name of the author may not be used to endorse or promote
14556dce83SDag-Erling Smørgrav.\"    products derived from this software without specific prior written
15556dce83SDag-Erling Smørgrav.\"    permission.
16556dce83SDag-Erling Smørgrav.\"
17556dce83SDag-Erling Smørgrav.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18556dce83SDag-Erling Smørgrav.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19556dce83SDag-Erling Smørgrav.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20556dce83SDag-Erling Smørgrav.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
21556dce83SDag-Erling Smørgrav.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22556dce83SDag-Erling Smørgrav.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23556dce83SDag-Erling Smørgrav.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24556dce83SDag-Erling Smørgrav.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25556dce83SDag-Erling Smørgrav.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26556dce83SDag-Erling Smørgrav.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27556dce83SDag-Erling Smørgrav.\" SUCH DAMAGE.
28556dce83SDag-Erling Smørgrav.\"
29*3ba4c8c8SDag-Erling Smørgrav.Dd June 27, 2023
30556dce83SDag-Erling Smørgrav.Dt PAM.CONF 5
31556dce83SDag-Erling Smørgrav.Os
32556dce83SDag-Erling Smørgrav.Sh NAME
33556dce83SDag-Erling Smørgrav.Nm pam.conf
34556dce83SDag-Erling Smørgrav.Nd PAM policy file format
35556dce83SDag-Erling Smørgrav.Sh DESCRIPTION
36556dce83SDag-Erling SmørgravThe PAM library searches for policies in the following files, in
37556dce83SDag-Erling Smørgravdecreasing order of preference:
38556dce83SDag-Erling Smørgrav.Bl -enum
39556dce83SDag-Erling Smørgrav.It
40556dce83SDag-Erling Smørgrav.Pa /etc/pam.d/ Ns Ar service-name
41556dce83SDag-Erling Smørgrav.It
42556dce83SDag-Erling Smørgrav.Pa /etc/pam.conf
43556dce83SDag-Erling Smørgrav.It
44556dce83SDag-Erling Smørgrav.Pa /usr/local/etc/pam.d/ Ns Ar service-name
45556dce83SDag-Erling Smørgrav.It
46556dce83SDag-Erling Smørgrav.Pa /usr/local/etc/pam.conf
47556dce83SDag-Erling Smørgrav.El
48556dce83SDag-Erling Smørgrav.Pp
49556dce83SDag-Erling SmørgravIf none of these locations contains a policy for the given service,
50556dce83SDag-Erling Smørgravthe
512f3ed619SDag-Erling Smørgrav.Dq Dv other
52556dce83SDag-Erling Smørgravpolicy is used instead, if it exists.
53556dce83SDag-Erling Smørgrav.Pp
54556dce83SDag-Erling SmørgravEntries in per-service policy files must be of one of the two forms
55556dce83SDag-Erling Smørgravbelow:
56556dce83SDag-Erling Smørgrav.Bd -unfilled -offset indent
577f106882SDag-Erling Smørgrav.Ar facility control-flag module-path Op Ar arguments ...
587f106882SDag-Erling Smørgrav.Ar facility Cm include Ar other-service-name
59556dce83SDag-Erling Smørgrav.Ed
60556dce83SDag-Erling Smørgrav.Pp
61556dce83SDag-Erling SmørgravEntries in
62556dce83SDag-Erling Smørgrav.Pa pam.conf Ns -style
63556dce83SDag-Erling Smørgravpolicy files are of the same form, but are prefixed by an additional
64556dce83SDag-Erling Smørgravfield specifying the name of the service they apply to.
65556dce83SDag-Erling Smørgrav.Pp
66ce77a8d6SDag-Erling SmørgravIn both cases, blank lines and comments introduced by a
6705640c12SDag-Erling Smørgrav.Ql #
68ce77a8d6SDag-Erling Smørgravsign are ignored, and the normal shell quoting rules apply.
69ce77a8d6SDag-Erling SmørgravThe precise details of how the file is tokenized are described in
70ce77a8d6SDag-Erling Smørgrav.Xr openpam_readword 3 .
71556dce83SDag-Erling Smørgrav.Pp
72556dce83SDag-Erling SmørgravThe
737f106882SDag-Erling Smørgrav.Ar facility
747f106882SDag-Erling Smørgravfield specifies the facility the entry applies to, and is one of:
75ce77a8d6SDag-Erling Smørgrav.Bl -tag -width 12n
76556dce83SDag-Erling Smørgrav.It Cm auth
77556dce83SDag-Erling SmørgravAuthentication functions
78556dce83SDag-Erling Smørgrav.Po
79556dce83SDag-Erling Smørgrav.Xr pam_authenticate 3 ,
80556dce83SDag-Erling Smørgrav.Xr pam_setcred 3
81556dce83SDag-Erling Smørgrav.Pc
82556dce83SDag-Erling Smørgrav.It Cm account
83556dce83SDag-Erling SmørgravAccount management functions
84556dce83SDag-Erling Smørgrav.Pq Xr pam_acct_mgmt 3
85556dce83SDag-Erling Smørgrav.It Cm session
86556dce83SDag-Erling SmørgravSession handling functions
87556dce83SDag-Erling Smørgrav.Po
88556dce83SDag-Erling Smørgrav.Xr pam_open_session 3 ,
89556dce83SDag-Erling Smørgrav.Xr pam_close_session 3
90556dce83SDag-Erling Smørgrav.Pc
91556dce83SDag-Erling Smørgrav.It Cm password
92556dce83SDag-Erling SmørgravPassword management functions
93556dce83SDag-Erling Smørgrav.Pq Xr pam_chauthtok 3
94556dce83SDag-Erling Smørgrav.El
95556dce83SDag-Erling Smørgrav.Pp
96556dce83SDag-Erling SmørgravThe
97556dce83SDag-Erling Smørgrav.Ar control-flag
98556dce83SDag-Erling Smørgravfield determines how the result returned by the module affects the
99556dce83SDag-Erling Smørgravflow of control through (and the final result of) the rest of the
100556dce83SDag-Erling Smørgravchain, and is one of:
101ce77a8d6SDag-Erling Smørgrav.Bl -tag -width 12n
102556dce83SDag-Erling Smørgrav.It Cm required
103556dce83SDag-Erling SmørgravIf this module succeeds, the result of the chain will be success
104556dce83SDag-Erling Smørgravunless a later module fails.
105556dce83SDag-Erling SmørgravIf it fails, the rest of the chain still runs, but the final result
106556dce83SDag-Erling Smørgravwill be failure regardless of the success of later modules.
107556dce83SDag-Erling Smørgrav.It Cm requisite
108556dce83SDag-Erling SmørgravIf this module succeeds, the result of the chain will be success
109556dce83SDag-Erling Smørgravunless a later module fails.
110b5a3d78aSDag-Erling SmørgravIf the module fails, the chain is broken and the result is failure.
111556dce83SDag-Erling Smørgrav.It Cm sufficient
112556dce83SDag-Erling SmørgravIf this module succeeds, the chain is broken and the result is
113556dce83SDag-Erling Smørgravsuccess.
114556dce83SDag-Erling SmørgravIf it fails, the rest of the chain still runs, but the final result
115556dce83SDag-Erling Smørgravwill be failure unless a later module succeeds.
116556dce83SDag-Erling Smørgrav.It Cm binding
117556dce83SDag-Erling SmørgravIf this module succeeds, the chain is broken and the result is
118556dce83SDag-Erling Smørgravsuccess.
119556dce83SDag-Erling SmørgravIf it fails, the rest of the chain still runs, but the final result
120556dce83SDag-Erling Smørgravwill be failure regardless of the success of later modules.
121556dce83SDag-Erling Smørgrav.It Cm optional
122556dce83SDag-Erling SmørgravIf this module succeeds, the result of the chain will be success
123556dce83SDag-Erling Smørgravunless a later module fails.
124556dce83SDag-Erling SmørgravIf this module fails, the result of the chain will be failure unless a
125556dce83SDag-Erling Smørgravlater module succeeds.
126556dce83SDag-Erling Smørgrav.El
127556dce83SDag-Erling Smørgrav.Pp
128556dce83SDag-Erling SmørgravThere are two exceptions to the above:
129556dce83SDag-Erling Smørgrav.Cm sufficient
130556dce83SDag-Erling Smørgravand
131556dce83SDag-Erling Smørgrav.Cm binding
132556dce83SDag-Erling Smørgravmodules are treated as
133556dce83SDag-Erling Smørgrav.Cm optional
134556dce83SDag-Erling Smørgravby
135556dce83SDag-Erling Smørgrav.Xr pam_setcred 3 ,
136556dce83SDag-Erling Smørgravand in the
137556dce83SDag-Erling Smørgrav.Dv PAM_PRELIM_CHECK
138556dce83SDag-Erling Smørgravphase of
139556dce83SDag-Erling Smørgrav.Xr pam_chauthtok 3 .
140556dce83SDag-Erling Smørgrav.Pp
141556dce83SDag-Erling SmørgravThe
142556dce83SDag-Erling Smørgrav.Ar module-path
143ce77a8d6SDag-Erling Smørgravfield specifies the name or full path of the module to call.
144ce77a8d6SDag-Erling SmørgravIf only the name is specified, the PAM library will search for it in
145ce77a8d6SDag-Erling Smørgravthe following locations:
146ce77a8d6SDag-Erling Smørgrav.Bl -enum
147ce77a8d6SDag-Erling Smørgrav.It
148ce77a8d6SDag-Erling Smørgrav.Pa /usr/lib
149ce77a8d6SDag-Erling Smørgrav.It
150ce77a8d6SDag-Erling Smørgrav.Pa /usr/local/lib
151ce77a8d6SDag-Erling Smørgrav.El
152556dce83SDag-Erling Smørgrav.Pp
153ce77a8d6SDag-Erling SmørgravThe remaining fields, if any, are passed unmodified to the module if
154ce77a8d6SDag-Erling Smørgravand when it is invoked.
155556dce83SDag-Erling Smørgrav.Pp
156556dce83SDag-Erling SmørgravThe
157556dce83SDag-Erling Smørgrav.Cm include
158556dce83SDag-Erling Smørgravform of entry causes entries from a different chain (specified by
159556dce83SDag-Erling Smørgrav.Ar other-system-name )
160556dce83SDag-Erling Smørgravto be included in the current one.
161556dce83SDag-Erling SmørgravThis allows one to define system-wide policies which are then included
162556dce83SDag-Erling Smørgravinto service-specific policies.
163556dce83SDag-Erling SmørgravThe system-wide policy can then be modified without having to also
164556dce83SDag-Erling Smørgravmodify each and every service-specific policy.
165ce77a8d6SDag-Erling Smørgrav.Pp
166ce77a8d6SDag-Erling Smørgrav.Bf -symbolic
167ce77a8d6SDag-Erling SmørgravTake care not to introduce loops when using
168ce77a8d6SDag-Erling Smørgrav.Cm include
169ce77a8d6SDag-Erling Smørgravrules, as there is currently no loop detection in place.
170ce77a8d6SDag-Erling Smørgrav.Ef
171ce77a8d6SDag-Erling Smørgrav.Sh MODULE OPTIONS
172ce77a8d6SDag-Erling SmørgravSome PAM library functions may alter their behavior when called by a
173ce77a8d6SDag-Erling Smørgravservice module if certain module options were specified, regardless of
174ce77a8d6SDag-Erling Smørgravwhether the module itself accords them any importance.
175ce77a8d6SDag-Erling SmørgravOne such option is
176ce77a8d6SDag-Erling Smørgrav.Cm debug ,
177ce77a8d6SDag-Erling Smørgravwhich causes the dispatcher to enable debugging messages before
178ce77a8d6SDag-Erling Smørgravcalling each service function, and disable them afterwards (unless
179ce77a8d6SDag-Erling Smørgravthey were already enabled).
180ce77a8d6SDag-Erling SmørgravOther special options include:
181ce77a8d6SDag-Erling Smørgrav.Bl -tag -width 12n
182ce77a8d6SDag-Erling Smørgrav.It Cm authtok_prompt Ns = Ns Ar prompt , Cm oldauthtok_prompt Ns = Ns Ar prompt , Cm user_prompt Ns = Ns Ar prompt
183ce77a8d6SDag-Erling SmørgravThese options can be used to override the prompts used by
184ce77a8d6SDag-Erling Smørgrav.Xr pam_get_authtok 3
185ce77a8d6SDag-Erling Smørgravand
186ce77a8d6SDag-Erling Smørgrav.Xr pam_get_user 3 .
187ce77a8d6SDag-Erling Smørgrav.It Cm echo_pass
188ce77a8d6SDag-Erling SmørgravThis option controls whether
189ce77a8d6SDag-Erling Smørgrav.Xr pam_get_authtok 3
190ce77a8d6SDag-Erling Smørgravwill allow the user to see what they are typing.
191ce77a8d6SDag-Erling Smørgrav.It Cm try_first_pass , Cm use_first_pass
192ce77a8d6SDag-Erling SmørgravThese options control
193ce77a8d6SDag-Erling Smørgrav.Xr pam_get_authtok 3 Ns 's
194ce77a8d6SDag-Erling Smørgravuse of cached authentication tokens.
195ce77a8d6SDag-Erling Smørgrav.El
196556dce83SDag-Erling Smørgrav.Sh SEE ALSO
197556dce83SDag-Erling Smørgrav.Xr pam 3
198556dce83SDag-Erling Smørgrav.Sh STANDARDS
199556dce83SDag-Erling Smørgrav.Rs
200556dce83SDag-Erling Smørgrav.%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
201556dce83SDag-Erling Smørgrav.%D "June 1997"
202556dce83SDag-Erling Smørgrav.Re
203556dce83SDag-Erling Smørgrav.Sh AUTHORS
20405640c12SDag-Erling SmørgravThe OpenPAM library was developed for the
20505640c12SDag-Erling Smørgrav.Fx
2067f106882SDag-Erling SmørgravProject by ThinkSec AS and Network Associates Laboratories, the
2077f106882SDag-Erling SmørgravSecurity Research Division of Network Associates, Inc.\& under
2087f106882SDag-Erling SmørgravDARPA/SPAWAR contract N66001-01-C-8035
209556dce83SDag-Erling Smørgrav.Pq Dq CBOSS ,
210556dce83SDag-Erling Smørgravas part of the DARPA CHATS research program.
211556dce83SDag-Erling Smørgrav.Pp
2122f3ed619SDag-Erling SmørgravThe OpenPAM library is maintained by
213f3b0ac34SDag-Erling Smørgrav.An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .
214