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">
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>
52 <command>pam_systemd.so</command>
57 <title>Description</title>
59 <para><command>pam_systemd</command> registers user
60 sessions in the systemd login manager
61 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
62 and hence the systemd control group hierarchy.</para>
64 <para>On login, this module ensures the following:</para>
67 <listitem><para>If it does not exist yet, the
68 user runtime directory
69 <filename>/run/user/$USER</filename> is
70 created and its ownership changed to the user
71 that is logging in.</para></listitem>
74 <varname>$XDG_SESSION_ID</varname> environment
75 variable is initialized. If auditing is
77 <command>pam_loginuid.so</command> run before
78 this module (which is highly recommended), the
79 variable is initialized from the auditing
81 (<filename>/proc/self/sessionid</filename>). Otherwise
82 an independent session counter is
83 used.</para></listitem>
85 <listitem><para>A new control group
86 <filename>/user/$USER/$XDG_SESSION_ID</filename>
87 is created and the login process moved into
91 <para>On logout, this module ensures the following:</para>
95 <varname>$XDG_SESSION_ID</varname> is set and
96 <option>kill-session-processes=1</option> specified, all
97 remaining processes in the
98 <filename>/user/$USER/$XDG_SESSION_ID</filename>
99 control group are killed and the control group
100 is removed.</para></listitem>
102 <listitem><para>If the last subgroup of the
103 <filename>/user/$USER</filename> control group
105 <varname>$XDG_RUNTIME_DIR</varname> directory
106 and all its contents are
107 removed, too.</para></listitem>
110 <para>If the system was not booted up with systemd as
111 init system, this module does nothing and immediately
112 returns PAM_SUCCESS.</para>
117 <title>Options</title>
119 <para>The following options are understood:</para>
121 <variablelist class='pam-directives'>
123 <term><option>kill-session-processes=</option></term>
125 <listitem><para>Takes a boolean
126 argument. If true, all processes
127 created by the user during his session
128 and from his session will be
129 terminated when he logs out from his
130 session.</para></listitem>
134 <term><option>kill-only-users=</option></term>
136 <listitem><para>Takes a comma
137 separated list of user names or
138 numeric user ids as argument. If this
139 option is used the effect of the
140 <option>kill-session-processes=</option> options
141 will apply only to the listed
142 users. If this option is not used the
143 option applies to all local
145 <option>kill-exclude-users=</option>
146 takes precedence over this list and is
147 hence subtracted from the list
148 specified here.</para></listitem>
152 <term><option>kill-exclude-users=</option></term>
154 <listitem><para>Takes a comma
155 separated list of user names or
156 numeric user ids as argument. Users
157 listed in this argument will not be
158 subject to the effect of
159 <option>kill-session-processes=</option>. Note
160 that this option takes precedence
162 <option>kill-only-users=</option>, and
163 hence whatever is listed for
164 <option>kill-exclude-users=</option>
165 is guaranteed to never be killed by
166 this PAM module, independent of any
168 setting.</para></listitem>
172 <term><option>controllers=</option></term>
174 <listitem><para>Takes a comma
175 separated list of control group
176 controllers in which hierarchies a
177 user/session control group will be
178 created by default for each user
179 logging in, in addition to the control
180 group in the named 'name=systemd'
181 hierarchy. If omitted, defaults to an
182 empty list.</para></listitem>
186 <term><option>reset-controllers=</option></term>
188 <listitem><para>Takes a comma
189 separated list of control group
190 controllers in which hierarchies the
191 logged in processes will be reset to
193 group.</para></listitem>
197 <term><option>class=</option></term>
199 <listitem><para>Takes a string
200 argument which sets the session class.
201 The XDG_SESSION_CLASS environmental variable
202 takes precedence.</para></listitem>
206 <term><option>debug=</option></term>
208 <listitem><para>Takes a boolean
209 argument. If yes, the module will log
210 debugging information as it
211 operates.</para></listitem>
215 <para>Note that setting
216 <varname>kill-session-processes=1</varname> will break tools
218 <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
221 <varname>kill-session-processes=1</varname> is a
223 <varname>KillUserProcesses=1</varname> which may be
224 configured system-wide in
225 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
226 former kills processes of a session as soon as it
227 ends, the latter kills processes as soon as the last
228 session of the user ends.</para>
230 <para>If the options are omitted they default to
231 <option>kill-session-processes=0</option>,
232 <option>kill-only-users=</option>,
233 <option>kill-exclude-users=</option>,
234 <option>controllers=</option>,
235 <option>reset-controllers=</option>,
236 <option>debug=no</option>.</para>
240 <title>Module Types Provided</title>
242 <para>Only <option>session</option> is provided.</para>
246 <title>Environment</title>
248 <para>The following environment variables are set for the processes of the user's session:</para>
250 <variablelist class='environment-variables'>
252 <term><varname>$XDG_SESSION_ID</varname></term>
254 <listitem><para>A session identifier,
255 suitable to be used in file names. The
256 string itself should be considered
257 opaque, although often it is just the
258 audit session ID as reported by
259 <filename>/proc/self/sessionid</filename>. Each
260 ID will be assigned only once during
261 machine uptime. It may hence be used
262 to uniquely label files or other
264 session.</para></listitem>
268 <term><varname>$XDG_RUNTIME_DIR</varname></term>
270 <listitem><para>Path to a user-private
271 user-writable directory that is bound
272 to the user login time on the
273 machine. It is automatically created
274 the first time a user logs in and
275 removed on his final logout. If a user
276 logs in twice at the same time, both
277 sessions will see the same
278 <varname>$XDG_RUNTIME_DIR</varname>
279 and the same contents. If a user logs
280 in once, then logs out again, and logs
281 in again, the directory contents will
282 have been lost in between, but
283 applications should not rely on this
284 behavior and must be able to deal with
285 stale files. To store session-private
286 data in this directory the user should
287 include the value of <varname>$XDG_SESSION_ID</varname>
288 in the filename. This directory shall
289 be used for runtime file system
290 objects such as AF_UNIX sockets,
291 FIFOs, PID files and similar. It is
292 guaranteed that this directory is
293 local and offers the greatest possible
294 file system feature set the
296 provides.</para></listitem>
302 <title>Example</title>
304 <programlisting>#%PAM-1.0
305 auth required pam_unix.so
306 auth required pam_nologin.so
307 account required pam_unix.so
308 password required pam_unix.so
309 session required pam_unix.so
310 session required pam_loginuid.so
311 session required pam_systemd.so kill-session-processes=1</programlisting>
315 <title>See Also</title>
317 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
318 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
319 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
320 <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
321 <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
322 <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
323 <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
324 <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>