dasharo/systemd
0
0
Fork 0
mirror of https://github.com/Dasharo/systemd.git synced 2026-03-06 15:02:31 -08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #6855 from keszybz/more-docs

Browse Source 
More docs
This commit is contained in:
Lennart Poettering
2017-09-19 10:38:40 +02:00
committed by GitHub
parent 22043e4317 f8f1e666a6
commit c9f7fb0f3c
3 changed files with 160 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

150
man/sd-login.xml
View File

@@ -66,11 +66,6 @@
and monitor seat, login session and user status information on the
local system. </para>
<para>See <ulink
url="https://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat
on Linux</ulink> for an introduction into multi-seat support on
Linux, the background for this set of APIs.</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
@@ -115,6 +110,146 @@
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 (&lt;= 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>
@@ -130,6 +265,11 @@
<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>

18
man/sd_bus_default.xml
View File

@@ -165,13 +165,17 @@
not set, a suitable default for the default system D-Bus instance
will be used.</para>
<para><function>sd_bus_open_system_remote()</function> connects to
the system bus on the specified <parameter>host</parameter> using
<citerefentry
project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>. <parameter>host</parameter>
consists of an optional user name followed by the
<literal>@</literal> symbol, and the hostname.
</para>
<para><function>sd_bus_open_system_remote()</function> connects to the system bus on
the specified host using
<citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
<parameter>host</parameter> consists of an optional user name followed by the
<literal>@</literal> symbol, and the hostname, optionally followed by a
<literal>:</literal> and a machine name. If the machine name is given, a connection
is created to the system bus in the specified container on the remote machine, and
otherwise a connection to the system bus on the specified host is created.</para>
<para>Note that entering a container is a privileged operation, and will likely only
work for the root user on the remote machine.</para>
<para><function>sd_bus_open_system_machine()</function> connects
to the system bus in the specified <parameter>machine</parameter>,

8
man/systemd-logind.service.xml
View File

@@ -63,13 +63,13 @@
<listitem><para>Keeping track of users and sessions, their processes and their idle state. This is implemented by
allocating a systemd slice unit for each user below <filename>user.slice</filename>, and a scope unit below it
for each concurrent session of a user. Also, a per-user service manager is started as system service instance of
<filename>user@.service</filename> for each user logged in.</para></listitem>
<filename>user@.service</filename> for each logged in user.</para></listitem>
<listitem><para>Generating and managing session IDs. If auditing is available and an audit session ID is set for
a session already, the session ID is initialized from it. Otherwise, an independent session counter is
<listitem><para>Generating and managing session IDs. If auditing is available and an audit session ID is already set for
a session, then this ID is reused as the session ID. Otherwise, an independent session counter is
used.</para></listitem>
<listitem><para>Providing PolicyKit-based access for users to
<listitem><para>Providing PolicyKit-based access for users for
operations such as system shutdown or sleep</para></listitem>
<listitem><para>Implementing a shutdown/sleep inhibition logic