pam_userdb

auth [control] pam_userdb.so [options]
account [control] pam_userdb.so [options]
password [control] pam_userdb.so [options]

db=/path/to/file
    Specifies the absolute path to the Berkeley DB user database file. The default path is usually /etc/security/userdb.db.

crypt=
    Sets the cryptographic hash algorithm to be used for storing and verifying passwords. Common types include md5, sha256, sha512, and blowfish (bcrypt). If not specified, the system default is used.

config_file=/path/to/file
    Points to a configuration file that contains additional parameters for the chosen cryptographic algorithm, such as the number of rounds for bcrypt (blowfish).

read_only
    When present, this option prevents the module from making any modifications to the database file, especially when used with the password module type (e.g., for password changes).

debug
    Enables verbose debugging output, which can be useful for troubleshooting PAM configuration issues. Messages are typically logged to syslog.

pam_userdb.so is a PAM (Pluggable Authentication Modules) module that provides authentication and account management services by querying a simple database file, typically a Berkeley DB file named userdb.db.

This module is particularly useful for managing specific sets of user accounts for particular services, allowing them to operate independently of the system's primary user databases like /etc/passwd or /etc/shadow. It retrieves username and hashed password pairs from the specified database to verify user credentials during login or other authentication processes.

While primarily focused on authentication, pam_userdb.so can also handle basic account management aspects, such as checking account validity or expiry, if supported by the database structure and module configuration. Its integration occurs within PAM configuration files (e.g., in /etc/pam.d/), where it is specified as an auth or account module. The database file itself needs to be pre-created and maintained using appropriate external database utilities from the Berkeley DB package.

The userdb.db file must be manually created and maintained using external Berkeley DB utilities like db_load or db_dump. It is not managed directly by standard user management commands like useradd or passwd.

Proper file permissions for the userdb.db file are critical for security; it should typically be owned by root and have restrictive permissions (e.g., 0600) to prevent unauthorized access.

This module is generally not recommended for large-scale user management; more robust solutions like LDAP or Kerberos are better suited for enterprise environments.

Password changes via the pam_passwd utility will only function if pam_userdb.so is configured as a password module type and the read_only option is not set.

The userdb.db file is a Berkeley DB hash file. It's typically populated from a plain text file containing username:password_hash pairs, or sometimes username:password (if the crypt option is handled by the module), using the db_load utility.

Example for creating a database with a SHA512 hashed password:
1. Generate password hash: openssl passwd -6 -salt $(head /dev/urandom | tr -dc A-Za-z0-9_.- | head -c 16) your_password_here
2. Create a temporary text file (e.g., userdb.txt):
your_username_here:your_sha512_hash_here
3. Load into DB: db_load -T -t hash -f userdb.txt userdb.db
4. Set permissions: chmod 600 userdb.db && chown root:root userdb.db
Ensure the userdb.db file is placed in a secure location, e.g., /etc/security/.

pam_userdb.so is commonly integrated into PAM configuration files (e.g., in /etc/pam.d/system-auth or a service-specific file like /etc/pam.d/ftp) using the auth and account module types:

Authentication:
auth sufficient pam_userdb.so db=/etc/security/userdb.db crypt=sha512

Account Management:
account sufficient pam_userdb.so db=/etc/security/userdb.db

The control flag (e.g., sufficient, required, requisite, optional) determines how the module's success or failure affects the overall PAM stack processing.

pam_userdb.so is a component of the Linux-PAM project, which provides a flexible and modular approach to authentication services on Linux systems. It was developed to offer a simple, file-based alternative for user authentication, serving specific use cases where traditional system accounts or complex directory services are not required or desired. Its usage often involves specialized applications or environments needing an isolated, self-contained user database, making it a versatile tool for specific authentication challenges.

pam(8), pam.conf(5), db_load(1), db_dump(1), openssl(1)