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