pam_systemd.xml revision 47c490345256f2db32d8d883cd7c5243158a14e1
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
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering under the terms of the GNU Lesser General Public License as published by
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering the Free Software Foundation; either version 2.1 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
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering Lesser General Public License for more details.
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering You should have received a copy of the GNU Lesser General Public License
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
47c490345256f2db32d8d883cd7c5243158a14e1Zbigniew Jędrzejewski-Szmek<refentry id="pam_systemd" conditional='HAVE_PAM'>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <refentryinfo>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </authorgroup>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </refentryinfo>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <refentrytitle>pam_systemd</refentrytitle>
af3bccd6d87759f0b146bf5980bdd56144d70c7eLennart Poettering <refpurpose>Register user sessions in the systemd login manager</refpurpose>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <refsynopsisdiv>
e670b166a08b7c1031a9e7d7675fa9a29c3e19c9Zbigniew Jędrzejewski-Szmek <para><filename>pam_systemd.so</filename></para>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </refsynopsisdiv>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <para><command>pam_systemd</command> registers user
af3bccd6d87759f0b146bf5980bdd56144d70c7eLennart Poettering sessions in the systemd login manager
af3bccd6d87759f0b146bf5980bdd56144d70c7eLennart Poettering <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
af3bccd6d87759f0b146bf5980bdd56144d70c7eLennart Poettering and hence the systemd control group hierarchy.</para>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <para>On login, this module ensures the following:</para>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering user runtime directory
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 </orderedlist>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <para>On logout, this module ensures the following:</para>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <varname>$XDG_SESSION_ID</varname> is set and
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering <option>kill-session-processes=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
071d73c1aad44e5d8f9bfb11442d468e3131200aThomas Hindoe Paaboel Andersen <listitem><para>If the last subgroup of the
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>
ccc9a4f9ffdab069b0b785627c48962fdadf6d46Zbigniew Jędrzejewski-Szmek <variablelist class='pam-directives'>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <varlistentry>
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering <term><option>kill-session-processes=</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>
3add4d215b30c746ee617d7412ee007ed3c87249Lennart Poettering <varlistentry>
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering <term><option>kill-only-users=</option></term>
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering separated list of user names or
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering numeric user ids as argument. If this
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering option is used the effect of the
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering <option>kill-session-processes=</option> options
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering will apply only to the listed
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering users. If this option is not used the
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering option applies to all local
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering users. Note that
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering takes precedence over this list and is
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering hence subtracted from the list
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering </varlistentry>
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering <varlistentry>
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering <term><option>kill-exclude-users=</option></term>
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering separated list of user names or
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering numeric user ids as argument. Users
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering listed in this argument will not be
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering subject to the effect of
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering <option>kill-session-processes=</option>. Note
c53158818d8cdaf46b3f1b5299b9bda118a1043fThomas Hindoe Paaboel Andersen that this option takes precedence
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering hence whatever is listed for
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering is guaranteed to never be killed by
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering this PAM module, independent of any
e9fbc77c8f6a396ce9432e3791710e30de6e570bLennart Poettering other configuration
3add4d215b30c746ee617d7412ee007ed3c87249Lennart Poettering </varlistentry>
4611d77694effd27ad0e191c820498dbff25907cLennart Poettering <varlistentry>
4611d77694effd27ad0e191c820498dbff25907cLennart Poettering <term><option>controllers=</option></term>
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering separated list of control group
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering controllers in which hierarchies a
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering created by default for each user
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering logging in, in addition to the control
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering group in the named 'name=systemd'
9f7dad774ebfad23269800b7096eaad087481debVille Skyttä hierarchy. If omitted, defaults to an
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering </varlistentry>
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering <varlistentry>
b20c6be697ded108e3c3bd5b8812fee13326eefcLennart Poettering <term><option>reset-controllers=</option></term>
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering separated list of control group
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering controllers in which hierarchies the
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering logged in processes will be reset to
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering the root control
4611d77694effd27ad0e191c820498dbff25907cLennart Poettering </varlistentry>
485507b8c031e0c75f43c4b4fce5a0082a812fbbMatthew Monaco <varlistentry>
485507b8c031e0c75f43c4b4fce5a0082a812fbbMatthew Monaco argument which sets the session class.
485507b8c031e0c75f43c4b4fce5a0082a812fbbMatthew Monaco The XDG_SESSION_CLASS environmental variable
485507b8c031e0c75f43c4b4fce5a0082a812fbbMatthew Monaco </varlistentry>
0e318cad06d483624076777c105bdcdd6aca3596Michal Schmidt <varlistentry>
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering argument. If yes, the module will log
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering debugging information as it
0e318cad06d483624076777c105bdcdd6aca3596Michal Schmidt </varlistentry>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </variablelist>
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering <para>Note that setting
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering <varname>kill-session-processes=1</varname> will break tools
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering <para>Note that
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering <varname>kill-session-processes=1</varname> is a
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering stricter version of
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering <varname>KillUserProcesses=1</varname> which may be
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering configured system-wide in
18b754d345ecb0b15e369978aaffa72e9814b86aKay Sievers <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering former kills processes of a session as soon as it
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering ends, the latter kills processes as soon as the last
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering session of the user ends.</para>
7874bcd6028d1efbb4451c8b5cf5b2ac8d77af74Lennart Poettering <para>If the options are omitted they default to
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poettering <option>kill-session-processes=0</option>,
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>
ccc9a4f9ffdab069b0b785627c48962fdadf6d46Zbigniew Jędrzejewski-Szmek <variablelist class='environment-variables'>
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
c53158818d8cdaf46b3f1b5299b9bda118a1043fThomas Hindoe Paaboel Andersen behavior 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
c36eecdfcb4afa09850002fbb81a95a24ffde599Lennart Poetteringsession required pam_systemd.so kill-session-processes=1</programlisting>
af3bccd6d87759f0b146bf5980bdd56144d70c7eLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
af3bccd6d87759f0b146bf5980bdd56144d70c7eLennart Poettering <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
af3bccd6d87759f0b146bf5980bdd56144d70c7eLennart Poettering <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
af3bccd6d87759f0b146bf5980bdd56144d70c7eLennart Poettering <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
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>,
af3bccd6d87759f0b146bf5980bdd56144d70c7eLennart Poettering <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>