]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/pam_systemd.xml
util: conf_files_list() return list as parameter
[thirdparty/systemd.git] / man / pam_systemd.xml
CommitLineData
160cd5c9
LP
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">
4
5<!--
6 This file is part of systemd.
7
8 Copyright 2010 Lennart Poettering
9
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.
14
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.
19
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/>.
22-->
23
24<refentry id="pam_systemd">
25
26 <refentryinfo>
27 <title>pam_systemd</title>
28 <productname>systemd</productname>
29
30 <authorgroup>
31 <author>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
36 </author>
37 </authorgroup>
38 </refentryinfo>
39
40 <refmeta>
41 <refentrytitle>pam_systemd</refentrytitle>
42 <manvolnum>8</manvolnum>
43 </refmeta>
44
45 <refnamediv>
46 <refname>pam_systemd</refname>
47 <refpurpose>Register user sessions in the systemd control group hierarchy</refpurpose>
48 </refnamediv>
49
50 <refsynopsisdiv>
51 <cmdsynopsis>
52 <command>pam_systemd.so</command>
53 </cmdsynopsis>
54 </refsynopsisdiv>
55
56 <refsect1>
57 <title>Description</title>
58
59 <para><command>pam_systemd</command> registers user
60 sessions in the systemd control group
61 hierarchy.</para>
62
63 <para>On login, this module ensures the following:</para>
64
65 <orderedlist>
af62c704 66 <listitem><para>If it does not exist yet, the
160cd5c9 67 user runtime directory
bb29785e 68 <filename>/run/user/$USER</filename> is
160cd5c9
LP
69 created and its ownership changed to the user
70 that is logging in.</para></listitem>
71
72 <listitem><para>If
af62c704 73 <option>create-session=1</option> is set, the
160cd5c9
LP
74 <varname>$XDG_SESSION_ID</varname> environment
75 variable is initialized. If auditing is
76 available and
77 <command>pam_loginuid.so</command> run before
af62c704 78 this module (which is highly recommended), the
160cd5c9
LP
79 variable is initialized from the auditing
80 session id
81 (<filename>/proc/self/sessionid</filename>). Otherwise
82 an independent session counter is
83 used.</para></listitem>
84
85 <listitem><para>If
af62c704 86 <option>create-session=1</option> is set, a new
160cd5c9
LP
87 control group
88 <filename>/user/$USER/$XDG_SESSION_ID</filename>
89 is created and the login process moved into
90 it.</para></listitem>
91
92 <listitem><para>If
af62c704 93 <option>create-session=0</option> is set, a new
160cd5c9 94 control group
824a1d59 95 <filename>/user/$USER/user</filename>
160cd5c9
LP
96 is created and the login process moved into
97 it.</para></listitem>
98
99 </orderedlist>
100
101 <para>On logout, this module ensures the following:</para>
102
103 <orderedlist>
104 <listitem><para>If
105 <varname>$XDG_SESSION_ID</varname> is set and
106 <option>kill-session=1</option> specified, all
107 remaining processes in the
108 <filename>/user/$USER/$XDG_SESSION_ID</filename>
109 control group are killed and the control group
af62c704 110 is removed.</para></listitem>
160cd5c9
LP
111
112 <listitem><para>If
113 <varname>$XDG_SESSION_ID</varname> is set and
114 <option>kill-session=0</option> specified, all
115 remaining processes in the
116 <filename>/user/$USER/$XDG_SESSION_ID</filename>
117 control group are migrated to
824a1d59 118 <filename>/user/$USER/user</filename> and
af62c704 119 the original control group is
160cd5c9
LP
120 removed.</para></listitem>
121
122 <listitem><para>If
123 <option>kill-user=1</option> is specified, and
af62c704 124 no other user session control group remains,
160cd5c9 125 except
824a1d59 126 <filename>/user/$USER/user</filename>,
160cd5c9
LP
127 all remaining processes in the
128 <filename>/user/$USER</filename> hierarchy
af62c704 129 are killed and the control group is removed.</para></listitem>
160cd5c9
LP
130
131 <listitem><para>If
132 <option>kill-user=0</option> is specified, and
133 no process remains in the
134 <filename>/user/$USER</filename> hierarchy the
135 control group is removed.</para></listitem>
136
137 <listitem><para>If the
138 <filename>/user/$USER</filename> control group
139 was removed the
140 <varname>$XDG_RUNTIME_DIR</varname> directory
141 and all its contents are
142 removed, too.</para></listitem>
143 </orderedlist>
144
145 <para>If the system was not booted up with systemd as
af62c704 146 init system, this module does nothing and immediately
160cd5c9
LP
147 returns PAM_SUCCESS.</para>
148
149 </refsect1>
150
151 <refsect1>
152 <title>Options</title>
153
154 <para>The following options are understood:</para>
155
156 <variablelist>
157 <varlistentry>
158 <term><option>create-session=</option></term>
159
160 <listitem><para>Takes a boolean
161 argument. If true, a new session is
162 created: the
163 <varname>$XDG_SESSION_ID</varname>
164 environment variable is set and the
165 login process moved to the
166 <filename>/user/$USER/$XDG_SESSION_ID</filename>
167 control group. It is recommended that
af62c704 168 all services which are directly created
160cd5c9
LP
169 on the user's behalf set this
170 option. Only for services that shall
171 automatically be terminated when the
af62c704 172 user logs out completely, otherwise
160cd5c9
LP
173 <varname>create-session=0</varname>
174 should be set.</para></listitem>
175 </varlistentry>
176
177 <varlistentry>
178 <term><option>kill-session=</option></term>
179
180 <listitem><para>Takes a boolean
181 argument. If true, all processes
182 created by the user during his session
183 and from his session will be
184 terminated when he logs out from his
185 session.</para></listitem>
186 </varlistentry>
187
188 <varlistentry>
189 <term><option>kill-user=</option></term>
190
191 <listitem><para>Takes a boolean
192 argument. If true, all processes
193 created by the user during his session
194 and from his session will be
195 terminated after he logged out
196 completely. This is a weaker version
197 of <option>kill-session=1</option> and is
198 more friendly for users logged in more
af62c704 199 than once, as their processes are
160cd5c9
LP
200 terminated only on their complete
201 logout.</para></listitem>
202 </varlistentry>
4611d776 203
3add4d21 204 <varlistentry>
e9fbc77c 205 <term><option>kill-only-users=</option></term>
3add4d21 206
e9fbc77c
LP
207 <listitem><para>Takes a comma
208 separated list of user names or
209 numeric user ids as argument. If this
210 option is used the effect of the
211 <option>kill-session=</option> and
212 <option>kill-user=</option> options
213 will apply only to the listed
214 users. If this option is not used the
215 option applies to all local
216 users. Note that
217 <option>kill-exclude-users=</option>
218 takes precedence over this list and is
219 hence subtracted from the list
220 specified here.</para></listitem>
221 </varlistentry>
222
223 <varlistentry>
224 <term><option>kill-exclude-users=</option></term>
225
226 <listitem><para>Takes a comma
227 separated list of user names or
228 numeric user ids as argument. Users
229 listed in this argument will not be
230 subject to the effect of
231 <option>kill-session=</option> or
232 <option>kill-user=</option>. Note
233 that that this option takes precedence
234 over
235 <option>kill-only-users=</option>, and
236 hence whatever is listed for
237 <option>kill-exclude-users=</option>
238 is guaranteed to never be killed by
239 this PAM module, independent of any
240 other configuration
241 setting.</para></listitem>
3add4d21
LP
242 </varlistentry>
243
4611d776
LP
244 <varlistentry>
245 <term><option>controllers=</option></term>
246
247 <listitem><para>Takes a comma
5471472d 248 separated list of cgroup controllers
4611d776 249 in which hierarchies a user/session
5471472d 250 cgroup will be created by default for
b20c6be6
LP
251 each user logging in, in addition to
252 the cgroup in the named 'name=systemd'
253 hierarchy. If ommited, defaults to an
254 empty list. This may be used to move
255 user sessions into their own groups in
256 the 'cpu' hierarchy which ensures that
257 every logged in user gets an equal
258 amount of CPU time regardless how many
259 processes he has
260 started.</para></listitem>
261 </varlistentry>
262
263 <varlistentry>
264 <term><option>reset-controllers=</option></term>
265
266 <listitem><para>Takes a comma
267 separated list of cgroup controllers
268 in which hierarchies the logged in
269 processes will be reset to the root
270 cgroup. If ommited, defaults to 'cpu',
271 meaning that a 'cpu' cgroup grouping
272 inherited from the login manager will
273 be reset for the processes of the
274 logged in user.</para></listitem>
4611d776 275 </varlistentry>
160cd5c9
LP
276 </variablelist>
277
278 <para>Note that setting <varname>kill-user=1</varname>
279 or even <varname>kill-session=1</varname> will break
280 tools like
281 <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
282
7874bcd6
LP
283 <para>If the options are omitted they default to
284 <option>create-session=1</option>,
285 <option>kill-session=0</option>,
3add4d21 286 <option>kill-user=0</option>,
e9fbc77c
LP
287 <option>reset-controllers=cpu</option>,
288 <option>kill-only-users=</option>,
289 <option>kill-exclude-users=root</option>.</para>
160cd5c9
LP
290 </refsect1>
291
292 <refsect1>
293 <title>Module Types Provided</title>
294
295 <para>Only <option>session</option> is provided.</para>
296 </refsect1>
297
298 <refsect1>
299 <title>Environment</title>
300
58474090
LP
301 <para>The following environment variables are set for the processes of the user's session:</para>
302
160cd5c9
LP
303 <variablelist>
304 <varlistentry>
305 <term><varname>$XDG_SESSION_ID</varname></term>
306
307 <listitem><para>A session identifier,
308 suitable to be used in file names. The
309 string itself should be considered
310 opaque, although often it is just the
311 audit session ID as reported by
312 <filename>/proc/self/sessionid</filename>. Each
313 ID will be assigned only once during
314 machine uptime. It may hence be used
315 to uniquely label files or other
316 resources of this
317 session.</para></listitem>
318 </varlistentry>
319
320 <varlistentry>
321 <term><varname>$XDG_RUNTIME_DIR</varname></term>
322
323 <listitem><para>Path to a user-private
324 user-writable directory that is bound
325 to the user login time on the
326 machine. It is automatically created
327 the first time a user logs in and
328 removed on his final logout. If a user
329 logs in twice at the same time, both
330 sessions will see the same
331 <varname>$XDG_RUNTIME_DIR</varname>
332 and the same contents. If a user logs
333 in once, then logs out again, and logs
334 in again, the directory contents will
335 have been lost in between, but
336 applications should not rely on this
337 behaviour and must be able to deal with
338 stale files. To store session-private
339 data in this directory the user should
340 include the value of <varname>$XDG_SESSION_ID</varname>
341 in the filename. This directory shall
342 be used for runtime file system
343 objects such as AF_UNIX sockets,
344 FIFOs, PID files and similar. It is
345 guaranteed that this directory is
346 local and offers the greatest possible
347 file system feature set the
348 operating system
349 provides.</para></listitem>
350 </varlistentry>
351 </variablelist>
352 </refsect1>
353
354 <refsect1>
355 <title>Example</title>
356
357 <programlisting>#%PAM-1.0
358auth required pam_unix.so
359auth required pam_nologin.so
360account required pam_unix.so
361password required pam_unix.so
362session required pam_unix.so
363session required pam_loginuid.so
58474090 364session required pam_systemd.so kill-user=1</programlisting>
160cd5c9
LP
365 </refsect1>
366
367 <refsect1>
368 <title>See Also</title>
369 <para>
370 <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
371 <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
372 <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
373 <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
374 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
375 </para>
376 </refsect1>
377
378</refentry>