chiark / gitweb /
rtnl: match - only match on one type at a time
[elogind.git] / man / pam_systemd.xml
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
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.
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
18   Lesser General Public License for more details.
19
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/>.
22 -->
23
24 <refentry id="pam_systemd" conditional='HAVE_PAM'>
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>
47                 <refpurpose>Register user sessions in the systemd login manager</refpurpose>
48         </refnamediv>
49
50         <refsynopsisdiv>
51                 <para><filename>pam_systemd.so</filename></para>
52         </refsynopsisdiv>
53
54         <refsect1>
55                 <title>Description</title>
56
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>
61
62                 <para>On login, this module ensures the following:</para>
63
64                 <orderedlist>
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>
70
71                         <listitem><para>The
72                         <varname>$XDG_SESSION_ID</varname> environment
73                         variable is initialized. If auditing is
74                         available and
75                         <command>pam_loginuid.so</command> run before
76                         this module (which is highly recommended), the
77                         variable is initialized from the auditing
78                         session id
79                         (<filename>/proc/self/sessionid</filename>). Otherwise
80                         an independent session counter is
81                         used.</para></listitem>
82
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>
92                 </orderedlist>
93
94                 <para>On logout, this module ensures the following:</para>
95
96                 <orderedlist>
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>
103
104                         <listitem><para>If the last concurrent session
105                         of a user ends, the
106                         <varname>$XDG_RUNTIME_DIR</varname> directory
107                         and all its contents are removed,
108                         too.</para></listitem>
109                 </orderedlist>
110
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>
114
115         </refsect1>
116
117         <refsect1>
118                 <title>Options</title>
119
120                 <para>The following options are understood:</para>
121
122                 <variablelist class='pam-directives'>
123
124                         <varlistentry>
125                                 <term><option>class=</option></term>
126
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>
131                         </varlistentry>
132
133                         <varlistentry>
134                                 <term><option>debug<optional>=</optional></option></term>
135
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>
141                         </varlistentry>
142                 </variablelist>
143         </refsect1>
144
145         <refsect1>
146                 <title>Module Types Provided</title>
147
148                 <para>Only <option>session</option> is provided.</para>
149         </refsect1>
150
151         <refsect1>
152                 <title>Environment</title>
153
154                 <para>The following environment variables are set for the processes of the user's session:</para>
155
156                 <variablelist class='environment-variables'>
157                         <varlistentry>
158                                 <term><varname>$XDG_SESSION_ID</varname></term>
159
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
169                                 resources of this
170                                 session.</para></listitem>
171                         </varlistentry>
172
173                         <varlistentry>
174                                 <term><varname>$XDG_RUNTIME_DIR</varname></term>
175
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
201                                 operating system
202                                 provides.</para></listitem>
203                         </varlistentry>
204                 </variablelist>
205         </refsect1>
206
207         <refsect1>
208                 <title>Example</title>
209
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>
218         </refsect1>
219
220         <refsect1>
221                 <title>See Also</title>
222                 <para>
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>
234                 </para>
235         </refsect1>
236
237 </refentry>