chiark / gitweb /
man: ipv4 link-local
[elogind.git] / man / pam_systemd.xml
index 27edea7..3022cdb 100644 (file)
@@ -21,7 +21,7 @@
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
-<refentry id="pam_systemd">
+<refentry id="pam_systemd" conditional='HAVE_PAM'>
 
         <refentryinfo>
                 <title>pam_systemd</title>
         </refnamediv>
 
         <refsynopsisdiv>
-                <cmdsynopsis>
-                        <command>pam_systemd.so</command>
-                </cmdsynopsis>
+                <para><filename>pam_systemd.so</filename></para>
         </refsynopsisdiv>
 
         <refsect1>
                 <title>Description</title>
 
                 <para><command>pam_systemd</command> registers user
-                sessions in the systemd login manager
+                sessions with the systemd login manager
                 <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                 and hence the systemd control group hierarchy.</para>
 
                         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>
+                        <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
-                        <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
+                        <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>
+                        and all its contents are removed,
+                        too.</para></listitem>
                 </orderedlist>
 
                 <para>If the system was not booted up with systemd as
 
                 <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>
+                <variablelist class='pam-directives'>
 
                         <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>
+                                <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>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 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>
+                                <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>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>
+                                <term><option>debug<optional>=</optional></option></term>
 
-                        <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
+                                <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>
-
-                <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>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>
 
                 <para>The following environment variables are set for the processes of the user's session:</para>
 
-                <variablelist>
+                <variablelist class='environment-variables'>
                         <varlistentry>
                                 <term><varname>$XDG_SESSION_ID</varname></term>
 
                                 <listitem><para>A session identifier,
-                                suitable to be used in file names. The
+                                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
                                 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
+                                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,
+                                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
                                 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>
 
@@ -299,7 +295,7 @@ 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>
+session    required     pam_systemd.so</programlisting>
         </refsect1>
 
         <refsect1>
@@ -312,7 +308,10 @@ session    required     pam_systemd.so kill-session-processes=1</programlisting>
                         <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>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>