faillog
View and manage user login failure records
SYNOPSIS
faillog [OPTIONS] [USER...]
PARAMETERS
-a, --all
Display faillog records for all users registered on the system. This option is often used in conjunction with -r to reset all failed login attempts or -m to set maximum attempts for all users.
-u USER, --user USER
Specify one or more user names for whom to display or modify faillog records. This is used to target specific accounts. Multiple users can be specified separated by spaces.
-r, --reset
Reset the failed login count for the specified user(s) or for all users if used with -a. This is commonly used to unlock an account that has been temporarily locked due to too many failed login attempts.
-t DAYS, --time DAYS
Display faillog records that are more recent than the specified number of DAYS. This allows filtering the output to show only recent failed attempts.
-m MAX, --maximum MAX
Set the maximum number of consecutive failed login attempts allowed for a user before their account is locked. This option must be used with -u or -a.
DESCRIPTION
faillog is a command-line utility used to display and manage a log of failed login attempts for users on a Linux system. It's a crucial tool for system administrators to monitor potential brute-force attacks and manage user account security. The command primarily interacts with the /var/log/faillog file, which stores information such as the number of consecutive failed login attempts, the time of the last failure, and the terminal from which the attempt originated.
While faillog can display this information for all users or specific users, it also provides options to reset the failed login count, which can be necessary to unlock a user's account after too many incorrect password entries. Furthermore, it can be used to set a maximum number of allowed failed attempts for a user, though the actual locking policy is typically enforced by Pluggable Authentication Modules (PAM) like pam_faillock. Accessing or modifying all user records generally requires root privileges.
CAVEATS
Viewing or modifying faillog records for all users (e.g., with -a or -r without -u) typically requires root privileges.
The faillog file (/var/log/faillog) is a sparse file, not a plain text file, and should not be edited manually or viewed with standard text utilities like cat or less.
While faillog stores the data, the actual enforcement of account locking policies (e.g., temporarily locking an account after N failures) is handled by Pluggable Authentication Modules (PAM), specifically pam_faillock.so, which reads from and writes to the faillog file.
This command primarily tracks local login failures. Other services (like SSH) might also contribute to faillog entries if configured through PAM, but their own logging mechanisms might also exist.
FILE LOCATION
The faillog data is stored in the /var/log/faillog file. This file is not a human-readable text file and should only be accessed and managed by the faillog command itself or other tools designed to interact with its specific format.
PAM INTEGRATION
The primary mechanism for enforcing account lockout policies based on failed login attempts on modern Linux systems is through PAM (Pluggable Authentication Modules), particularly the pam_faillock.so module. This module leverages the faillog file to track failures and apply configured policies, such as temporarily locking an account. faillog itself provides the interface to view and reset this underlying data, but PAM handles the real-time policy enforcement.
SECURITY AUDITING
faillog output can be valuable for security auditing, allowing administrators to quickly identify users experiencing numerous failed login attempts, which might indicate a brute-force attack or a user repeatedly forgetting their password. Regularly reviewing faillog data helps maintain system security.
HISTORY
faillog is a longstanding utility that has been part of the shadow-utils package for many years. The shadow-utils project emerged to enhance system security by separating sensitive user account information (like hashed passwords) from public files. faillog provides a simple and standardized way to record and manage failed login attempts, an essential feature for identifying and mitigating brute-force attacks against user accounts. Its core functionality has remained consistent, serving as the data backend for more sophisticated PAM-based authentication policies.