pam_systemd_home(8)

1PAM_SYSTEMD_HOME(8)            pam_systemd_home            PAM_SYSTEMD_HOME(8)
2
3
4

NAME

6       pam_systemd_home - Automatically mount home directories managed by
7       systemd-homed.service on login, and unmount them on logout
8

SYNOPSIS

10       pam_systemd_home.so
11

DESCRIPTION

13       pam_systemd_home ensures that home directories managed by systemd-
14       homed.service(8) are automatically activated (mounted) on user login,
15       and are deactivated (unmounted) when the last session of the user ends.
16

OPTIONS

18       The following options are understood:
19
20       suspend=
21           Takes a boolean argument. If true, the home directory of the user
22           will be suspended automatically during system suspend; if false it
23           will remain active. Automatic suspending of the home directory
24           improves security substantially as secret key material is
25           automatically removed from memory before the system is put to sleep
26           and must be re-acquired (through user re-authentication) when
27           coming back from suspend. It is recommended to set this parameter
28           for all PAM applications that have support for automatically
29           re-authenticating via PAM on system resume. If multiple sessions of
30           the same user are open in parallel the user's home directory will
31           be left unsuspended on system suspend as long as at least one of
32           the sessions does not set this parameter to on. Defaults to off.
33
34           Note that TTY logins generally do not support re-authentication on
35           system resume. Re-authentication on system resume is primarily a
36           concept implementable in graphical environments, in the form of
37           lock screens brought up automatically when the system goes to
38           sleep. This means that if a user concurrently uses graphical login
39           sessions that implement the required re-authentication mechanism
40           and console logins that do not, the home directory is not locked
41           during suspend, due to the logic explained above. That said, it is
42           possible to set this field for TTY logins too, ignoring the fact
43           that TTY logins actually don't support the re-authentication
44           mechanism. In that case the TTY sessions will appear hung until the
45           user logs in on another virtual terminal (regardless if via another
46           TTY session or graphically) which will resume the home directory
47           and unblock the original TTY session. (Do note that lack of screen
48           locking on TTY sessions means even though the TTY session appears
49           hung, keypresses can still be queued into it, and the existing
50           screen contents be read without re-authentication; this limitation
51           is unrelated to the home directory management pam_systemd_home and
52           systemd-homed.service implement.)
53
54           Turning this option on by default is highly recommended for all
55           sessions, but only if the service managing these sessions correctly
56           implements the aforementioned re-authentication. Note that the
57           re-authentication must take place from a component running outside
58           of the user's context, so that it does not require access to the
59           user's home directory for operation. Traditionally, most desktop
60           environments do not implement screen locking this way, and need to
61           be updated accordingly.
62
63           This setting may also be controlled via the $SYSTEMD_HOME_SUSPEND
64           environment variable (see below), which pam_systemd_home reads
65           during initialization and sets for sessions. If both the
66           environment variable is set and the module parameter specified the
67           latter takes precedence.
68
69       debug[=]
70           Takes an optional boolean argument. If yes or without the argument,
71           the module will log debugging information as it operates.
72

MODULE TYPES PROVIDED

74       The module provides all four management operations: auth, account,
75       session, password.
76

ENVIRONMENT

78       The following environment variables are initialized by the module and
79       available to the processes of the user's session:
80
81       $SYSTEMD_HOME=1
82           Indicates that the user's home directory is managed by
83           systemd-homed.service.
84
85       $SYSTEMD_HOME_SUSPEND=
86           Indicates whether the session has been registered with the suspend
87           mechanism enabled or disabled (see above). The variable's value is
88           either "0" or "1". Note that the module both reads the variable
89           when initializing, and sets it for sessions.
90

EXAMPLE

92       Here's an example PAM configuration fragment that permits users managed
93       by systemd-homed.service to log in:
94
95           #%PAM-1.0
96           auth      sufficient pam_unix.so
97           -auth     sufficient pam_systemd_home.so
98           auth      required   pam_deny.so
99
100           account   required   pam_nologin.so
101           -account  sufficient pam_systemd_home.so
102           account   sufficient pam_unix.so
103           account   required   pam_permit.so
104
105           -password sufficient pam_systemd_home.so
106           password  sufficient pam_unix.so sha512 shadow try_first_pass use_authtok
107           password  required   pam_deny.so
108
109           -session  optional   pam_keyinit.so revoke
110           -session  optional   pam_loginuid.so
111           -session  optional   pam_systemd_home.so
112           -session  optional   pam_systemd.so
113           session   required   pam_unix.so
114