1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="pam_systemd" conditional='HAVE_PAM'>
27 <title>pam_systemd</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>pam_systemd</refentrytitle>
42 <manvolnum>8</manvolnum>
46 <refname>pam_systemd</refname>
47 <refpurpose>Register user sessions in the systemd login manager</refpurpose>
51 <para><filename>pam_systemd.so</filename></para>
55 <title>Description</title>
57 <para><command>pam_systemd</command> registers user
58 sessions in the systemd login manager
59 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
60 and hence the systemd control group hierarchy.</para>
62 <para>On login, this module ensures the following:</para>
65 <listitem><para>If it does not exist yet, the
66 user runtime directory
67 <filename>/run/user/$USER</filename> is
68 created and its ownership changed to the user
69 that is logging in.</para></listitem>
72 <varname>$XDG_SESSION_ID</varname> environment
73 variable is initialized. If auditing is
75 <command>pam_loginuid.so</command> run before
76 this module (which is highly recommended), the
77 variable is initialized from the auditing
79 (<filename>/proc/self/sessionid</filename>). Otherwise
80 an independent session counter is
81 used.</para></listitem>
83 <listitem><para>A new control group
84 <filename>/user/$USER/$XDG_SESSION_ID</filename>
85 is created and the login process moved into
89 <para>On logout, this module ensures the following:</para>
93 <varname>$XDG_SESSION_ID</varname> is set and
94 <option>kill-session-processes=1</option> specified, all
95 remaining processes in the
96 <filename>/user/$USER/$XDG_SESSION_ID</filename>
97 control group are killed and the control group
98 is removed.</para></listitem>
100 <listitem><para>If the last subgroup of the
101 <filename>/user/$USER</filename> control group
103 <varname>$XDG_RUNTIME_DIR</varname> directory
104 and all its contents are
105 removed, too.</para></listitem>
108 <para>If the system was not booted up with systemd as
109 init system, this module does nothing and immediately
110 returns PAM_SUCCESS.</para>
115 <title>Options</title>
117 <para>The following options are understood:</para>
119 <variablelist class='pam-directives'>
121 <term><option>kill-session-processes=</option></term>
123 <listitem><para>Takes a boolean
124 argument. If true, all processes
125 created by the user during his session
126 and from his session will be
127 terminated when he logs out from his
128 session.</para></listitem>
132 <term><option>kill-only-users=</option></term>
134 <listitem><para>Takes a comma
135 separated list of user names or
136 numeric user ids as argument. If this
137 option is used the effect of the
138 <option>kill-session-processes=</option> options
139 will apply only to the listed
140 users. If this option is not used the
141 option applies to all local
143 <option>kill-exclude-users=</option>
144 takes precedence over this list and is
145 hence subtracted from the list
146 specified here.</para></listitem>
150 <term><option>kill-exclude-users=</option></term>
152 <listitem><para>Takes a comma
153 separated list of user names or
154 numeric user ids as argument. Users
155 listed in this argument will not be
156 subject to the effect of
157 <option>kill-session-processes=</option>. Note
158 that this option takes precedence
160 <option>kill-only-users=</option>, and
161 hence whatever is listed for
162 <option>kill-exclude-users=</option>
163 is guaranteed to never be killed by
164 this PAM module, independent of any
166 setting.</para></listitem>
170 <term><option>controllers=</option></term>
172 <listitem><para>Takes a comma
173 separated list of control group
174 controllers in which hierarchies a
175 user/session control group will be
176 created by default for each user
177 logging in, in addition to the control
178 group in the named 'name=systemd'
179 hierarchy. If omitted, defaults to an
180 empty list.</para></listitem>
184 <term><option>reset-controllers=</option></term>
186 <listitem><para>Takes a comma
187 separated list of control group
188 controllers in which hierarchies the
189 logged in processes will be reset to
191 group.</para></listitem>
195 <term><option>class=</option></term>
197 <listitem><para>Takes a string
198 argument which sets the session class.
199 The XDG_SESSION_CLASS environmental variable
200 takes precedence.</para></listitem>
204 <term><option>debug=</option></term>
206 <listitem><para>Takes a boolean
207 argument. If yes, the module will log
208 debugging information as it
209 operates.</para></listitem>
213 <para>Note that setting
214 <varname>kill-session-processes=1</varname> will break tools
216 <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
219 <varname>kill-session-processes=1</varname> is a
221 <varname>KillUserProcesses=1</varname> which may be
222 configured system-wide in
223 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
224 former kills processes of a session as soon as it
225 ends, the latter kills processes as soon as the last
226 session of the user ends.</para>
228 <para>If the options are omitted they default to
229 <option>kill-session-processes=0</option>,
230 <option>kill-only-users=</option>,
231 <option>kill-exclude-users=</option>,
232 <option>controllers=</option>,
233 <option>reset-controllers=</option>,
234 <option>debug=no</option>.</para>
238 <title>Module Types Provided</title>
240 <para>Only <option>session</option> is provided.</para>
244 <title>Environment</title>
246 <para>The following environment variables are set for the processes of the user's session:</para>
248 <variablelist class='environment-variables'>
250 <term><varname>$XDG_SESSION_ID</varname></term>
252 <listitem><para>A session identifier,
253 suitable to be used in file names. The
254 string itself should be considered
255 opaque, although often it is just the
256 audit session ID as reported by
257 <filename>/proc/self/sessionid</filename>. Each
258 ID will be assigned only once during
259 machine uptime. It may hence be used
260 to uniquely label files or other
262 session.</para></listitem>
266 <term><varname>$XDG_RUNTIME_DIR</varname></term>
268 <listitem><para>Path to a user-private
269 user-writable directory that is bound
270 to the user login time on the
271 machine. It is automatically created
272 the first time a user logs in and
273 removed on his final logout. If a user
274 logs in twice at the same time, both
275 sessions will see the same
276 <varname>$XDG_RUNTIME_DIR</varname>
277 and the same contents. If a user logs
278 in once, then logs out again, and logs
279 in again, the directory contents will
280 have been lost in between, but
281 applications should not rely on this
282 behavior and must be able to deal with
283 stale files. To store session-private
284 data in this directory the user should
285 include the value of <varname>$XDG_SESSION_ID</varname>
286 in the filename. This directory shall
287 be used for runtime file system
288 objects such as AF_UNIX sockets,
289 FIFOs, PID files and similar. It is
290 guaranteed that this directory is
291 local and offers the greatest possible
292 file system feature set the
294 provides.</para></listitem>
300 <title>Example</title>
302 <programlisting>#%PAM-1.0
303 auth required pam_unix.so
304 auth required pam_nologin.so
305 account required pam_unix.so
306 password required pam_unix.so
307 session required pam_unix.so
308 session required pam_loginuid.so
309 session required pam_systemd.so kill-session-processes=1</programlisting>
313 <title>See Also</title>
315 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
316 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
317 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
318 <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
319 <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
320 <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
321 <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
322 <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>