diff --git a/man/sd-login.xml b/man/sd-login.xml
index 6861fbe257..5022ff6be3 100644
--- a/man/sd-login.xml
+++ b/man/sd-login.xml
@@ -66,11 +66,6 @@
and monitor seat, login session and user status information on the
local system.
- See Multi-Seat
- on Linux for an introduction into multi-seat support on
- Linux, the background for this set of APIs.
-
Note that these APIs only allow purely passive access and
monitoring of seats, sessions and users. To actively make changes
to the seat configuration, terminate login sessions, or switch
@@ -115,6 +110,146 @@
implemented.
+
+ Definition of Terms
+
+
+
+ seat
+
+ A seat consists of all hardware devices assigned to a specific
+ workplace. It consists of at least one graphics device, and usually also includes
+ keyboard, mouse. It can also include video cameras, sound cards and more. Seats
+ are identified by seat names, which are short strings (<= 64 chars), that start
+ with the four characters seat followed by at least one more
+ character from the range [a-zA-Z0-9], _ and
+ -. They are suitable for inclusion in file names. Seat names
+ may or may not be stable and may be reused if a seat becomes available again.
+
+
+
+
+ session
+
+ A session is defined by the time a user is logged in until they
+ log out. A session is bound to one or no seats (the latter for 'virtual' ssh
+ logins). Multiple sessions can be attached to the same seat, but only one of them
+ can be active, the others are in the background. A session is identified by a
+ short string.
+
+
+ systemd1
+ ensures that audit sessions are identical to systemd sessions, and uses the audit
+ session ID as session ID in systemd (if auditing is enabled). The session
+ identifier too shall be considered a short string (<= 64 chars) consisting only
+ of [a-zA-Z0-9], _ and -, suitable for
+ inclusion in a file name. Session IDs are unique on the local machine and are
+ never reused as long as the machine is online. A user (the way we know it on UNIX)
+ corresponds to the person using a computer. A single user can have multiple
+ sessions open at the same time. A user is identified by a numeric user id (UID) or
+ a user name (a string). A multi-session system allows multiple user sessions on
+ the same seat at the same time. A multi-seat system allows multiple independent
+ seats that can be individually and simultaneously used by different users.
+
+
+
+
+ All hardware devices that are eligible to being assigned to a seat, are assigned
+ to one. A device can be assigned to only one seat at a time. If a device is not
+ assigned to any particular other seat it is implicitly assigned to the special default
+ seat called seat0.
+
+ Note that hardware like printers, hard disks or network cards is generally not
+ assigned to a specific seat. They are available to all seats equally. (Well, with one
+ exception: USB sticks can be assigned to a seat.)
+
+ seat0 always exists.
+
+
+
+ udev Rules
+
+ Assignment of hardware devices to seats is managed inside the udev database, via
+ settings on the devices:
+
+
+
+ Tag seat
+
+ When set, a device is eligible to be assigned to a seat. This tag
+ is set for graphics devices, mice, keyboards, video cards, sound cards and
+ more. Note that some devices like sound cards consist of multiple subdevices
+ (i.e. a PCM for input and another one for output). This tag will be set only for
+ the originating device, not for the individual subdevices. A UI for configuring
+ assignment of devices to seats should enumerate and subscribe to all devices with
+ this tag set and show them in the UI. Note that USB hubs can be assigned to a seat
+ as well, in which case all (current and future) devices plugged into it will also
+ be assigned to the same seat (unless they are explicitly assigned to another
+ seat).
+
+
+
+
+ Tag master-of-seat
+
+ When set, this device is enough for a seat to be considered
+ existent. This tag is usually set for the framebuffer device of graphics cards. A
+ seat hence consists of an arbitrary number of devices marked with the
+ seat tag, but (at least) one of these devices needs to be
+ tagged with master-of-seat before the seat is actually
+ considered to be around.
+
+
+
+ Property ID_SEAT
+
+ This property specifies the name of the seat a specific device is
+ assigned to. If not set the device is assigned to seat0. Also,
+ to speed up enumeration of hardware belonging to a specific seat, the seat is also
+ set as tag on the device. I.e. if the property
+ ID_SEAT=seat-waldo is set for a device, the tag
+ seat-waldo will be set as well. Note that if a device is
+ assigned to seat0, it will usually not carry such a tag and you
+ need to enumerate all devices and check the ID_SEAT property
+ manually. Again, if a device is assigned to seat0 this is visible on the device in
+ two ways: with a property ID_SEAT=seat0 and with no property
+ ID_SEAT set for it at all.
+
+
+
+ Property ID_AUTOSEAT
+
+ When set to 1, this device automatically
+ generates a new and independent seat, which is named after the path of the
+ device. This is set for specialized USB hubs like the Plugable devices, which when
+ plugged in should create a hotplug seat without further configuration.
+
+
+
+
+ Property ID_FOR_SEAT
+
+ When creating additional (manual) seats starting from a graphics
+ device this is a good choice to name the seat after. It is created from the path
+ of the device. This is useful in UIs for configuring seats: as soon as you create
+ a new seat from a graphics device, read this property and prefix it with
+ seat- and use it as name for the seat.
+
+
+
+ A seat exists only and exclusively because a properly tagged device with the
+ right ID_SEAT property exists. Besides udev rules there is no
+ persistent data about seats stored on disk.
+
+ Note that
+ systemd-logind8
+ manages ACLs on a number of device classes, to allow user code to access the device
+ nodes attached to a seat as long as the user has an active session on it. This is
+ mostly transparent to applications. As mentioned above, for certain user software it
+ might be a good idea to watch whether they can access device nodes instead of thinking
+ about seats.
+
+
@@ -130,6 +265,11 @@
sd-daemon3,
pkg-config1
+
+
+ Multi-Seat on Linux
+ for an introduction to multi-seat support on Linux and the background for this set of APIs.
+
diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml
index 5433269638..47089fd8c7 100644
--- a/man/systemd-logind.service.xml
+++ b/man/systemd-logind.service.xml
@@ -63,13 +63,13 @@
Keeping track of users and sessions, their processes and their idle state. This is implemented by
allocating a systemd slice unit for each user below user.slice, and a scope unit below it
for each concurrent session of a user. Also, a per-user service manager is started as system service instance of
- user@.service for each user logged in.
+ user@.service for each logged in user.
- Generating and managing session IDs. If auditing is available and an audit session ID is set for
- a session already, the session ID is initialized from it. Otherwise, an independent session counter is
+ Generating and managing session IDs. If auditing is available and an audit session ID is already set for
+ a session, then this ID is reused as the session ID. Otherwise, an independent session counter is
used.
- Providing PolicyKit-based access for users to
+ Providing PolicyKit-based access for users for
operations such as system shutdown or sleep
Implementing a shutdown/sleep inhibition logic