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 in 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 control group
  84                         <filename>/user/$USER/$XDG_SESSION_ID</filename>
  85                         is created and the login process moved into
  86                         it.</para></listitem>
  87                 </orderedlist>
  88
  89                 <para>On logout, this module ensures the following:</para>
  90
  91                 <orderedlist>
  92                         <listitem><para>If
  93                         <varname>$XDG_SESSION_ID</varname> is set and
  94                         <option>kill-session-processes=1</option> specified, all
  95                         remaining processes in the
  96                         <filename>/user/$USER/$XDG_SESSION_ID</filename>
  97                         control group are killed and the control group
  98                         is removed.</para></listitem>
  99
 100                         <listitem><para>If the last subgroup of the
 101                         <filename>/user/$USER</filename> control group
 102                         was removed the
 103                         <varname>$XDG_RUNTIME_DIR</varname> directory
 104                         and all its contents are
 105                         removed, too.</para></listitem>
 106                 </orderedlist>
 107
 108                 <para>If the system was not booted up with systemd as
 109                 init system, this module does nothing and immediately
 110                 returns PAM_SUCCESS.</para>
 111
 112         </refsect1>
 113
 114         <refsect1>
 115                 <title>Options</title>
 116
 117                 <para>The following options are understood:</para>
 118
 119                 <variablelist class='pam-directives'>
 120                         <varlistentry>
 121                                 <term><option>kill-session-processes=</option></term>
 122
 123                                 <listitem><para>Takes a boolean
 124                                 argument. If true, all processes
 125                                 created by the user during his session
 126                                 and from his session will be
 127                                 terminated when he logs out from his
 128                                 session.</para></listitem>
 129                         </varlistentry>
 130
 131                         <varlistentry>
 132                                 <term><option>kill-only-users=</option></term>
 133
 134                                 <listitem><para>Takes a comma-separated
 135                                 list of usernames or
 136                                 numeric user IDs as argument. If this
 137                                 option is used, the effect of the
 138                                 <option>kill-session-processes=</option> options
 139                                 will apply only to the listed
 140                                 users. If this option is not used, the
 141                                 option applies to all local
 142                                 users. Note that
 143                                 <option>kill-exclude-users=</option>
 144                                 takes precedence over this list and is
 145                                 hence subtracted from the list
 146                                 specified here.</para></listitem>
 147                         </varlistentry>
 148
 149                         <varlistentry>
 150                                 <term><option>kill-exclude-users=</option></term>
 151
 152                                 <listitem><para>Takes a comma-separated
 153                                 list of usernames or
 154                                 numeric user IDs as argument. Users
 155                                 listed in this argument will not be
 156                                 subject to the effect of
 157                                 <option>kill-session-processes=</option>.
 158                                 Note that this option takes precedence
 159                                 over
 160                                 <option>kill-only-users=</option>, and
 161                                 hence whatever is listed for
 162                                 <option>kill-exclude-users=</option>
 163                                 is guaranteed to never be killed by
 164                                 this PAM module, independent of any
 165                                 other configuration
 166                                 setting.</para></listitem>
 167                         </varlistentry>
 168
 169                         <varlistentry>
 170                                 <term><option>controllers=</option></term>
 171
 172                                 <listitem><para>Takes a comma-separated
 173                                 list of control group
 174                                 controllers in which hierarchies a
 175                                 user/session control group will be
 176                                 created by default for each user
 177                                 logging in, in addition to the control
 178                                 group in the named 'name=systemd'
 179                                 hierarchy. If omitted, defaults to an
 180                                 empty list.</para></listitem>
 181                         </varlistentry>
 182
 183                         <varlistentry>
 184                                 <term><option>reset-controllers=</option></term>
 185
 186                                 <listitem><para>Takes a comma-separated
 187                                 list of control group
 188                                 controllers in which hierarchies the
 189                                 logged in processes will be reset to
 190                                 the root control
 191                                 group.</para></listitem>
 192                         </varlistentry>
 193
 194                         <varlistentry>
 195                                 <term><option>class=</option></term>
 196
 197                                 <listitem><para>Takes a string
 198                                 argument which sets the session class.
 199                                 The XDG_SESSION_CLASS environmental variable
 200                                 takes precedence.</para></listitem>
 201                         </varlistentry>
 202
 203                         <varlistentry>
 204                                 <term><option>debug=</option></term>
 205
 206                                 <listitem><para>Takes a boolean
 207                                 argument. If yes, the module will log
 208                                 debugging information as it
 209                                 operates.</para></listitem>
 210                         </varlistentry>
 211                 </variablelist>
 212
 213                 <para>Note that setting
 214                 <varname>kill-session-processes=1</varname> will break tools
 215                 like
 216                 <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 217
 218                 <para>Note that
 219                 <varname>kill-session-processes=1</varname> is a
 220                 stricter version of
 221                 <varname>KillUserProcesses=1</varname> which may be
 222                 configured system-wide in
 223                 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
 224                 former kills processes of a session as soon as it
 225                 ends; the latter kills processes as soon as the last
 226                 session of the user ends.</para>
 227
 228                 <para>If the options are omitted they default to
 229                 <option>kill-session-processes=0</option>,
 230                 <option>kill-only-users=</option>,
 231                 <option>kill-exclude-users=</option>,
 232                 <option>controllers=</option>,
 233                 <option>reset-controllers=</option>,
 234                 <option>debug=no</option>.</para>
 235         </refsect1>
 236
 237         <refsect1>
 238                 <title>Module Types Provided</title>
 239
 240                 <para>Only <option>session</option> is provided.</para>
 241         </refsect1>
 242
 243         <refsect1>
 244                 <title>Environment</title>
 245
 246                 <para>The following environment variables are set for the processes of the user's session:</para>
 247
 248                 <variablelist class='environment-variables'>
 249                         <varlistentry>
 250                                 <term><varname>$XDG_SESSION_ID</varname></term>
 251
 252                                 <listitem><para>A session identifier,
 253                                 suitable to be used in filenames. The
 254                                 string itself should be considered
 255                                 opaque, although often it is just the
 256                                 audit session ID as reported by
 257                                 <filename>/proc/self/sessionid</filename>. Each
 258                                 ID will be assigned only once during
 259                                 machine uptime. It may hence be used
 260                                 to uniquely label files or other
 261                                 resources of this
 262                                 session.</para></listitem>
 263                         </varlistentry>
 264
 265                         <varlistentry>
 266                                 <term><varname>$XDG_RUNTIME_DIR</varname></term>
 267
 268                                 <listitem><para>Path to a user-private
 269                                 user-writable directory that is bound
 270                                 to the user login time on the
 271                                 machine. It is automatically created
 272                                 the first time a user logs in and
 273                                 removed on his final logout. If a user
 274                                 logs in twice at the same time, both
 275                                 sessions will see the same
 276                                 <varname>$XDG_RUNTIME_DIR</varname>
 277                                 and the same contents. If a user logs
 278                                 in once, then logs out again, and logs
 279                                 in again, the directory contents will
 280                                 have been lost in between, but
 281                                 applications should not rely on this
 282                                 behavior and must be able to deal with
 283                                 stale files. To store session-private
 284                                 data in this directory, the user should
 285                                 include the value of <varname>$XDG_SESSION_ID</varname>
 286                                 in the filename. This directory shall
 287                                 be used for runtime file system
 288                                 objects such as <constant>AF_UNIX</constant> sockets,
 289                                 FIFOs, PID files and similar. It is
 290                                 guaranteed that this directory is
 291                                 local and offers the greatest possible
 292                                 file system feature set the
 293                                 operating system
 294                                 provides.</para></listitem>
 295                         </varlistentry>
 296                 </variablelist>
 297         </refsect1>
 298
 299         <refsect1>
 300                 <title>Example</title>
 301
 302                 <programlisting>#%PAM-1.0
 303 auth       required     pam_unix.so
 304 auth       required     pam_nologin.so
 305 account    required     pam_unix.so
 306 password   required     pam_unix.so
 307 session    required     pam_unix.so
 308 session    required     pam_loginuid.so
 309 session    required     pam_systemd.so kill-session-processes=1</programlisting>
 310         </refsect1>
 311
 312         <refsect1>
 313                 <title>See Also</title>
 314                 <para>
 315                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 316                         <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 317                         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 318                         <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 319                         <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 320                         <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 321                         <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 322                         <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 323                 </para>
 324         </refsect1>
 325
 326 </refentry>