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 <varname>$XDG_RUNTIME_DIR</varname> directory 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>.</para></listitem>
 196       </varlistentry>
 197
 198     </variablelist>
 199
 200     <para>The following environment variables are read by the module
 201     and may be used by the PAM service to pass metadata to the
 202     module:</para>
 203
 204     <variablelist class='environment-variables'>
 205       <varlistentry>
 206         <term><varname>$XDG_SESSION_TYPE</varname></term>
 207
 208         <listitem><para>The session type. This may be used instead of
 209         <option>session=</option> on the module parameter line, and is
 210         usually preferred.</para></listitem>
 211       </varlistentry>
 212
 213       <varlistentry>
 214         <term><varname>$XDG_SESSION_CLASS</varname></term>
 215
 216         <listitem><para>The session class. This may be used instead of
 217         <option>class=</option> on the module parameter line, and is
 218         usually preferred.</para></listitem>
 219       </varlistentry>
 220
 221       <varlistentry>
 222         <term><varname>$XDG_SESSION_DESKTOP</varname></term>
 223
 224         <listitem><para>A single, short identifier string for the
 225         desktop environment. This may be used to indicate the session
 226         desktop used, where this applies and if this information is
 227         available. For example: <literal>GNOME</literal>, or
 228         <literal>KDE</literal>. It is recommended to use the same
 229         identifiers and capitalization as for
 230         <varname>$XDG_CURRENT_DESKTOP</varname>, as defined by the
 231         <ulink
 232         url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
 233         Entry Specification</ulink>. (However, note that
 234         <varname>$XDG_SESSION_DESKTOP</varname> only takes a single
 235         item, and not a colon-separated list like
 236         <varname>$XDG_CURRENT_DESKTOP</varname>.) See
 237         <citerefentry><refentrytitle>sd_session_get_desktop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 238         for more details.</para></listitem>
 239       </varlistentry>
 240
 241       <varlistentry>
 242         <term><varname>$XDG_SEAT</varname></term>
 243
 244         <listitem><para>The seat name the session shall be registered
 245         for, if any.</para></listitem>
 246       </varlistentry>
 247
 248       <varlistentry>
 249         <term><varname>$XDG_VTNR</varname></term>
 250
 251         <listitem><para>The VT number the session shall be registered
 252         for, if any. (Only applies to seats with a VT available, such
 253         as <literal>seat0</literal>)</para></listitem>
 254       </varlistentry>
 255
 256     </variablelist>
 257   </refsect1>
 258
 259   <refsect1>
 260     <title>Example</title>
 261
 262     <programlisting>#%PAM-1.0
 263 auth       required     pam_unix.so
 264 auth       required     pam_nologin.so
 265 account    required     pam_unix.so
 266 password   required     pam_unix.so
 267 session    required     pam_unix.so
 268 session    required     pam_loginuid.so
 269 session    required     pam_elogind.so</programlisting>
 270   </refsect1>
 271
 272   <refsect1>
 273     <title>See Also</title>
 274     <para>
 275       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 276       <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 277       <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 278       <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 279       <citerefentry project='man-pages'><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 280       <citerefentry project='man-pages'><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 281       <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 282       <citerefentry project='man-pages'><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 283       <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 284       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 285       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 286     </para>
 287   </refsect1>
 288
 289 </refentry>