]>
Commit | Line | Data |
---|---|---|
28e208a7 LP |
1 | <?xml version='1.0'?> <!--*-nxml-*--> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
28e208a7 | 5 | |
4623eecb AK |
6 | <refentry id="pam_systemd_home" conditional='ENABLE_PAM_HOME' |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
28e208a7 LP |
8 | |
9 | <refentryinfo> | |
10 | <title>pam_systemd_home</title> | |
11 | <productname>systemd</productname> | |
12 | </refentryinfo> | |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>pam_systemd_home</refentrytitle> | |
16 | <manvolnum>8</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>pam_systemd_home</refname> | |
9e6df034 ZJS |
21 | <refpurpose>Authenticate users and mount home directories via <filename>systemd-homed.service</filename> |
22 | </refpurpose> | |
28e208a7 LP |
23 | </refnamediv> |
24 | ||
25 | <refsynopsisdiv> | |
26 | <para><filename>pam_systemd_home.so</filename></para> | |
27 | </refsynopsisdiv> | |
28 | ||
29 | <refsect1> | |
30 | <title>Description</title> | |
31 | ||
32 | <para><command>pam_systemd_home</command> ensures that home directories managed by | |
33 | <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
34 | are automatically activated (mounted) on user login, and are deactivated (unmounted) when the last | |
9e6df034 ZJS |
35 | session of the user ends. For such users, it also provides authentication (when per-user disk encryption |
36 | is used, the disk encryption key is derived from the authentication credential supplied at login time), | |
37 | account management (the <ulink url="https://systemd.io/USER_RECORD/">JSON user record</ulink> embedded in | |
38 | the home store contains account details), and implements the updating of the encryption password (which | |
39 | is also used for user authentication).</para> | |
28e208a7 LP |
40 | </refsect1> |
41 | ||
42 | <refsect1> | |
43 | <title>Options</title> | |
44 | ||
45 | <para>The following options are understood:</para> | |
46 | ||
47 | <variablelist class='pam-directives'> | |
48 | ||
49 | <varlistentry> | |
50 | <term><varname>suspend=</varname></term> | |
51 | ||
52 | <listitem><para>Takes a boolean argument. If true, the home directory of the user will be suspended | |
53 | automatically during system suspend; if false it will remain active. Automatic suspending of the home | |
54 | directory improves security substantially as secret key material is automatically removed from memory | |
2a4be3c5 ZJS |
55 | before the system is put to sleep and must be re-acquired (through user re-authentication) when |
56 | coming back from suspend. It is recommended to set this parameter for all PAM applications that have | |
57 | support for automatically re-authenticating via PAM on system resume. If multiple sessions of the | |
58 | same user are open in parallel the user's home directory will be left unsuspended on system suspend | |
562ffaca LP |
59 | as long as at least one of the sessions does not set this parameter to on. Defaults to |
60 | off.</para> | |
61 | ||
62 | <para>Note that TTY logins generally do not support re-authentication on system resume. | |
63 | Re-authentication on system resume is primarily a concept implementable in graphical environments, in | |
64 | the form of lock screens brought up automatically when the system goes to sleep. This means that if a | |
65 | user concurrently uses graphical login sessions that implement the required re-authentication | |
66 | mechanism and console logins that do not, the home directory is not locked during suspend, due to the | |
67 | logic explained above. That said, it is possible to set this field for TTY logins too, ignoring the | |
68 | fact that TTY logins actually don't support the re-authentication mechanism. In that case the TTY | |
69 | sessions will appear hung until the user logs in on another virtual terminal (regardless if via | |
70 | another TTY session or graphically) which will resume the home directory and unblock the original TTY | |
71 | session. (Do note that lack of screen locking on TTY sessions means even though the TTY session | |
72 | appears hung, keypresses can still be queued into it, and the existing screen contents be read | |
73 | without re-authentication; this limitation is unrelated to the home directory management | |
74 | <command>pam_systemd_home</command> and <filename>systemd-homed.service</filename> implement.)</para> | |
75 | ||
76 | <para>Turning this option on by default is highly recommended for all sessions, but only if the | |
77 | service managing these sessions correctly implements the aforementioned re-authentication. Note that | |
86b52a39 | 78 | the re-authentication must take place from a component running outside of the user's context, so that |
562ffaca LP |
79 | it does not require access to the user's home directory for operation. Traditionally, most desktop |
80 | environments do not implement screen locking this way, and need to be updated | |
764ae4dd LP |
81 | accordingly.</para> |
82 | ||
83 | <para>This setting may also be controlled via the <varname>$SYSTEMD_HOME_SUSPEND</varname> | |
84 | environment variable (see below), which <command>pam_systemd_home</command> reads during initialization and sets | |
85 | for sessions. If both the environment variable is set and the module parameter specified the latter | |
ec07c3c8 AK |
86 | takes precedence.</para> |
87 | ||
88 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
28e208a7 LP |
89 | </varlistentry> |
90 | ||
91 | <varlistentry> | |
92 | <term><varname>debug</varname><optional>=</optional></term> | |
93 | ||
94 | <listitem><para>Takes an optional boolean argument. If yes or without the argument, the module will log | |
ec07c3c8 AK |
95 | debugging information as it operates.</para> |
96 | ||
97 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
28e208a7 LP |
98 | </varlistentry> |
99 | </variablelist> | |
100 | </refsect1> | |
101 | ||
102 | <refsect1> | |
103 | <title>Module Types Provided</title> | |
104 | ||
8b9f0921 ZJS |
105 | <para>The module implements all four PAM operations: <option>auth</option> (to allow authentication using |
106 | the encrypted data), <option>account</option> (because users with | |
9e6df034 ZJS |
107 | <filename>systemd-homed.service</filename> user accounts are described in a <ulink |
108 | url="https://systemd.io/USER_RECORD/">JSON user record</ulink> and may be configured in more detail than | |
8b9f0921 ZJS |
109 | in the traditional Linux user database), <option>session</option> (because user sessions must be tracked |
110 | in order to implement automatic release when the last session of the user is gone), | |
111 | <option>password</option> (to change the encryption password — also used for user authentication — | |
112 | through PAM).</para> | |
28e208a7 LP |
113 | </refsect1> |
114 | ||
115 | <refsect1> | |
116 | <title>Environment</title> | |
117 | ||
118 | <para>The following environment variables are initialized by the module and available to the processes of the | |
119 | user's session:</para> | |
120 | ||
121 | <variablelist class='environment-variables'> | |
122 | <varlistentry> | |
123 | <term><varname>$SYSTEMD_HOME=1</varname></term> | |
124 | ||
ec07c3c8 AK |
125 | <listitem><para>Indicates that the user's home directory is managed by <filename>systemd-homed.service</filename>.</para> |
126 | ||
127 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
28e208a7 LP |
128 | </varlistentry> |
129 | ||
764ae4dd LP |
130 | <varlistentry> |
131 | <term><varname>$SYSTEMD_HOME_SUSPEND=</varname></term> | |
132 | ||
133 | <listitem><para>Indicates whether the session has been registered with the suspend mechanism enabled | |
134 | or disabled (see above). The variable's value is either <literal>0</literal> or | |
135 | <literal>1</literal>. Note that the module both reads the variable when initializing, and sets it for | |
ec07c3c8 AK |
136 | sessions.</para> |
137 | ||
138 | <xi:include href="version-info.xml" xpointer="v246"/></listitem> | |
764ae4dd LP |
139 | </varlistentry> |
140 | ||
28e208a7 LP |
141 | </variablelist> |
142 | </refsect1> | |
143 | ||
144 | <refsect1> | |
145 | <title>Example</title> | |
146 | ||
147 | <para>Here's an example PAM configuration fragment that permits users managed by | |
148 | <filename>systemd-homed.service</filename> to log in:</para> | |
149 | ||
150 | <programlisting>#%PAM-1.0 | |
151 | auth sufficient pam_unix.so | |
c6472bb0 | 152 | <command>-auth sufficient pam_systemd_home.so</command> |
28e208a7 LP |
153 | auth required pam_deny.so |
154 | ||
155 | account required pam_nologin.so | |
c6472bb0 | 156 | <command>-account sufficient pam_systemd_home.so</command> |
28e208a7 LP |
157 | account sufficient pam_unix.so |
158 | account required pam_permit.so | |
159 | ||
c6472bb0 | 160 | <command>-password sufficient pam_systemd_home.so</command> |
971c07fc | 161 | password sufficient pam_unix.so sha512 shadow try_first_pass use_authtok |
28e208a7 LP |
162 | password required pam_deny.so |
163 | ||
164 | -session optional pam_keyinit.so revoke | |
165 | -session optional pam_loginuid.so | |
c6472bb0 | 166 | <command>-session optional pam_systemd_home.so</command> |
28e208a7 LP |
167 | -session optional pam_systemd.so |
168 | session required pam_unix.so</programlisting> | |
169 | </refsect1> | |
170 | ||
171 | <refsect1> | |
172 | <title>See Also</title> | |
13a69c12 DT |
173 | <para><simplelist type="inline"> |
174 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
175 | <member><citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
176 | <member><citerefentry><refentrytitle>homed.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
177 | <member><citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
178 | <member><citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
179 | <member><citerefentry project='man-pages'><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
180 | <member><citerefentry project='man-pages'><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
181 | <member><citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
182 | </simplelist></para> | |
28e208a7 LP |
183 | </refsect1> |
184 | ||
185 | </refentry> |