pam_systemd.xml revision b20c6be697ded108e3c3bd5b8812fee13326eefc
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 user runtime directory
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/var/run/user/$USER</filename> is
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering created and its ownership changed to the user
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
af62c704053b5d34672497eb5bdc4764ebbb5f4fKay Sievers this module (which is highly 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 <filename>/user/$USER/$XDG_SESSION_ID</filename>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering is created and the login process moved into
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
824a1d590a0ec4d83baa51264a9913a702793230Lennart Poettering <filename>/user/$USER/user</filename> and
af62c704053b5d34672497eb5bdc4764ebbb5f4fKay Sievers the original control group is
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <option>kill-user=1</option> is specified, and
af62c704053b5d34672497eb5bdc4764ebbb5f4fKay Sievers no other user session control group remains,
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering all remaining processes in the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <filename>/user/$USER</filename> hierarchy
af62c704053b5d34672497eb5bdc4764ebbb5f4fKay Sievers are killed and the control group is 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
af62c704053b5d34672497eb5bdc4764ebbb5f4fKay Sievers 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
af62c704053b5d34672497eb5bdc4764ebbb5f4fKay Sievers all services which 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
af62c704053b5d34672497eb5bdc4764ebbb5f4fKay Sievers 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
af62c704053b5d34672497eb5bdc4764ebbb5f4fKay Sievers than once, as their processes are
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering terminated only on their complete
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </varlistentry>
3add4d215b30c746ee617d7412ee007ed3c87249Lennart Poettering <varlistentry>
3add4d215b30c746ee617d7412ee007ed3c87249Lennart Poettering argument. If true, all processes
3add4d215b30c746ee617d7412ee007ed3c87249Lennart Poettering created by the root user (UID 0) during his
3add4d215b30c746ee617d7412ee007ed3c87249Lennart Poettering session and from his session will be
3add4d215b30c746ee617d7412ee007ed3c87249Lennart Poettering kept around after he logged out. This
3add4d215b30c746ee617d7412ee007ed3c87249Lennart Poettering option allows cancelling the effect of
3add4d215b30c746ee617d7412ee007ed3c87249Lennart Poettering </varlistentry>
4611d77694effd27ad0e191c820498dbff25907cLennart Poettering <varlistentry>
4611d77694effd27ad0e191c820498dbff25907cLennart Poettering <term><option>controllers=</option></term>
5471472d441d9ac48640f11a3b07e6a1fd6d1b63Miklos Vajna separated list of cgroup controllers
5471472d441d9ac48640f11a3b07e6a1fd6d1b63Miklos Vajna cgroup will be created by default for
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering each user logging in, in addition to
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering the cgroup in the named 'name=systemd'
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering hierarchy. If ommited, defaults to an
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering empty list. This may be used to move
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering user sessions into their own groups in
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering the 'cpu' hierarchy which ensures that
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering every logged in user gets an equal
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering amount of CPU time regardless how many
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering processes he has
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering </varlistentry>
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering <varlistentry>
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering <term><option>reset-controllers=</option></term>
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering separated list of cgroup controllers
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering in which hierarchies the logged in
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering processes will be reset to the root
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering cgroup. If ommited, defaults to 'cpu',
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering meaning that a 'cpu' cgroup grouping
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering inherited from the login manager will
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering be reset for the processes of the
4611d77694effd27ad0e191c820498dbff25907cLennart 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>
7874bcd6028d1efbb4451c8b5cf5b2ac8d77af74Lennart Poettering <para>If the options are omitted they default to
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering <option>reset-controllers=cpu</option>.</para>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <para>Only <option>session</option> is provided.</para>
58474090e965d5fcb9677bc746b5ecd079528de1Lennart Poettering <para>The following environment variables are set for the processes of the user's session:</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
58474090e965d5fcb9677bc746b5ecd079528de1Lennart Poetteringsession required pam_systemd.so 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>