pam_systemd.xml revision 160cd5c9aa2301892e13950015de7968c764340d
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering This file is part of systemd.
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering Copyright 2010 Lennart Poettering
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering systemd is free software; you can redistribute it and/or modify it
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering under the terms of the GNU General Public License as published by
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering the Free Software Foundation; either version 2 of the License, or
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering (at your option) any later version.
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering systemd is distributed in the hope that it will be useful, but
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering General Public License for more details.
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering You should have received a copy of the GNU General Public License
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <refentryinfo>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </authorgroup>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </refentryinfo>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <refentrytitle>pam_systemd</refentrytitle>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <refpurpose>Register user sessions in the systemd control group hierarchy</refpurpose>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <refsynopsisdiv>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </cmdsynopsis>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </refsynopsisdiv>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <para><command>pam_systemd</command> registers user
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering sessions in the systemd control group
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering hierarchy.</para>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <para>On login, this module ensures the following:</para>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <listitem><para>If it does not exist yet the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering user runtime directory
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/var/run/user/$USER</filename> is
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering created and its ownership changed to the user
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <option>create-session=1</option> is set the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <varname>$XDG_SESSION_ID</varname> environment
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering variable is initialized. If auditing is
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <command>pam_loginuid.so</command> run before
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering this module (which es recommended), the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering variable is initialized from the auditing
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering (<filename>/proc/self/sessionid</filename>). Otherwise
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering an independent session counter is
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <option>create-session=1</option> is set a new
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/user/$USER/$XDG_SESSION_ID</filename>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering is created and the login process moved into
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <option>create-session=0</option> is set a new
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/user/$USER/no-session</filename>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering is created and the login process moved into
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </orderedlist>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <para>On logout, this module ensures the following:</para>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <varname>$XDG_SESSION_ID</varname> is set and
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <option>kill-session=1</option> specified, all
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering remaining processes in the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/user/$USER/$XDG_SESSION_ID</filename>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering control group are killed and the control group
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <varname>$XDG_SESSION_ID</varname> is set and
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <option>kill-session=0</option> specified, all
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering remaining processes in the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/user/$USER/$XDG_SESSION_ID</filename>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering control group are migrated to
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/user/$USER/no-session</filename> and
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering the original control group
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <option>kill-user=1</option> is specified, and
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering no other user session control group remains
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/user/$USER/no-session</filename>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering all remaining processes in the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/user/$USER</filename> hierarchy
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering are killed and the control group removed.</para></listitem>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <option>kill-user=0</option> is specified, and
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering no process remains in the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/user/$USER</filename> hierarchy the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering control group is removed.</para></listitem>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/user/$USER</filename> control group
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering was removed the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <varname>$XDG_RUNTIME_DIR</varname> directory
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering and all its contents are
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </orderedlist>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <para>If the system was not booted up with systemd as
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering init system this module does nothing and immediately
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering returns PAM_SUCCESS.</para>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <para>The following options are understood:</para>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <variablelist>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <varlistentry>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <term><option>create-session=</option></term>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering argument. If true, a new session is
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering environment variable is set and the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering login process moved to the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/user/$USER/$XDG_SESSION_ID</filename>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering control group. It is recommended that
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering all services that are directly created
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering on the user's behalf set this
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering option. Only for services that shall
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering automatically be terminated when the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering user logs out completely otherwise,
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </varlistentry>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <varlistentry>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <term><option>kill-session=</option></term>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering argument. If true, all processes
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering created by the user during his session
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering and from his session will be
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering terminated when he logs out from his
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </varlistentry>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <varlistentry>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering argument. If true, all processes
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering created by the user during his session
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering and from his session will be
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering terminated after he logged out
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering completely. This is a weaker version
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering of <option>kill-session=1</option> and is
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering more friendly for users logged in more
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering than once as their processes are
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering terminated only on their complete
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </varlistentry>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </variablelist>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <para>Note that setting <varname>kill-user=1</varname>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering or even <varname>kill-session=1</varname> will break
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <para>Only <option>session</option> is provided.</para>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <variablelist>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <varlistentry>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <term><varname>$XDG_SESSION_ID</varname></term>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering suitable to be used in file names. The
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering string itself should be considered
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering opaque, although often it is just the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering audit session ID as reported by
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/proc/self/sessionid</filename>. Each
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering ID will be assigned only once during
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering machine uptime. It may hence be used
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering to uniquely label files or other
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering resources of this
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </varlistentry>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <varlistentry>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <term><varname>$XDG_RUNTIME_DIR</varname></term>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering user-writable directory that is bound
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering to the user login time on the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering machine. It is automatically created
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering the first time a user logs in and
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering removed on his final logout. If a user
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering logs in twice at the same time, both
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering sessions will see the same
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering and the same contents. If a user logs
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering in once, then logs out again, and logs
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering in again, the directory contents will
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering have been lost in between, but
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering applications should not rely on this
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering behaviour and must be able to deal with
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering stale files. To store session-private
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering data in this directory the user should
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering include the value of <varname>$XDG_SESSION_ID</varname>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering in the filename. This directory shall
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering be used for runtime file system
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering objects such as AF_UNIX sockets,
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering FIFOs, PID files and similar. It is
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering guaranteed that this directory is
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering local and offers the greatest possible
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering file system feature set the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering operating system
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </varlistentry>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </variablelist>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <programlisting>#%PAM-1.0
160cd5c9aa2301892e13950015de7968c764340dLennart Poetteringpassword required pam_unix.so
160cd5c9aa2301892e13950015de7968c764340dLennart Poetteringsession required pam_systemd.so create-session=1 kill-user=1</programlisting>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>