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> or
149 <literal>wayland</literal>. See
150 <citerefentry><refentrytitle>sd_session_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry>
151 for details about the session type.</para></listitem>
155 <term><option>debug<optional>=</optional></option></term>
157 <listitem><para>Takes an optional
158 boolean argument. If yes or without
159 the argument, the module will log
160 debugging information as it
161 operates.</para></listitem>
167 <title>Module Types Provided</title>
169 <para>Only <option>session</option> is provided.</para>
173 <title>Environment</title>
175 <para>The following environment variables are set for the processes of the user's session:</para>
177 <variablelist class='environment-variables'>
179 <term><varname>$XDG_SESSION_ID</varname></term>
181 <listitem><para>A session identifier,
182 suitable to be used in filenames. The
183 string itself should be considered
184 opaque, although often it is just the
185 audit session ID as reported by
186 <filename>/proc/self/sessionid</filename>. Each
187 ID will be assigned only once during
188 machine uptime. It may hence be used
189 to uniquely label files or other
191 session.</para></listitem>
195 <term><varname>$XDG_RUNTIME_DIR</varname></term>
197 <listitem><para>Path to a user-private
198 user-writable directory that is bound
199 to the user login time on the
200 machine. It is automatically created
201 the first time a user logs in and
202 removed on his final logout. If a user
203 logs in twice at the same time, both
204 sessions will see the same
205 <varname>$XDG_RUNTIME_DIR</varname>
206 and the same contents. If a user logs
207 in once, then logs out again, and logs
208 in again, the directory contents will
209 have been lost in between, but
210 applications should not rely on this
211 behavior and must be able to deal with
212 stale files. To store session-private
213 data in this directory, the user should
214 include the value of <varname>$XDG_SESSION_ID</varname>
215 in the filename. This directory shall
216 be used for runtime file system
217 objects such as <constant>AF_UNIX</constant> sockets,
218 FIFOs, PID files and similar. It is
219 guaranteed that this directory is
220 local and offers the greatest possible
221 file system feature set the
223 provides.</para></listitem>
228 <para>The following environment variables are read by
229 the module and may be used by the PAM service to pass
230 metadata to the module:</para>
232 <variablelist class='environment-variables'>
234 <term><varname>$XDG_SESSION_TYPE</varname></term>
236 <listitem><para>The session type. This
237 may be used instead of
238 <option>session=</option> on the
239 module parameter line, and is usually
240 preferred.</para></listitem>
244 <term><varname>$XDG_SESSION_CLASS</varname></term>
246 <listitem><para>The session class. This
247 may be used instead of
248 <option>class=</option> on the
249 module parameter line, and is usually
250 preferred.</para></listitem>
254 <term><varname>$XDG_SESSION_DESKTOP</varname></term>
256 <listitem><para>The session
257 deskop. This may be used to indicate
258 the session desktop used, where this
259 applies. This should be a short,
260 lowercase string identifying the
261 desktop environment used if this
262 information is available. For example:
263 <literal>gnome</literal>, or
264 <literal>kde</literal>.</para></listitem>
268 <term><varname>$XDG_SEAT</varname></term>
270 <listitem><para>The seat name the session
271 shall be registered for, if
272 any.</para></listitem>
276 <term><varname>$XDG_VTNR</varname></term>
278 <listitem><para>The VT number the
279 session shall be registered for, if
280 any. (Only applies to seats with a VT
282 <literal>seat0</literal>)</para></listitem>
289 <title>Example</title>
291 <programlisting>#%PAM-1.0
292 auth required pam_unix.so
293 auth required pam_nologin.so
294 account required pam_unix.so
295 password required pam_unix.so
296 session required pam_unix.so
297 session required pam_loginuid.so
298 session required pam_systemd.so</programlisting>
302 <title>See Also</title>
304 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
305 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
306 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
307 <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
308 <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
309 <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
310 <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
311 <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
312 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
313 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
314 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>