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> 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 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>
94 <para>On logout, this module ensures the following:</para>
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>
104 <listitem><para>If the last concurrent session
106 <varname>$XDG_RUNTIME_DIR</varname> directory
107 and all its contents are removed,
108 too.</para></listitem>
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>
118 <title>Options</title>
120 <para>The following options are understood:</para>
122 <variablelist class='pam-directives'>
125 <term><option>class=</option></term>
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>
140 <term><option>type=</option></term>
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>
156 <term><option>debug<optional>=</optional></option></term>
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>
168 <title>Module Types Provided</title>
170 <para>Only <option>session</option> is provided.</para>
174 <title>Environment</title>
176 <para>The following environment variables are set for the processes of the user's session:</para>
178 <variablelist class='environment-variables'>
180 <term><varname>$XDG_SESSION_ID</varname></term>
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
192 session.</para></listitem>
196 <term><varname>$XDG_RUNTIME_DIR</varname></term>
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
224 provides.</para></listitem>
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>
233 <variablelist class='environment-variables'>
235 <term><varname>$XDG_SESSION_TYPE</varname></term>
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>
245 <term><varname>$XDG_SESSION_CLASS</varname></term>
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>
255 <term><varname>$XDG_SESSION_DESKTOP</varname></term>
257 <listitem><para>The session
258 deskop. This may be used to indicate
259 the session desktop used, where this
260 applies. This should be a short,
261 lowercase string identifying the
262 desktop environment used if this
263 information is available. For example:
264 <literal>gnome</literal>, or
265 <literal>kde</literal>.</para></listitem>
269 <term><varname>$XDG_SEAT</varname></term>
271 <listitem><para>The seat name the session
272 shall be registered for, if
273 any.</para></listitem>
277 <term><varname>$XDG_VTNR</varname></term>
279 <listitem><para>The VT number the
280 session shall be registered for, if
281 any. (Only applies to seats with a VT
283 <literal>seat0</literal>)</para></listitem>
290 <title>Example</title>
292 <programlisting>#%PAM-1.0
293 auth required pam_unix.so
294 auth required pam_nologin.so
295 account required pam_unix.so
296 password required pam_unix.so
297 session required pam_unix.so
298 session required pam_loginuid.so
299 session required pam_systemd.so</programlisting>
303 <title>See Also</title>
305 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
306 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
307 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
308 <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
309 <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
310 <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
311 <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
312 <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
313 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
314 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
315 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>