man/sd-login.xml

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