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 systemd.
8 Copyright 2010 Lennart Poettering
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.
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.
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/>.
24 <refentry id="pam_systemd" conditional='HAVE_PAM'>
27 <title>pam_systemd</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>pam_systemd</refentrytitle>
42 <manvolnum>8</manvolnum>
46 <refname>pam_systemd</refname>
47 <refpurpose>Register user sessions in the systemd login manager</refpurpose>
51 <para><filename>pam_systemd.so</filename></para>
55 <title>Description</title>
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>
62 <para>On login, this module ensures the following:</para>
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>
72 <varname>$XDG_SESSION_ID</varname> environment
73 variable is initialized. If auditing is
75 <command>pam_loginuid.so</command> was run before
76 this module (which is highly recommended), the
77 variable is initialized from the auditing
79 (<filename>/proc/self/sessionid</filename>). Otherwise,
80 an independent session counter is
81 used.</para></listitem>
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.
94 <para>On logout, this module ensures the following:</para>
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, their
102 user systemd instance will be terminated too,
103 and so will the user's slice
104 unit.</para></listitem>
106 <listitem><para>If the last concurrent session
108 <varname>$XDG_RUNTIME_DIR</varname> directory
109 and all its contents are removed,
110 too.</para></listitem>
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>
120 <title>Options</title>
122 <para>The following options are understood:</para>
124 <variablelist class='pam-directives'>
127 <term><option>class=</option></term>
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>
142 <term><option>type=</option></term>
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>
158 <term><option>debug<optional>=</optional></option></term>
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>
170 <title>Module Types Provided</title>
172 <para>Only <option>session</option> is provided.</para>
176 <title>Environment</title>
178 <para>The following environment variables are set for the processes of the user's session:</para>
180 <variablelist class='environment-variables'>
182 <term><varname>$XDG_SESSION_ID</varname></term>
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
194 session.</para></listitem>
198 <term><varname>$XDG_RUNTIME_DIR</varname></term>
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 their 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
226 provides.</para></listitem>
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>
235 <variablelist class='environment-variables'>
237 <term><varname>$XDG_SESSION_TYPE</varname></term>
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>
247 <term><varname>$XDG_SESSION_CLASS</varname></term>
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>
257 <term><varname>$XDG_SESSION_DESKTOP</varname></term>
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
273 Specification</ulink>. See
274 <citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
275 for more details.</para></listitem>
279 <term><varname>$XDG_SEAT</varname></term>
281 <listitem><para>The seat name the session
282 shall be registered for, if
283 any.</para></listitem>
287 <term><varname>$XDG_VTNR</varname></term>
289 <listitem><para>The VT number the
290 session shall be registered for, if
291 any. (Only applies to seats with a VT
293 <literal>seat0</literal>)</para></listitem>
300 <title>Example</title>
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>
313 <title>See Also</title>
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>