mirror of
https://git.proxmox.com/git/mirror_zfs.git
synced 2026-05-22 02:27:36 +03:00
Added support for multiple homes in pam_zfs_key module (#18084)
This implemented support for having multiple datasets unlocked and mounted when a session is opened. Example: `homes=rpool/home,tank/users` Extra unit tests have been added A man page documents have been added `man 8 pam_zfs_key`. A few references to the new man page have also been added in other documents. Signed-off-by: Dennis Vestergaard Værum <github@varum.dk> Reviewed-by: Tony Hutter <hutter2@llnl.gov> Reviewed-by: Tino Reichardt <milky-zfs@mcmilk.de>
This commit is contained in:
Dennis Værum
@@ -0,0 +1,221 @@
|
||||
.\" SPDX-License-Identifier: BSD-3-Clause
|
||||
.\"
|
||||
.\" Copyright (c) 2020, Felix Dörre
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.Dd December 24, 2025
|
||||
.Dt PAM_ZFS_KEY 8
|
||||
.Os
|
||||
.
|
||||
.Sh NAME
|
||||
.Nm pam_zfs_key
|
||||
.Nd PAM module for ZFS encryption key management
|
||||
.Sh SYNOPSIS
|
||||
.Nm pam_zfs_key.so
|
||||
.Op Ar options
|
||||
.
|
||||
.Sh DESCRIPTION
|
||||
.Nm
|
||||
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.
|
||||
.Pp
|
||||
The module tracks active sessions using reference counting to support multiple
|
||||
simultaneous logins from the same user.
|
||||
.Ss 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.
|
||||
.Pp
|
||||
For example, with datasets 1, 2, 3 where dataset 2 fails:
|
||||
.Bl -bullet -compact
|
||||
.It
|
||||
Auth/session: datasets 1 and 3 are unlocked and mounted, dataset 2 is not.
|
||||
.It
|
||||
Password change: datasets 1 and 3 have the new password,
|
||||
dataset 2 retains the old.
|
||||
.El
|
||||
.Pp
|
||||
With
|
||||
.Sy required ,
|
||||
login fails even though datasets 1 and 3 succeeded.
|
||||
With
|
||||
.Sy optional ,
|
||||
login proceeds.
|
||||
For password changes, datasets 1 and 3 are updated while dataset 2
|
||||
retains the old password.
|
||||
With
|
||||
.Sy required ,
|
||||
the user sees an error.
|
||||
With
|
||||
.Sy optional ,
|
||||
the user sees success and may not notice the inconsistency.
|
||||
Either way, passwords are left out of sync.
|
||||
.Pp
|
||||
Errors are logged to syslog.
|
||||
Use
|
||||
.Xr zfs-change-key 8
|
||||
to resync passwords after partial failure.
|
||||
.
|
||||
.Sh OPTIONS
|
||||
.Bl -tag -width "mount_recursively"
|
||||
.It Sy homes Ns = Ns Ar path Ns Oo , Ns Ar path2 Ns ... Oc
|
||||
Comma-separated list of dataset prefixes where user home directories
|
||||
are located.
|
||||
The module constructs the full dataset path as
|
||||
.Ar prefix Ns / Ns Ar username .
|
||||
Default:
|
||||
.Sy zroot/home
|
||||
on
|
||||
.Fx ,
|
||||
.Sy rpool/home
|
||||
on Linux.
|
||||
.It Sy runstatedir Ns = Ns Ar path
|
||||
Directory for storing session reference counts.
|
||||
Default:
|
||||
.Pa /var/run/pam_zfs_key .
|
||||
.It Sy uid_min Ns = Ns Ar uid
|
||||
Minimum user ID for which the module will operate.
|
||||
Default: 1000.
|
||||
.It Sy uid_max Ns = Ns Ar uid
|
||||
Maximum user ID for which the module will operate.
|
||||
Default: MAXUID.
|
||||
.It Sy nounmount
|
||||
Do not unmount datasets or unload encryption keys when sessions close.
|
||||
Datasets remain mounted and keys remain loaded.
|
||||
.It Sy forceunmount
|
||||
Force unmount datasets even if busy
|
||||
.Pq Dv MS_FORCE .
|
||||
.It Sy recursive_homes
|
||||
Recursively search for encrypted datasets under the homes prefix.
|
||||
.It Sy mount_recursively
|
||||
Mount and unmount child datasets recursively.
|
||||
.It Sy prop_mountpoint
|
||||
Find the user's dataset by matching the dataset's
|
||||
.Sy mountpoint
|
||||
property to the user's home directory from
|
||||
.Pa /etc/passwd ,
|
||||
instead of constructing the dataset name as
|
||||
.Ar prefix Ns / Ns Ar username .
|
||||
.El
|
||||
.
|
||||
.Sh FILES
|
||||
.Bl -tag -width Pa
|
||||
.It Pa /var/run/pam_zfs_key/ Ns Ar uid
|
||||
Session reference count files tracking active logins per user.
|
||||
.El
|
||||
.
|
||||
.Sh EXAMPLES
|
||||
.Ss Example 1: Basic Configuration
|
||||
Add to
|
||||
.Pa /etc/pam.d/system-auth :
|
||||
.Bd -literal -offset indent
|
||||
auth optional pam_zfs_key.so
|
||||
password optional pam_zfs_key.so
|
||||
session optional pam_zfs_key.so
|
||||
.Ed
|
||||
.Pp
|
||||
This configuration uses default settings.
|
||||
User home datasets are expected at
|
||||
.Sy zroot/home/ Ns Ar username
|
||||
on
|
||||
.Fx
|
||||
or
|
||||
.Sy rpool/home/ Ns Ar username
|
||||
on Linux.
|
||||
.
|
||||
.Ss Example 2: Custom Home Directory Prefix
|
||||
.Bd -literal -offset indent
|
||||
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
|
||||
.Ed
|
||||
.Pp
|
||||
Looks for user datasets at
|
||||
.Sy tank/users/ Ns Ar username .
|
||||
.
|
||||
.Ss Example 3: Multiple Dataset Prefixes
|
||||
.Bd -literal -offset indent
|
||||
session optional pam_zfs_key.so homes=rpool/home,tank/users
|
||||
.Ed
|
||||
.Pp
|
||||
Searches for user datasets in both
|
||||
.Sy rpool/home
|
||||
and
|
||||
.Sy tank/users .
|
||||
.
|
||||
.Ss Example 4: Keep Datasets Mounted
|
||||
.Bd -literal -offset indent
|
||||
session optional pam_zfs_key.so nounmount
|
||||
.Ed
|
||||
.Pp
|
||||
Leaves datasets mounted and keys loaded when sessions close.
|
||||
Useful for systems with background processes accessing the home directory.
|
||||
.
|
||||
.Ss Example 5: Recursive Mounting
|
||||
.Bd -literal -offset indent
|
||||
session optional pam_zfs_key.so mount_recursively
|
||||
.Ed
|
||||
.Pp
|
||||
Mounts child datasets recursively, useful when user data is organized
|
||||
hierarchically like
|
||||
.Sy rpool/home/alice/documents
|
||||
and
|
||||
.Sy rpool/home/alice/photos .
|
||||
.
|
||||
.Ss Example 6: Creating an Encrypted Home Dataset
|
||||
.Bd -literal -offset indent
|
||||
# zfs create -o encryption=on \e
|
||||
-o keyformat=passphrase \e
|
||||
-o keylocation=prompt \e
|
||||
-o canmount=on \e
|
||||
-o mountpoint=/home/alice \e
|
||||
rpool/home/alice
|
||||
.Ed
|
||||
.Pp
|
||||
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
|
||||
.Sy canmount Ns = Ns Sy on
|
||||
for automatic mounting.
|
||||
.
|
||||
.Ss Example 7: Multiple Homes with Password Sync Check
|
||||
.Bd -literal -offset indent
|
||||
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
|
||||
.Ed
|
||||
.Pp
|
||||
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
|
||||
.Sx Multiple Home Prefixes
|
||||
for failure behavior.
|
||||
.
|
||||
.Sh SEE ALSO
|
||||
.Xr pam 8 ,
|
||||
.Xr zfs-change-key 8 ,
|
||||
.Xr zfs-load-key 8 ,
|
||||
.Xr zfs-mount 8
|
||||
.
|
||||
.Sh NOTES
|
||||
.Bl -bullet -compact
|
||||
.It
|
||||
Only works with datasets using
|
||||
.Sy keyformat Ns = Ns Sy passphrase .
|
||||
.It
|
||||
Datasets must have
|
||||
.Sy keylocation Ns = Ns Sy prompt .
|
||||
.It
|
||||
Datasets with
|
||||
.Sy mountpoint Ns = Ns Sy legacy ,
|
||||
.Sy canmount Ns = Ns Sy off ,
|
||||
or
|
||||
.Sy canmount Ns = Ns Sy noauto
|
||||
will have keys loaded but not be automatically mounted.
|
||||
.El
|
||||
@@ -92,6 +92,9 @@ will ask for the key and mount the dataset
|
||||
see
|
||||
.Xr zfs-mount 8
|
||||
.Pc .
|
||||
For automated key management during user login,
|
||||
.Xr pam_zfs_key 8
|
||||
can load keys and mount encrypted home directories on systems with PAM support.
|
||||
Once the key is loaded the
|
||||
.Sy keystatus
|
||||
property will become
|
||||
@@ -301,5 +304,6 @@ written.
|
||||
.
|
||||
.Sh SEE ALSO
|
||||
.Xr zfsprops 7 ,
|
||||
.Xr pam_zfs_key 8 ,
|
||||
.Xr zfs-create 8 ,
|
||||
.Xr zfs-set 8
|
||||
|
||||
@@ -110,6 +110,9 @@ on each encryption root before mounting it.
|
||||
Note that if a filesystem has
|
||||
.Sy keylocation Ns = Ns Sy prompt ,
|
||||
this will cause the terminal to interactively block after asking for the key.
|
||||
On systems with PAM support,
|
||||
.Xr pam_zfs_key 8
|
||||
can automate this process during user login.
|
||||
.It Fl v
|
||||
Report mount progress.
|
||||
.It Fl f
|
||||
@@ -138,3 +141,6 @@ The command can also be given a path to a ZFS file system mount point on the
|
||||
system.
|
||||
.El
|
||||
.El
|
||||
.
|
||||
.Sh SEE ALSO
|
||||
.Xr pam_zfs_key 8
|
||||
|
||||
@@ -805,6 +805,7 @@ don't wait.
|
||||
.Xr exportfs 8 ,
|
||||
.Xr mount 8 ,
|
||||
.Xr net 8 ,
|
||||
.Xr pam_zfs_key 8 ,
|
||||
.Xr selinux 8 ,
|
||||
.Xr zfs-allow 8 ,
|
||||
.Xr zfs-bookmark 8 ,
|
||||
|
||||
Reference in New Issue
Block a user