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

NAME

6       pam_systemd_home - Authenticate users and mount home directories via
7       systemd-homed.service
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       For such users, it also provides authentication (when per-user disk
17       encryption is used, the disk encryption key is derived from the
18       authentication credential supplied at login time), account management
19       (the JSON user record[1] embedded in the home store contains account
20       details), and implements the updating of the encryption password (which
21       is also used for user authentication).
22

OPTIONS

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

MODULE TYPES PROVIDED

80       The module implements all four PAM operations: auth (reason: to allow
81       authentication using the encrypted data), account (reason: users with
82       systemd-homed.service user accounts are described in a JSON user
83       record[1] and may be configured in more detail than in the traditional
84       Linux user database), session (user sessions must be tracked in order
85       to implement automatic release when the last session of the user is
86       gone), password (to change the encryption password — also used for user
87       authentication — through PAM).
88

ENVIRONMENT

90       The following environment variables are initialized by the module and
91       available to the processes of the user's session:
92
93       $SYSTEMD_HOME=1
94           Indicates that the user's home directory is managed by
95           systemd-homed.service.
96
97       $SYSTEMD_HOME_SUSPEND=
98           Indicates whether the session has been registered with the suspend
99           mechanism enabled or disabled (see above). The variable's value is
100           either "0" or "1". Note that the module both reads the variable
101           when initializing, and sets it for sessions.
102

EXAMPLE

104       Here's an example PAM configuration fragment that permits users managed
105       by systemd-homed.service to log in:
106
107           #%PAM-1.0
108           auth      sufficient pam_unix.so
109           -auth     sufficient pam_systemd_home.so
110           auth      required   pam_deny.so
111
112           account   required   pam_nologin.so
113           -account  sufficient pam_systemd_home.so
114           account   sufficient pam_unix.so
115           account   required   pam_permit.so
116
117           -password sufficient pam_systemd_home.so
118           password  sufficient pam_unix.so sha512 shadow try_first_pass use_authtok
119           password  required   pam_deny.so
120
121           -session  optional   pam_keyinit.so revoke
122           -session  optional   pam_loginuid.so
123           -session  optional   pam_systemd_home.so
124           -session  optional   pam_systemd.so
125           session   required   pam_unix.so
126

SEE ALSO

128       systemd(1), systemd-homed.service(8), homed.conf(5), homectl(1),
129       pam_systemd(8), pam.conf(5), pam.d(5), pam(8)
130

NOTES

132        1. JSON user record
133           https://systemd.io/USER_RECORD/
134
135
136
137systemd 251                                                PAM_SYSTEMD_HOME(8)
Impressum