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