pam_mkhomedir

pam_mkhomedir is a PAM module configured within PAM configuration files, typically found in the /etc/pam.d/ directory. Its configuration follows the standard PAM module syntax:
module_type control_flag module_path [options]
For pam_mkhomedir, it is almost exclusively used as a session module, often with the optional control flag:
session optional pam_mkhomedir.so [options]
Common placements include /etc/pam.d/common-session or /etc/pam.d/system-auth, ensuring it runs for most login types.

skel=/path/to/skel
    Specifies an alternative skeleton directory from which to copy files and directories for the new home directory. The default is /etc/skel.

umask=0XXX
    Sets the umask (file mode creation mask) to be applied when creating the home directory. This masks out specific permission bits. The default umask is 077.

mode=0XXX
    Sets the explicit permission mode (octal) for the newly created home directory. This option overrides any specified umask. The default mode is 0700.

subdir_perms=0XXX
    Sets the permissions (octal) for any subdirectories copied from the skeleton directory. The default is 0700.

usergroups
    If specified, ensures that a user's private group (UPG) is created if it does not already exist. This is useful for systems where UPGs are not automatically handled by user creation tools.

silent
    Suppresses output messages to stderr, making operations quieter and reducing log verbosity.

debug
    Enables debug logging for the module, providing more verbose output to assist with troubleshooting and understanding module behavior.

The pam_mkhomedir module is a Pluggable Authentication Module (PAM) designed to automatically create a user's home directory if it does not already exist upon their first successful login. This module is essential for simplifying user management in multi-user systems, as it automates a typically manual setup step. Upon creation, it populates the new home directory by copying files and directories from a specified skeleton directory, usually /etc/skel, ensuring new users have a consistent and pre-configured environment. It also handles setting the correct ownership and permissions for the newly created directory, which is crucial for security and user privacy. pam_mkhomedir is commonly configured within the PAM session stack, allowing it to execute during the establishment of a user's login session.

Incorrect configuration of umask or mode options can lead to insecure home directories with overly permissive settings. The module only creates the home directory and copies skeleton files; it does not handle the creation of the user account itself. Ensure the specified skeleton directory (e.g., /etc/skel) is secure and contains only appropriate default files and settings. For correct functionality, the module must be placed within the session stack of PAM configuration files.

pam_mkhomedir is almost exclusively configured as a session module. This type signifies that it runs when a user's session is being established (or terminated). The most common control flag associated with it is optional. An optional flag means that if the module encounters a non-critical failure (e.g., low disk space preventing directory creation), the overall authentication or session establishment process will still continue, preventing a user from being locked out. While other flags like required could be used for stricter enforcement, optional is typically preferred to balance security with usability for home directory creation.

The /etc/skel directory serves as the default template for new user home directories created by pam_mkhomedir. It should contain standard dotfiles (e.g., .bashrc, .profile, .config/) and any other default directories or files that users need upon their first login. Maintaining and securing this directory is critical, as its contents are replicated for every new user, directly impacting their initial environment and the system's security posture.

The pam_mkhomedir module is a fundamental component of the Linux-PAM (Pluggable Authentication Modules) framework, which emerged as a standard for modularizing authentication services on Linux systems. It has been present since the early days of Linux-PAM, addressing the common need for automatic home directory provisioning in multi-user environments. Its development was driven by the goal of simplifying system administration tasks, ensuring that new user accounts are consistently set up with their necessary home directories and default configurations without requiring manual intervention, thereby enhancing both efficiency and security.

pam(8), pam.conf(5), pam.d(5), useradd(8), adduser(8), skel(5)