chiark / gitweb /
headers: fix git URLs for source files
[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 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>
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>
71
72                         <listitem><para>The
73                         <varname>$XDG_SESSION_ID</varname> environment
74                         variable is initialized. If auditing is
75                         available and
76                         <command>pam_loginuid.so</command> run before
77                         this module (which is highly recommended), the
78                         variable is initialized from the auditing
79                         session id
80                         (<filename>/proc/self/sessionid</filename>). Otherwise
81                         an independent session counter is
82                         used.</para></listitem>
83
84                         <listitem><para>A new control group
85                         <filename>/user/$USER/$XDG_SESSION_ID</filename>
86                         is created and the login process moved into
87                         it.</para></listitem>
88                 </orderedlist>
89
90                 <para>On logout, this module ensures the following:</para>
91
92                 <orderedlist>
93                         <listitem><para>If
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>
100
101                         <listitem><para>If last subgroup of the
102                         <filename>/user/$USER</filename> control group
103                         was removed the
104                         <varname>$XDG_RUNTIME_DIR</varname> directory
105                         and all its contents are
106                         removed, too.</para></listitem>
107                 </orderedlist>
108
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>
112
113         </refsect1>
114
115         <refsect1>
116                 <title>Options</title>
117
118                 <para>The following options are understood:</para>
119
120                 <variablelist>
121                         <varlistentry>
122                                 <term><option>kill-session-processes=</option></term>
123
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>
130                         </varlistentry>
131
132                         <varlistentry>
133                                 <term><option>kill-only-users=</option></term>
134
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
143                                 users. Note that
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>
148                         </varlistentry>
149
150                         <varlistentry>
151                                 <term><option>kill-exclude-users=</option></term>
152
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
160                                 over
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
166                                 other configuration
167                                 setting.</para></listitem>
168                         </varlistentry>
169
170                         <varlistentry>
171                                 <term><option>controllers=</option></term>
172
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>
182                         </varlistentry>
183
184                         <varlistentry>
185                                 <term><option>reset-controllers=</option></term>
186
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
191                                 the root control
192                                 group.</para></listitem>
193                         </varlistentry>
194
195                         <varlistentry>
196                                 <term><option>debug=</option></term>
197
198                                 <listitem><para>Takes a boolean
199                                 argument. If yes, the module will log
200                                 debugging information as it
201                                 operates.</para></listitem>
202                         </varlistentry>
203                 </variablelist>
204
205                 <para>Note that setting
206                 <varname>kill-session-processes=1</varname> will break tools
207                 like
208                 <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
209
210                 <para>Note that
211                 <varname>kill-session-processes=1</varname> is a
212                 stricter version of
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>
219
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>
227         </refsect1>
228
229         <refsect1>
230                 <title>Module Types Provided</title>
231
232                 <para>Only <option>session</option> is provided.</para>
233         </refsect1>
234
235         <refsect1>
236                 <title>Environment</title>
237
238                 <para>The following environment variables are set for the processes of the user's session:</para>
239
240                 <variablelist>
241                         <varlistentry>
242                                 <term><varname>$XDG_SESSION_ID</varname></term>
243
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
253                                 resources of this
254                                 session.</para></listitem>
255                         </varlistentry>
256
257                         <varlistentry>
258                                 <term><varname>$XDG_RUNTIME_DIR</varname></term>
259
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
285                                 operating system
286                                 provides.</para></listitem>
287                         </varlistentry>
288                 </variablelist>
289         </refsect1>
290
291         <refsect1>
292                 <title>Example</title>
293
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>
302         </refsect1>
303
304         <refsect1>
305                 <title>See Also</title>
306                 <para>
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>
313                 </para>
314         </refsect1>
315
316 </refentry>