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 systemd login manager
59 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
60 and hence the systemd control group hierarchy.</para>
62 <para>On login, this module — in conjunction with <filename>systemd-logind.service</filename> — ensures the
66 <listitem><para>If it does not exist yet, the user runtime directory <filename>/run/user/$UID</filename> is
67 either created or mounted as new <literal>tmpfs</literal> file system with quota applied, and its ownership
68 changed to the user that is logging in.</para></listitem>
70 <listitem><para>The <varname>$XDG_SESSION_ID</varname> environment variable is initialized. If auditing is
71 available and <command>pam_loginuid.so</command> was run before this module (which is highly recommended), the
72 variable is initialized from the auditing session id (<filename>/proc/self/sessionid</filename>). Otherwise, an
73 independent session counter is used.</para></listitem>
75 <listitem><para>A new systemd scope unit is created for the session. If this is the first concurrent session of
76 the user, an implicit per-user slice unit below <filename>user.slice</filename> is automatically created and the
77 scope placed into it. An instance of the system service <filename>user@.service</filename>, which runs the
78 systemd user manager instance, is started. </para></listitem>
81 <para>On logout, this module ensures the following:</para>
84 <listitem><para>If enabled in
85 <citerefentry><refentrytitle>logind.conf</refentrytitle>
86 <manvolnum>5</manvolnum></citerefentry> (<varname>KillUserProcesses=</varname>), all processes of the session are
87 terminated. If the last concurrent session of a user ends, the user's systemd instance will be terminated too,
88 and so will the user's slice unit.</para></listitem>
90 <listitem><para>If the last concurrent session of a user ends,
91 the <varname>$XDG_RUNTIME_DIR</varname> directory and all its
92 contents are removed, too.</para></listitem>
95 <para>If the system was not booted up with systemd as init system,
96 this module does nothing and immediately returns
97 <constant>PAM_SUCCESS</constant>.</para>
102 <title>Options</title>
104 <para>The following options are understood:</para>
106 <variablelist class='pam-directives'>
109 <term><option>class=</option></term>
111 <listitem><para>Takes a string argument which sets the session
112 class. The XDG_SESSION_CLASS environmental variable takes
114 <literal>user</literal>,
115 <literal>greeter</literal>,
116 <literal>lock-screen</literal> or
117 <literal>background</literal>. See
118 <citerefentry><refentrytitle>sd_session_get_class</refentrytitle><manvolnum>3</manvolnum></citerefentry>
119 for details about the session class.</para></listitem>
123 <term><option>type=</option></term>
125 <listitem><para>Takes a string argument which sets the session
126 type. The XDG_SESSION_TYPE environmental variable takes
128 <literal>unspecified</literal>,
129 <literal>tty</literal>,
130 <literal>x11</literal>,
131 <literal>wayland</literal> or
132 <literal>mir</literal>. See
133 <citerefentry><refentrytitle>sd_session_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry>
134 for details about the session type.</para></listitem>
138 <term><option>debug<optional>=</optional></option></term>
140 <listitem><para>Takes an optional
141 boolean argument. If yes or without
142 the argument, the module will log
143 debugging information as it
144 operates.</para></listitem>
150 <title>Module Types Provided</title>
152 <para>Only <option>session</option> is provided.</para>
156 <title>Environment</title>
158 <para>The following environment variables are set for the
159 processes of the user's session:</para>
161 <variablelist class='environment-variables'>
163 <term><varname>$XDG_SESSION_ID</varname></term>
165 <listitem><para>A session identifier, suitable to be used in
166 filenames. The string itself should be considered opaque,
167 although often it is just the audit session ID as reported by
168 <filename>/proc/self/sessionid</filename>. Each ID will be
169 assigned only once during machine uptime. It may hence be used
170 to uniquely label files or other resources of this
171 session.</para></listitem>
175 <term><varname>$XDG_RUNTIME_DIR</varname></term>
177 <listitem><para>Path to a user-private user-writable directory
178 that is bound to the user login time on the machine. It is
179 automatically created the first time a user logs in and
180 removed on the user's final logout. If a user logs in twice at
181 the same time, both sessions will see the same
182 <varname>$XDG_RUNTIME_DIR</varname> and the same contents. If
183 a user logs in once, then logs out again, and logs in again,
184 the directory contents will have been lost in between, but
185 applications should not rely on this behavior and must be able
186 to deal with stale files. To store session-private data in
187 this directory, the user should include the value of
188 <varname>$XDG_SESSION_ID</varname> in the filename. This
189 directory shall be used for runtime file system objects such
190 as <constant>AF_UNIX</constant> sockets, FIFOs, PID files and
191 similar. It is guaranteed that this directory is local and
192 offers the greatest possible file system feature set the
193 operating system provides. For further details, see the <ulink
194 url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
195 Base Directory Specification</ulink>.</para></listitem>
200 <para>The following environment variables are read by the module
201 and may be used by the PAM service to pass metadata to the
204 <variablelist class='environment-variables'>
206 <term><varname>$XDG_SESSION_TYPE</varname></term>
208 <listitem><para>The session type. This may be used instead of
209 <option>session=</option> on the module parameter line, and is
210 usually preferred.</para></listitem>
214 <term><varname>$XDG_SESSION_CLASS</varname></term>
216 <listitem><para>The session class. This may be used instead of
217 <option>class=</option> on the module parameter line, and is
218 usually preferred.</para></listitem>
222 <term><varname>$XDG_SESSION_DESKTOP</varname></term>
224 <listitem><para>A single, short identifier string for the
225 desktop environment. This may be used to indicate the session
226 desktop used, where this applies and if this information is
227 available. For example: <literal>GNOME</literal>, or
228 <literal>KDE</literal>. It is recommended to use the same
229 identifiers and capitalization as for
230 <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the
232 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
233 Entry Specification</ulink>. (However, note that
234 <varname>$XDG_SESSION_DESKTOP</varname> only takes a single
235 item, and not a colon-separated list like
236 <varname>$XDG_CURRENT_DESKTOP</varname>.) See
237 <citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
238 for more details.</para></listitem>
242 <term><varname>$XDG_SEAT</varname></term>
244 <listitem><para>The seat name the session shall be registered
245 for, if any.</para></listitem>
249 <term><varname>$XDG_VTNR</varname></term>
251 <listitem><para>The VT number the session shall be registered
252 for, if any. (Only applies to seats with a VT available, such
253 as <literal>seat0</literal>)</para></listitem>
260 <title>Example</title>
262 <programlisting>#%PAM-1.0
263 auth required pam_unix.so
264 auth required pam_nologin.so
265 account required pam_unix.so
266 password required pam_unix.so
267 session required pam_unix.so
268 session required pam_loginuid.so
269 session required pam_elogind.so</programlisting>
273 <title>See Also</title>
275 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
276 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
277 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
278 <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
279 <citerefentry project='man-pages'><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
280 <citerefentry project='man-pages'><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
281 <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
282 <citerefentry project='man-pages'><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
283 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
284 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
285 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>