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 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 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>debug=</option></term>
 198
 199                                 <listitem><para>Takes a boolean
 200                                 argument. If yes, the module will log
 201                                 debugging information as it
 202                                 operates.</para></listitem>
 203                         </varlistentry>
 204                 </variablelist>
 205
 206                 <para>Note that setting
 207                 <varname>kill-session-processes=1</varname> will break tools
 208                 like
 209                 <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 210
 211                 <para>Note that
 212                 <varname>kill-session-processes=1</varname> is a
 213                 stricter version of
 214                 <varname>KillUserProcesses=1</varname> which may be
 215                 configured system-wide in
 216                 <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
 217                 former kills processes of a session as soon as it
 218                 ends, the latter kills processes as soon as the last
 219                 session of the user ends.</para>
 220
 221                 <para>If the options are omitted they default to
 222                 <option>kill-session-processes=0</option>,
 223                 <option>kill-only-users=</option>,
 224                 <option>kill-exclude-users=</option>,
 225                 <option>controllers=</option>,
 226                 <option>reset-controllers=</option>,
 227                 <option>debug=no</option>.</para>
 228         </refsect1>
 229
 230         <refsect1>
 231                 <title>Module Types Provided</title>
 232
 233                 <para>Only <option>session</option> is provided.</para>
 234         </refsect1>
 235
 236         <refsect1>
 237                 <title>Environment</title>
 238
 239                 <para>The following environment variables are set for the processes of the user's session:</para>
 240
 241                 <variablelist>
 242                         <varlistentry>
 243                                 <term><varname>$XDG_SESSION_ID</varname></term>
 244
 245                                 <listitem><para>A session identifier,
 246                                 suitable to be used in file names. The
 247                                 string itself should be considered
 248                                 opaque, although often it is just the
 249                                 audit session ID as reported by
 250                                 <filename>/proc/self/sessionid</filename>. Each
 251                                 ID will be assigned only once during
 252                                 machine uptime. It may hence be used
 253                                 to uniquely label files or other
 254                                 resources of this
 255                                 session.</para></listitem>
 256                         </varlistentry>
 257
 258                         <varlistentry>
 259                                 <term><varname>$XDG_RUNTIME_DIR</varname></term>
 260
 261                                 <listitem><para>Path to a user-private
 262                                 user-writable directory that is bound
 263                                 to the user login time on the
 264                                 machine. It is automatically created
 265                                 the first time a user logs in and
 266                                 removed on his final logout. If a user
 267                                 logs in twice at the same time, both
 268                                 sessions will see the same
 269                                 <varname>$XDG_RUNTIME_DIR</varname>
 270                                 and the same contents. If a user logs
 271                                 in once, then logs out again, and logs
 272                                 in again, the directory contents will
 273                                 have been lost in between, but
 274                                 applications should not rely on this
 275                                 behaviour and must be able to deal with
 276                                 stale files. To store session-private
 277                                 data in this directory the user should
 278                                 include the value of <varname>$XDG_SESSION_ID</varname>
 279                                 in the filename. This directory shall
 280                                 be used for runtime file system
 281                                 objects such as AF_UNIX sockets,
 282                                 FIFOs, PID files and similar. It is
 283                                 guaranteed that this directory is
 284                                 local and offers the greatest possible
 285                                 file system feature set the
 286                                 operating system
 287                                 provides.</para></listitem>
 288                         </varlistentry>
 289                 </variablelist>
 290         </refsect1>
 291
 292         <refsect1>
 293                 <title>Example</title>
 294
 295                 <programlisting>#%PAM-1.0
 296 auth       required     pam_unix.so
 297 auth       required     pam_nologin.so
 298 account    required     pam_unix.so
 299 password   required     pam_unix.so
 300 session    required     pam_unix.so
 301 session    required     pam_loginuid.so
 302 session    required     pam_systemd.so kill-session-processes=1</programlisting>
 303         </refsect1>
 304
 305         <refsect1>
 306                 <title>See Also</title>
 307                 <para>
 308                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 309                         <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 310                         <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 311                         <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 312                         <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 313                         <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 314                         <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 315                         <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 316                 </para>
 317         </refsect1>
 318
 319 </refentry>