mirror of
https://github.com/systemd/systemd.git
synced 2024-11-02 19:21:53 +03:00
387 lines
18 KiB
XML
387 lines
18 KiB
XML
<?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 omitted, 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 omitted, 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>
|
|
|
|
<varlistentry>
|
|
<term><option>debug=</option></term>
|
|
|
|
<listitem><para>Takes a boolean
|
|
argument. If true, logs debugging
|
|
information.</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>
|