pam_systemd.xml revision 3e2f69b779aa0f3466ebb45837e8507baa0832f7
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
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering <listitem><para>A new systemd scope unit is
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering created for the session. If this is the first
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering concurrent session of the user an implicit
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering slice below <filename>user.slice</filename> is
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering automatically created and the scope placed in
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering it. In instance of the system service
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering <filename>user@.service</filename> which runt
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering the systemd user manager
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering </orderedlist>
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <para>On logout, this module ensures the following:</para>
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering processes of the session are terminated. If
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering the last concurrent session of a user ends his
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering user systemd instance will be terminated too,
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering and so will the user's slice
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering <listitem><para>If the las concurrent session
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering of a user ends the
160cd5c9aa2301892e13950015de7968c764340dLennart Poettering <varname>$XDG_RUNTIME_DIR</varname> directory
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering and all its contents are removed,
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'>
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>
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>
e9dd9f9547350c7dc0473583b5c2228dc8f0ab76Jason St. John suitable to be used in filenames. 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
e9dd9f9547350c7dc0473583b5c2228dc8f0ab76Jason St. John 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
74d005783e355acc784d123024e33bbb66ef9ef1Zbigniew Jędrzejewski-Szmek objects such as <constant>AF_UNIX</constant> 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
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poetteringsession required pam_systemd.so</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>,
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
3e2f69b779aa0f3466ebb45837e8507baa0832f7Lennart Poettering <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>