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