chiark / gitweb /
man: use unicode ellipsis in more places
[elogind.git] / man / pam_elogind.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 elogind.
7
8   Copyright 2010 Lennart Poettering
9
10   elogind 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   elogind 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 elogind; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="pam_elogind" conditional='HAVE_PAM'>
25
26   <refentryinfo>
27     <title>pam_elogind</title>
28     <productname>elogind</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_elogind</refentrytitle>
42     <manvolnum>8</manvolnum>
43   </refmeta>
44
45   <refnamediv>
46     <refname>pam_elogind</refname>
47     <refpurpose>Register user sessions in the elogind login manager</refpurpose>
48   </refnamediv>
49
50   <refsynopsisdiv>
51     <para><filename>pam_elogind.so</filename></para>
52   </refsynopsisdiv>
53
54   <refsect1>
55     <title>Description</title>
56
57     <para><command>pam_elogind</command> registers user sessions with
58     the elogind login manager and hence the elogind control group
59     hierarchy.</para>
60
61     <para>On login, this module ensures the following:</para>
62
63     <orderedlist>
64       <listitem><para>If it does not exist yet, the user runtime
65       directory <filename>/run/user/$USER</filename> is created and
66       its ownership changed to the user that is logging
67       in.</para></listitem>
68
69       <listitem><para>The <varname>$XDG_SESSION_ID</varname>
70       environment variable is initialized. If auditing is available
71       and <command>pam_loginuid.so</command> was run before this
72       module (which is highly recommended), the variable is
73       initialized from the auditing session id
74       (<filename>/proc/self/sessionid</filename>). Otherwise, an
75       independent session counter is used.</para></listitem>
76     </orderedlist>
77
78     <para>On logout, this module ensures the following:</para>
79
80     <orderedlist>
81       <listitem><para>If enabled in
82       <citerefentry><refentrytitle>logind.conf</refentrytitle>
83       <manvolnum>5</manvolnum></citerefentry>, all processes of the
84       session are terminated.</para></listitem>
85
86       <listitem><para>If the last concurrent session of a user ends,
87       the <varname>$XDG_RUNTIME_DIR</varname> directory and all its
88       contents are removed, too.</para></listitem>
89     </orderedlist>
90
91   </refsect1>
92
93   <refsect1>
94     <title>Options</title>
95
96     <para>The following options are understood:</para>
97
98     <variablelist class='pam-directives'>
99
100       <varlistentry>
101         <term><option>class=</option></term>
102
103         <listitem><para>Takes a string argument which sets the session
104         class. The XDG_SESSION_CLASS environmental variable takes
105         precedence. One of
106         <literal>user</literal>,
107         <literal>greeter</literal>,
108         <literal>lock-screen</literal> or
109         <literal>background</literal>. See
110         <citerefentry><refentrytitle>sd_session_get_class</refentrytitle><manvolnum>3</manvolnum></citerefentry>
111         for details about the session class.</para></listitem>
112       </varlistentry>
113
114       <varlistentry>
115         <term><option>type=</option></term>
116
117         <listitem><para>Takes a string argument which sets the session
118         type. The XDG_SESSION_TYPE environmental variable takes
119         precedence. One of
120         <literal>unspecified</literal>,
121         <literal>tty</literal>,
122         <literal>x11</literal>,
123         <literal>wayland</literal> or
124         <literal>mir</literal>. See
125         <citerefentry><refentrytitle>sd_session_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry>
126         for details about the session type.</para></listitem>
127       </varlistentry>
128
129       <varlistentry>
130         <term><option>debug<optional>=</optional></option></term>
131
132         <listitem><para>Takes an optional
133         boolean argument. If yes or without
134         the argument, the module will log
135         debugging information as it
136         operates.</para></listitem>
137       </varlistentry>
138     </variablelist>
139   </refsect1>
140
141   <refsect1>
142     <title>Module Types Provided</title>
143
144     <para>Only <option>session</option> is provided.</para>
145   </refsect1>
146
147   <refsect1>
148     <title>Environment</title>
149
150     <para>The following environment variables are set for the
151     processes of the user's session:</para>
152
153     <variablelist class='environment-variables'>
154       <varlistentry>
155         <term><varname>$XDG_SESSION_ID</varname></term>
156
157         <listitem><para>A session identifier, suitable to be used in
158         filenames. The string itself should be considered opaque,
159         although often it is just the audit session ID as reported by
160         <filename>/proc/self/sessionid</filename>. Each ID will be
161         assigned only once during machine uptime. It may hence be used
162         to uniquely label files or other resources of this
163         session.</para></listitem>
164       </varlistentry>
165
166       <varlistentry>
167         <term><varname>$XDG_RUNTIME_DIR</varname></term>
168
169         <listitem><para>Path to a user-private user-writable directory
170         that is bound to the user login time on the machine. It is
171         automatically created the first time a user logs in and
172         removed on the user's final logout. If a user logs in twice at
173         the same time, both sessions will see the same
174         <varname>$XDG_RUNTIME_DIR</varname> and the same contents. If
175         a user logs in once, then logs out again, and logs in again,
176         the directory contents will have been lost in between, but
177         applications should not rely on this behavior and must be able
178         to deal with stale files. To store session-private data in
179         this directory, the user should include the value of
180         <varname>$XDG_SESSION_ID</varname> in the filename. This
181         directory shall be used for runtime file system objects such
182         as <constant>AF_UNIX</constant> sockets, FIFOs, PID files and
183         similar. It is guaranteed that this directory is local and
184         offers the greatest possible file system feature set the
185         operating system provides. For further details see the <ulink
186         url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
187         Base Directory Specification</ulink>.</para></listitem>
188       </varlistentry>
189
190     </variablelist>
191
192     <para>The following environment variables are read by the module
193     and may be used by the PAM service to pass metadata to the
194     module:</para>
195
196     <variablelist class='environment-variables'>
197       <varlistentry>
198         <term><varname>$XDG_SESSION_TYPE</varname></term>
199
200         <listitem><para>The session type. This may be used instead of
201         <option>session=</option> on the module parameter line, and is
202         usually preferred.</para></listitem>
203       </varlistentry>
204
205       <varlistentry>
206         <term><varname>$XDG_SESSION_CLASS</varname></term>
207
208         <listitem><para>The session class. This may be used instead of
209         <option>class=</option> on the module parameter line, and is
210         usually preferred.</para></listitem>
211       </varlistentry>
212
213       <varlistentry>
214         <term><varname>$XDG_SESSION_DESKTOP</varname></term>
215
216         <listitem><para>A single, short identifier string for the
217         desktop environment. This may be used to indicate the session
218         desktop used, where this applies and if this information is
219         available. For example: <literal>GNOME</literal>, or
220         <literal>KDE</literal>. It is recommended to use the same
221         identifiers and capitalization as for
222         <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the
223         <ulink
224         url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
225         Entry Specification</ulink>. (However, note that
226         <varname>$XDG_SESSION_DESKTOP</varname> only takes a single
227         item, and not a colon-separated list like
228         <varname>$XDG_CURRENT_DESKTOP</varname>.) See
229         <citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
230         for more details.</para></listitem>
231       </varlistentry>
232
233       <varlistentry>
234         <term><varname>$XDG_SEAT</varname></term>
235
236         <listitem><para>The seat name the session shall be registered
237         for, if any.</para></listitem>
238       </varlistentry>
239
240       <varlistentry>
241         <term><varname>$XDG_VTNR</varname></term>
242
243         <listitem><para>The VT number the session shall be registered
244         for, if any. (Only applies to seats with a VT available, such
245         as <literal>seat0</literal>)</para></listitem>
246       </varlistentry>
247
248     </variablelist>
249   </refsect1>
250
251   <refsect1>
252     <title>Example</title>
253
254     <programlisting>#%PAM-1.0
255 auth       required     pam_unix.so
256 auth       required     pam_nologin.so
257 account    required     pam_unix.so
258 password   required     pam_unix.so
259 session    required     pam_unix.so
260 session    required     pam_loginuid.so
261 session    required     pam_elogind.so</programlisting>
262   </refsect1>
263
264   <refsect1>
265     <title>See Also</title>
266     <para>
267       <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
268       <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
269       <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
270       <citerefentry project='man-pages'><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
271       <citerefentry project='man-pages'><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
272       <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
273       <citerefentry project='man-pages'><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>
274     </para>
275   </refsect1>
276
277 </refentry>