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