| 1 |
'\" t |
| 2 |
.TH "SD\-LOGIN" "3" "" "systemd 261~rc3" "sd-login" |
| 3 |
.\" ----------------------------------------------------------------- |
| 4 |
.\" * Define some portability stuff |
| 5 |
.\" ----------------------------------------------------------------- |
| 6 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 7 |
.\" http://bugs.debian.org/507673 |
| 8 |
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| 9 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 10 |
.ie \n(.g .ds Aq \(aq |
| 11 |
.el .ds Aq ' |
| 12 |
.\" ----------------------------------------------------------------- |
| 13 |
.\" * set default formatting |
| 14 |
.\" ----------------------------------------------------------------- |
| 15 |
.\" disable hyphenation |
| 16 |
.nh |
| 17 |
.\" disable justification (adjust text to left margin only) |
| 18 |
.ad l |
| 19 |
.\" ----------------------------------------------------------------- |
| 20 |
.\" * MAIN CONTENT STARTS HERE * |
| 21 |
.\" ----------------------------------------------------------------- |
| 22 |
.SH "NAME" |
| 23 |
sd-login \- APIs for tracking logins |
| 24 |
.SH "SYNOPSIS" |
| 25 |
.sp |
| 26 |
.ft B |
| 27 |
.nf |
| 28 |
#include <systemd/sd\-login\&.h> |
| 29 |
.fi |
| 30 |
.ft |
| 31 |
.HP \w'\fBpkg\-config\ \-\-cflags\ \-\-libs\ libsystemd\fR\ 'u |
| 32 |
\fBpkg\-config \-\-cflags \-\-libs libsystemd\fR |
| 33 |
.SH "DESCRIPTION" |
| 34 |
.PP |
| 35 |
sd\-login\&.h |
| 36 |
is part of |
| 37 |
\fBlibsystemd\fR(3) |
| 38 |
and provides APIs to introspect and monitor seat, login session, and user status information on the local system\&. |
| 39 |
.PP |
| 40 |
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 session on a seat you need to utilize the D\-Bus API of systemd\-logind instead\&. |
| 41 |
.PP |
| 42 |
These functions synchronously access data in |
| 43 |
/proc/, |
| 44 |
/sys/fs/cgroup/ |
| 45 |
and |
| 46 |
/run/\&. All of these are virtual file systems, hence the runtime cost of the accesses is relatively cheap\&. |
| 47 |
.PP |
| 48 |
It is possible (and often a very good choice) to mix calls to the synchronous interface of |
| 49 |
sd\-login\&.h |
| 50 |
with the asynchronous D\-Bus interface of systemd\-logind\&. However, if this is done you need to think a bit about possible races since the stream of events from D\-Bus and from |
| 51 |
sd\-login\&.h |
| 52 |
interfaces such as the login monitor are asynchronous and not ordered against each other\&. |
| 53 |
.PP |
| 54 |
If the functions return string arrays, these are generally |
| 55 |
\fBNULL\fR\-terminated and need to be freed by the caller with the libc |
| 56 |
\fBfree\fR(3) |
| 57 |
call after use, including the strings referenced therein\&. Similarly, individual strings returned need to be freed, as well\&. |
| 58 |
.PP |
| 59 |
As a special exception, instead of an empty string array |
| 60 |
\fBNULL\fR |
| 61 |
may be returned, which should be treated equivalent to an empty string array\&. |
| 62 |
.PP |
| 63 |
See |
| 64 |
\fBsd_pid_get_session\fR(3), |
| 65 |
\fBsd_uid_get_state\fR(3), |
| 66 |
\fBsd_session_is_active\fR(3), |
| 67 |
\fBsd_seat_get_active\fR(3), |
| 68 |
\fBsd_get_seats\fR(3), |
| 69 |
\fBsd_login_monitor_new\fR(3) |
| 70 |
for more information about the functions implemented\&. |
| 71 |
.SH "DEFINITION OF TERMS" |
| 72 |
.PP |
| 73 |
seat |
| 74 |
.RS 4 |
| 75 |
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 strings (<= 255 characters), that start with the four characters |
| 76 |
"seat" |
| 77 |
followed by at least one character from the range [a\-zA\-Z0\-9], |
| 78 |
"_" |
| 79 |
and |
| 80 |
"\-"\&. They are suitable for use as file names\&. Seat names may or may not be stable and may be reused if a seat becomes available again\&. |
| 81 |
.sp |
| 82 |
Added in version 235\&. |
| 83 |
.RE |
| 84 |
.PP |
| 85 |
session |
| 86 |
.RS 4 |
| 87 |
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 \*(Aqvirtual\*(Aq 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\&. |
| 88 |
.sp |
| 89 |
\fBsystemd\fR(1) |
| 90 |
ensures that audit sessions are identical to systemd sessions, and uses the audit session ID as session ID in systemd (if auditing is enabled)\&. In general the session identifier is a short string consisting only of [a\-zA\-Z0\-9], |
| 91 |
"_" |
| 92 |
and |
| 93 |
"\-", suitable for use as 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\&. |
| 94 |
.sp |
| 95 |
Added in version 235\&. |
| 96 |
.RE |
| 97 |
.PP |
| 98 |
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 |
| 99 |
"seat0"\&. |
| 100 |
.PP |
| 101 |
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\&.) |
| 102 |
.PP |
| 103 |
"seat0" |
| 104 |
always exists\&. |
| 105 |
.SH "UDEV RULES" |
| 106 |
.PP |
| 107 |
Assignment of hardware devices to seats is managed inside the udev database, via settings on the devices: |
| 108 |
.PP |
| 109 |
Tag "seat" |
| 110 |
.RS 4 |
| 111 |
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)\&. |
| 112 |
.sp |
| 113 |
Added in version 235\&. |
| 114 |
.RE |
| 115 |
.PP |
| 116 |
Tag "master\-of\-seat" |
| 117 |
.RS 4 |
| 118 |
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 |
| 119 |
"seat" |
| 120 |
tag, but (at least) one of these devices needs to be tagged with |
| 121 |
"master\-of\-seat" |
| 122 |
before the seat is actually considered to be around\&. |
| 123 |
.sp |
| 124 |
Added in version 235\&. |
| 125 |
.RE |
| 126 |
.PP |
| 127 |
Tag "uaccess" |
| 128 |
.RS 4 |
| 129 |
When set, access to this device is tied to an active seat\&. As the session on the seat becomes active or inactive, access to the device is updated accordingly\&. |
| 130 |
.RE |
| 131 |
.PP |
| 132 |
Tag "xaccess\-*" |
| 133 |
.RS 4 |
| 134 |
When |
| 135 |
"xaccess\-\fIID\fR" |
| 136 |
is set, access to this device is granted to sessions created with |
| 137 |
"\fIID\fR" |
| 138 |
listed in |
| 139 |
"ExtraDeviceAccess"\&. As the sessions with some |
| 140 |
"ExtraDeviceAccess" |
| 141 |
open and close, access to the device is updated accordingly\&. |
| 142 |
.sp |
| 143 |
Added in version 260\&. |
| 144 |
.RE |
| 145 |
.PP |
| 146 |
Property \fIID_SEAT\fR |
| 147 |
.RS 4 |
| 148 |
This property specifies the name of the seat a specific device is assigned to\&. If not set the device is assigned to |
| 149 |
"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 |
| 150 |
\fIID_SEAT=seat\-waldo\fR |
| 151 |
is set for a device, the tag |
| 152 |
"seat\-waldo" |
| 153 |
will be set as well\&. Note that if a device is assigned to |
| 154 |
"seat0", it will usually not carry such a tag and you need to enumerate all devices and check the |
| 155 |
\fIID_SEAT\fR |
| 156 |
property manually\&. Again, if a device is assigned to seat0 this is visible on the device in two ways: with a property |
| 157 |
\fIID_SEAT=seat0\fR |
| 158 |
and with no property |
| 159 |
\fIID_SEAT\fR |
| 160 |
set for it at all\&. |
| 161 |
.sp |
| 162 |
Added in version 235\&. |
| 163 |
.RE |
| 164 |
.PP |
| 165 |
Property \fIID_AUTOSEAT\fR |
| 166 |
.RS 4 |
| 167 |
When set to |
| 168 |
"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 Pluggable devices, which when plugged in should create a hotplug seat without further configuration\&. |
| 169 |
.sp |
| 170 |
Added in version 235\&. |
| 171 |
.RE |
| 172 |
.PP |
| 173 |
Property \fIID_FOR_SEAT\fR |
| 174 |
.RS 4 |
| 175 |
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 |
| 176 |
"seat\-" |
| 177 |
and use it as name for the seat\&. |
| 178 |
.sp |
| 179 |
Added in version 235\&. |
| 180 |
.RE |
| 181 |
.PP |
| 182 |
A seat exists only and exclusively because a properly tagged device with the right |
| 183 |
\fIID_SEAT\fR |
| 184 |
property exists\&. Besides udev rules there is no persistent data about seats stored on disk\&. |
| 185 |
.PP |
| 186 |
Note that |
| 187 |
\fBsystemd-logind\fR(8) |
| 188 |
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\&. |
| 189 |
.SH "NOTES" |
| 190 |
.PP |
| 191 |
Functions described here are available as a shared library, which can be compiled against and linked to with the |
| 192 |
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1) |
| 193 |
file\&. |
| 194 |
.PP |
| 195 |
The code described here uses |
| 196 |
\fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call |
| 197 |
\fBsetenv\fR(3) |
| 198 |
from a parallel thread\&. It is recommended to only do calls to |
| 199 |
\fBsetenv()\fR |
| 200 |
from an early phase of the program when no other threads have been started\&. |
| 201 |
.SH "SEE ALSO" |
| 202 |
.PP |
| 203 |
\fBsystemd\fR(1), \fBsd_pid_get_session\fR(3), \fBsd_uid_get_state\fR(3), \fBsd_session_is_active\fR(3), \fBsd_seat_get_active\fR(3), \fBsd_get_seats\fR(3), \fBsd_login_monitor_new\fR(3), \fBsd-daemon\fR(3), \fBpkg-config\fR(1) |
| 204 |
.PP |
| 205 |
\m[blue]\fBMulti\-Seat on Linux\fR\m[]\&\s-2\u[1]\d\s+2 |
| 206 |
may also be of historical interest\&. |
| 207 |
.SH "NOTES" |
| 208 |
.IP " 1." 4 |
| 209 |
Multi-Seat on Linux |
| 210 |
.RS 4 |
| 211 |
\%https://www.freedesktop.org/wiki/Software/systemd/multiseat |
| 212 |
.RE |