chiark / gitweb /
pam_systemd: new option for the session class
[elogind.git] / man / pam_systemd.xml
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 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.
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   Lesser General Public License for more details.
19
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/>.
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 login manager</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 login manager
61                 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
62                 and hence the systemd control group hierarchy.</para>
63
64                 <para>On login, this module ensures the following:</para>
65
66                 <orderedlist>
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>
72
73                         <listitem><para>The
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
78                         this module (which is highly recommended), the
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>A new control group
86                         <filename>/user/$USER/$XDG_SESSION_ID</filename>
87                         is created and the login process moved into
88                         it.</para></listitem>
89                 </orderedlist>
90
91                 <para>On logout, this module ensures the following:</para>
92
93                 <orderedlist>
94                         <listitem><para>If
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>
101
102                         <listitem><para>If the last subgroup of the
103                         <filename>/user/$USER</filename> control group
104                         was removed the
105                         <varname>$XDG_RUNTIME_DIR</varname> directory
106                         and all its contents are
107                         removed, too.</para></listitem>
108                 </orderedlist>
109
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>
113
114         </refsect1>
115
116         <refsect1>
117                 <title>Options</title>
118
119                 <para>The following options are understood:</para>
120
121                 <variablelist>
122                         <varlistentry>
123                                 <term><option>kill-session-processes=</option></term>
124
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>
131                         </varlistentry>
132
133                         <varlistentry>
134                                 <term><option>kill-only-users=</option></term>
135
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
144                                 users. Note that
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>
149                         </varlistentry>
150
151                         <varlistentry>
152                                 <term><option>kill-exclude-users=</option></term>
153
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
161                                 over
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
167                                 other configuration
168                                 setting.</para></listitem>
169                         </varlistentry>
170
171                         <varlistentry>
172                                 <term><option>controllers=</option></term>
173
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>
183                         </varlistentry>
184
185                         <varlistentry>
186                                 <term><option>reset-controllers=</option></term>
187
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
192                                 the root control
193                                 group.</para></listitem>
194                         </varlistentry>
195
196                         <varlistentry>
197                                 <term><option>class=</option></term>
198
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>
203                         </varlistentry>
204
205                         <varlistentry>
206                                 <term><option>debug=</option></term>
207
208                                 <listitem><para>Takes a boolean
209                                 argument. If yes, the module will log
210                                 debugging information as it
211                                 operates.</para></listitem>
212                         </varlistentry>
213                 </variablelist>
214
215                 <para>Note that setting
216                 <varname>kill-session-processes=1</varname> will break tools
217                 like
218                 <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
219
220                 <para>Note that
221                 <varname>kill-session-processes=1</varname> is a
222                 stricter version of
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>
229
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>
237         </refsect1>
238
239         <refsect1>
240                 <title>Module Types Provided</title>
241
242                 <para>Only <option>session</option> is provided.</para>
243         </refsect1>
244
245         <refsect1>
246                 <title>Environment</title>
247
248                 <para>The following environment variables are set for the processes of the user's session:</para>
249
250                 <variablelist>
251                         <varlistentry>
252                                 <term><varname>$XDG_SESSION_ID</varname></term>
253
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
263                                 resources of this
264                                 session.</para></listitem>
265                         </varlistentry>
266
267                         <varlistentry>
268                                 <term><varname>$XDG_RUNTIME_DIR</varname></term>
269
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
295                                 operating system
296                                 provides.</para></listitem>
297                         </varlistentry>
298                 </variablelist>
299         </refsect1>
300
301         <refsect1>
302                 <title>Example</title>
303
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>
312         </refsect1>
313
314         <refsect1>
315                 <title>See Also</title>
316                 <para>
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>
325                 </para>
326         </refsect1>
327
328 </refentry>