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. One of
 131                                 <literal>user</literal>,
 132                                 <literal>greeter</literal>,
 133                                 <literal>lock-screen</literal> or
 134                                 <literal>background</literal>. See
 135                                 <citerefentry><refentrytitle>sd_session_get_class</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 136                                 for details about the session class.</para></listitem>
 137                         </varlistentry>
 138
 139                         <varlistentry>
 140                                 <term><option>type=</option></term>
 141
 142                                 <listitem><para>Takes a string
 143                                 argument which sets the session type.
 144                                 The XDG_SESSION_TYPE environmental
 145                                 variable takes precedence. One of
 146                                 <literal>unspecified</literal>,
 147                                 <literal>tty</literal>,
 148                                 <literal>x11</literal>,
 149                                 <literal>wayland</literal> or
 150                                 <literal>mir</literal>. See
 151                                 <citerefentry><refentrytitle>sd_session_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 152                                 for details about the session type.</para></listitem>
 153                         </varlistentry>
 154
 155                         <varlistentry>
 156                                 <term><option>debug<optional>=</optional></option></term>
 157
 158                                 <listitem><para>Takes an optional
 159                                 boolean argument. If yes or without
 160                                 the argument, the module will log
 161                                 debugging information as it
 162                                 operates.</para></listitem>
 163                         </varlistentry>
 164                 </variablelist>
 165         </refsect1>
 166
 167         <refsect1>
 168                 <title>Module Types Provided</title>
 169
 170                 <para>Only <option>session</option> is provided.</para>
 171         </refsect1>
 172
 173         <refsect1>
 174                 <title>Environment</title>
 175
 176                 <para>The following environment variables are set for the processes of the user's session:</para>
 177
 178                 <variablelist class='environment-variables'>
 179                         <varlistentry>
 180                                 <term><varname>$XDG_SESSION_ID</varname></term>
 181
 182                                 <listitem><para>A session identifier,
 183                                 suitable to be used in filenames. The
 184                                 string itself should be considered
 185                                 opaque, although often it is just the
 186                                 audit session ID as reported by
 187                                 <filename>/proc/self/sessionid</filename>. Each
 188                                 ID will be assigned only once during
 189                                 machine uptime. It may hence be used
 190                                 to uniquely label files or other
 191                                 resources of this
 192                                 session.</para></listitem>
 193                         </varlistentry>
 194
 195                         <varlistentry>
 196                                 <term><varname>$XDG_RUNTIME_DIR</varname></term>
 197
 198                                 <listitem><para>Path to a user-private
 199                                 user-writable directory that is bound
 200                                 to the user login time on the
 201                                 machine. It is automatically created
 202                                 the first time a user logs in and
 203                                 removed on his final logout. If a user
 204                                 logs in twice at the same time, both
 205                                 sessions will see the same
 206                                 <varname>$XDG_RUNTIME_DIR</varname>
 207                                 and the same contents. If a user logs
 208                                 in once, then logs out again, and logs
 209                                 in again, the directory contents will
 210                                 have been lost in between, but
 211                                 applications should not rely on this
 212                                 behavior and must be able to deal with
 213                                 stale files. To store session-private
 214                                 data in this directory, the user should
 215                                 include the value of <varname>$XDG_SESSION_ID</varname>
 216                                 in the filename. This directory shall
 217                                 be used for runtime file system
 218                                 objects such as <constant>AF_UNIX</constant> sockets,
 219                                 FIFOs, PID files and similar. It is
 220                                 guaranteed that this directory is
 221                                 local and offers the greatest possible
 222                                 file system feature set the
 223                                 operating system
 224                                 provides.</para></listitem>
 225                         </varlistentry>
 226
 227                 </variablelist>
 228
 229                 <para>The following environment variables are read by
 230                 the module and may be used by the PAM service to pass
 231                 metadata to the module:</para>
 232
 233                 <variablelist class='environment-variables'>
 234                         <varlistentry>
 235                                 <term><varname>$XDG_SESSION_TYPE</varname></term>
 236
 237                                 <listitem><para>The session type. This
 238                                 may be used instead of
 239                                 <option>session=</option> on the
 240                                 module parameter line, and is usually
 241                                 preferred.</para></listitem>
 242                         </varlistentry>
 243
 244                         <varlistentry>
 245                                 <term><varname>$XDG_SESSION_CLASS</varname></term>
 246
 247                                 <listitem><para>The session class. This
 248                                 may be used instead of
 249                                 <option>class=</option> on the
 250                                 module parameter line, and is usually
 251                                 preferred.</para></listitem>
 252                         </varlistentry>
 253
 254                         <varlistentry>
 255                                 <term><varname>$XDG_SESSION_DESKTOP</varname></term>
 256
 257                                 <listitem><para>A single, short
 258                                 identifier string for the desktop
 259                                 environment. This may be used to
 260                                 indicate the session desktop used,
 261                                 where this applies and if this
 262                                 information is available. For example:
 263                                 <literal>GNOME</literal>, or
 264                                 <literal>KDE</literal>. It is
 265                                 recommended to use the same
 266                                 identifiers and capitalization as for
 267                                 <varname>$XDG_CURRENT_DESKTOP</varname>,
 268                                 as defined by the <ulink
 269                                 url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop
 270                                 Entry
 271                                 Specification</ulink>.</para></listitem>
 272                         </varlistentry>
 273
 274                         <varlistentry>
 275                                 <term><varname>$XDG_SEAT</varname></term>
 276
 277                                 <listitem><para>The seat name the session
 278                                 shall be registered for, if
 279                                 any.</para></listitem>
 280                         </varlistentry>
 281
 282                         <varlistentry>
 283                                 <term><varname>$XDG_VTNR</varname></term>
 284
 285                                 <listitem><para>The VT number the
 286                                 session shall be registered for, if
 287                                 any. (Only applies to seats with a VT
 288                                 available, such as
 289                                 <literal>seat0</literal>)</para></listitem>
 290                         </varlistentry>
 291
 292                 </variablelist>
 293         </refsect1>
 294
 295         <refsect1>
 296                 <title>Example</title>
 297
 298                 <programlisting>#%PAM-1.0
 299 auth       required     pam_unix.so
 300 auth       required     pam_nologin.so
 301 account    required     pam_unix.so
 302 password   required     pam_unix.so
 303 session    required     pam_unix.so
 304 session    required     pam_loginuid.so
 305 session    required     pam_systemd.so</programlisting>
 306         </refsect1>
 307
 308         <refsect1>
 309                 <title>See Also</title>
 310                 <para>
 311                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 312                         <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 313                         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 314                         <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 315                         <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 316                         <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 317                         <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 318                         <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 319                         <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 320                         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 321                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 322                 </para>
 323         </refsect1>
 324
 325 </refentry>