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

meta data 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>