3802a3d3d7af51ddff31943d5514382f01265770Lennart Poettering<?xml version='1.0'?> <!--*-nxml-*-->

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

301af7e4853ad0281402f8d86f5a77c6cb7ce9f4Josh Triplett<refentry id="pam_systemd">

301af7e4853ad0281402f8d86f5a77c6cb7ce9f4Josh Triplett

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <refentryinfo>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <title>pam_systemd</title>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <productname>systemd</productname>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <authorgroup>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <author>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <contrib>Developer</contrib>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <firstname>Lennart</firstname>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <surname>Poettering</surname>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek </author>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek </authorgroup>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek </refentryinfo>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <refmeta>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <refentrytitle>pam_systemd</refentrytitle>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <manvolnum>8</manvolnum>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek </refmeta>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <refnamediv>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <refname>pam_systemd</refname>

301af7e4853ad0281402f8d86f5a77c6cb7ce9f4Josh Triplett <refpurpose>Register user sessions in the systemd control group hierarchy</refpurpose>

301af7e4853ad0281402f8d86f5a77c6cb7ce9f4Josh Triplett </refnamediv>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <refsynopsisdiv>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <cmdsynopsis>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <command>pam_systemd.so</command>

301af7e4853ad0281402f8d86f5a77c6cb7ce9f4Josh Triplett </cmdsynopsis>

301af7e4853ad0281402f8d86f5a77c6cb7ce9f4Josh Triplett </refsynopsisdiv>

301af7e4853ad0281402f8d86f5a77c6cb7ce9f4Josh Triplett

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <refsect1>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <title>Description</title>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <para><command>pam_systemd</command> registers user

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek sessions in the systemd control group

18ead1b00dff180a97507d014325cb46198e6657Chris Mayo hierarchy.</para>

18ead1b00dff180a97507d014325cb46198e6657Chris Mayo

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <para>On login, this module ensures the following:</para>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <orderedlist>

e93549ef29c4123d9ee45acb5815048390201e49Zbigniew Jędrzejewski-Szmek <listitem><para>If it does not exist yet, the

301af7e4853ad0281402f8d86f5a77c6cb7ce9f4Josh Triplett user runtime directory

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <filename>/run/user/$USER</filename> is

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek created and its ownership changed to the user

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek that is logging in.</para></listitem>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <listitem><para>If

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <option>create-session=1</option> is set, the

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <varname>$XDG_SESSION_ID</varname> environment

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek variable is initialized. If auditing is

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek available and

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <command>pam_loginuid.so</command> run before

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek this module (which is highly recommended), the

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek variable is initialized from the auditing

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek session id

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek (<filename>/proc/self/sessionid</filename>). Otherwise

8d0e0ddda6501479eb69164687c83c1a7667b33aJan Engelhardt an independent session counter is

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek used.</para></listitem>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <listitem><para>If

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <option>create-session=1</option> is set, a new

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek control group

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <filename>/user/$USER/$XDG_SESSION_ID</filename>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek is created and the login process moved into

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek it.</para></listitem>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <listitem><para>If

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <option>create-session=0</option> is set, a new

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek control group

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <filename>/user/$USER/user</filename>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek is created and the login process moved into

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek it.</para></listitem>

8c9571d0ae50656f730a5e37378d5c3dcf3b9789Lennart Poettering

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek </orderedlist>

442f7f155358a7396a350d3c47ea42e86bee4024Chris Atkinson

8c9571d0ae50656f730a5e37378d5c3dcf3b9789Lennart Poettering <para>On logout, this module ensures the following:</para>

8c9571d0ae50656f730a5e37378d5c3dcf3b9789Lennart Poettering

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <orderedlist>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <listitem><para>If

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <varname>$XDG_SESSION_ID</varname> is set and

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <option>kill-session=1</option> specified, all

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek remaining processes in the

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <filename>/user/$USER/$XDG_SESSION_ID</filename>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek control group are killed and the control group

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek is removed.</para></listitem>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <listitem><para>If

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <varname>$XDG_SESSION_ID</varname> is set and

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <option>kill-session=0</option> specified, all

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek remaining processes in the

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <filename>/user/$USER/$XDG_SESSION_ID</filename>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek control group are migrated to

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <filename>/user/$USER/user</filename> and

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek the original control group is

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek removed.</para></listitem>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering <listitem><para>If

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering <option>kill-user=1</option> is specified, and

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering no other user session control group remains,

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering except

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering <filename>/user/$USER/user</filename>,

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering all remaining processes in the

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering <filename>/user/$USER</filename> hierarchy

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering are killed and the control group is removed.</para></listitem>

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering <listitem><para>If

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering <option>kill-user=0</option> is specified, and

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering no process remains in the

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering <filename>/user/$USER</filename> hierarchy the

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering control group is removed.</para></listitem>

cbfaff65cb086e3eb3709cf86dcf63b46622389bKarel Zak

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering <listitem><para>If the

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering <filename>/user/$USER</filename> control group

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek was removed the

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <varname>$XDG_RUNTIME_DIR</varname> directory

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek and all its contents are

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek removed, too.</para></listitem>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek </orderedlist>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <para>If the system was not booted up with systemd as

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek init system, this module does nothing and immediately

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering returns PAM_SUCCESS.</para>

0dc5d23c85db85f96b141d4d32deee8018e56a6aLennart Poettering

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek </refsect1>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <refsect1>

3cc765d2718ac9b4ff978044ceabf5ad59d73edfZbigniew Jędrzejewski-Szmek <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>