Debian Codegraph @

upstream/debian-unstable/man8/pam_filter.8

raw
1 '\" t
2 .\" Title: pam_filter
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_FILTER" "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_filter \- PAM filter module
32 .SH "SYNOPSIS"
33 .HP \w'\fBpam_filter\&.so\fR\ 'u
34 \fBpam_filter\&.so\fR [debug] [new_term] [non_term] run1|run2 \fIfilter\fR [\fI\&.\&.\&.\fR]
35 .SH "DESCRIPTION"
36 .PP
37 This module is intended to be a platform for providing access to all of the input/output that passes between the user and the application\&. It is only suitable for tty\-based and (stdin/stdout) applications\&.
38 .PP
39 To function this module requires
40 \fIfilters\fR
41 to be installed on the system\&. The single filter provided with the module simply transposes upper and lower case letters in the input and output streams\&. (This can be very annoying and is not kind to termcap based editors)\&.
42 .PP
43 Each component of the module has the potential to invoke the desired filter\&. The filter is always
44 \fBexecv\fR(2)
45 with the privilege of the calling application and
46 \fInot\fR
47 that of the user\&. For this reason it cannot usually be killed by the user without closing their session\&.
48 .SH "OPTIONS"
49 .PP
50 .PP
51 debug
52 .RS 4
53 Print debug information\&.
54 .RE
55 .PP
56 new_term
57 .RS 4
58 The default action of the filter is to set the
59 \fIPAM_TTY\fR
60 item to indicate the terminal that the user is using to connect to the application\&. This argument indicates that the filter should set
61 \fIPAM_TTY\fR
62 to the filtered pseudo\-terminal\&.
63 .RE
64 .PP
65 non_term
66 .RS 4
67 don\*(Aqt try to set the
68 \fIPAM_TTY\fR
69 item\&.
70 .RE
71 .PP
72 runX
73 .RS 4
74 In order that the module can invoke a filter it should know when to invoke it\&. This argument is required to tell the filter when to do this\&.
75 .sp
76 Permitted values for
77 \fIX\fR
78 are
79 \fI1\fR
80 and
81 \fI2\fR\&. These indicate the precise time that the filter is to be run\&. To understand this concept it will be useful to have read the
82 \fBpam\fR(3)
83 manual page\&. Basically, for each management group there are up to two ways of calling the module\*(Aqs functions\&. In the case of the
84 \fIauthentication\fR
85 and
86 \fIsession\fR
87 components there are actually two separate functions\&. For the case of authentication, these functions are
88 \fBpam_authenticate\fR(3)
89 and
90 \fBpam_setcred\fR(3), here
91 \fBrun1\fR
92 means run the filter from the
93 \fBpam_authenticate\fR
94 function and
95 \fBrun2\fR
96 means run the filter from
97 \fBpam_setcred\fR\&. In the case of the session modules,
98 \fIrun1\fR
99 implies that the filter is invoked at the
100 \fBpam_open_session\fR(3)
101 stage, and
102 \fIrun2\fR
103 for
104 \fBpam_close_session\fR(3)\&.
105 .sp
106 For the case of the account component\&. Either
107 \fIrun1\fR
108 or
109 \fIrun2\fR
110 may be used\&.
111 .sp
112 For the case of the password component,
113 \fIrun1\fR
114 is used to indicate that the filter is run on the first occasion of
115 \fBpam_chauthtok\fR(3)
116 (the
117 \fIPAM_PRELIM_CHECK\fR
118 phase) and
119 \fIrun2\fR
120 is used to indicate that the filter is run on the second occasion (the
121 \fIPAM_UPDATE_AUTHTOK\fR
122 phase)\&.
123 .RE
124 .PP
125 filter
126 .RS 4
127 The full pathname of the filter to be run and any command line arguments that the filter might expect\&.
128 .RE
129 .SH "MODULE TYPES PROVIDED"
130 .PP
131 All module types (\fBauth\fR,
132 \fBaccount\fR,
133 \fBpassword\fR
134 and
135 \fBsession\fR) are provided\&.
136 .SH "RETURN VALUES"
137 .PP
138 .PP
139 PAM_SUCCESS
140 .RS 4
141 The new filter was set successfully\&.
142 .RE
143 .PP
144 PAM_ABORT
145 .RS 4
146 Critical error, immediate abort\&.
147 .RE
148 .SH "EXAMPLES"
149 .PP
150 Add the following line to
151 /etc/pam\&.d/login
152 to see how to configure login to transpose upper and lower case letters once the user has logged in:
153 .sp
154 .if n \{\
155 .RS 4
156 .\}
157 .nf
158 session required pam_filter\&.so run1 /lib/security/pam_filter/upperLOWER
159
160 .fi
161 .if n \{\
162 .RE
163 .\}
164 .sp
165 .SH "SEE ALSO"
166 .PP
167 \fBpam.conf\fR(5),
168 \fBpam.d\fR(5),
169 \fBpam\fR(7)
170 .SH "AUTHOR"
171 .PP
172 pam_filter was written by Andrew G\&. Morgan <morgan@kernel\&.org>\&.