<?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">

<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 in 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 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 the 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 class='pam-directives'>

<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 usernames 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 usernames 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>

</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>class=</option></term>

<listitem><para>Takes a string

argument which sets the session class.

The XDG_SESSION_CLASS environmental variable

takes precedence.</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>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 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>

</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>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>

</para>

</refsect1>

</refentry>