| <?xml version='1.0'?> <!--*-nxml-*--> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| |
| <!-- |
| This file is part of systemd. |
| |
| Copyright 2010 Lennart Poettering |
| |
| systemd is free software; you can redistribute it and/or modify it |
| under the terms of the GNU General Public License as published by |
| the Free Software Foundation; either version 2 of the License, or |
| (at your option) any later version. |
| |
| systemd is distributed in the hope that it will be useful, but |
| WITHOUT ANY WARRANTY; without even the implied warranty of |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| General Public License for more details. |
| |
| You should have received a copy of the GNU General Public License |
| along with systemd; If not, see <http://www.gnu.org/licenses/>. |
| --> |
| |
| <refentry id="pam_systemd"> |
| |
| <refentryinfo> |
| <title>pam_systemd</title> |
| <productname>systemd</productname> |
| |
| <authorgroup> |
| <author> |
| <contrib>Developer</contrib> |
| <firstname>Lennart</firstname> |
| <surname>Poettering</surname> |
| <email>lennart@poettering.net</email> |
| </author> |
| </authorgroup> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>pam_systemd</refentrytitle> |
| <manvolnum>8</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>pam_systemd</refname> |
| <refpurpose>Register user sessions in the systemd control group hierarchy</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>pam_systemd.so</command> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para><command>pam_systemd</command> registers user |
| sessions in the systemd control group |
| hierarchy.</para> |
| |
| <para>On login, this module ensures the following:</para> |
| |
| <orderedlist> |
| <listitem><para>If it does not exist yet, the |
| user runtime directory |
| <filename>/run/user/$USER</filename> is |
| created and its ownership changed to the user |
| that is logging in.</para></listitem> |
| |
| <listitem><para>The |
| <varname>$XDG_SESSION_ID</varname> environment |
| variable is initialized. If auditing is |
| available and |
| <command>pam_loginuid.so</command> run before |
| this module (which is highly recommended), the |
| variable is initialized from the auditing |
| session id |
| (<filename>/proc/self/sessionid</filename>). Otherwise |
| an independent session counter is |
| used.</para></listitem> |
| |
| <listitem><para>A new control group |
| <filename>/user/$USER/$XDG_SESSION_ID</filename> |
| is created and the login process moved into |
| it.</para></listitem> |
| </orderedlist> |
| |
| <para>On logout, this module ensures the following:</para> |
| |
| <orderedlist> |
| <listitem><para>If |
| <varname>$XDG_SESSION_ID</varname> is set and |
| <option>kill-session-processes=1</option> specified, all |
| remaining processes in the |
| <filename>/user/$USER/$XDG_SESSION_ID</filename> |
| control group are killed and the control group |
| is removed.</para></listitem> |
| |
| <listitem><para>If last subgroup of the |
| <filename>/user/$USER</filename> control group |
| was removed the |
| <varname>$XDG_RUNTIME_DIR</varname> directory |
| and all its contents are |
| removed, too.</para></listitem> |
| </orderedlist> |
| |
| <para>If the system was not booted up with systemd as |
| init system, this module does nothing and immediately |
| returns PAM_SUCCESS.</para> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>Options</title> |
| |
| <para>The following options are understood:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><option>kill-session-processes=</option></term> |
| |
| <listitem><para>Takes a boolean |
| argument. If true, all processes |
| created by the user during his session |
| and from his session will be |
| terminated when he logs out from his |
| session.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>kill-only-users=</option></term> |
| |
| <listitem><para>Takes a comma |
| separated list of user names or |
| numeric user ids as argument. If this |
| option is used the effect of the |
| <option>kill-session-processes=</option> options |
| will apply only to the listed |
| users. If this option is not used the |
| option applies to all local |
| users. Note that |
| <option>kill-exclude-users=</option> |
| takes precedence over this list and is |
| hence subtracted from the list |
| specified here.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>kill-exclude-users=</option></term> |
| |
| <listitem><para>Takes a comma |
| separated list of user names or |
| numeric user ids as argument. Users |
| listed in this argument will not be |
| subject to the effect of |
| <option>kill-session-processes=</option>. Note |
| that that this option takes precedence |
| over |
| <option>kill-only-users=</option>, and |
| hence whatever is listed for |
| <option>kill-exclude-users=</option> |
| is guaranteed to never be killed by |
| this PAM module, independent of any |
| other configuration |
| setting.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>controllers=</option></term> |
| |
| <listitem><para>Takes a comma |
| separated list of control group |
| controllers in which hierarchies a |
| user/session control group will be |
| created by default for each user |
| logging in, in addition to the control |
| group in the named 'name=systemd' |
| hierarchy. If omitted, defaults to an |
| empty list.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>reset-controllers=</option></term> |
| |
| <listitem><para>Takes a comma |
| separated list of control group |
| controllers in which hierarchies the |
| logged in processes will be reset to |
| the root control |
| group.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>debug=</option></term> |
| |
| <listitem><para>Takes a boolean |
| argument. If yes, the module will log |
| debugging information as it |
| operates.</para></listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <para>Note that setting |
| <varname>kill-session-processes=1</varname> will break tools |
| like |
| <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> |
| |
| <para>Note that |
| <varname>kill-session-processes=1</varname> is a |
| stricter version of |
| <varname>KillUserProcesses=1</varname> which may be |
| configured system-wide in |
| <citerefentry><refentrytitle>systemd-logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The |
| former kills processes of a session as soon as it |
| ends, the latter kills processes as soon as the last |
| session of the user ends.</para> |
| |
| <para>If the options are omitted they default to |
| <option>kill-session-processes=0</option>, |
| <option>kill-only-users=</option>, |
| <option>kill-exclude-users=</option>, |
| <option>controllers=</option>, |
| <option>reset-controllers=</option>, |
| <option>debug=no</option>.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Module Types Provided</title> |
| |
| <para>Only <option>session</option> is provided.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Environment</title> |
| |
| <para>The following environment variables are set for the processes of the user's session:</para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><varname>$XDG_SESSION_ID</varname></term> |
| |
| <listitem><para>A session identifier, |
| suitable to be used in file names. The |
| string itself should be considered |
| opaque, although often it is just the |
| audit session ID as reported by |
| <filename>/proc/self/sessionid</filename>. Each |
| ID will be assigned only once during |
| machine uptime. It may hence be used |
| to uniquely label files or other |
| resources of this |
| session.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>$XDG_RUNTIME_DIR</varname></term> |
| |
| <listitem><para>Path to a user-private |
| user-writable directory that is bound |
| to the user login time on the |
| machine. It is automatically created |
| the first time a user logs in and |
| removed on his final logout. If a user |
| logs in twice at the same time, both |
| sessions will see the same |
| <varname>$XDG_RUNTIME_DIR</varname> |
| and the same contents. If a user logs |
| in once, then logs out again, and logs |
| in again, the directory contents will |
| have been lost in between, but |
| applications should not rely on this |
| behaviour and must be able to deal with |
| stale files. To store session-private |
| data in this directory the user should |
| include the value of <varname>$XDG_SESSION_ID</varname> |
| in the filename. This directory shall |
| be used for runtime file system |
| objects such as AF_UNIX sockets, |
| FIFOs, PID files and similar. It is |
| guaranteed that this directory is |
| local and offers the greatest possible |
| file system feature set the |
| operating system |
| provides.</para></listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>Example</title> |
| |
| <programlisting>#%PAM-1.0 |
| auth required pam_unix.so |
| auth required pam_nologin.so |
| account required pam_unix.so |
| password required pam_unix.so |
| session required pam_unix.so |
| session required pam_loginuid.so |
| session required pam_systemd.so kill-session-processes=1</programlisting> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |