| <?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 Lesser General Public License as published by |
| the Free Software Foundation; either version 2.1 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 |
| Lesser General Public License for more details. |
| |
| You should have received a copy of the GNU Lesser General Public License |
| along with systemd; If not, see <http://www.gnu.org/licenses/>. |
| --> |
| |
| <refentry id="pam_systemd" conditional='HAVE_PAM'> |
| |
| <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 login manager</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <para><filename>pam_systemd.so</filename></para> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para><command>pam_systemd</command> registers user |
| sessions with the systemd login manager |
| <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| and hence 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 systemd scope unit is |
| created for the session. If this is the first |
| concurrent session of the user, an implicit |
| slice below <filename>user.slice</filename> is |
| automatically created and the scope placed in |
| it. In instance of the system service |
| <filename>user@.service</filename> which runs |
| the systemd user manager |
| instance.</para></listitem> |
| </orderedlist> |
| |
| <para>On logout, this module ensures the following:</para> |
| |
| <orderedlist> |
| <listitem><para>If this is enabled, all |
| processes of the session are terminated. If |
| the last concurrent session of a user ends, his |
| user systemd instance will be terminated too, |
| and so will the user's slice |
| unit.</para></listitem> |
| |
| <listitem><para>If the last concurrent session |
| of a user ends, 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 class='pam-directives'> |
| |
| <varlistentry> |
| <term><option>class=</option></term> |
| |
| <listitem><para>Takes a string |
| argument which sets the session class. |
| The XDG_SESSION_CLASS environmental variable |
| takes precedence. One of |
| <literal>user</literal>, |
| <literal>greeter</literal>, |
| <literal>lock-screen</literal> or |
| <literal>background</literal>. See |
| <citerefentry><refentrytitle>sd_session_get_class</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
| for details about the session class.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>type=</option></term> |
| |
| <listitem><para>Takes a string |
| argument which sets the session type. |
| The XDG_SESSION_TYPE environmental |
| variable takes precedence. One of |
| <literal>unspecified</literal>, |
| <literal>tty</literal>, |
| <literal>x11</literal> or |
| <literal>wayland</literal>. See |
| <citerefentry><refentrytitle>sd_session_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
| for details about the session type.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>debug<optional>=</optional></option></term> |
| |
| <listitem><para>Takes an optional |
| boolean argument. If yes or without |
| the argument, the module will log |
| debugging information as it |
| operates.</para></listitem> |
| </varlistentry> |
| </variablelist> |
| </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 class='environment-variables'> |
| <varlistentry> |
| <term><varname>$XDG_SESSION_ID</varname></term> |
| |
| <listitem><para>A session identifier, |
| suitable to be used in filenames. 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 |
| behavior 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 <constant>AF_UNIX</constant> 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> |
| |
| <para>The following environment variables are read by |
| the module and may be used by the PAM service to pass |
| metadata to the module:</para> |
| |
| <variablelist class='environment-variables'> |
| <varlistentry> |
| <term><varname>$XDG_SESSION_TYPE</varname></term> |
| |
| <listitem><para>The session type. This |
| may be used instead of |
| <option>session=</option> on the |
| module parameter line, and is usually |
| preferred.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>$XDG_SESSION_CLASS</varname></term> |
| |
| <listitem><para>The session class. This |
| may be used instead of |
| <option>class=</option> on the |
| module parameter line, and is usually |
| preferred.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>$XDG_SESSION_DESKTOP</varname></term> |
| |
| <listitem><para>The session |
| deskop. This may be used to indicate |
| the session desktop used, where this |
| applies. This should be a short, |
| lowercase string identifying the |
| desktop environment used if this |
| information is available. For example: |
| <literal>gnome</literal>, or |
| <literal>kde</literal>.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>$XDG_SEAT</varname></term> |
| |
| <listitem><para>The seat name the session |
| shall be registered for, if |
| any.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><varname>$XDG_VTNR</varname></term> |
| |
| <listitem><para>The VT number the |
| session shall be registered for, if |
| any. (Only applies to seats with a VT |
| available, such as |
| <literal>seat0</literal>)</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</programlisting> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <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.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |