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