mirror of
https://github.com/systemd/systemd.git
synced 2024-11-01 17:51:22 +03:00
11a1589223
Files which are installed as-is (any .service and other unit files, .conf files, .policy files, etc), are left as is. My assumption is that SPDX identifiers are not yet that well known, so it's better to retain the extended header to avoid any doubt. I also kept any copyright lines. We can probably remove them, but it'd nice to obtain explicit acks from all involved authors before doing that.
265 lines
12 KiB
XML
265 lines
12 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<!--
|
|
SPDX-License-Identifier: LGPL-2.1+
|
|
|
|
This file is part of systemd.
|
|
|
|
Copyright 2010 Lennart Poettering
|
|
-->
|
|
|
|
<refentry id="sd-login" conditional='HAVE_PAM'
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>sd-login</title>
|
|
<productname>systemd</productname>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>Developer</contrib>
|
|
<firstname>Lennart</firstname>
|
|
<surname>Poettering</surname>
|
|
<email>lennart@poettering.net</email>
|
|
</author>
|
|
</authorgroup>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>sd-login</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>sd-login</refname>
|
|
<refpurpose>APIs for
|
|
tracking logins</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
|
|
</funcsynopsis>
|
|
|
|
<cmdsynopsis>
|
|
<command>pkg-config --cflags --libs libsystemd</command>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para><filename>sd-login.h</filename> provides APIs to introspect
|
|
and monitor seat, login session and user status information on the
|
|
local system. </para>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>These functions synchronously access data in
|
|
<filename>/proc</filename>, <filename>/sys/fs/cgroup</filename>
|
|
and <filename>/run</filename>. All of these are virtual file
|
|
systems, hence the runtime cost of the accesses is relatively
|
|
cheap.</para>
|
|
|
|
<para>It is possible (and often a very good choice) to mix calls
|
|
to the synchronous interface of <filename>sd-login.h</filename>
|
|
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
|
|
<filename>sd-login.h</filename> interfaces such as the login
|
|
monitor are asynchronous and not ordered against each
|
|
other.</para>
|
|
|
|
<para>If the functions return string arrays, these are generally
|
|
<constant>NULL</constant> terminated and need to be freed by the
|
|
caller with the libc
|
|
<citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
call after use, including the strings referenced therein.
|
|
Similarly, individual strings returned need to be freed, as
|
|
well.</para>
|
|
|
|
<para>As a special exception, instead of an empty string array
|
|
<constant>NULL</constant> may be returned, which should be treated
|
|
equivalent to an empty string array.</para>
|
|
|
|
<para>See
|
|
<citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
for more information about the functions
|
|
implemented.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Definition of Terms</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>seat</term>
|
|
|
|
<listitem><para>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 <literal>seat</literal> followed by at least one
|
|
character from the range [a-zA-Z0-9], <literal>_</literal> and
|
|
<literal>-</literal>. 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.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>session</term>
|
|
|
|
<listitem><para>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.</para>
|
|
|
|
<para>
|
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
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],
|
|
<literal>_</literal> and <literal>-</literal>, 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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>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 <literal>seat0</literal>.</para>
|
|
|
|
<para>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.)</para>
|
|
|
|
<para><literal>seat0</literal> always exists.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>udev Rules</title>
|
|
|
|
<para>Assignment of hardware devices to seats is managed inside the udev database, via
|
|
settings on the devices:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Tag <literal>seat</literal></term>
|
|
|
|
<listitem><para>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).
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Tag <literal>master-of-seat</literal></term>
|
|
|
|
<listitem><para>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
|
|
<literal>seat</literal> tag, but (at least) one of these devices needs to be
|
|
tagged with <literal>master-of-seat</literal> before the seat is actually
|
|
considered to be around.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Property <varname>ID_SEAT</varname></term>
|
|
|
|
<listitem><para>This property specifies the name of the seat a specific device is
|
|
assigned to. If not set the device is assigned to <literal>seat0</literal>. 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
|
|
<varname>ID_SEAT=seat-waldo</varname> is set for a device, the tag
|
|
<literal>seat-waldo</literal> will be set as well. Note that if a device is
|
|
assigned to <literal>seat0</literal>, it will usually not carry such a tag and you
|
|
need to enumerate all devices and check the <varname>ID_SEAT</varname> property
|
|
manually. Again, if a device is assigned to seat0 this is visible on the device in
|
|
two ways: with a property <varname>ID_SEAT=seat0</varname> and with no property
|
|
<varname>ID_SEAT</varname> set for it at all.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Property <varname>ID_AUTOSEAT</varname></term>
|
|
|
|
<listitem><para>When set to <literal>1</literal>, 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.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Property <varname>ID_FOR_SEAT</varname></term>
|
|
|
|
<listitem><para>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
|
|
<literal>seat-</literal> and use it as name for the seat.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>A seat exists only and exclusively because a properly tagged device with the
|
|
right <varname>ID_SEAT</varname> property exists. Besides udev rules there is no
|
|
persistent data about seats stored on disk.</para>
|
|
|
|
<para>Note that
|
|
<citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
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.</para>
|
|
</refsect1>
|
|
|
|
<xi:include href="libsystemd-pkgconfig.xml" />
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
</para>
|
|
|
|
<para>
|
|
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat on Linux</ulink>
|
|
for an introduction to multi-seat support on Linux and the background for this set of APIs.
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|