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.</para></listitem>
134 <term><option>debug<optional>=</optional></option></term>
136 <listitem><para>Takes an optional
137 boolean argument. If yes or without
138 the argument, the module will log
139 debugging information as it
140 operates.</para></listitem>
146 <title>Module Types Provided</title>
148 <para>Only <option>session</option> is provided.</para>
152 <title>Environment</title>
154 <para>The following environment variables are set for the processes of the user's session:</para>
156 <variablelist class='environment-variables'>
158 <term><varname>$XDG_SESSION_ID</varname></term>
160 <listitem><para>A session identifier,
161 suitable to be used in filenames. The
162 string itself should be considered
163 opaque, although often it is just the
164 audit session ID as reported by
165 <filename>/proc/self/sessionid</filename>. Each
166 ID will be assigned only once during
167 machine uptime. It may hence be used
168 to uniquely label files or other
170 session.</para></listitem>
174 <term><varname>$XDG_RUNTIME_DIR</varname></term>
176 <listitem><para>Path to a user-private
177 user-writable directory that is bound
178 to the user login time on the
179 machine. It is automatically created
180 the first time a user logs in and
181 removed on his final logout. If a user
182 logs in twice at the same time, both
183 sessions will see the same
184 <varname>$XDG_RUNTIME_DIR</varname>
185 and the same contents. If a user logs
186 in once, then logs out again, and logs
187 in again, the directory contents will
188 have been lost in between, but
189 applications should not rely on this
190 behavior and must be able to deal with
191 stale files. To store session-private
192 data in this directory, the user should
193 include the value of <varname>$XDG_SESSION_ID</varname>
194 in the filename. This directory shall
195 be used for runtime file system
196 objects such as <constant>AF_UNIX</constant> sockets,
197 FIFOs, PID files and similar. It is
198 guaranteed that this directory is
199 local and offers the greatest possible
200 file system feature set the
202 provides.</para></listitem>
208 <title>Example</title>
210 <programlisting>#%PAM-1.0
211 auth required pam_unix.so
212 auth required pam_nologin.so
213 account required pam_unix.so
214 password required pam_unix.so
215 session required pam_unix.so
216 session required pam_loginuid.so
217 session required pam_systemd.so</programlisting>
221 <title>See Also</title>
223 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
224 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
225 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
226 <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
227 <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
228 <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
229 <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
230 <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
231 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
232 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
233 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>