From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/pam_systemd_home.xml | 175 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 man/pam_systemd_home.xml (limited to 'man/pam_systemd_home.xml') diff --git a/man/pam_systemd_home.xml b/man/pam_systemd_home.xml new file mode 100644 index 0000000..ff4735c --- /dev/null +++ b/man/pam_systemd_home.xml @@ -0,0 +1,175 @@ + + + + + + + + pam_systemd_home + systemd + + + + pam_systemd_home + 8 + + + + pam_systemd_home + Authenticate users and mount home directories via systemd-homed.service + + + + + pam_systemd_home.so + + + + Description + + pam_systemd_home ensures that home directories managed by + systemd-homed.service8 + are automatically activated (mounted) on user login, and are deactivated (unmounted) when the last + session of the user ends. For such users, it also provides authentication (when per-user disk encryption + is used, the disk encryption key is derived from the authentication credential supplied at login time), + account management (the JSON user record embedded in + the home store contains account details), and implements the updating of the encryption password (which + is also used for user authentication). + + + + Options + + The following options are understood: + + + + + suspend= + + Takes a boolean argument. If true, the home directory of the user will be suspended + automatically during system suspend; if false it will remain active. Automatic suspending of the home + directory improves security substantially as secret key material is automatically removed from memory + before the system is put to sleep and must be re-acquired (through user re-authentication) when + coming back from suspend. It is recommended to set this parameter for all PAM applications that have + support for automatically re-authenticating via PAM on system resume. If multiple sessions of the + same user are open in parallel the user's home directory will be left unsuspended on system suspend + as long as at least one of the sessions does not set this parameter to on. Defaults to + off. + + Note that TTY logins generally do not support re-authentication on system resume. + Re-authentication on system resume is primarily a concept implementable in graphical environments, in + the form of lock screens brought up automatically when the system goes to sleep. This means that if a + user concurrently uses graphical login sessions that implement the required re-authentication + mechanism and console logins that do not, the home directory is not locked during suspend, due to the + logic explained above. That said, it is possible to set this field for TTY logins too, ignoring the + fact that TTY logins actually don't support the re-authentication mechanism. In that case the TTY + sessions will appear hung until the user logs in on another virtual terminal (regardless if via + another TTY session or graphically) which will resume the home directory and unblock the original TTY + session. (Do note that lack of screen locking on TTY sessions means even though the TTY session + appears hung, keypresses can still be queued into it, and the existing screen contents be read + without re-authentication; this limitation is unrelated to the home directory management + pam_systemd_home and systemd-homed.service implement.) + + Turning this option on by default is highly recommended for all sessions, but only if the + service managing these sessions correctly implements the aforementioned re-authentication. Note that + the re-authentication must take place from a component running outside of the user's context, so that + it does not require access to the user's home directory for operation. Traditionally, most desktop + environments do not implement screen locking this way, and need to be updated + accordingly. + + This setting may also be controlled via the $SYSTEMD_HOME_SUSPEND + environment variable (see below), which pam_systemd_home reads during initialization and sets + for sessions. If both the environment variable is set and the module parameter specified the latter + takes precedence. + + + + debug= + + Takes an optional boolean argument. If yes or without the argument, the module will log + debugging information as it operates. + + + + + + Module Types Provided + + The module implements all four PAM operations: (reason: to allow + authentication using the encrypted data), (reason: users with + systemd-homed.service user accounts are described in a JSON user record and may be configured in more detail than + in the traditional Linux user database), (user sessions must be tracked in order + to implement automatic release when the last session of the user is gone), (to + change the encryption password — also used for user authentication — through PAM). + + + + Environment + + The following environment variables are initialized by the module and available to the processes of the + user's session: + + + + $SYSTEMD_HOME=1 + + Indicates that the user's home directory is managed by systemd-homed.service. + + + + $SYSTEMD_HOME_SUSPEND= + + Indicates whether the session has been registered with the suspend mechanism enabled + or disabled (see above). The variable's value is either 0 or + 1. Note that the module both reads the variable when initializing, and sets it for + sessions. + + + + + + + Example + + Here's an example PAM configuration fragment that permits users managed by + systemd-homed.service to log in: + + #%PAM-1.0 +auth sufficient pam_unix.so +-auth sufficient pam_systemd_home.so +auth required pam_deny.so + +account required pam_nologin.so +-account sufficient pam_systemd_home.so +account sufficient pam_unix.so +account required pam_permit.so + +-password sufficient pam_systemd_home.so +password sufficient pam_unix.so sha512 shadow try_first_pass +password required pam_deny.so + +-session optional pam_keyinit.so revoke +-session optional pam_loginuid.so +-session optional pam_systemd_home.so +-session optional pam_systemd.so +session required pam_unix.so + + + + See Also + + systemd1, + systemd-homed.service8, + homed.conf5, + homectl1, + pam_systemd8, + pam.conf5, + pam.d5, + pam8 + + + + -- cgit v1.2.3