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