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