1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"sd-login" conditional='HAVE_PAM'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>sd-login
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>sd-login
</refentrytitle>
16 <manvolnum>3</manvolnum>
20 <refname>sd-login
</refname>
22 tracking logins
</refpurpose>
27 <funcsynopsisinfo>#include
<systemd/sd-login.h
></funcsynopsisinfo>
31 <command>pkg-config --cflags --libs libsystemd
</command>
36 <title>Description
</title>
38 <para><filename>sd-login.h
</filename> provides APIs to introspect
39 and monitor seat, login session and user status information on the
42 <para>Note that these APIs only allow purely passive access and
43 monitoring of seats, sessions and users. To actively make changes
44 to the seat configuration, terminate login sessions, or switch
45 session on a seat you need to utilize the D-Bus API of
46 systemd-logind, instead.
</para>
48 <para>These functions synchronously access data in
49 <filename>/proc
</filename>,
<filename>/sys/fs/cgroup
</filename>
50 and
<filename>/run
</filename>. All of these are virtual file
51 systems, hence the runtime cost of the accesses is relatively
54 <para>It is possible (and often a very good choice) to mix calls
55 to the synchronous interface of
<filename>sd-login.h
</filename>
56 with the asynchronous D-Bus interface of systemd-logind. However,
57 if this is done you need to think a bit about possible races since
58 the stream of events from D-Bus and from
59 <filename>sd-login.h
</filename> interfaces such as the login
60 monitor are asynchronous and not ordered against each
63 <para>If the functions return string arrays, these are generally
64 <constant>NULL
</constant> terminated and need to be freed by the
66 <citerefentry project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
67 call after use, including the strings referenced therein.
68 Similarly, individual strings returned need to be freed, as
71 <para>As a special exception, instead of an empty string array
72 <constant>NULL
</constant> may be returned, which should be treated
73 equivalent to an empty string array.
</para>
76 <citerefentry><refentrytitle>sd_pid_get_session
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
77 <citerefentry><refentrytitle>sd_uid_get_state
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
78 <citerefentry><refentrytitle>sd_session_is_active
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
79 <citerefentry><refentrytitle>sd_seat_get_active
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
80 <citerefentry><refentrytitle>sd_get_seats
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
81 <citerefentry><refentrytitle>sd_login_monitor_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
82 for more information about the functions
87 <title>Definition of Terms
</title>
93 <listitem><para>A seat consists of all hardware devices assigned to a specific
94 workplace. It consists of at least one graphics device, and usually also includes
95 keyboard, mouse. It can also include video cameras, sound cards and more. Seats
96 are identified by seat names, which are strings (
<=
255 characters), that start
97 with the four characters
<literal>seat
</literal> followed by at least one
98 character from the range [a-zA-Z0-
9],
<literal>_
</literal> and
99 <literal>-
</literal>. They are suitable for use as file names. Seat names may or
100 may not be stable and may be reused if a seat becomes available again.
107 <listitem><para>A session is defined by the time a user is logged in until they
108 log out. A session is bound to one or no seats (the latter for 'virtual' ssh
109 logins). Multiple sessions can be attached to the same seat, but only one of them
110 can be active, the others are in the background. A session is identified by a
114 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
115 ensures that audit sessions are identical to systemd sessions, and uses the audit
116 session ID as session ID in systemd (if auditing is enabled). In general the
117 session identifier is a short string consisting only of [a-zA-Z0-
9],
118 <literal>_
</literal> and
<literal>-
</literal>, suitable for use as a file name.
119 Session IDs are unique on the local machine and are
120 never reused as long as the machine is online. A user (the way we know it on UNIX)
121 corresponds to the person using a computer. A single user can have multiple
122 sessions open at the same time. A user is identified by a numeric user id (UID) or
123 a user name (a string). A multi-session system allows multiple user sessions on
124 the same seat at the same time. A multi-seat system allows multiple independent
125 seats that can be individually and simultaneously used by different users.
</para>
130 <para>All hardware devices that are eligible to being assigned to a seat, are assigned
131 to one. A device can be assigned to only one seat at a time. If a device is not
132 assigned to any particular other seat it is implicitly assigned to the special default
133 seat called
<literal>seat0
</literal>.
</para>
135 <para>Note that hardware like printers, hard disks or network cards is generally not
136 assigned to a specific seat. They are available to all seats equally. (Well, with one
137 exception: USB sticks can be assigned to a seat.)
</para>
139 <para><literal>seat0
</literal> always exists.
</para>
143 <title>udev Rules
</title>
145 <para>Assignment of hardware devices to seats is managed inside the udev database, via
146 settings on the devices:
</para>
148 <variablelist class='udev-directives'
>
150 <term>Tag
<literal>seat
</literal></term>
152 <listitem><para>When set, a device is eligible to be assigned to a seat. This tag
153 is set for graphics devices, mice, keyboards, video cards, sound cards and
154 more. Note that some devices like sound cards consist of multiple subdevices
155 (i.e. a PCM for input and another one for output). This tag will be set only for
156 the originating device, not for the individual subdevices. A UI for configuring
157 assignment of devices to seats should enumerate and subscribe to all devices with
158 this tag set and show them in the UI. Note that USB hubs can be assigned to a seat
159 as well, in which case all (current and future) devices plugged into it will also
160 be assigned to the same seat (unless they are explicitly assigned to another
166 <term>Tag
<literal>master-of-seat
</literal></term>
168 <listitem><para>When set, this device is enough for a seat to be considered
169 existent. This tag is usually set for the framebuffer device of graphics cards. A
170 seat hence consists of an arbitrary number of devices marked with the
171 <literal>seat
</literal> tag, but (at least) one of these devices needs to be
172 tagged with
<literal>master-of-seat
</literal> before the seat is actually
173 considered to be around.
</para></listitem>
177 <term>Property
<varname>ID_SEAT
</varname></term>
179 <listitem><para>This property specifies the name of the seat a specific device is
180 assigned to. If not set the device is assigned to
<literal>seat0
</literal>. Also,
181 to speed up enumeration of hardware belonging to a specific seat, the seat is also
182 set as tag on the device. I.e. if the property
183 <varname>ID_SEAT=seat-waldo
</varname> is set for a device, the tag
184 <literal>seat-waldo
</literal> will be set as well. Note that if a device is
185 assigned to
<literal>seat0
</literal>, it will usually not carry such a tag and you
186 need to enumerate all devices and check the
<varname>ID_SEAT
</varname> property
187 manually. Again, if a device is assigned to seat0 this is visible on the device in
188 two ways: with a property
<varname>ID_SEAT=seat0
</varname> and with no property
189 <varname>ID_SEAT
</varname> set for it at all.
</para></listitem>
193 <term>Property
<varname>ID_AUTOSEAT
</varname></term>
195 <listitem><para>When set to
<literal>1</literal>, this device automatically
196 generates a new and independent seat, which is named after the path of the
197 device. This is set for specialized USB hubs like the Pluggable devices, which when
198 plugged in should create a hotplug seat without further configuration.
</para>
203 <term>Property
<varname>ID_FOR_SEAT
</varname></term>
205 <listitem><para>When creating additional (manual) seats starting from a graphics
206 device this is a good choice to name the seat after. It is created from the path
207 of the device. This is useful in UIs for configuring seats: as soon as you create
208 a new seat from a graphics device, read this property and prefix it with
209 <literal>seat-
</literal> and use it as name for the seat.
</para></listitem>
213 <para>A seat exists only and exclusively because a properly tagged device with the
214 right
<varname>ID_SEAT
</varname> property exists. Besides udev rules there is no
215 persistent data about seats stored on disk.
</para>
218 <citerefentry><refentrytitle>systemd-logind
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
219 manages ACLs on a number of device classes, to allow user code to access the device
220 nodes attached to a seat as long as the user has an active session on it. This is
221 mostly transparent to applications. As mentioned above, for certain user software it
222 might be a good idea to watch whether they can access device nodes instead of thinking
226 <xi:include href=
"libsystemd-pkgconfig.xml" />
229 <title>See Also
</title>
231 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
232 <citerefentry><refentrytitle>sd_pid_get_session
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
233 <citerefentry><refentrytitle>sd_uid_get_state
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
234 <citerefentry><refentrytitle>sd_session_is_active
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
235 <citerefentry><refentrytitle>sd_seat_get_active
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
236 <citerefentry><refentrytitle>sd_get_seats
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
237 <citerefentry><refentrytitle>sd_login_monitor_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
238 <citerefentry><refentrytitle>sd-daemon
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
239 <citerefentry project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
243 <ulink url=
"https://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat on Linux
</ulink>
244 for an introduction to multi-seat support on Linux and the background for this set of APIs.