1PAM_SYSTEMD_HOME(8) pam_systemd_home PAM_SYSTEMD_HOME(8)
2
6 pam_systemd_home - Authenticate users and mount home directories via
7 systemd-homed.service
8
10 pam_systemd_home.so
11
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
24 The following options are understood:
25 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 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 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 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 debug[=]
76 Takes an optional boolean argument. If yes or without the argument,
77 the module will log debugging information as it operates.
78
80 The module implements all four PAM operations: auth (to allow
81 authentication using the encrypted data), account (because 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 (because user sessions must be tracked in
85 order to implement automatic release when the last session of the user
86 is gone), password (to change the encryption password — also used for
87 user authentication — through PAM).
88
90 The following environment variables are initialized by the module and
91 available to the processes of the user's session:
92 $SYSTEMD_HOME=1
94 Indicates that the user's home directory is managed by
95 systemd-homed.service.
96 $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
104 Here's an example PAM configuration fragment that permits users managed
105 by systemd-homed.service to log in:
106 #%PAM-1.0
108 auth sufficient pam_unix.so
109 -auth sufficient pam_systemd_home.so
110 auth required pam_deny.so
111 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 -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 -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
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
132 1. JSON user record
133 https://systemd.io/USER_RECORD/
134systemd 254 PAM_SYSTEMD_HOME(8)