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