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 General Public License as published by
12 the Free Software Foundation; either version 2 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 General Public License for more details.
20 You should have received a copy of the GNU 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 control group hierarchy</refpurpose>
52 <command>pam_systemd.so</command>
57 <title>Description</title>
59 <para><command>pam_systemd</command> registers user
60 sessions in the systemd control group
63 <para>On login, this module ensures the following:</para>
66 <listitem><para>If it does not exist yet, the
67 user runtime directory
68 <filename>/run/user/$USER</filename> is
69 created and its ownership changed to the user
70 that is logging in.</para></listitem>
73 <varname>$XDG_SESSION_ID</varname> environment
74 variable is initialized. If auditing is
76 <command>pam_loginuid.so</command> run before
77 this module (which is highly recommended), the
78 variable is initialized from the auditing
80 (<filename>/proc/self/sessionid</filename>). Otherwise
81 an independent session counter is
82 used.</para></listitem>
84 <listitem><para>A new control group
85 <filename>/user/$USER/$XDG_SESSION_ID</filename>
86 is created and the login process moved into
90 <para>On logout, this module ensures the following:</para>
94 <varname>$XDG_SESSION_ID</varname> is set and
95 <option>kill-session-processes=1</option> specified, all
96 remaining processes in the
97 <filename>/user/$USER/$XDG_SESSION_ID</filename>
98 control group are killed and the control group
99 is removed.</para></listitem>
101 <listitem><para>If last subgroup of the
102 <filename>/user/$USER</filename> control group
104 <varname>$XDG_RUNTIME_DIR</varname> directory
105 and all its contents are
106 removed, too.</para></listitem>
109 <para>If the system was not booted up with systemd as
110 init system, this module does nothing and immediately
111 returns PAM_SUCCESS.</para>
116 <title>Options</title>
118 <para>The following options are understood:</para>
122 <term><option>kill-session-processes=</option></term>
124 <listitem><para>Takes a boolean
125 argument. If true, all processes
126 created by the user during his session
127 and from his session will be
128 terminated when he logs out from his
129 session.</para></listitem>
133 <term><option>kill-only-users=</option></term>
135 <listitem><para>Takes a comma
136 separated list of user names or
137 numeric user ids as argument. If this
138 option is used the effect of the
139 <option>kill-session-processes=</option> options
140 will apply only to the listed
141 users. If this option is not used the
142 option applies to all local
144 <option>kill-exclude-users=</option>
145 takes precedence over this list and is
146 hence subtracted from the list
147 specified here.</para></listitem>
151 <term><option>kill-exclude-users=</option></term>
153 <listitem><para>Takes a comma
154 separated list of user names or
155 numeric user ids as argument. Users
156 listed in this argument will not be
157 subject to the effect of
158 <option>kill-session-processes=</option>. Note
159 that that this option takes precedence
161 <option>kill-only-users=</option>, and
162 hence whatever is listed for
163 <option>kill-exclude-users=</option>
164 is guaranteed to never be killed by
165 this PAM module, independent of any
167 setting.</para></listitem>
171 <term><option>controllers=</option></term>
173 <listitem><para>Takes a comma
174 separated list of control group
175 controllers in which hierarchies a
176 user/session control group will be
177 created by default for each user
178 logging in, in addition to the control
179 group in the named 'name=systemd'
180 hierarchy. If omitted, defaults to an
181 empty list.</para></listitem>
185 <term><option>reset-controllers=</option></term>
187 <listitem><para>Takes a comma
188 separated list of control group
189 controllers in which hierarchies the
190 logged in processes will be reset to
192 group.</para></listitem>
196 <term><option>debug=</option></term>
198 <listitem><para>Takes a boolean
199 argument. If yes, the module will log
200 debugging information as it
201 operates.</para></listitem>
205 <para>Note that setting
206 <varname>kill-session-processes=1</varname> will break tools
208 <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
211 <varname>kill-session-processes=1</varname> is a
213 <varname>KillUserProcesses=1</varname> which may be
214 configured system-wide in
215 <citerefentry><refentrytitle>systemd-logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
216 former kills processes of a session as soon as it
217 ends, the latter kills processes as soon as the last
218 session of the user ends.</para>
220 <para>If the options are omitted they default to
221 <option>kill-session-processes=0</option>,
222 <option>kill-only-users=</option>,
223 <option>kill-exclude-users=</option>,
224 <option>controllers=</option>,
225 <option>reset-controllers=</option>,
226 <option>debug=no</option>.</para>
230 <title>Module Types Provided</title>
232 <para>Only <option>session</option> is provided.</para>
236 <title>Environment</title>
238 <para>The following environment variables are set for the processes of the user's session:</para>
242 <term><varname>$XDG_SESSION_ID</varname></term>
244 <listitem><para>A session identifier,
245 suitable to be used in file names. The
246 string itself should be considered
247 opaque, although often it is just the
248 audit session ID as reported by
249 <filename>/proc/self/sessionid</filename>. Each
250 ID will be assigned only once during
251 machine uptime. It may hence be used
252 to uniquely label files or other
254 session.</para></listitem>
258 <term><varname>$XDG_RUNTIME_DIR</varname></term>
260 <listitem><para>Path to a user-private
261 user-writable directory that is bound
262 to the user login time on the
263 machine. It is automatically created
264 the first time a user logs in and
265 removed on his final logout. If a user
266 logs in twice at the same time, both
267 sessions will see the same
268 <varname>$XDG_RUNTIME_DIR</varname>
269 and the same contents. If a user logs
270 in once, then logs out again, and logs
271 in again, the directory contents will
272 have been lost in between, but
273 applications should not rely on this
274 behaviour and must be able to deal with
275 stale files. To store session-private
276 data in this directory the user should
277 include the value of <varname>$XDG_SESSION_ID</varname>
278 in the filename. This directory shall
279 be used for runtime file system
280 objects such as AF_UNIX sockets,
281 FIFOs, PID files and similar. It is
282 guaranteed that this directory is
283 local and offers the greatest possible
284 file system feature set the
286 provides.</para></listitem>
292 <title>Example</title>
294 <programlisting>#%PAM-1.0
295 auth required pam_unix.so
296 auth required pam_nologin.so
297 account required pam_unix.so
298 password required pam_unix.so
299 session required pam_unix.so
300 session required pam_loginuid.so
301 session required pam_systemd.so kill-session-processes=1</programlisting>
305 <title>See Also</title>
307 <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
308 <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
309 <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
310 <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
311 <citerefentry><refentrytitle>systemd-logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
312 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>