chiark / gitweb /
man: minor addition to coredumpctl example
[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" conditional='HAVE_PAM'>
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                 <para><filename>pam_systemd.so</filename></para>
52         </refsynopsisdiv>
53
54         <refsect1>
55                 <title>Description</title>
56
57                 <para><command>pam_systemd</command> registers user
58                 sessions with the systemd login manager
59                 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
60                 and hence the systemd control group hierarchy.</para>
61
62                 <para>On login, this module ensures the following:</para>
63
64                 <orderedlist>
65                         <listitem><para>If it does not exist yet, the
66                         user runtime directory
67                         <filename>/run/user/$USER</filename> is
68                         created and its ownership changed to the user
69                         that is logging in.</para></listitem>
70
71                         <listitem><para>The
72                         <varname>$XDG_SESSION_ID</varname> environment
73                         variable is initialized. If auditing is
74                         available and
75                         <command>pam_loginuid.so</command> was run before
76                         this module (which is highly recommended), the
77                         variable is initialized from the auditing
78                         session id
79                         (<filename>/proc/self/sessionid</filename>). Otherwise,
80                         an independent session counter is
81                         used.</para></listitem>
82
83                         <listitem><para>A new systemd scope unit is
84                         created for the session. If this is the first
85                         concurrent session of the user, an implicit
86                         slice below <filename>user.slice</filename> is
87                         automatically created and the scope placed into
88                         it. An instance of the system service
89                         <filename>user@.service</filename>, which runs
90                         the systemd user manager instance, is started.
91                         </para></listitem>
92                 </orderedlist>
93
94                 <para>On logout, this module ensures the following:</para>
95
96                 <orderedlist>
97                         <listitem><para>If enabled in
98                         <citerefentry><refentrytitle>logind.conf</refentrytitle>
99                         <manvolnum>5</manvolnum></citerefentry>,
100                         all processes of the session are terminated. If
101                         the last concurrent session of a user ends, his
102                         user systemd instance will be terminated too,
103                         and so will the user's slice
104                         unit.</para></listitem>
105
106                         <listitem><para>If the last concurrent session
107                         of a user ends, the
108                         <varname>$XDG_RUNTIME_DIR</varname> directory
109                         and all its contents are removed,
110                         too.</para></listitem>
111                 </orderedlist>
112
113                 <para>If the system was not booted up with systemd as
114                 init system, this module does nothing and immediately
115                 returns PAM_SUCCESS.</para>
116
117         </refsect1>
118
119         <refsect1>
120                 <title>Options</title>
121
122                 <para>The following options are understood:</para>
123
124                 <variablelist class='pam-directives'>
125
126                         <varlistentry>
127                                 <term><option>class=</option></term>
128
129                                 <listitem><para>Takes a string
130                                 argument which sets the session class.
131                                 The XDG_SESSION_CLASS environmental variable
132                                 takes precedence. One of
133                                 <literal>user</literal>,
134                                 <literal>greeter</literal>,
135                                 <literal>lock-screen</literal> or
136                                 <literal>background</literal>. See
137                                 <citerefentry><refentrytitle>sd_session_get_class</refentrytitle><manvolnum>3</manvolnum></citerefentry>
138                                 for details about the session class.</para></listitem>
139                         </varlistentry>
140
141                         <varlistentry>
142                                 <term><option>type=</option></term>
143
144                                 <listitem><para>Takes a string
145                                 argument which sets the session type.
146                                 The XDG_SESSION_TYPE environmental
147                                 variable takes precedence. One of
148                                 <literal>unspecified</literal>,
149                                 <literal>tty</literal>,
150                                 <literal>x11</literal>,
151                                 <literal>wayland</literal> or
152                                 <literal>mir</literal>. See
153                                 <citerefentry><refentrytitle>sd_session_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry>
154                                 for details about the session type.</para></listitem>
155                         </varlistentry>
156
157                         <varlistentry>
158                                 <term><option>debug<optional>=</optional></option></term>
159
160                                 <listitem><para>Takes an optional
161                                 boolean argument. If yes or without
162                                 the argument, the module will log
163                                 debugging information as it
164                                 operates.</para></listitem>
165                         </varlistentry>
166                 </variablelist>
167         </refsect1>
168
169         <refsect1>
170                 <title>Module Types Provided</title>
171
172                 <para>Only <option>session</option> is provided.</para>
173         </refsect1>
174
175         <refsect1>
176                 <title>Environment</title>
177
178                 <para>The following environment variables are set for the processes of the user's session:</para>
179
180                 <variablelist class='environment-variables'>
181                         <varlistentry>
182                                 <term><varname>$XDG_SESSION_ID</varname></term>
183
184                                 <listitem><para>A session identifier,
185                                 suitable to be used in filenames. The
186                                 string itself should be considered
187                                 opaque, although often it is just the
188                                 audit session ID as reported by
189                                 <filename>/proc/self/sessionid</filename>. Each
190                                 ID will be assigned only once during
191                                 machine uptime. It may hence be used
192                                 to uniquely label files or other
193                                 resources of this
194                                 session.</para></listitem>
195                         </varlistentry>
196
197                         <varlistentry>
198                                 <term><varname>$XDG_RUNTIME_DIR</varname></term>
199
200                                 <listitem><para>Path to a user-private
201                                 user-writable directory that is bound
202                                 to the user login time on the
203                                 machine. It is automatically created
204                                 the first time a user logs in and
205                                 removed on his final logout. If a user
206                                 logs in twice at the same time, both
207                                 sessions will see the same
208                                 <varname>$XDG_RUNTIME_DIR</varname>
209                                 and the same contents. If a user logs
210                                 in once, then logs out again, and logs
211                                 in again, the directory contents will
212                                 have been lost in between, but
213                                 applications should not rely on this
214                                 behavior and must be able to deal with
215                                 stale files. To store session-private
216                                 data in this directory, the user should
217                                 include the value of <varname>$XDG_SESSION_ID</varname>
218                                 in the filename. This directory shall
219                                 be used for runtime file system
220                                 objects such as <constant>AF_UNIX</constant> sockets,
221                                 FIFOs, PID files and similar. It is
222                                 guaranteed that this directory is
223                                 local and offers the greatest possible
224                                 file system feature set the
225                                 operating system
226                                 provides.</para></listitem>
227                         </varlistentry>
228
229                 </variablelist>
230
231                 <para>The following environment variables are read by
232                 the module and may be used by the PAM service to pass
233                 metadata to the module:</para>
234
235                 <variablelist class='environment-variables'>
236                         <varlistentry>
237                                 <term><varname>$XDG_SESSION_TYPE</varname></term>
238
239                                 <listitem><para>The session type. This
240                                 may be used instead of
241                                 <option>session=</option> on the
242                                 module parameter line, and is usually
243                                 preferred.</para></listitem>
244                         </varlistentry>
245
246                         <varlistentry>
247                                 <term><varname>$XDG_SESSION_CLASS</varname></term>
248
249                                 <listitem><para>The session class. This
250                                 may be used instead of
251                                 <option>class=</option> on the
252                                 module parameter line, and is usually
253                                 preferred.</para></listitem>
254                         </varlistentry>
255
256                         <varlistentry>
257                                 <term><varname>$XDG_SESSION_DESKTOP</varname></term>
258
259                                 <listitem><para>A single, short
260                                 identifier string for the desktop
261                                 environment. This may be used to
262                                 indicate the session desktop used,
263                                 where this applies and if this
264                                 information is available. For example:
265                                 <literal>GNOME</literal>, or
266                                 <literal>KDE</literal>. It is
267                                 recommended to use the same
268                                 identifiers and capitalization as for
269                                 <varname>$XDG_CURRENT_DESKTOP</varname>,
270                                 as defined by the <ulink
271                                 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
272                                 Entry
273                                 Specification</ulink>. See
274                                 <citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
275                                 for more details.</para></listitem>
276                         </varlistentry>
277
278                         <varlistentry>
279                                 <term><varname>$XDG_SEAT</varname></term>
280
281                                 <listitem><para>The seat name the session
282                                 shall be registered for, if
283                                 any.</para></listitem>
284                         </varlistentry>
285
286                         <varlistentry>
287                                 <term><varname>$XDG_VTNR</varname></term>
288
289                                 <listitem><para>The VT number the
290                                 session shall be registered for, if
291                                 any. (Only applies to seats with a VT
292                                 available, such as
293                                 <literal>seat0</literal>)</para></listitem>
294                         </varlistentry>
295
296                 </variablelist>
297         </refsect1>
298
299         <refsect1>
300                 <title>Example</title>
301
302                 <programlisting>#%PAM-1.0
303 auth       required     pam_unix.so
304 auth       required     pam_nologin.so
305 account    required     pam_unix.so
306 password   required     pam_unix.so
307 session    required     pam_unix.so
308 session    required     pam_loginuid.so
309 session    required     pam_systemd.so</programlisting>
310         </refsect1>
311
312         <refsect1>
313                 <title>See Also</title>
314                 <para>
315                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
316                         <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
317                         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
318                         <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
319                         <citerefentry project='man-pages'><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
320                         <citerefentry project='man-pages'><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
321                         <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
322                         <citerefentry project='man-pages'><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
323                         <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
324                         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
325                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
326                 </para>
327         </refsect1>
328
329 </refentry>