chiark / gitweb /
man: document systemd-notify
[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 es 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                         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
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 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 that 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                 <variablelist>
226                         <varlistentry>
227                                 <term><varname>$XDG_SESSION_ID</varname></term>
228
229                                 <listitem><para>A session identifier,
230                                 suitable to be used in file names. The
231                                 string itself should be considered
232                                 opaque, although often it is just the
233                                 audit session ID as reported by
234                                 <filename>/proc/self/sessionid</filename>. Each
235                                 ID will be assigned only once during
236                                 machine uptime. It may hence be used
237                                 to uniquely label files or other
238                                 resources of this
239                                 session.</para></listitem>
240                         </varlistentry>
241
242                         <varlistentry>
243                                 <term><varname>$XDG_RUNTIME_DIR</varname></term>
244
245                                 <listitem><para>Path to a user-private
246                                 user-writable directory that is bound
247                                 to the user login time on the
248                                 machine. It is automatically created
249                                 the first time a user logs in and
250                                 removed on his final logout. If a user
251                                 logs in twice at the same time, both
252                                 sessions will see the same
253                                 <varname>$XDG_RUNTIME_DIR</varname>
254                                 and the same contents. If a user logs
255                                 in once, then logs out again, and logs
256                                 in again, the directory contents will
257                                 have been lost in between, but
258                                 applications should not rely on this
259                                 behaviour and must be able to deal with
260                                 stale files. To store session-private
261                                 data in this directory the user should
262                                 include the value of <varname>$XDG_SESSION_ID</varname>
263                                 in the filename. This directory shall
264                                 be used for runtime file system
265                                 objects such as AF_UNIX sockets,
266                                 FIFOs, PID files and similar. It is
267                                 guaranteed that this directory is
268                                 local and offers the greatest possible
269                                 file system feature set the
270                                 operating system
271                                 provides.</para></listitem>
272                         </varlistentry>
273                 </variablelist>
274         </refsect1>
275
276         <refsect1>
277                 <title>Example</title>
278
279                 <programlisting>#%PAM-1.0
280 auth       required     pam_unix.so
281 auth       required     pam_nologin.so
282 account    required     pam_unix.so
283 password   required     pam_unix.so
284 session    required     pam_unix.so
285 session    required     pam_loginuid.so
286 session    required     pam_systemd.so create-session=1 kill-user=1</programlisting>
287         </refsect1>
288
289         <refsect1>
290                 <title>See Also</title>
291                 <para>
292                         <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
293                         <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
294                         <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
295                         <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
296                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
297                 </para>
298         </refsect1>
299
300 </refentry>