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