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">
6 This file is part of elogind.
8 Copyright 2010 Lennart Poettering
10 elogind 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.
15 elogind 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.
20 You should have received a copy of the GNU Lesser General Public License
21 along with elogind; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="pam_elogind" conditional='HAVE_PAM'>
27 <title>pam_elogind</title>
28 <productname>elogind</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>pam_elogind</refentrytitle>
42 <manvolnum>8</manvolnum>
46 <refname>pam_elogind</refname>
47 <refpurpose>Register user sessions in the elogind login manager</refpurpose>
51 <para><filename>pam_elogind.so</filename></para>
55 <title>Description</title>
57 <para><command>pam_elogind</command> registers user sessions with
58 the elogind login manager and hence the elogind control group
61 <para>On login, this module ensures the following:</para>
64 <listitem><para>If it does not exist yet, the user runtime
65 directory <filename>/run/user/$USER</filename> is created and
66 its ownership changed to the user that is logging
69 <listitem><para>The <varname>$XDG_SESSION_ID</varname>
70 environment variable is initialized. If auditing is available
71 and <command>pam_loginuid.so</command> was run before this
72 module (which is highly recommended), the variable is
73 initialized from the auditing session id
74 (<filename>/proc/self/sessionid</filename>). Otherwise, an
75 independent session counter is used.</para></listitem>
78 <para>On logout, this module ensures the following:</para>
81 <listitem><para>If enabled in
82 <citerefentry><refentrytitle>logind.conf</refentrytitle>
83 <manvolnum>5</manvolnum></citerefentry>, all processes of the
84 session are terminated.</para></listitem>
86 <listitem><para>If the last concurrent session of a user ends,
87 the <varname>$XDG_RUNTIME_DIR</varname> directory and all its
88 contents are removed, too.</para></listitem>
94 <title>Options</title>
96 <para>The following options are understood:</para>
98 <variablelist class='pam-directives'>
101 <term><option>class=</option></term>
103 <listitem><para>Takes a string argument which sets the session
104 class. The XDG_SESSION_CLASS environmental variable takes
106 <literal>user</literal>,
107 <literal>greeter</literal>,
108 <literal>lock-screen</literal> or
109 <literal>background</literal>. See
110 <citerefentry><refentrytitle>sd_session_get_class</refentrytitle><manvolnum>3</manvolnum></citerefentry>
111 for details about the session class.</para></listitem>
115 <term><option>type=</option></term>
117 <listitem><para>Takes a string argument which sets the session
118 type. The XDG_SESSION_TYPE environmental variable takes
120 <literal>unspecified</literal>,
121 <literal>tty</literal>,
122 <literal>x11</literal>,
123 <literal>wayland</literal> or
124 <literal>mir</literal>. See
125 <citerefentry><refentrytitle>sd_session_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry>
126 for details about the session type.</para></listitem>
130 <term><option>debug<optional>=</optional></option></term>
132 <listitem><para>Takes an optional
133 boolean argument. If yes or without
134 the argument, the module will log
135 debugging information as it
136 operates.</para></listitem>
142 <title>Module Types Provided</title>
144 <para>Only <option>session</option> is provided.</para>
148 <title>Environment</title>
150 <para>The following environment variables are set for the
151 processes of the user's session:</para>
153 <variablelist class='environment-variables'>
155 <term><varname>$XDG_SESSION_ID</varname></term>
157 <listitem><para>A session identifier, suitable to be used in
158 filenames. The string itself should be considered opaque,
159 although often it is just the audit session ID as reported by
160 <filename>/proc/self/sessionid</filename>. Each ID will be
161 assigned only once during machine uptime. It may hence be used
162 to uniquely label files or other resources of this
163 session.</para></listitem>
167 <term><varname>$XDG_RUNTIME_DIR</varname></term>
169 <listitem><para>Path to a user-private user-writable directory
170 that is bound to the user login time on the machine. It is
171 automatically created the first time a user logs in and
172 removed on the user's final logout. If a user logs in twice at
173 the same time, both sessions will see the same
174 <varname>$XDG_RUNTIME_DIR</varname> and the same contents. If
175 a user logs in once, then logs out again, and logs in again,
176 the directory contents will have been lost in between, but
177 applications should not rely on this behavior and must be able
178 to deal with stale files. To store session-private data in
179 this directory, the user should include the value of
180 <varname>$XDG_SESSION_ID</varname> in the filename. This
181 directory shall be used for runtime file system objects such
182 as <constant>AF_UNIX</constant> sockets, FIFOs, PID files and
183 similar. It is guaranteed that this directory is local and
184 offers the greatest possible file system feature set the
185 operating system provides. For further details see the <ulink
186 url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
187 Base Directory Specification</ulink>.</para></listitem>
192 <para>The following environment variables are read by the module
193 and may be used by the PAM service to pass metadata to the
196 <variablelist class='environment-variables'>
198 <term><varname>$XDG_SESSION_TYPE</varname></term>
200 <listitem><para>The session type. This may be used instead of
201 <option>session=</option> on the module parameter line, and is
202 usually preferred.</para></listitem>
206 <term><varname>$XDG_SESSION_CLASS</varname></term>
208 <listitem><para>The session class. This may be used instead of
209 <option>class=</option> on the module parameter line, and is
210 usually preferred.</para></listitem>
214 <term><varname>$XDG_SESSION_DESKTOP</varname></term>
216 <listitem><para>A single, short identifier string for the
217 desktop environment. This may be used to indicate the session
218 desktop used, where this applies and if this information is
219 available. For example: <literal>GNOME</literal>, or
220 <literal>KDE</literal>. It is recommended to use the same
221 identifiers and capitalization as for
222 <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the
224 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
225 Entry Specification</ulink>. (However, note that
226 <varname>$XDG_SESSION_DESKTOP</varname> only takes a single
227 item, and not a colon-separated list like
228 <varname>$XDG_CURRENT_DESKTOP</varname>.) See
229 <citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
230 for more details.</para></listitem>
234 <term><varname>$XDG_SEAT</varname></term>
236 <listitem><para>The seat name the session shall be registered
237 for, if any.</para></listitem>
241 <term><varname>$XDG_VTNR</varname></term>
243 <listitem><para>The VT number the session shall be registered
244 for, if any. (Only applies to seats with a VT available, such
245 as <literal>seat0</literal>)</para></listitem>
252 <title>Example</title>
254 <programlisting>#%PAM-1.0
255 auth required pam_unix.so
256 auth required pam_nologin.so
257 account required pam_unix.so
258 password required pam_unix.so
259 session required pam_unix.so
260 session required pam_loginuid.so
261 session required pam_elogind.so</programlisting>
265 <title>See Also</title>
267 <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
268 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
269 <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
270 <citerefentry project='man-pages'><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
271 <citerefentry project='man-pages'><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
272 <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
273 <citerefentry project='man-pages'><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>