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>