summaryrefslogtreecommitdiffstats
path: root/modules/pam_faillock/pam_faillock.8.xml
blob: f43b40158a59c8779231e70a5d5194adac3dd1c6 (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
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
<?xml version="1.0" encoding='UTF-8'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<refentry id="pam_faillock">

  <refmeta>
    <refentrytitle>pam_faillock</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
  </refmeta>

  <refnamediv id="pam_faillock-name">
    <refname>pam_faillock</refname>
    <refpurpose>Module counting authentication failures during a specified interval</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis id="pam_faillock-cmdsynopsisauth">
      <command>auth ... pam_faillock.so</command>
      <arg choice="req">
        preauth|authfail|authsucc
      </arg>
      <arg choice="opt">
        conf=<replaceable>/path/to/config-file</replaceable>
      </arg>
      <arg choice="opt">
        dir=<replaceable>/path/to/tally-directory</replaceable>
      </arg>
      <arg choice="opt">
        even_deny_root
      </arg>
      <arg choice="opt">
        deny=<replaceable>n</replaceable>
      </arg>
      <arg choice="opt">
        fail_interval=<replaceable>n</replaceable>
      </arg>
      <arg choice="opt">
        unlock_time=<replaceable>n</replaceable>
      </arg>
      <arg choice="opt">
        root_unlock_time=<replaceable>n</replaceable>
      </arg>
      <arg choice="opt">
        admin_group=<replaceable>name</replaceable>
      </arg>
      <arg choice="opt">
        audit
      </arg>
      <arg choice="opt">
        silent
      </arg>
      <arg choice="opt">
        no_log_info
      </arg>
    </cmdsynopsis>
    <cmdsynopsis id="pam_faillock-cmdsynopsisacct">
      <command>account ... pam_faillock.so</command>
      <arg choice="opt">
        dir=<replaceable>/path/to/tally-directory</replaceable>
      </arg>
      <arg choice="opt">
        no_log_info
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id="pam_faillock-description">

    <title>DESCRIPTION</title>

    <para>
      This module maintains a list of failed authentication attempts per
      user during a specified interval and locks the account in case
      there were more than <replaceable>deny</replaceable> consecutive
      failed authentications.
    </para>
    <para>
      Normally, failed attempts to authenticate <emphasis>root</emphasis> will
      <emphasis remap='B'>not</emphasis> cause the root account to become
      blocked, to prevent denial-of-service: if your users aren't given
      shell accounts and root may only login via <command>su</command> or
      at the machine console (not telnet/rsh, etc), this is safe.
    </para>
  </refsect1>

  <refsect1 id="pam_faillock-options">

    <title>OPTIONS</title>
        <variablelist>
            <varlistentry>
              <term>
                <option>{preauth|authfail|authsucc}</option>
              </term>
              <listitem>
                <para>
                  This argument must be set accordingly to the position of this module
                  instance in the PAM stack.
                </para>
                <para>
                  The <emphasis>preauth</emphasis> argument must be used when the module
                  is called before the modules which ask for the user credentials such
                  as the password. The module just examines whether the user should
                  be blocked from accessing the service in case there were anomalous
                  number of failed consecutive authentication attempts recently. This
                  call is optional if <emphasis>authsucc</emphasis> is used.
                </para>
                <para>
                  The <emphasis>authfail</emphasis> argument must be used when the module
                  is called after the modules which determine the authentication outcome,
                  failed. Unless the user is already blocked due to previous authentication
                  failures, the module will record the failure into the appropriate user
                  tally file.
                </para>
                <para>
                  The <emphasis>authsucc</emphasis> argument must be used when the module
                  is called after the modules which determine the authentication outcome,
                  succeeded. Unless the user is already blocked due to previous authentication
                  failures, the module will then clear the record of the failures in the
                  respective user tally file. Otherwise it will return authentication error.
                  If this call is not done, the pam_faillock will not distinguish between
                  consecutive and non-consecutive failed authentication attempts. The
                  <emphasis>preauth</emphasis> call must be used in such case. Due to
                  complications in the way the PAM stack can be configured it is also
                  possible to call <emphasis>pam_faillock</emphasis> as an account module.
                  In such configuration the module must be also called in the
                  <emphasis>preauth</emphasis> stage.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
               <term>
                 <option>conf=/path/to/config-file</option>
               </term>
               <listitem>
                 <para>
                   Use another configuration file instead of the default
                   <filename>/etc/security/faillock.conf</filename>.
                 </para>
               </listitem>
            </varlistentry>
        </variablelist>
        <para>
          The options for configuring the module behavior are described in the
          <citerefentry><refentrytitle>faillock.conf</refentrytitle><manvolnum>5</manvolnum>
          </citerefentry> manual page. The options specified on the module command
          line override the values from the configuration file.
        </para>
  </refsect1>

  <refsect1 id="pam_faillock-types">
    <title>MODULE TYPES PROVIDED</title>
    <para>
      The <option>auth</option> and <option>account</option> module types are
      provided.
    </para>
  </refsect1>

  <refsect1 id='pam_faillock-return_values'>
    <title>RETURN VALUES</title>
    <variablelist>
      <varlistentry>
        <term>PAM_AUTH_ERR</term>
        <listitem>
          <para>
            An invalid option was given, the module was not able
            to retrieve the user name, no valid counter file
            was found, or too many failed logins.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_BUF_ERR</term>
        <listitem>
          <para>
            Memory buffer error.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_CONV_ERR</term>
        <listitem>
          <para>
            The conversation method supplied by the application
            failed to obtain the username.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_INCOMPLETE</term>
        <listitem>
          <para>
            The conversation method supplied by the application
            returned PAM_CONV_AGAIN.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_SUCCESS</term>
        <listitem>
          <para>
            Everything was successful.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_IGNORE</term>
        <listitem>
          <para>
            User not present in passwd database.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id='pam_faillock-notes'>
    <title>NOTES</title>
    <para>
      Configuring options on the module command line is not recommend. The
      <filename>/etc/security/faillock.conf</filename> should be used instead.
    </para>
    <para>
      The setup of <emphasis>pam_faillock</emphasis> in the PAM stack is different
      from the <emphasis>pam_tally2</emphasis> module setup.
    </para>
    <para>
      Individual files with the failure records are created as owned by
      the user. This allows <emphasis remap='B'>pam_faillock.so</emphasis> module
      to work correctly when it is called from a screensaver.
    </para>
    <para>
      Note that using the module in <option>preauth</option> without the
      <option>silent</option> option specified in <filename>/etc/security/faillock.conf</filename>
      or with <emphasis>requisite</emphasis> control field leaks an information about
      existence or non-existence of an user account in the system because
      the failures are not recorded for the unknown users. The message
      about the user account being locked is never displayed for non-existing
      user accounts allowing the adversary to infer that a particular account
      is not existing on a system.
    </para>
  </refsect1>

  <refsect1 id='pam_faillock-examples'>
    <title>EXAMPLES</title>
    <para>
      Here are two possible configuration examples for <filename>/etc/pam.d/login</filename>.
      They make <emphasis>pam_faillock</emphasis> to lock the account after 4 consecutive
      failed logins during the default interval of 15 minutes. Root account will be locked
      as well. The accounts will be automatically unlocked after 20 minutes.
    </para>
    <para>
      In the first example the module is called only in the <emphasis>auth</emphasis>
      phase and the module does not print any information about the account being blocked
      by <emphasis>pam_faillock</emphasis>. The <emphasis>preauth</emphasis> call can
      be added to tell users that their logins are blocked by the module and also to abort
      the authentication without even asking for password in such case.
    </para>
    <para>
      <filename>/etc/security/faillock.conf</filename> file example:
    </para>
    <programlisting>
deny=4
unlock_time=1200
silent
    </programlisting>
    <para>
      /etc/pam.d/config file example:
    </para>
    <programlisting>
auth     required       pam_securetty.so
auth     required       pam_env.so
auth     required       pam_nologin.so
# optionally call: auth requisite pam_faillock.so preauth
# to display the message about account being locked
auth     [success=1 default=bad] pam_unix.so
auth     [default=die]  pam_faillock.so authfail
auth     sufficient     pam_faillock.so authsucc
auth     required       pam_deny.so
account  required       pam_unix.so
password required       pam_unix.so shadow
session  required       pam_selinux.so close
session  required       pam_loginuid.so
session  required       pam_unix.so
session  required       pam_selinux.so open
    </programlisting>
    <para>
      In the second example the module is called both in the <emphasis>auth</emphasis>
      and <emphasis>account</emphasis> phases and the module informs the authenticating
      user when the account is locked if <option>silent</option> option is not
      specified in the <filename>faillock.conf</filename>.
    </para>
    <programlisting>
auth     required       pam_securetty.so
auth     required       pam_env.so
auth     required       pam_nologin.so
auth     required       pam_faillock.so preauth
# optionally use requisite above if you do not want to prompt for the password
# on locked accounts
auth     sufficient     pam_unix.so
auth     [default=die]  pam_faillock.so authfail
auth     required       pam_deny.so
account  required       pam_faillock.so
# if you drop the above call to pam_faillock.so the lock will be done also
# on non-consecutive authentication failures
account  required       pam_unix.so
password required       pam_unix.so shadow
session  required       pam_selinux.so close
session  required       pam_loginuid.so
session  required       pam_unix.so
session  required       pam_selinux.so open
    </programlisting>
  </refsect1>

  <refsect1 id="pam_faillock-files">
    <title>FILES</title>
    <variablelist>
      <varlistentry>
        <term><filename>/var/run/faillock/*</filename></term>
        <listitem>
          <para>the files logging the authentication failures for users</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>/etc/security/faillock.conf</filename></term>
        <listitem>
          <para>the config file for pam_faillock options</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id='pam_faillock-see_also'>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>faillock</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>faillock.conf</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>
    </para>
  </refsect1>

  <refsect1 id='pam_faillock-author'>
    <title>AUTHOR</title>
      <para>
        pam_faillock was written by Tomas Mraz.
      </para>
  </refsect1>

</refentry>