| <?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>If |
| <option>create-session=1</option> is set, 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>If |
| <option>create-session=1</option> is set, a new |
| control group |
| <filename>/user/$USER/$XDG_SESSION_ID</filename> |
| is created and the login process moved into |
| it.</para></listitem> |
| |
| <listitem><para>If |
| <option>create-session=0</option> is set, a new |
| control group |
| <filename>/user/$USER/user</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=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 |
| <varname>$XDG_SESSION_ID</varname> is set and |
| <option>kill-session=0</option> specified, all |
| remaining processes in the |
| <filename>/user/$USER/$XDG_SESSION_ID</filename> |
| control group are migrated to |
| <filename>/user/$USER/user</filename> and |
| the original control group is |
| removed.</para></listitem> |
| |
| <listitem><para>If |
| <option>kill-user=1</option> is specified, and |
| no other user session control group remains, |
| except |
| <filename>/user/$USER/user</filename>, |
| all remaining processes in the |
| <filename>/user/$USER</filename> hierarchy |
| are killed and the control group is removed.</para></listitem> |
| |
| <listitem><para>If |
| <option>kill-user=0</option> is specified, and |
| no process remains in the |
| <filename>/user/$USER</filename> hierarchy the |
| control group is removed.</para></listitem> |
| |
| <listitem><para>If 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>create-session=</option></term> |
| |
| <listitem><para>Takes a boolean |
| argument. If true, a new session is |
| created: the |
| <varname>$XDG_SESSION_ID</varname> |
| environment variable is set and the |
| login process moved to the |
| <filename>/user/$USER/$XDG_SESSION_ID</filename> |
| control group. It is recommended that |
| all services which are directly created |
| on the user's behalf set this |
| option. Only for services that shall |
| automatically be terminated when the |
| user logs out completely, otherwise |
| <varname>create-session=0</varname> |
| should be set.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>kill-session=</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-user=</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 after he logged out |
| completely. This is a weaker version |
| of <option>kill-session=1</option> and is |
| more friendly for users logged in more |
| than once, as their processes are |
| terminated only on their complete |
| logout.</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=</option> and |
| <option>kill-user=</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=</option> or |
| <option>kill-user=</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 cgroup controllers |
| in which hierarchies a user/session |
| cgroup will be created by default for |
| each user logging in, in addition to |
| the cgroup in the named 'name=systemd' |
| hierarchy. If ommited, defaults to an |
| empty list. This may be used to move |
| user sessions into their own groups in |
| the 'cpu' hierarchy which ensures that |
| every logged in user gets an equal |
| amount of CPU time regardless how many |
| processes he has |
| started.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>reset-controllers=</option></term> |
| |
| <listitem><para>Takes a comma |
| separated list of cgroup controllers |
| in which hierarchies the logged in |
| processes will be reset to the root |
| cgroup. If ommited, defaults to 'cpu', |
| meaning that a 'cpu' cgroup grouping |
| inherited from the login manager will |
| be reset for the processes of the |
| logged in user.</para></listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <para>Note that setting <varname>kill-user=1</varname> |
| or even <varname>kill-session=1</varname> will break |
| tools like |
| <citerefentry><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> |
| |
| <para>If the options are omitted they default to |
| <option>create-session=1</option>, |
| <option>kill-session=0</option>, |
| <option>kill-user=0</option>, |
| <option>reset-controllers=cpu</option>, |
| <option>kill-only-users=</option>, |
| <option>kill-exclude-users=root</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-user=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</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |