pam_zfs_key.8

PAM_ZFS_KEY(8)

System Manager's Manual

PAM_ZFS_KEY(8)

NAME

pam_zfs_key — PAM module for ZFS encryption key management

SYNOPSIS

pam_zfs_key.so

[options]

DESCRIPTION

pam_zfs_key is a PAM module that automatically manages encryption keys for ZFS datasets during user authentication and session management. When a user logs in, the module uses their password to unlock their encrypted home directory. When the last session closes, the module unmounts the dataset and unloads the key.

The module tracks active sessions using reference counting to support multiple simultaneous logins from the same user.

Multiple Home Prefixes

When configured with multiple home prefixes, the module attempts operations on all matching datasets. Operations that succeed are not rolled back if others fail. The module returns success only if all operations succeed.

For example, with datasets 1, 2, 3 where dataset 2 fails:

• Auth/session: datasets 1 and 3 are unlocked and mounted, dataset 2 is not.
• Password change: datasets 1 and 3 have the new password, dataset 2 retains the old.

With required, login fails even though datasets 1 and 3 succeeded. With optional, login proceeds. For password changes, datasets 1 and 3 are updated while dataset 2 retains the old password. With required, the user sees an error. With optional, the user sees success and may not notice the inconsistency. Either way, passwords are left out of sync.

Errors are logged to syslog. Use zfs-change-key(8) to resync passwords after partial failure.

OPTIONS

homes=path[,path2...]

Comma-separated list of dataset prefixes where user home directories are located. The module constructs the full dataset path as prefix/username. Default: zroot/home on FreeBSD, rpool/home on Linux.

runstatedir=path

Directory for storing session reference counts. Default: /var/run/pam_zfs_key.

uid_min=uid

Minimum user ID for which the module will operate. Default: 1000.

uid_max=uid

Maximum user ID for which the module will operate. Default: MAXUID.

nounmount

Do not unmount datasets or unload encryption keys when sessions close. Datasets remain mounted and keys remain loaded.

forceunmount

Force unmount datasets even if busy (MS_FORCE).

recursive_homes

Recursively search for encrypted datasets under the homes prefix.

mount_recursively

Mount and unmount child datasets recursively.

prop_mountpoint

Find the user's dataset by matching the dataset's mountpoint property to the user's home directory from /etc/passwd, instead of constructing the dataset name as prefix/username.

FILES

/var/run/pam_zfs_key/uid

Session reference count files tracking active logins per user.

EXAMPLES

Example 1: Basic Configuration

Add to /etc/pam.d/system-auth:

auth     optional  pam_zfs_key.so
password optional  pam_zfs_key.so
session  optional  pam_zfs_key.so

This configuration uses default settings. User home datasets are expected at zroot/home/username on FreeBSD or rpool/home/username on Linux.

Example 2: Custom Home Directory Prefix

auth     optional  pam_zfs_key.so homes=tank/users
password optional  pam_zfs_key.so homes=tank/users
session  optional  pam_zfs_key.so homes=tank/users

Looks for user datasets at tank/users/username.

Example 3: Multiple Dataset Prefixes

session  optional  pam_zfs_key.so homes=rpool/home,tank/users

Searches for user datasets in both rpool/home and tank/users.

Example 4: Keep Datasets Mounted

session  optional  pam_zfs_key.so nounmount

Leaves datasets mounted and keys loaded when sessions close. Useful for systems with background processes accessing the home directory.

Example 5: Recursive Mounting

session  optional  pam_zfs_key.so mount_recursively

Mounts child datasets recursively, useful when user data is organized hierarchically like rpool/home/alice/documents and rpool/home/alice/photos.

Example 6: Creating an Encrypted Home Dataset

# zfs create -o encryption=on \
    -o keyformat=passphrase \
    -o keylocation=prompt \
    -o canmount=on \
    -o mountpoint=/home/alice \
    rpool/home/alice

The user's login password must match the dataset passphrase for automatic unlocking to work. The dataset must have a ZFS-managed mountpoint (not legacy) and canmount=on for automatic mounting.

Example 7: Multiple Homes with Password Sync Check

auth     optional  pam_zfs_key.so homes=rpool/home,tank/home
password required  pam_zfs_key.so homes=rpool/home,tank/home
session  optional  pam_zfs_key.so homes=rpool/home,tank/home

Login proceeds even if some datasets are unavailable. Password changes fail if any dataset cannot be updated, ensuring the user is notified of sync issues. See Multiple Home Prefixes for failure behavior.

SEE ALSO

zfs-change-key(8), zfs-load-key(8), zfs-mount(8)

NOTES

• Only works with datasets using keyformat=passphrase.
• Datasets must have keylocation=prompt.
• Datasets with mountpoint=legacy, canmount=off, or canmount=noauto will have keys loaded but not be automatically mounted.

December 24, 2025

Debian