]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/pam_systemd.xml
zsh-completion: remove duplicate function
[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,
5aaeda04 102 the user's systemd instance will be
c1405e4f 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
4a9dfff9
LP
216 data in this directory, the user
217 should include the value of
218 <varname>$XDG_SESSION_ID</varname> in
219 the filename. This directory shall be
220 used for runtime file system objects
221 such as <constant>AF_UNIX</constant>
222 sockets, FIFOs, PID files and
223 similar. It is guaranteed that this
224 directory is local and offers the
225 greatest possible file system feature
226 set the operating system provides. For
227 further details see the <ulink
228 url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
229 Base Directory
230 Specification</ulink>.</para></listitem>
160cd5c9 231 </varlistentry>
a4cd87e9
LP
232
233 </variablelist>
234
235 <para>The following environment variables are read by
236 the module and may be used by the PAM service to pass
66f756d4 237 metadata to the module:</para>
a4cd87e9
LP
238
239 <variablelist class='environment-variables'>
240 <varlistentry>
241 <term><varname>$XDG_SESSION_TYPE</varname></term>
242
243 <listitem><para>The session type. This
244 may be used instead of
245 <option>session=</option> on the
246 module parameter line, and is usually
247 preferred.</para></listitem>
248 </varlistentry>
249
250 <varlistentry>
251 <term><varname>$XDG_SESSION_CLASS</varname></term>
252
253 <listitem><para>The session class. This
254 may be used instead of
255 <option>class=</option> on the
256 module parameter line, and is usually
257 preferred.</para></listitem>
258 </varlistentry>
259
260 <varlistentry>
261 <term><varname>$XDG_SESSION_DESKTOP</varname></term>
262
44231166
LP
263 <listitem><para>A single, short
264 identifier string for the desktop
265 environment. This may be used to
266 indicate the session desktop used,
267 where this applies and if this
a4cd87e9 268 information is available. For example:
44231166
LP
269 <literal>GNOME</literal>, or
270 <literal>KDE</literal>. It is
271 recommended to use the same
272 identifiers and capitalization as for
273 <varname>$XDG_CURRENT_DESKTOP</varname>,
274 as defined by the <ulink
275 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
d1b6f12e
LP
276 Entry Specification</ulink>. (However,
277 note that
278 <varname>$XDG_SESSION_DESKTOP</varname>
279 only takes a single item, and not a
280 colon-separated list like
281 <varname>$XDG_CURRENT_DESKTOP</varname>.)
282 See
c72d5456
DH
283 <citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
284 for more details.</para></listitem>
a4cd87e9
LP
285 </varlistentry>
286
287 <varlistentry>
288 <term><varname>$XDG_SEAT</varname></term>
289
290 <listitem><para>The seat name the session
291 shall be registered for, if
292 any.</para></listitem>
293 </varlistentry>
294
295 <varlistentry>
296 <term><varname>$XDG_VTNR</varname></term>
297
298 <listitem><para>The VT number the
299 session shall be registered for, if
300 any. (Only applies to seats with a VT
301 available, such as
302 <literal>seat0</literal>)</para></listitem>
303 </varlistentry>
304
160cd5c9
LP
305 </variablelist>
306 </refsect1>
307
308 <refsect1>
309 <title>Example</title>
310
311 <programlisting>#%PAM-1.0
312auth required pam_unix.so
313auth required pam_nologin.so
314account required pam_unix.so
315password required pam_unix.so
316session required pam_unix.so
317session required pam_loginuid.so
3e2f69b7 318session required pam_systemd.so</programlisting>
160cd5c9
LP
319 </refsect1>
320
321 <refsect1>
322 <title>See Also</title>
323 <para>
af3bccd6
LP
324 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
325 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
326 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
327 <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
5aded369
ZJS
328 <citerefentry project='man-pages'><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
329 <citerefentry project='man-pages'><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
330 <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
331 <citerefentry project='man-pages'><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
3e2f69b7
LP
332 <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
333 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
334 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
160cd5c9
LP
335 </para>
336 </refsect1>
337
338</refentry>