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