[thirdparty/systemd.git] / docs / WRITING_DISPLAY_MANAGERS.md

---
title: Writing Display Managers
category: Documentation for Developers
layout: default
SPDX-License-Identifier: LGPL-2.1-or-later
---

# Writing Display Managers

_Or: How to hook up your favorite X11 display manager with systemd_

systemd's logind service obsoletes ConsoleKit which was previously widely used on Linux distributions.
For X11 display managers the switch to logind requires a minimal amount of porting, however brings a couple of new features:
true automatic multi-seat support, proper tracking of session processes, (optional) automatic killing of user processes on logout, a synchronous low-level C API and much simplification.

This document should be read together with [Writing Desktop Environments](/WRITING_DESKTOP_ENVIRONMENTS) which focuses on the porting work necessary for desktop environments.

If required it is possible to implement ConsoleKit and systemd-logind support in the same display manager, detecting at runtime which interface is needed.
The [sd_booted()](http://www.freedesktop.org/software/systemd/man/sd_booted.html) call may be used to determine at runtime whether systemd is used.

To a certain level ConsoleKit and systemd-logind may be used side-by-side, but a number of features are not available if ConsoleKit is used, for example automatic multi-seat support.

Please have a look at the [Bus API of logind](https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.login1.html) and the C API as documented in [sd-login(7)](http://www.freedesktop.org/software/systemd/man/sd-login.html).
(Also see below)

Minimal porting (without multi-seat) requires the following:

1. Remove/disable all code responsible for registering your service with ConsoleKit.
2. Make sure to register your greeter session via the PAM session stack, and make sure the PAM session modules include pam_systemd.
   Also, make sure to set the session class to "greeter." This may be done by setting the environment variable XDG_SESSION_CLASS to "greeter" with pam_misc_setenv() or setting the "class=greeter" option in the pam_systemd module, in order to allow applications to filter out greeter sessions from normal login sessions.
3. Make sure to register your logged in session via the PAM session stack as well, also including pam_systemd in it.
4. Optionally, use pam_misc_setenv() to set the environment variables XDG_SEAT and XDG_VTNR.
   The former should contain "seat0", the latter the VT number your session runs on. pam_systemd can determine these values automatically but it's nice to pass these variables anyway.
In summary: porting a display manager from ConsoleKit to systemd primarily means removing code, not necessarily adding any new code. Here, a cheers to simplicity!

Complete porting (with multi-seat) requires the following (Before you continue, make sure to read up on [Multi-Seat on Linux](https://www.freedesktop.org/wiki/Software/systemd/multiseat) first.):

1. Subscribe to seats showing up and going away, via the systemd-logind D-Bus interface's SeatAdded and SeatRemoved signals.
   Take possession of each seat by spawning your greeter on it.
   However, do so exclusively for seats where the boolean CanGraphical property is true.
   Note that there are seats that cannot do graphical, and there are seats that are text-only first, and gain graphical support later on.
   Most prominently this is actually seat0 which comes up in text mode, and where the graphics driver is then loaded and probed during boot.
   This means display managers must watch PropertyChanged events on all seats, to see if they gain (or lose) the CanGraphical field.
2. Use ListSeats() on the D-Bus interface to acquire a list of already available seats and also take possession of them.
3. For each seat you spawn a greeter/user session on use the XDG_SEAT and XDG_VTNR PAM environment variables to inform pam_systemd about the seat name, resp.
   VT number you start them on. Note that only the special seat "seat0" actually knows kernel VTs, so you shouldn't pass the VT number on any but the main seat, since it doesn't make any sense there.
4. Pass the seat name to the X server you start via the -seat parameter.
5. At this time X interprets the -seat parameter natively only for input devices, not for graphics devices.
   To work around this limitation we provide a tiny wrapper /lib/systemd/systemd-multi-seat-x which emulates the enumeration for graphics devices too.
   This wrapper will eventually go away, as soon as X learns udev-based graphics device enumeration natively, instead of the current PCI based one.
   Hence it is a good idea to fall back to the real X when this wrapper is not found.
   You may use this wrapper exactly like the real X server, and internally it will just exec() it after putting together a minimal multi-seat configuration.
   And that's already it.

While most information about seats, sessions and users is available on systemd-logind's D-Bus interface, this is not the only API.
The synchronous [sd-login(7)](http://www.freedesktop.org/software/systemd/man/sd-login.html) C interface is often easier to use and much faster too.
In fact it is possible to implement the scheme above entirely without D-Bus relying only on this API.
Note however, that this C API is purely passive, and if you want to execute an actually state changing operation you need to use the bus interface (for example, to switch sessions, or to kill sessions and suchlike).
Also have a look at the [logind Bus API](https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.login1.html).
Commit	Line	Data
163e2c83 MG	1	---
	2	title: Writing Display Managers
	3	category: Documentation for Developers
	4	layout: default
	5	SPDX-License-Identifier: LGPL-2.1-or-later
	6	---
	7
	8	# Writing Display Managers
	9
	10	_Or: How to hook up your favorite X11 display manager with systemd_
	11
a4fd4d9c	12	systemd's logind service obsoletes ConsoleKit which was previously widely used on Linux distributions.
	13	For X11 display managers the switch to logind requires a minimal amount of porting, however brings a couple of new features:
	14	true automatic multi-seat support, proper tracking of session processes, (optional) automatic killing of user processes on logout, a synchronous low-level C API and much simplification.
163e2c83	15
0d592a5e	16	This document should be read together with [Writing Desktop Environments](/WRITING_DESKTOP_ENVIRONMENTS) which focuses on the porting work necessary for desktop environments.
163e2c83	17
a4fd4d9c	18	If required it is possible to implement ConsoleKit and systemd-logind support in the same display manager, detecting at runtime which interface is needed.
a4fd4d9c	19	The [sd_booted()](http://www.freedesktop.org/software/systemd/man/sd_booted.html) call may be used to determine at runtime whether systemd is used.
163e2c83 MG	20
	21	To a certain level ConsoleKit and systemd-logind may be used side-by-side, but a number of features are not available if ConsoleKit is used, for example automatic multi-seat support.
	22
a4fd4d9c	23	Please have a look at the [Bus API of logind](https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.login1.html) and the C API as documented in [sd-login(7)](http://www.freedesktop.org/software/systemd/man/sd-login.html).
a4fd4d9c	24	(Also see below)
163e2c83 MG	25
	26	Minimal porting (without multi-seat) requires the following:
	27
	28	1. Remove/disable all code responsible for registering your service with ConsoleKit.
a4fd4d9c	29	2. Make sure to register your greeter session via the PAM session stack, and make sure the PAM session modules include pam_systemd.
a4fd4d9c	30	Also, make sure to set the session class to "greeter." This may be done by setting the environment variable XDG_SESSION_CLASS to "greeter" with pam_misc_setenv() or setting the "class=greeter" option in the pam_systemd module, in order to allow applications to filter out greeter sessions from normal login sessions.
163e2c83	31	3. Make sure to register your logged in session via the PAM session stack as well, also including pam_systemd in it.
a4fd4d9c	32	4. Optionally, use pam_misc_setenv() to set the environment variables XDG_SEAT and XDG_VTNR.
	33	The former should contain "seat0", the latter the VT number your session runs on. pam_systemd can determine these values automatically but it's nice to pass these variables anyway.
	34	In summary: porting a display manager from ConsoleKit to systemd primarily means removing code, not necessarily adding any new code. Here, a cheers to simplicity!
163e2c83	35
b479ff87	36	Complete porting (with multi-seat) requires the following (Before you continue, make sure to read up on [Multi-Seat on Linux](https://www.freedesktop.org/wiki/Software/systemd/multiseat) first.):
163e2c83	37
a4fd4d9c	38	1. Subscribe to seats showing up and going away, via the systemd-logind D-Bus interface's SeatAdded and SeatRemoved signals.
	39	Take possession of each seat by spawning your greeter on it.
	40	However, do so exclusively for seats where the boolean CanGraphical property is true.
	41	Note that there are seats that cannot do graphical, and there are seats that are text-only first, and gain graphical support later on.
	42	Most prominently this is actually seat0 which comes up in text mode, and where the graphics driver is then loaded and probed during boot.
	43	This means display managers must watch PropertyChanged events on all seats, to see if they gain (or lose) the CanGraphical field.
163e2c83	44	2. Use ListSeats() on the D-Bus interface to acquire a list of already available seats and also take possession of them.
a4fd4d9c	45	3. For each seat you spawn a greeter/user session on use the XDG_SEAT and XDG_VTNR PAM environment variables to inform pam_systemd about the seat name, resp.
a4fd4d9c	46	VT number you start them on. Note that only the special seat "seat0" actually knows kernel VTs, so you shouldn't pass the VT number on any but the main seat, since it doesn't make any sense there.
163e2c83	47	4. Pass the seat name to the X server you start via the -seat parameter.
a4fd4d9c	48	5. At this time X interprets the -seat parameter natively only for input devices, not for graphics devices.
	49	To work around this limitation we provide a tiny wrapper /lib/systemd/systemd-multi-seat-x which emulates the enumeration for graphics devices too.
	50	This wrapper will eventually go away, as soon as X learns udev-based graphics device enumeration natively, instead of the current PCI based one.
	51	Hence it is a good idea to fall back to the real X when this wrapper is not found.
	52	You may use this wrapper exactly like the real X server, and internally it will just exec() it after putting together a minimal multi-seat configuration.
163e2c83 MG	53	And that's already it.
163e2c83 MG	54
a4fd4d9c	55	While most information about seats, sessions and users is available on systemd-logind's D-Bus interface, this is not the only API.
	56	The synchronous [sd-login(7)](http://www.freedesktop.org/software/systemd/man/sd-login.html) C interface is often easier to use and much faster too.
	57	In fact it is possible to implement the scheme above entirely without D-Bus relying only on this API.
	58	Note however, that this C API is purely passive, and if you want to execute an actually state changing operation you need to use the bus interface (for example, to switch sessions, or to kill sessions and suchlike).
	59	Also have a look at the [logind Bus API](https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.login1.html).