chiark / gitweb /
docs: typo fixes in logind.conf.xml and os-release.xml
[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 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>debug=</option></term>
198
199                                 <listitem><para>Takes a boolean
200                                 argument. If yes, the module will log
201                                 debugging information as it
202                                 operates.</para></listitem>
203                         </varlistentry>
204                 </variablelist>
205
206                 <para>Note that setting
207                 <varname>kill-session-processes=1</varname> will break tools
208                 like
209                 <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
210
211                 <para>Note that
212                 <varname>kill-session-processes=1</varname> is a
213                 stricter version of
214                 <varname>KillUserProcesses=1</varname> which may be
215                 configured system-wide in
216                 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
217                 former kills processes of a session as soon as it
218                 ends, the latter kills processes as soon as the last
219                 session of the user ends.</para>
220
221                 <para>If the options are omitted they default to
222                 <option>kill-session-processes=0</option>,
223                 <option>kill-only-users=</option>,
224                 <option>kill-exclude-users=</option>,
225                 <option>controllers=</option>,
226                 <option>reset-controllers=</option>,
227                 <option>debug=no</option>.</para>
228         </refsect1>
229
230         <refsect1>
231                 <title>Module Types Provided</title>
232
233                 <para>Only <option>session</option> is provided.</para>
234         </refsect1>
235
236         <refsect1>
237                 <title>Environment</title>
238
239                 <para>The following environment variables are set for the processes of the user's session:</para>
240
241                 <variablelist>
242                         <varlistentry>
243                                 <term><varname>$XDG_SESSION_ID</varname></term>
244
245                                 <listitem><para>A session identifier,
246                                 suitable to be used in file names. The
247                                 string itself should be considered
248                                 opaque, although often it is just the
249                                 audit session ID as reported by
250                                 <filename>/proc/self/sessionid</filename>. Each
251                                 ID will be assigned only once during
252                                 machine uptime. It may hence be used
253                                 to uniquely label files or other
254                                 resources of this
255                                 session.</para></listitem>
256                         </varlistentry>
257
258                         <varlistentry>
259                                 <term><varname>$XDG_RUNTIME_DIR</varname></term>
260
261                                 <listitem><para>Path to a user-private
262                                 user-writable directory that is bound
263                                 to the user login time on the
264                                 machine. It is automatically created
265                                 the first time a user logs in and
266                                 removed on his final logout. If a user
267                                 logs in twice at the same time, both
268                                 sessions will see the same
269                                 <varname>$XDG_RUNTIME_DIR</varname>
270                                 and the same contents. If a user logs
271                                 in once, then logs out again, and logs
272                                 in again, the directory contents will
273                                 have been lost in between, but
274                                 applications should not rely on this
275                                 behavior and must be able to deal with
276                                 stale files. To store session-private
277                                 data in this directory the user should
278                                 include the value of <varname>$XDG_SESSION_ID</varname>
279                                 in the filename. This directory shall
280                                 be used for runtime file system
281                                 objects such as AF_UNIX sockets,
282                                 FIFOs, PID files and similar. It is
283                                 guaranteed that this directory is
284                                 local and offers the greatest possible
285                                 file system feature set the
286                                 operating system
287                                 provides.</para></listitem>
288                         </varlistentry>
289                 </variablelist>
290         </refsect1>
291
292         <refsect1>
293                 <title>Example</title>
294
295                 <programlisting>#%PAM-1.0
296 auth       required     pam_unix.so
297 auth       required     pam_nologin.so
298 account    required     pam_unix.so
299 password   required     pam_unix.so
300 session    required     pam_unix.so
301 session    required     pam_loginuid.so
302 session    required     pam_systemd.so kill-session-processes=1</programlisting>
303         </refsect1>
304
305         <refsect1>
306                 <title>See Also</title>
307                 <para>
308                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
309                         <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
310                         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
311                         <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
312                         <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
313                         <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
314                         <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
315                         <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>
316                 </para>
317         </refsect1>
318
319 </refentry>