chiark / gitweb /
systemctl: at full stop after last message before shutting down
[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>/var/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>If
73                         <option>create-session=1</option> is set, 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>If
86                         <option>create-session=1</option> is set, a new
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
93                         <option>create-session=0</option> is set, a new
94                         control group
95                         <filename>/user/$USER/no-session</filename>
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
110                         is removed.</para></listitem>
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
118                         <filename>/user/$USER/no-session</filename> and
119                         the original control group is
120                         removed.</para></listitem>
121
122                         <listitem><para>If
123                         <option>kill-user=1</option> is specified, and
124                         no other user session control group remains,
125                         except
126                         <filename>/user/$USER/no-session</filename>,
127                         all remaining processes in the
128                         <filename>/user/$USER</filename> hierarchy
129                         are killed and the control group is removed.</para></listitem>
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
146                 init system, this module does nothing and immediately
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
168                                 all services which are directly created
169                                 on the user's behalf set this
170                                 option. Only for services that shall
171                                 automatically be terminated when the
172                                 user logs out completely, otherwise
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
199                                 than once, as their processes are
200                                 terminated only on their complete
201                                 logout.</para></listitem>
202                         </varlistentry>
203                 </variablelist>
204
205                 <para>Note that setting <varname>kill-user=1</varname>
206                 or even <varname>kill-session=1</varname> will break
207                 tools like
208                 <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
209
210                 <para>If the options are omitted they default to
211                 <option>create-session=1</option>,
212                 <option>kill-session=0</option>,
213                 <option>kill-user=0</option>.</para>
214         </refsect1>
215
216         <refsect1>
217                 <title>Module Types Provided</title>
218
219                 <para>Only <option>session</option> is provided.</para>
220         </refsect1>
221
222         <refsect1>
223                 <title>Environment</title>
224
225                 <para>The following environment variables are set for the processes of the user's session:</para>
226
227                 <variablelist>
228                         <varlistentry>
229                                 <term><varname>$XDG_SESSION_ID</varname></term>
230
231                                 <listitem><para>A session identifier,
232                                 suitable to be used in file names. The
233                                 string itself should be considered
234                                 opaque, although often it is just the
235                                 audit session ID as reported by
236                                 <filename>/proc/self/sessionid</filename>. Each
237                                 ID will be assigned only once during
238                                 machine uptime. It may hence be used
239                                 to uniquely label files or other
240                                 resources of this
241                                 session.</para></listitem>
242                         </varlistentry>
243
244                         <varlistentry>
245                                 <term><varname>$XDG_RUNTIME_DIR</varname></term>
246
247                                 <listitem><para>Path to a user-private
248                                 user-writable directory that is bound
249                                 to the user login time on the
250                                 machine. It is automatically created
251                                 the first time a user logs in and
252                                 removed on his final logout. If a user
253                                 logs in twice at the same time, both
254                                 sessions will see the same
255                                 <varname>$XDG_RUNTIME_DIR</varname>
256                                 and the same contents. If a user logs
257                                 in once, then logs out again, and logs
258                                 in again, the directory contents will
259                                 have been lost in between, but
260                                 applications should not rely on this
261                                 behaviour and must be able to deal with
262                                 stale files. To store session-private
263                                 data in this directory the user should
264                                 include the value of <varname>$XDG_SESSION_ID</varname>
265                                 in the filename. This directory shall
266                                 be used for runtime file system
267                                 objects such as AF_UNIX sockets,
268                                 FIFOs, PID files and similar. It is
269                                 guaranteed that this directory is
270                                 local and offers the greatest possible
271                                 file system feature set the
272                                 operating system
273                                 provides.</para></listitem>
274                         </varlistentry>
275                 </variablelist>
276         </refsect1>
277
278         <refsect1>
279                 <title>Example</title>
280
281                 <programlisting>#%PAM-1.0
282 auth       required     pam_unix.so
283 auth       required     pam_nologin.so
284 account    required     pam_unix.so
285 password   required     pam_unix.so
286 session    required     pam_unix.so
287 session    required     pam_loginuid.so
288 session    required     pam_systemd.so kill-user=1</programlisting>
289         </refsect1>
290
291         <refsect1>
292                 <title>See Also</title>
293                 <para>
294                         <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
295                         <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
296                         <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
297                         <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
298                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
299                 </para>
300         </refsect1>
301
302 </refentry>