{ "content": [ { "type": "text", "text": "# pam_faillock(8) (man)\n\n**Summary:** pamfaillock - Module counting authentication failures during a specified interval\n\n**Synopsis:** auth ... pamfaillock.so {preauth|authfail|authsucc} [conf=/path/to/config-file]\n[dir=/path/to/tally-directory] [evendenyroot] [deny=n]\n[failinterval=n] [unlocktime=n] [rootunlocktime=n]\n[admingroup=name] [audit] [silent] [nologinfo]\naccount ... pamfaillock.so [dir=/path/to/tally-directory] [nologinfo]\n\n## Examples\n\n- `Here are two possible configuration examples for /etc/pam.d/login. They make pamfaillock to`\n- `lock the account after 4 consecutive failed logins during the default interval of 15 minutes.`\n- `Root account will be locked as well. The accounts will be automatically unlocked after 20`\n- `minutes.`\n- `In the first example the module is called only in the auth phase and the module does not`\n- `print any information about the account being blocked by pamfaillock. The preauth call can`\n- `be added to tell users that their logins are blocked by the module and also to abort the`\n- `authentication without even asking for password in such case.`\n- `/etc/security/faillock.conf file example:`\n- `deny=4`\n- `unlocktime=1200`\n- `silent`\n- `/etc/pam.d/config file example:`\n- `auth required pamsecuretty.so`\n- `auth required pamenv.so`\n- `auth required pamnologin.so`\n- `# optionally call: auth requisite pamfaillock.so preauth`\n- `# to display the message about account being locked`\n- `auth [success=1 default=bad] pamunix.so`\n- `auth [default=die] pamfaillock.so authfail`\n- `auth sufficient pamfaillock.so authsucc`\n- `auth required pamdeny.so`\n- `account required pamunix.so`\n- `password required pamunix.so shadow`\n- `session required pamselinux.so close`\n- `session required pamloginuid.so`\n- `session required pamunix.so`\n- `session required pamselinux.so open`\n- `In the second example the module is called both in the auth and account phases and the module`\n- `informs the authenticating user when the account is locked if silent option is not specified`\n- `in the faillock.conf.`\n- `auth required pamsecuretty.so`\n- `auth required pamenv.so`\n- `auth required pamnologin.so`\n- `auth required pamfaillock.so preauth`\n- `# optionally use requisite above if you do not want to prompt for the password`\n- `# on locked accounts`\n- `auth sufficient pamunix.so`\n- `auth [default=die] pamfaillock.so authfail`\n- `auth required pamdeny.so`\n- `account required pamfaillock.so`\n- `# if you drop the above call to pamfaillock.so the lock will be done also`\n- `# on non-consecutive authentication failures`\n- `account required pamunix.so`\n- `password required pamunix.so shadow`\n- `session required pamselinux.so close`\n- `session required pamloginuid.so`\n- `session required pamunix.so`\n- `session required pamselinux.so open`\n\n## See Also\n\n- faillock(8)\n- faillock.conf(5)\n- pam.conf(5)\n- pam.d(5)\n- pam(8)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (7 lines)\n- **DESCRIPTION** (8 lines)\n- **OPTIONS** (1 lines) — 2 subsections\n - {preauth|authfail|authsucc} (24 lines)\n - conf=/path/to/config-file (6 lines)\n- **MODULE TYPES PROVIDED** (2 lines)\n- **RETURN VALUES** (19 lines)\n- **NOTES** (15 lines)\n- **EXAMPLES** (60 lines)\n- **FILES** (6 lines)\n- **SEE ALSO** (2 lines)\n- **AUTHOR** (5 lines)\n\n## Full Content\n\n### NAME\n\npamfaillock - Module counting authentication failures during a specified interval\n\n### SYNOPSIS\n\nauth ... pamfaillock.so {preauth|authfail|authsucc} [conf=/path/to/config-file]\n[dir=/path/to/tally-directory] [evendenyroot] [deny=n]\n[failinterval=n] [unlocktime=n] [rootunlocktime=n]\n[admingroup=name] [audit] [silent] [nologinfo]\n\naccount ... pamfaillock.so [dir=/path/to/tally-directory] [nologinfo]\n\n### DESCRIPTION\n\nThis module maintains a list of failed authentication attempts per user during a specified\ninterval and locks the account in case there were more than deny consecutive failed\nauthentications.\n\nNormally, failed attempts to authenticate root will not cause the root account to become\nblocked, to prevent denial-of-service: if your users aren't given shell accounts and root may\nonly login via su or at the machine console (not telnet/rsh, etc), this is safe.\n\n### OPTIONS\n\n#### {preauth|authfail|authsucc}\n\nThis argument must be set accordingly to the position of this module instance in the PAM\nstack.\n\nThe preauth argument must be used when the module is called before the modules which ask\nfor the user credentials such as the password. The module just examines whether the user\nshould be blocked from accessing the service in case there were anomalous number of\nfailed consecutive authentication attempts recently. This call is optional if authsucc is\nused.\n\nThe authfail argument must be used when the module is called after the modules which\ndetermine the authentication outcome, failed. Unless the user is already blocked due to\nprevious authentication failures, the module will record the failure into the appropriate\nuser tally file.\n\nThe authsucc argument must be used when the module is called after the modules which\ndetermine the authentication outcome, succeeded. Unless the user is already blocked due\nto previous authentication failures, the module will then clear the record of the\nfailures in the respective user tally file. Otherwise it will return authentication\nerror. If this call is not done, the pamfaillock will not distinguish between\nconsecutive and non-consecutive failed authentication attempts. The preauth call must be\nused in such case. Due to complications in the way the PAM stack can be configured it is\nalso possible to call pamfaillock as an account module. In such configuration the module\nmust be also called in the preauth stage.\n\n#### conf=/path/to/config-file\n\nUse another configuration file instead of the default /etc/security/faillock.conf.\n\nThe options for configuring the module behavior are described in the faillock.conf(5) manual\npage. The options specified on the module command line override the values from the\nconfiguration file.\n\n### MODULE TYPES PROVIDED\n\nThe auth and account module types are provided.\n\n### RETURN VALUES\n\nPAMAUTHERR\nAn invalid option was given, the module was not able to retrieve the user name, no valid\ncounter file was found, or too many failed logins.\n\nPAMBUFERR\nMemory buffer error.\n\nPAMCONVERR\nThe conversation method supplied by the application failed to obtain the username.\n\nPAMINCOMPLETE\nThe conversation method supplied by the application returned PAMCONVAGAIN.\n\nPAMSUCCESS\nEverything was successful.\n\nPAMIGNORE\nUser not present in passwd database.\n\n### NOTES\n\nConfiguring options on the module command line is not recommend. The\n/etc/security/faillock.conf should be used instead.\n\nThe setup of pamfaillock in the PAM stack is different from the pamtally2 module setup.\n\nIndividual files with the failure records are created as owned by the user. This allows\npamfaillock.so module to work correctly when it is called from a screensaver.\n\nNote that using the module in preauth without the silent option specified in\n/etc/security/faillock.conf or with requisite control field leaks an information about\nexistence or non-existence of an user account in the system because the failures are not\nrecorded for the unknown users. The message about the user account being locked is never\ndisplayed for non-existing user accounts allowing the adversary to infer that a particular\naccount is not existing on a system.\n\n### EXAMPLES\n\nHere are two possible configuration examples for /etc/pam.d/login. They make pamfaillock to\nlock the account after 4 consecutive failed logins during the default interval of 15 minutes.\nRoot account will be locked as well. The accounts will be automatically unlocked after 20\nminutes.\n\nIn the first example the module is called only in the auth phase and the module does not\nprint any information about the account being blocked by pamfaillock. The preauth call can\nbe added to tell users that their logins are blocked by the module and also to abort the\nauthentication without even asking for password in such case.\n\n/etc/security/faillock.conf file example:\n\ndeny=4\nunlocktime=1200\nsilent\n\n\n/etc/pam.d/config file example:\n\nauth required pamsecuretty.so\nauth required pamenv.so\nauth required pamnologin.so\n# optionally call: auth requisite pamfaillock.so preauth\n# to display the message about account being locked\nauth [success=1 default=bad] pamunix.so\nauth [default=die] pamfaillock.so authfail\nauth sufficient pamfaillock.so authsucc\nauth required pamdeny.so\naccount required pamunix.so\npassword required pamunix.so shadow\nsession required pamselinux.so close\nsession required pamloginuid.so\nsession required pamunix.so\nsession required pamselinux.so open\n\n\nIn the second example the module is called both in the auth and account phases and the module\ninforms the authenticating user when the account is locked if silent option is not specified\nin the faillock.conf.\n\nauth required pamsecuretty.so\nauth required pamenv.so\nauth required pamnologin.so\nauth required pamfaillock.so preauth\n# optionally use requisite above if you do not want to prompt for the password\n# on locked accounts\nauth sufficient pamunix.so\nauth [default=die] pamfaillock.so authfail\nauth required pamdeny.so\naccount required pamfaillock.so\n# if you drop the above call to pamfaillock.so the lock will be done also\n# on non-consecutive authentication failures\naccount required pamunix.so\npassword required pamunix.so shadow\nsession required pamselinux.so close\nsession required pamloginuid.so\nsession required pamunix.so\nsession required pamselinux.so open\n\n### FILES\n\n/var/run/faillock/*\nthe files logging the authentication failures for users\n\n/etc/security/faillock.conf\nthe config file for pamfaillock options\n\n### SEE ALSO\n\nfaillock(8), faillock.conf(5), pam.conf(5), pam.d(5), pam(8)\n\n### AUTHOR\n\npamfaillock was written by Tomas Mraz.\n\n\n\nLinux-PAM Manual 06/08/2020 PAMFAILLOCK(8)\n\n" } ], "structuredContent": { "command": "pam_faillock", "section": "8", "mode": "man", "summary": "pamfaillock - Module counting authentication failures during a specified interval", "synopsis": "auth ... pamfaillock.so {preauth|authfail|authsucc} [conf=/path/to/config-file]\n[dir=/path/to/tally-directory] [evendenyroot] [deny=n]\n[failinterval=n] [unlocktime=n] [rootunlocktime=n]\n[admingroup=name] [audit] [silent] [nologinfo]\naccount ... pamfaillock.so [dir=/path/to/tally-directory] [nologinfo]", "flags": [], "examples": [ "Here are two possible configuration examples for /etc/pam.d/login. They make pamfaillock 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.", "In the first example the module is called only in the auth phase and the module does not", "print any information about the account being blocked by pamfaillock. The preauth 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.", "/etc/security/faillock.conf file example:", "deny=4", "unlocktime=1200", "silent", "/etc/pam.d/config file example:", "auth required pamsecuretty.so", "auth required pamenv.so", "auth required pamnologin.so", "# optionally call: auth requisite pamfaillock.so preauth", "# to display the message about account being locked", "auth [success=1 default=bad] pamunix.so", "auth [default=die] pamfaillock.so authfail", "auth sufficient pamfaillock.so authsucc", "auth required pamdeny.so", "account required pamunix.so", "password required pamunix.so shadow", "session required pamselinux.so close", "session required pamloginuid.so", "session required pamunix.so", "session required pamselinux.so open", "In the second example the module is called both in the auth and account phases and the module", "informs the authenticating user when the account is locked if silent option is not specified", "in the faillock.conf.", "auth required pamsecuretty.so", "auth required pamenv.so", "auth required pamnologin.so", "auth required pamfaillock.so preauth", "# optionally use requisite above if you do not want to prompt for the password", "# on locked accounts", "auth sufficient pamunix.so", "auth [default=die] pamfaillock.so authfail", "auth required pamdeny.so", "account required pamfaillock.so", "# if you drop the above call to pamfaillock.so the lock will be done also", "# on non-consecutive authentication failures", "account required pamunix.so", "password required pamunix.so shadow", "session required pamselinux.so close", "session required pamloginuid.so", "session required pamunix.so", "session required pamselinux.so open" ], "see_also": [ { "name": "faillock", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/faillock/8/json" }, { "name": "faillock.conf", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/faillock.conf/5/json" }, { "name": "pam.conf", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/pam.conf/5/json" }, { "name": "pam.d", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/pam.d/5/json" }, { "name": "pam", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/pam/8/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 7, "subsections": [] }, { "name": "DESCRIPTION", "lines": 8, "subsections": [] }, { "name": "OPTIONS", "lines": 1, "subsections": [ { "name": "{preauth|authfail|authsucc}", "lines": 24 }, { "name": "conf=/path/to/config-file", "lines": 6 } ] }, { "name": "MODULE TYPES PROVIDED", "lines": 2, "subsections": [] }, { "name": "RETURN VALUES", "lines": 19, "subsections": [] }, { "name": "NOTES", "lines": 15, "subsections": [] }, { "name": "EXAMPLES", "lines": 60, "subsections": [] }, { "name": "FILES", "lines": 6, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "AUTHOR", "lines": 5, "subsections": [] } ] } }