]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/pam_systemd.xml
man: avoid gendered singular pronouns
[thirdparty/systemd.git] / man / pam_systemd.xml
CommitLineData
160cd5c9
LP
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">
4
5<!--
6 This file is part of systemd.
7
8 Copyright 2010 Lennart Poettering
9
10 systemd is free software; you can redistribute it and/or modify it
5430f7f2
LP
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
160cd5c9
LP
13 (at your option) any later version.
14
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
5430f7f2 18 Lesser General Public License for more details.
160cd5c9 19
5430f7f2 20 You should have received a copy of the GNU Lesser General Public License
160cd5c9
LP
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
22-->
23
47c49034 24<refentry id="pam_systemd" conditional='HAVE_PAM'>
160cd5c9
LP
25
26 <refentryinfo>
27 <title>pam_systemd</title>
28 <productname>systemd</productname>
29
30 <authorgroup>
31 <author>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
36 </author>
37 </authorgroup>
38 </refentryinfo>
39
40 <refmeta>
41 <refentrytitle>pam_systemd</refentrytitle>
42 <manvolnum>8</manvolnum>
43 </refmeta>
44
45 <refnamediv>
46 <refname>pam_systemd</refname>
af3bccd6 47 <refpurpose>Register user sessions in the systemd login manager</refpurpose>
160cd5c9
LP
48 </refnamediv>
49
50 <refsynopsisdiv>
e670b166 51 <para><filename>pam_systemd.so</filename></para>
160cd5c9
LP
52 </refsynopsisdiv>
53
54 <refsect1>
55 <title>Description</title>
56
57 <para><command>pam_systemd</command> registers user
3fde5f30 58 sessions with the systemd login manager
af3bccd6
LP
59 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
60 and hence the systemd control group hierarchy.</para>
160cd5c9
LP
61
62 <para>On login, this module ensures the following:</para>
63
64 <orderedlist>
af62c704 65 <listitem><para>If it does not exist yet, the
160cd5c9 66 user runtime directory
bb29785e 67 <filename>/run/user/$USER</filename> is
160cd5c9
LP
68 created and its ownership changed to the user
69 that is logging in.</para></listitem>
70
c36eecdf 71 <listitem><para>The
160cd5c9
LP
72 <varname>$XDG_SESSION_ID</varname> environment
73 variable is initialized. If auditing is
74 available and
af951ff5 75 <command>pam_loginuid.so</command> was run before
af62c704 76 this module (which is highly recommended), the
160cd5c9
LP
77 variable is initialized from the auditing
78 session id
af951ff5 79 (<filename>/proc/self/sessionid</filename>). Otherwise,
160cd5c9
LP
80 an independent session counter is
81 used.</para></listitem>
82
3e2f69b7
LP
83 <listitem><para>A new systemd scope unit is
84 created for the session. If this is the first
fbce1139 85 concurrent session of the user, an implicit
3e2f69b7 86 slice below <filename>user.slice</filename> is
af951ff5
DM
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.
91 </para></listitem>
160cd5c9
LP
92 </orderedlist>
93
94 <para>On logout, this module ensures the following:</para>
95
96 <orderedlist>
af951ff5
DM
97 <listitem><para>If enabled in
98 <citerefentry><refentrytitle>logind.conf</refentrytitle>
c1405e4f
LP
99 <manvolnum>5</manvolnum></citerefentry>, all
100 processes of the session are terminated. If
101 the last concurrent session of a user ends,
102 ther user's systemd instance will be
103 terminated too, and so will the user's slice
3e2f69b7
LP
104 unit.</para></listitem>
105
fbce1139
JE
106 <listitem><para>If the last concurrent session
107 of a user ends, the
160cd5c9 108 <varname>$XDG_RUNTIME_DIR</varname> directory
3e2f69b7
LP
109 and all its contents are removed,
110 too.</para></listitem>
160cd5c9
LP
111 </orderedlist>
112
113 <para>If the system was not booted up with systemd as
af62c704 114 init system, this module does nothing and immediately
160cd5c9
LP
115 returns PAM_SUCCESS.</para>
116
117 </refsect1>
118
119 <refsect1>
120 <title>Options</title>
121
122 <para>The following options are understood:</para>
123
ccc9a4f9 124 <variablelist class='pam-directives'>
0e318cad 125
485507b8
MM
126 <varlistentry>
127 <term><option>class=</option></term>
128
129 <listitem><para>Takes a string
130 argument which sets the session class.
131 The XDG_SESSION_CLASS environmental variable
49ebd11f
LP
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>
139 </varlistentry>
140
141 <varlistentry>
142 <term><option>type=</option></term>
143
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>,
9541666b
DH
150 <literal>x11</literal>,
151 <literal>wayland</literal> or
152 <literal>mir</literal>. See
49ebd11f
LP
153 <citerefentry><refentrytitle>sd_session_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry>
154 for details about the session type.</para></listitem>
485507b8
MM
155 </varlistentry>
156
0e318cad 157 <varlistentry>
05a049cc 158 <term><option>debug<optional>=</optional></option></term>
0e318cad 159
05a049cc
ZJS
160 <listitem><para>Takes an optional
161 boolean argument. If yes or without
162 the argument, the module will log
c36eecdf
LP
163 debugging information as it
164 operates.</para></listitem>
0e318cad 165 </varlistentry>
160cd5c9 166 </variablelist>
160cd5c9
LP
167 </refsect1>
168
169 <refsect1>
170 <title>Module Types Provided</title>
171
172 <para>Only <option>session</option> is provided.</para>
173 </refsect1>
174
175 <refsect1>
176 <title>Environment</title>
177
58474090
LP
178 <para>The following environment variables are set for the processes of the user's session:</para>
179
ccc9a4f9 180 <variablelist class='environment-variables'>
160cd5c9
LP
181 <varlistentry>
182 <term><varname>$XDG_SESSION_ID</varname></term>
183
184 <listitem><para>A session identifier,
e9dd9f95 185 suitable to be used in filenames. The
160cd5c9
LP
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
193 resources of this
194 session.</para></listitem>
195 </varlistentry>
196
197 <varlistentry>
198 <term><varname>$XDG_RUNTIME_DIR</varname></term>
199
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
c1405e4f
LP
205 removed on the user's final logout. If
206 a user logs in twice at the same time,
207 both sessions will see the same
160cd5c9
LP
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
c5315881 214 behavior and must be able to deal with
160cd5c9 215 stale files. To store session-private
e9dd9f95 216 data in this directory, the user should
160cd5c9
LP
217 include the value of <varname>$XDG_SESSION_ID</varname>
218 in the filename. This directory shall
219 be used for runtime file system
74d00578 220 objects such as <constant>AF_UNIX</constant> sockets,
160cd5c9
LP
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
225 operating system
226 provides.</para></listitem>
227 </varlistentry>
a4cd87e9
LP
228
229 </variablelist>
230
231 <para>The following environment variables are read by
232 the module and may be used by the PAM service to pass
66f756d4 233 metadata to the module:</para>
a4cd87e9
LP
234
235 <variablelist class='environment-variables'>
236 <varlistentry>
237 <term><varname>$XDG_SESSION_TYPE</varname></term>
238
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>
244 </varlistentry>
245
246 <varlistentry>
247 <term><varname>$XDG_SESSION_CLASS</varname></term>
248
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>
254 </varlistentry>
255
256 <varlistentry>
257 <term><varname>$XDG_SESSION_DESKTOP</varname></term>
258
44231166
LP
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
a4cd87e9 264 information is available. For example:
44231166
LP
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
272 Entry
c72d5456
DH
273 Specification</ulink>. See
274 <citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
275 for more details.</para></listitem>
a4cd87e9
LP
276 </varlistentry>
277
278 <varlistentry>
279 <term><varname>$XDG_SEAT</varname></term>
280
281 <listitem><para>The seat name the session
282 shall be registered for, if
283 any.</para></listitem>
284 </varlistentry>
285
286 <varlistentry>
287 <term><varname>$XDG_VTNR</varname></term>
288
289 <listitem><para>The VT number the
290 session shall be registered for, if
291 any. (Only applies to seats with a VT
292 available, such as
293 <literal>seat0</literal>)</para></listitem>
294 </varlistentry>
295
160cd5c9
LP
296 </variablelist>
297 </refsect1>
298
299 <refsect1>
300 <title>Example</title>
301
302 <programlisting>#%PAM-1.0
303auth required pam_unix.so
304auth required pam_nologin.so
305account required pam_unix.so
306password required pam_unix.so
307session required pam_unix.so
308session required pam_loginuid.so
3e2f69b7 309session required pam_systemd.so</programlisting>
160cd5c9
LP
310 </refsect1>
311
312 <refsect1>
313 <title>See Also</title>
314 <para>
af3bccd6
LP
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>,
5aded369
ZJS
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>,
3e2f69b7
LP
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>
160cd5c9
LP
326 </para>
327 </refsect1>
328
329</refentry>