mirror of
https://github.com/systemd/systemd
synced 2024-09-06 16:56:43 +00:00
983 lines
52 KiB
XML
983 lines
52 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
|
|
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
|
|
|
|
<refentry id="org.freedesktop.login1" conditional='ENABLE_LOGIND'
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<refentryinfo>
|
|
<title>org.freedesktop.login1</title>
|
|
<productname>systemd</productname>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>org.freedesktop.login1</refentrytitle>
|
|
<manvolnum>5</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>org.freedesktop.login1</refname>
|
|
<refpurpose>The D-Bus interface of systemd-logind</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1>
|
|
<title>Introduction</title>
|
|
|
|
<para><citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
is a system service that keeps track of user logins and seats in various ways.</para>
|
|
|
|
<para>The daemon provides both a C library interface as well as a D-Bus interface. The library interface
|
|
may be used to introspect and watch the state of user logins and seats. The bus interface provides the
|
|
same, but in addition may also be used to make changes to system state. For more information please
|
|
consult <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>The Manager Object</title>
|
|
|
|
<para>The service exposes the following interfaces on the Manager object on the bus:</para>
|
|
|
|
<programlisting>
|
|
$ gdbus introspect --system \
|
|
--dest org.freedesktop.login1 \
|
|
--object-path /org/freedesktop/login1
|
|
|
|
node /org/freedesktop/login1 {
|
|
interface org.freedesktop.login1.Manager {
|
|
methods:
|
|
GetSession(in s session_id,
|
|
out o object_path);
|
|
GetSessionByPID(in u pid,
|
|
out o object_path);
|
|
GetUser(in u uid,
|
|
out o object_path);
|
|
GetUserByPID(in u pid,
|
|
out o object_path);
|
|
GetSeat(in s seat_id,
|
|
out o object_path);
|
|
ListSessions(out a(susso) sessions);
|
|
ListUsers(out a(uso) users);
|
|
ListSeats(out a(so) seats);
|
|
ListInhibitors(out a(ssssuu) inhibitors);
|
|
CreateSession(in u uid,
|
|
in u pid,
|
|
in s service,
|
|
in s type,
|
|
in s class,
|
|
in s desktop,
|
|
in s seat_id,
|
|
in u vtnr,
|
|
in s tty,
|
|
in s display,
|
|
in b remote,
|
|
in s remote_user,
|
|
in s remote_host,
|
|
in a(sv) properties,
|
|
out s session_id,
|
|
out o object_path,
|
|
out s runtime_path,
|
|
out h fifo_fd,
|
|
out u uid,
|
|
out s seat_id,
|
|
out u vtnr,
|
|
out b existing);
|
|
ReleaseSession(in s session_id);
|
|
ActivateSession(in s session_id);
|
|
ActivateSessionOnSeat(in s session_id,
|
|
in s seat_id);
|
|
LockSession(in s session_id);
|
|
UnlockSession(in s session_id);
|
|
LockSessions();
|
|
UnlockSessions();
|
|
KillSession(in s session_id,
|
|
in s who,
|
|
in i signal_number);
|
|
KillUser(in u uid,
|
|
in i signal_number);
|
|
TerminateSession(in s session_id);
|
|
TerminateUser(in u uid);
|
|
TerminateSeat(in s seat_id);
|
|
SetUserLinger(in u uid,
|
|
in b enable,
|
|
in b interactive);
|
|
AttachDevice(in s seat_id,
|
|
in s sysfs_path,
|
|
in b interactive);
|
|
FlushDevices(in b interactive);
|
|
PowerOff(in b interactive);
|
|
Reboot(in b interactive);
|
|
Halt(in b interactive);
|
|
Suspend(in b interactive);
|
|
Hibernate(in b interactive);
|
|
HybridSleep(in b interactive);
|
|
SuspendThenHibernate(in b interactive);
|
|
CanPowerOff(out s result);
|
|
CanReboot(out s result);
|
|
CanHalt(out s result);
|
|
CanSuspend(out s result);
|
|
CanHibernate(out s result);
|
|
CanHybridSleep(out s result);
|
|
CanSuspendThenHibernate(out s result);
|
|
ScheduleShutdown(in s type,
|
|
in t usec);
|
|
CancelScheduledShutdown(out b cancelled);
|
|
Inhibit(in s what,
|
|
in s who,
|
|
in s why,
|
|
in s mode,
|
|
out h pipe_fd);
|
|
CanRebootParameter(out s result);
|
|
SetRebootParameter(in s parameter);
|
|
CanRebootToFirmwareSetup(out s result);
|
|
SetRebootToFirmwareSetup(in b enable);
|
|
CanRebootToBootLoaderMenu(out s result);
|
|
SetRebootToBootLoaderMenu(in t timeout);
|
|
CanRebootToBootLoaderEntry(out s result);
|
|
SetRebootToBootLoaderEntry(in s boot_loader_entry);
|
|
SetWallMessage(in s wall_message,
|
|
in b enable);
|
|
signals:
|
|
SessionNew(s session_id,
|
|
o object_path);
|
|
SessionRemoved(s session_id,
|
|
o object_path);
|
|
UserNew(u uid,
|
|
o object_path);
|
|
UserRemoved(u uid,
|
|
o object_path);
|
|
SeatNew(s seat_id,
|
|
o object_path);
|
|
SeatRemoved(s seat_id,
|
|
o object_path);
|
|
PrepareForShutdown(b start);
|
|
PrepareForSleep(b start);
|
|
properties:
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
@org.freedesktop.systemd1.Privileged("true")
|
|
readwrite b EnableWallMessages = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
@org.freedesktop.systemd1.Privileged("true")
|
|
readwrite s WallMessage = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly u NAutoVTs = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly as KillOnlyUsers = ['...', ...];
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly as KillExcludeUsers = ['...', ...];
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly b KillUserProcesses = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly s RebootParameter = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly b RebootToFirmwareSetup = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly t RebootToBootLoaderMenu = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly s RebootToBootLoaderEntry = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly as BootLoaderEntries = ['...', ...];
|
|
readonly b IdleHint = ...;
|
|
readonly t IdleSinceHint = ...;
|
|
readonly t IdleSinceHintMonotonic = ...;
|
|
readonly s BlockInhibited = '...';
|
|
readonly s DelayInhibited = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly t InhibitDelayMaxUSec = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly t UserStopDelayUSec = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s HandlePowerKey = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s HandleSuspendKey = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s HandleHibernateKey = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s HandleLidSwitch = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s HandleLidSwitchExternalPower = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s HandleLidSwitchDocked = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly t HoldoffTimeoutUSec = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s IdleAction = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly t IdleActionUSec = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly b PreparingForShutdown = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly b PreparingForSleep = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly (st) ScheduledShutdown = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly b Docked = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly b LidClosed = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly b OnExternalPower = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly b RemoveIPC = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly t RuntimeDirectorySize = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly t InhibitorsMax = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly t NCurrentInhibitors = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly t SessionsMax = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly t NCurrentSessions = ...;
|
|
};
|
|
interface org.freedesktop.DBus.Peer { ... };
|
|
interface org.freedesktop.DBus.Introspectable { ... };
|
|
interface org.freedesktop.DBus.Properties { ... };
|
|
};
|
|
</programlisting>
|
|
|
|
<refsect2>
|
|
<title>Methods</title>
|
|
|
|
<para><function>GetSession()</function> may be used to get the session object path for the session with
|
|
the specified ID. Similarly, <function>GetUser()</function> and <function>GetSeat()</function> get the
|
|
user and seat objects, respectively. <function>GetSessionByPID()</function> and
|
|
<function>GetUserByPID()</function> get the session/user object the specified PID belongs to if there
|
|
is any.</para>
|
|
|
|
<para><function>ListSessions()</function> returns an array with all current sessions. The structures in
|
|
the array consist of the following fields: session id, user id, user name, seat id, session object
|
|
path. If a session does not have a seat attached the seat id field will be an empty string.</para>
|
|
|
|
<para><function>ListUsers()</function> returns an array with all currently logged in users. The
|
|
structures in the array consist of the following fields: user id, user name, user object path.</para>
|
|
|
|
<para><function>ListSeats()</function> returns an array with all currently available seats. The
|
|
structure in the array consists of the following fields: seat id, seat object path.</para>
|
|
|
|
<para><function>ListInhibitors()</function> lists all currently active inhibitors. Returns an array of
|
|
structures consisting of <varname>what</varname>, <varname>who</varname>, <varname>why</varname>,
|
|
<varname>mode</varname>, user ID <varname>uid</varname>, and process ID <varname>pid</varname>.</para>
|
|
|
|
<para><function>CreateSession()</function> and <function>ReleaseSession()</function> may be used to
|
|
open or close login sessions. These calls should <emphasis>never</emphasis> be invoked directly by
|
|
clients. Creating/closing sessions is exclusively the job of PAM and its
|
|
<citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
module.</para>
|
|
|
|
<para><function>ActivateSession()</function> brings the session with the specified ID into the
|
|
foreground. <function>ActivateSessionOnSeat()</function> does the same, but only if the seat id
|
|
matches.</para>
|
|
|
|
<para><function>LockSession()</function> asks the session with the specified ID to activate the screen
|
|
lock. <function>UnlockSession()</function> asks the session with the specified ID to remove an active
|
|
screen lock, if there is any. This is implemented by sending out the Lock() and Unlock() signals from
|
|
the respective session object which session managers are supposed to listen on.</para>
|
|
|
|
<para><function>LockSessions()</function> asks all sessions to activate the screen locks. This may be
|
|
used to lock any access to the machine in one action. Similarly, <function>UnlockSessions()</function>
|
|
asks all sessions to deactivate their screen locks.</para>
|
|
|
|
<para><function>KillSession()</function> may be used to send a Unix signal to one or all processes of a
|
|
session. As arguments it takes the session id, either the string <literal>leader</literal> or
|
|
<literal>all</literal> and a signal number. If <literal>leader</literal> is passed only the session
|
|
<literal>leader</literal> is killed. If <literal>all</literal> is passed all processes of the session
|
|
are killed.</para>
|
|
|
|
<para><function>KillUser()</function> may be used to send a Unix signal to all processes of a user. As
|
|
argument it takes the user id and a signal number.</para>
|
|
|
|
<para><function>TerminateSession()</function>, <function>TerminateUser()</function>,
|
|
<function>TerminateSeat()</function> may be used to forcibly terminate one specific session, all
|
|
processes of a user, and all sessions attached to a specific seat, respectively. The session, user,
|
|
and seat are identified by their respective IDs.</para>
|
|
|
|
<para><function>SetUserLinger()</function> enables or disables user lingering. If enabled the runtime
|
|
directory of a user is kept around and he may continue to run processes while he is logged out. If
|
|
disabled the runtime directory goes away as soon as he logs out. Expects three arguments: the UID, a
|
|
boolean whether to enable/disable and a boolean controlling the PolicyKit authorization interactivity
|
|
(see above). Note that the user linger state is persistently stored on disk.</para>
|
|
|
|
<para><function>AttachDevice()</function> may be used to assign a specific device to a specific
|
|
seat. The device is identified by its /sys path, and must be eligible for seat assignments. Takes three
|
|
arguments: the seat id, the sysfs path, and a boolean for controlling PolicyKit interactivity (see
|
|
above). Device assignments are persistently stored to disk. To create a new seat, simply specify a
|
|
previously unused seat id. For more information about the seat assignment logic see
|
|
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat for Linux</ulink>.
|
|
</para>
|
|
|
|
<para><function>FlushDevices()</function> removes all explicit seat assignments for devices, resetting
|
|
all assignments to the automatic defaults. The only argument this takes is the PolicyKit interactivity
|
|
boolean (see above).</para>
|
|
|
|
<para><function>PowerOff()</function>, <function>Reboot()</function>, <function>Halt()</function>,
|
|
<function>Suspend()</function>, <function>Hibernate()</function> result in the system being powered
|
|
off, rebooted, halted (shut down without turning off power), suspended (the store of the system is
|
|
saved to RAM and the CPU is turned off), or hibernated (the store of the system is saved to disk and
|
|
the machine is powered down). <function>HybridSleep()</function> results in the system entering a
|
|
hybrid-sleep mode, i.e. the system is both hibernated and suspended.
|
|
<function>SuspendThenHibernate()</function> results in the system being suspended, then later woken
|
|
using an RTC timer, and hibernated. The only argument is the PolicyKit interactivity boolean
|
|
<varname>interactive</varname> (see above). The main purpose of these calls is that they enforce
|
|
PolicyKit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged
|
|
users. They also enforce inhibition locks. UIs should expose these calls as primary mechanism to
|
|
poweroff/reboot/suspend/hibernate the machine.</para>
|
|
|
|
<para><function>SetRebootParameter()</function> sets the parameter for the subsequent reboot operation.
|
|
See the description of <command>reboot</command> in
|
|
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
|
|
<citerefentry project="man-pages"><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
|
|
for more information.</para>
|
|
|
|
<para><function>SetRebootToFirmwareSetup()</function>,
|
|
<function>SetRebootToBootLoaderMenu()</function>, and <function>SetRebootToBootLoaderEntry()</function>
|
|
configure the action to be taken from the boot loader after a reboot: respectively entering firmware
|
|
setup mode, or the boot loader menu, or a specific boot loader entry. See
|
|
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for the
|
|
command line interface.</para>
|
|
|
|
<para><function>CanPowerOff()</function>, <function>CanReboot()</function>,
|
|
<function>CanHalt()</function>, <function>CanSuspend()</function>, <function>CanHibernate()</function>,
|
|
<function>CanHybridSleep()</function>, <function>CanSuspendThenHibernate()</function>,
|
|
<function>CanRebootParameter()</function>, <function>CanRebootToFirmwareSetup()</function>,
|
|
<function>CanRebootToBootLoaderMenu()</function>, and
|
|
<function>CanRebootToBootLoaderEntry()</function>, test whether the system supports the respective
|
|
operation and whether the calling user is allowed to request it. Returns one of <literal>na</literal>,
|
|
<literal>yes</literal>, <literal>no</literal>, and <literal>challenge</literal>. If
|
|
<literal>na</literal> is returned, the operation is not available because hardware, kernel, or drivers
|
|
do not support it. If <literal>yes</literal> is returned, the operation is supported and the user may
|
|
execute the operation without further authentication. If <literal>no</literal> is returned the
|
|
operation is available but the user is not allowed to execute the operation. If
|
|
<literal>challenge</literal> is returned the operation is available, but only after
|
|
authorization.</para>
|
|
|
|
<para><function>ScheduleShutdown()</function> schedules a shutdown operation <varname>type</varname> at
|
|
time <varname>usec</varname> in microseconds since the UNIX epoch. <varname>type</varname> can be one
|
|
of <literal>poweroff</literal>, <literal>dry-poweroff</literal>, <literal>reboot</literal>,
|
|
<literal>dry-reboot</literal>, <literal>halt</literal>, and <literal>dry-halt</literal>. (The
|
|
<literal>dry-</literal> variants do not actually execute the shutdown action.)
|
|
<function>CancelScheduledShutdown()</function> cancels a scheduled shutdown. The output parameter
|
|
<varname>cancelled</varname> is true if a shutdown operation was scheduled.</para>
|
|
|
|
<para><function>SetWallMessage()</function> sets the wall message (the message that will be sent out to
|
|
all terminals and stored in an
|
|
<citerefentry><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry> record) for a
|
|
subsequent scheduled shutdown operation. The parameter <varname>wall_message</varname> specifies the
|
|
shutdown reason (and may be empty) which will be included in the shutdown message. The parameter
|
|
<varname>enable</varname> specifies whether to print a wall message on shutdown.</para>
|
|
|
|
<para><function>Inhibit()</function> creates an inhibition lock. It takes four parameters:
|
|
<varname>what</varname>, <varname>who</varname>, <varname>why</varname>, and
|
|
<varname>mode</varname>. <varname>what</varname> is one or more of <literal>shutdown</literal>,
|
|
<literal>sleep</literal>, <literal>idle</literal>, <literal>handle-power-key</literal>,
|
|
<literal>handle-suspend-key</literal>, <literal>handle-hibernate-key</literal>,
|
|
<literal>handle-lid-switch</literal>, separated by colons, for inhibiting poweroff/reboot,
|
|
suspend/hibernate, the automatic idle logic, or hardware key handling. <varname>who</varname> should be
|
|
a short human readable string identifying the application taking the lock. <varname>why</varname>
|
|
should be a short human readable string identifying the reason why the lock is taken. Finally,
|
|
<varname>mode</varname> is either <literal>block</literal> or <literal>delay</literal> which encodes
|
|
whether the inhibit shall be consider mandatory or whether it should just delay the operation to a
|
|
certain maximum time. The call returns a file descriptor. The lock is released the moment this file
|
|
descriptor (and all its duplicates) are closed. For more information on the inhibition logic see
|
|
<ulink url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks</ulink>.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Signals</title>
|
|
|
|
<para>Whenever the inhibition state or idle hint changes daemon <function>PropertyChanged</function>
|
|
signals are sent out to which clients can subscribe.</para>
|
|
|
|
<para>The <function>SessionNew</function>, <function>SessionRemoved</function>,
|
|
<function>UserNew</function>, <function>UserRemoved</function>, <function>SeatNew</function>,
|
|
<function>SeatRemoved</function> signals are sent each time a session is created or removed, a user
|
|
logs in or out, or a seat is added or removed. They each contain the ID of the object plus the object
|
|
path.</para>
|
|
|
|
<para>The <function>PrepareForShutdown()</function> and <function>PrepareForSleep()</function> signals
|
|
are sent right before (with the argument <literal>true</literal>) and after (with the argument
|
|
<literal>false</literal>) the system goes down for reboot/poweroff and suspend/hibernate,
|
|
respetively. This may be used by applications to save data on disk, release memory, or do other jobs
|
|
that shall be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks. After
|
|
completion of this work they should release their inhibition locks in order not to delay the operation
|
|
any further. For more information see
|
|
<ulink url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks</ulink>.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Properties</title>
|
|
|
|
<para>Most properties simply reflect the configuration, see
|
|
<citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
|
|
includes: <varname>NAutoVTs</varname>, <varname>KillOnlyUsers</varname>,
|
|
<varname>KillExcludeUsers</varname>, <varname>KillUserProcesses</varname>, <varname>IdleAction</varname>,
|
|
<varname>InhibitDelayMaxUSec</varname>,
|
|
<varname>InhibitorsMax</varname>,
|
|
<varname>UserStopDelayUSec</varname>,
|
|
<varname>HandlePowerKey</varname>, <varname>HandleSuspendKey</varname>,
|
|
<varname>HandleHibernateKey</varname>, <varname>HandleLidSwitch</varname>,
|
|
<varname>HandleLidSwitchExternalPower</varname>, <varname>HandleLidSwitchDocked</varname>,
|
|
<varname>IdleActionUSec</varname>, <varname>HoldoffTimeoutUSec</varname>,
|
|
<varname>RemoveIPC</varname>, <varname>RuntimeDirectorySize</varname>,
|
|
<varname>InhibitorsMax</varname>, and <varname>SessionsMax</varname>.
|
|
</para>
|
|
|
|
<para>The <varname>IdleHint</varname> property reflects the idle hint state of the system. If the
|
|
system is idle it might get into automatic suspend or shutdown, depending on configuration.</para>
|
|
|
|
<para><varname>IdleSinceHint</varname> and <varname>IdleSinceHintMonotonic</varname> encode the
|
|
timestamps of the last change of the idle hint boolean, in <constant>CLOCK_REALTIME</constant> and
|
|
<constant>CLOCK_MONOTONIC</constant> timestamps, respectively, in microseconds since the epoch.</para>
|
|
|
|
<para>The <varname>BlockInhibited</varname> and <varname>DelayInhibited</varname> properties encode
|
|
the currently active locks of the respective modes. They are colon separated lists of
|
|
<literal>shutdown</literal>, <literal>sleep</literal>, <literal>idle</literal> (see above).</para>
|
|
|
|
<para><varname>NCurrentSessions</varname> and <varname>NCurrentInhibitors</varname> contain the number
|
|
of currently registered sessions and inhibitors.</para>
|
|
|
|
<para>The <varname>BootLoaderEntries</varname> property contains a list of boot loader entries.
|
|
This includes boot loader entries defined in configuration, and any additional loader entries
|
|
reported by the boot loader. See
|
|
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
|
for more information.</para>
|
|
|
|
<para>The <varname>PreparingForShutdown</varname> and <varname>PreparingForSleep</varname> boolean
|
|
properties are true between the time when the two <function>PrepareForShutdown</function> and
|
|
<function>PrepareForSleep</function> signals are sent, respectively. Note that these properties do not
|
|
send out <function>PropertyChanged</function> signals.</para>
|
|
|
|
<para>The <varname>RebootParameter</varname> property shows the value set with
|
|
<function>SetRebootParameter()</function> method described above.</para>
|
|
|
|
<para>The <varname>ScheduledShutdown</varname> shows the value pair set with
|
|
<function>ScheduleShutdown()</function> method described above.</para>
|
|
|
|
<para><varname>RebootToFirmwareSetup</varname>, <varname>RebootToBootLoaderMenu</varname>, and
|
|
<varname>RebootToBootLoaderEntry</varname> are true when the resprective post-reboot operation was
|
|
selected with <function>SetRebootToFirmwareSetup</function>,
|
|
<function>SetRebootToBootLoaderMenu</function>, or
|
|
<function>SetRebootToBootLoaderEntry</function>.</para>
|
|
|
|
<para><varname>WallMessage</varname> and <varname>EnableWallMessages</varname> properties reflect the
|
|
shutdown reasoson and wall message enablement switch which can be set with
|
|
<varname>SetWallMessage()</varname> method described above.</para>
|
|
|
|
<para><varname>Docked</varname> is true if the machine is connected to dock.
|
|
<varname>LidClosed</varname> is true when the lid (of a laptop) is closed.
|
|
<varname>OnExternalPower</varname> is true when the machine is connected to an external power supply.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Security</title>
|
|
|
|
<para>A number of operations are protected via the PolicyKit privilege
|
|
system. <function>SetUserLinger()</function> requires the
|
|
<interfacename>org.freedesktop.login1.set-user-linger</interfacename>
|
|
privilege. <function>AttachDevice()</function> requires
|
|
<interfacename>org.freedesktop.login1.attach-device</interfacename> and
|
|
<function>FlushDevices()</function>
|
|
<interfacename>org.freedesktop.login1.flush-devices</interfacename>. <function>PowerOff()</function>,
|
|
<function>Reboot()</function>, <function>Halt()</function>, <function>Suspend()</function>,
|
|
<function>Hibernate()</function> require
|
|
<interfacename>org.freedesktop.login1.power-off</interfacename>,
|
|
<interfacename>org.freedesktop.login1.power-off-multiple-sessions</interfacename>,
|
|
<interfacename>org.freedesktop.login1.power-off-ignore-inhibit</interfacename>,
|
|
<interfacename>org.freedesktop.login1.reboot</interfacename>,
|
|
<interfacename>org.freedesktop.login1.reboot-multiple-sessions</interfacename>,
|
|
<interfacename>org.freedesktop.login1.reboot-ignore-inhibit</interfacename>,
|
|
<interfacename>org.freedesktop.login1.halt</interfacename>,
|
|
<interfacename>org.freedesktop.login1.halt-multiple-sessions</interfacename>,
|
|
<interfacename>org.freedesktop.login1.halt-ignore-inhibit</interfacename>,
|
|
<interfacename>org.freedesktop.login1.suspend</interfacename>,
|
|
<interfacename>org.freedesktop.login1.suspend-multiple-sessions</interfacename>,
|
|
<interfacename>org.freedesktop.login1.suspend-ignore-inhibit</interfacename>,
|
|
<interfacename>org.freedesktop.login1.hibernate</interfacename>,
|
|
<interfacename>org.freedesktop.login1.hibernate-multiple-sessions</interfacename>,
|
|
<interfacename>org.freedesktop.login1.hibernate-ignore-inhibit</interfacename>,
|
|
respectively, depending on whether there are other sessions around or active inhibits.
|
|
<function>HybridSleep()</function> and <function>SuspendThenHibernate()</function>
|
|
use the same privileges as <function>Hibernate()</function>.
|
|
<function>SetRebootParameter()</function> requires
|
|
<interfacename>org.freedesktop.login1.set-reboot-parameter</interfacename>.</para>
|
|
|
|
<para><function>SetRebootToFirmwareSetup</function> requires
|
|
<interfacename>org.freedesktop.login1.set-reboot-to-firmware-setup</interfacename>.
|
|
<function>SetRebootToBootLoaderMenu</function> requires
|
|
<interfacename>org.freedesktop.login1.set-reboot-to-boot-loader-menu</interfacename>.
|
|
<function>SetRebootToBootLoaderEntry</function> requires
|
|
<interfacename>org.freedesktop.login1.set-reboot-to-boot-loader-entry</interfacename>.
|
|
</para>
|
|
|
|
<para><function>ScheduleShutdown</function> and <function>CancelScheduledShutdown</function> require
|
|
the same privileges (listed above) as the immediate poweroff/reboot/halt operations.</para>
|
|
|
|
<para><function>Inhibit()</function> is protected via either one of
|
|
<interfacename>org.freedesktop.login1.inhibit-block-shutdown</interfacename>,
|
|
<interfacename>org.freedesktop.login1.inhibit-delay-shutdown</interfacename>,
|
|
<interfacename>org.freedesktop.login1.inhibit-block-sleep</interfacename>,
|
|
<interfacename>org.freedesktop.login1.inhibit-delay-sleep</interfacename>,
|
|
<interfacename>org.freedesktop.login1.inhibit-block-idle</interfacename>,
|
|
<interfacename>org.freedesktop.login1.inhibit-handle-power-key</interfacename>,
|
|
<interfacename>org.freedesktop.login1.inhibit-handle-suspend-key</interfacename>,
|
|
<interfacename>org.freedesktop.login1.inhibit-handle-hibernate-key</interfacename>,
|
|
<interfacename>org.freedesktop.login1.inhibit-handle-lid-switch</interfacename> depending on the lock
|
|
type and mode taken.</para>
|
|
|
|
<para>The <varname>interactive</varname> boolean parameters can be used to control whether PolicyKit
|
|
should interactively ask the user for authentication credentials if it needs to.</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Seat Objects</title>
|
|
|
|
<programlisting>
|
|
$ gdbus introspect --system --dest org.freedesktop.login1 \
|
|
--object-path /org/freedesktop/login1/seat/seat0
|
|
|
|
node /org/freedesktop/login1/seat/seat0 {
|
|
interface org.freedesktop.login1.Seat {
|
|
methods:
|
|
Terminate();
|
|
ActivateSession(in s session_id);
|
|
SwitchTo(in u vtnr);
|
|
SwitchToNext();
|
|
SwitchToPrevious();
|
|
properties:
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s Id = '...';
|
|
readonly (so) ActiveSession = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly b CanMultiSession = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly b CanTTY = ...;
|
|
readonly b CanGraphical = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly a(so) Sessions = [...];
|
|
readonly b IdleHint = ...;
|
|
readonly t IdleSinceHint = ...;
|
|
readonly t IdleSinceHintMonotonic = ...;
|
|
};
|
|
interface org.freedesktop.DBus.Peer { ... };
|
|
interface org.freedesktop.DBus.Introspectable { ... };
|
|
interface org.freedesktop.DBus.Properties { ... };
|
|
};
|
|
</programlisting>
|
|
|
|
<refsect2>
|
|
<title>Methods</title>
|
|
|
|
<para><function>Terminate()</function> and <function>ActivateSession()</function> work similar to
|
|
TerminateSeat(), ActivationSessionOnSeat() on the Manager object.</para>
|
|
|
|
<para><function>SwitchTo()</function> switches to the session on the virtual terminal
|
|
<varname>vtnr</varname>. <function>SwitchToNext()</function> and
|
|
<function>SwitchToPrevious()</function> switch to, respectively, the next and previous sessions on the
|
|
seat in the order of virtual terminals. If there is no active session, they switch to, respectively,
|
|
the first and last session on the seat.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Signals</title>
|
|
|
|
<para>Whenever <function>ActiveSession</function>, <function>Sessions</function>,
|
|
<function>CanGraphical</function>, <function>CanMultiSession</function> and <function>CanTTY</function>
|
|
or the idle state changes <function>PropertyChanged</function> signals are sent out to which clients
|
|
can subscribe.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Properties</title>
|
|
|
|
<para>The <varname>Id</varname> property encodes the ID of the seat.</para>
|
|
|
|
<para><varname>ActiveSession</varname> encodes the currently active session if there is one. It is a
|
|
structure consisting of session id and object path.</para>
|
|
|
|
<para><varname>CanMultiSession</varname> encodes whether the session is multi-session capable,
|
|
<varname>CanTTY</varname> whether it is suitable for text logins, <varname>CanGraphical</varname>
|
|
whether it is suitable for graphical sessions.</para>
|
|
|
|
<para>The <varname>Sessions</varname> property is an array of all current sessions of this seat, each
|
|
encoded in a structure consisting of the ID and the object path.</para>
|
|
|
|
<para>The <varname>IdleHint</varname>, <varname>IdleSinceHint</varname>,
|
|
<varname>IdleSinceHint</varname> properties encode the idle state, similar to the one exposed on the
|
|
Manager object, but specific for this seat.</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>User Objects</title>
|
|
|
|
<programlisting>
|
|
$ gdbus introspect --system --dest org.freedesktop.login1 \
|
|
--object-path /org/freedesktop/login1/user/_1000
|
|
|
|
node /org/freedesktop/login1/user/_1000 {
|
|
interface org.freedesktop.login1.User {
|
|
methods:
|
|
Terminate();
|
|
Kill(in i signal_number);
|
|
properties:
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly u UID = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly u GID = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s Name = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly t Timestamp = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly t TimestampMonotonic = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s RuntimePath = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s Service = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s Slice = '...';
|
|
readonly (so) Display = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly s State = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly a(so) Sessions = [...];
|
|
readonly b IdleHint = ...;
|
|
readonly t IdleSinceHint = ...;
|
|
readonly t IdleSinceHintMonotonic = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
|
|
readonly b Linger = ...;
|
|
};
|
|
interface org.freedesktop.DBus.Peer { ... };
|
|
interface org.freedesktop.DBus.Introspectable { ... };
|
|
interface org.freedesktop.DBus.Properties { ... };
|
|
};
|
|
</programlisting>
|
|
|
|
<refsect2>
|
|
<title>Methods</title>
|
|
|
|
<para><function>Terminate()</function> and <function>Kill()</function> work similar to the
|
|
<function>TerminateUser()</function> and <function>KillUser()</function> calls on the manager
|
|
object.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Signals</title>
|
|
|
|
<para>Whenever <varname>Sessions</varname> or the idle state changes
|
|
<function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Properties</title>
|
|
|
|
<para>The <varname>UID</varname> and <varname>GID</varname> properties encode the Unix UID and primary
|
|
GID of the user.</para>
|
|
|
|
<para>The <varname>Name</varname> property encodes the user name.</para>
|
|
|
|
<para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> encode the login time of
|
|
the user in usec since the epoch, in the <constant>CLOCK_REALTIME</constant> and
|
|
<constant>CLOCK_MONOTONIC</constant> clocks, respectively.</para>
|
|
|
|
<para><varname>RuntimePath</varname> encodes the runtime path of the user,
|
|
i.e. <varname>$XDG_RUNTIME_DIR</varname>, for details see the
|
|
<ulink url="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">
|
|
XDG Basedir Specification
|
|
</ulink>.</para>
|
|
|
|
<para><varname>Service</varname> contains the name of the user systemd service unit name of this
|
|
user. Each logged in user gets a user service unit assigned that runs a user systemd instance. This is
|
|
usually an instance of <filename>user@.service</filename>.</para>
|
|
|
|
<para><varname>Slice</varname> contains the name of the user systemd slice unit name of this user. Each
|
|
logged in user gets a private slice.</para>
|
|
|
|
<para><varname>Display</varname> encodes which graphical session should be used as primary UI display
|
|
for the use. It is a structure encoding session ID and object path of the session to use.</para>
|
|
|
|
<para><varname>State</varname> encodes the user state, one of <literal>offline</literal>,
|
|
<literal>lingering</literal>, <literal>online</literal>, <literal>active</literal>,
|
|
<literal>closing</literal>. See
|
|
<citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
for more information about the states.</para>
|
|
|
|
<para><varname>Sessions</varname> is an array of structures encoding all current sessions of the
|
|
user. Each structure consists of ID and object path.</para>
|
|
|
|
<para>The <varname>IdleHint</varname>, <varname>IdleSinceHint</varname>,
|
|
<varname>IdleSinceHintMonotonic</varname> properties encode the idle hint state of the user, similar to
|
|
the <interfacename>Manager</interfacename>'s properties, but specific for this user.</para>
|
|
|
|
<para>The <varname>Linger</varname> property shows whether lingering is enabled for the user.</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Session Objects</title>
|
|
|
|
<programlisting>
|
|
$ gdbus introspect --system --dest org.freedesktop.login1 \
|
|
--object-path /org/freedesktop/login1/session/45
|
|
|
|
node /org/freedesktop/login1/session/45 {
|
|
interface org.freedesktop.login1.Session {
|
|
methods:
|
|
Terminate();
|
|
Activate();
|
|
Lock();
|
|
Unlock();
|
|
SetIdleHint(in b idle);
|
|
SetLockedHint(in b locked);
|
|
Kill(in s who,
|
|
in i signal_number);
|
|
TakeControl(in b force);
|
|
ReleaseControl();
|
|
TakeDevice(in u major,
|
|
in u minor,
|
|
out h fd,
|
|
out b inactive);
|
|
ReleaseDevice(in u major,
|
|
in u minor);
|
|
PauseDeviceComplete(in u major,
|
|
in u minor);
|
|
SetBrightness(in s subsystem,
|
|
in s name,
|
|
in u brightness);
|
|
signals:
|
|
PauseDevice(u major,
|
|
u minor,
|
|
s type);
|
|
ResumeDevice(u major,
|
|
u minor,
|
|
h fd);
|
|
Lock();
|
|
Unlock();
|
|
properties:
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s Id = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly (uo) User = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s Name = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly t Timestamp = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly t TimestampMonotonic = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly u VTNr = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly (so) Seat = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s TTY = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s Display = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly b Remote = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s RemoteHost = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s RemoteUser = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s Service = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s Desktop = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s Scope = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly u Leader = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly u Audit = ...;
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s Type = '...';
|
|
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
|
|
readonly s Class = '...';
|
|
readonly b Active = ...;
|
|
readonly s State = '...';
|
|
readonly b IdleHint = ...;
|
|
readonly t IdleSinceHint = ...;
|
|
readonly t IdleSinceHintMonotonic = ...;
|
|
readonly b LockedHint = ...;
|
|
};
|
|
interface org.freedesktop.DBus.Peer { ... };
|
|
interface org.freedesktop.DBus.Introspectable { ... };
|
|
interface org.freedesktop.DBus.Properties { ... };
|
|
};
|
|
</programlisting>
|
|
|
|
<refsect2>
|
|
<title>Methods</title>
|
|
|
|
<para><function>Terminate()</function>, <function>Activate()</function>, <function>Lock()</function>,
|
|
<function>Unlock()</function>, <function>Kill()</function> work similarly to the respective calls on
|
|
the <interfacename>Manager</interfacename> object.</para>
|
|
|
|
<para><function>SetIdleHint()</function> shall be called by the session object to update the idle state
|
|
of the session, whenever it changes.</para>
|
|
|
|
<para><function>TakeControl()</function> allows a process to take exclusive managed device
|
|
access-control for that session. Only one dbus-connection can be a controller for a given session at a
|
|
time. If the <function>force</function> argument is set (root only), an existing controller is kicked
|
|
out and replaced. Otherwise, this call fails if there is already a controller. Note that this call is
|
|
limited to dbus-users with the effective UID set to the User of the Session or root.</para>
|
|
|
|
<para><function>ReleaseControl()</function> drops control of a given session again. Closing the
|
|
dbus-connection implicitly releases control, too. See <function>TakeControl()</function> for more. This
|
|
also releases all devices for the controller that were requested via <function>TakeDevice()</function>.
|
|
</para>
|
|
|
|
<para><function>TakeDevice()</function> allows a session-controller to get a file-descriptor for a
|
|
specific device. Pass in the major and minor numbers of the character-device and
|
|
<filename>systemd-logind</filename> will return a file-descriptor for the device. Only a limited set of
|
|
device-types is currently supported (but may be extended). <filename>systemd-logind</filename>
|
|
automatically mutes the file-descriptor if the session is inactive and resumes it once the session gets
|
|
active again. This guarantees that a session can only access session-devices if the session is
|
|
active. Note that this revoke/resume mechanism is asynchronous and may happen at any given time. This
|
|
only works on devices that are attached to the seat of the given session. A process is not required to
|
|
have direct access to the device-node. <filename>systemd-logind</filename> only requires you to be the
|
|
active session controller (see <function>TakeControl()</function>). Also note that any device can only
|
|
be requested once. As long as you don't release it, further <function>TakeDevice()</function> calls
|
|
will fail.</para>
|
|
|
|
<para><function>ReleaseDevice()</function> releases a device again (see
|
|
<function>TakeDevice()</function>). This is also implicitly done by
|
|
<function>ReleaseControl()</function> or when closing the dbus-connection.</para>
|
|
|
|
<para><function>PauseDeviceComplete()</function> allows a session-controller to synchronously pause a
|
|
device after receiving a <function>PauseDevice(<literal>pause</literal>)</function> signal. Forced
|
|
signals (or after an internal timeout) are automatically completed by
|
|
<filename>systemd-logind</filename> asynchronously.</para>
|
|
|
|
<para><function>SetLockedHint()</function> may be used to set the "idle hint" to
|
|
<varname>locked</varname>, i.e. information whether the session is locked. This is intended to be used
|
|
by the desktop environment to tell <command>systemd-logind</command> when the session is locked and
|
|
unlocked.</para>
|
|
|
|
<para><function>SetBrightness()</function> may be used to set the display brightness. This is intended
|
|
to be used by the desktop environment, and allows unprivileged programs to access hardware settings in
|
|
a controlled way. The <varname>subsystem</varname> parameter specifies a kernel subsystem, either
|
|
<literal>backlight</literal> or <literal>leds</literal>. The <varname>name</varname> parameter
|
|
specifies a device name under the specified subsystem. The <varname>brightness</varname> parameter
|
|
specifies the brightness. The range is defined by individual drivers, see
|
|
<filename>/sys/class/<varname>subsystem</varname>/<varname>name</varname>/max_brightness</filename>.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Signals</title>
|
|
|
|
<para>The active session-controller exclusively gets <function>PauseDevice</function> and
|
|
<function>ResumeDevice</function> events for any device it requested via
|
|
<function>TakeDevice()</function>. They notify the controller whenever a device is paused or resumed. A
|
|
device is never resumed if a session is inactive. Also note that <function>PauseDevice</function>
|
|
signals are sent before the <function>PropertyChanged</function> signal for the
|
|
<function>Active</function> state. The inverse is true for <function>ResumeDevice</function>. A device
|
|
may remain paused for unknown reasons even though the <interfacename>Session</interfacename> is active.
|
|
</para>
|
|
|
|
<para>A <function>PauseDevice</function> signal carries the major and minor and a string describing the
|
|
type as arguments. <function>force</function> means the device got paused by
|
|
<filename>systemd-logind</filename> already and this is only an asynchronous
|
|
notification. <function>pause</function> means <filename>systemd-logind</filename> tries to pause the
|
|
device and grants you limited amount of time to pause it. You must respond to this via
|
|
<function>PauseDeviceComplete()</function>. This synchronous pausing-mechanism is used for
|
|
backwards-compatibility to VTs and <filename>systemd-logind</filename> is free to not make use of
|
|
it. It is also free to send a forced <function>PauseDevice</function> if you don't respond in a timely
|
|
manner (or for any other reason). <function>gone</function> means the device was unplugged from the
|
|
system and you will no longer get any notifications about it. There is no reason to call
|
|
<function>ReleaseDevice()</function>. You may call <function>TakeDevice()</function> again if a new
|
|
device gets the major+minor combination assigned.</para>
|
|
|
|
<para><function>ResumeDevice</function> is sent whenever a session is active and a device is
|
|
resumed. It carries the major/minor as arguments and provides a new open file-descriptor. You should
|
|
switch to the new descriptor and close the old one. They are not guaranteed to have the same underlying
|
|
open-file-descriptor in the kernel (except for a limited set of device types).</para>
|
|
|
|
<para>Whenever <function>Active</function> or the idle state changes
|
|
<function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para>
|
|
|
|
<para><function>Lock</function>/<function>Unlock</function> is sent when the session is asked to be
|
|
screen-locked/unlocked. A session manager of the session should listen to this signal and act
|
|
accordingly. This signal is sent out as a result of the <function>Lock()</function> and
|
|
<function>Unlock()</function> methods, respectively.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Properties</title>
|
|
|
|
<para><varname>Id</varname> encodes the session ID.</para>
|
|
|
|
<para><varname>User</varname> encodes the user ID of the user this session belongs to. This is a
|
|
structure encoding the Unix UID and the object path.</para>
|
|
|
|
<para><varname>Name</varname> encodes the user name.</para>
|
|
|
|
<para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> encode the usec timestamp
|
|
since the epoch when the session was created, in <constant>CLOCK_REALTIME</constant> or
|
|
<constant>CLOCK_MONOTONIC</constant>, respectively.</para>
|
|
|
|
<para><varname>VTNr</varname> encodes the virtual terminal number of the session if there is any, 0
|
|
otherwise.</para>
|
|
|
|
<para><varname>Seat</varname> encodes the seat this session belongs to, if there is any. This is a
|
|
structure consisting of the ID and the seat object path.</para>
|
|
|
|
<para><varname>TTY</varname> encodes the kernel TTY path of the session if this is a text login. If not
|
|
this is an empty string.</para>
|
|
|
|
<para><varname>Display</varname> encodes the X11 display name if this is a graphical login. If not,
|
|
this is an empty string.</para>
|
|
|
|
<para><varname>Remote</varname> encodes whether the session is local or remote.</para>
|
|
|
|
<para><varname>RemoteHost</varname> and <varname>RemoteUser</varname> encode the remote host and user
|
|
if this is a remote session, or an empty string otherwise.</para>
|
|
|
|
<para><varname>Service</varname> encodes the PAM service name that registered the session.</para>
|
|
|
|
<para><varname>Desktop</varname> describes the desktop environment running in the session (if
|
|
known).</para>
|
|
|
|
<para><varname>Scope</varname> contains the systemd scope unit name of this session.</para>
|
|
|
|
<para><varname>Leader</varname> encodes the PID of the process that registered the session.</para>
|
|
|
|
<para><varname>Audit</varname> encodes the Kernel Audit session ID of the session, if auditing is
|
|
available.</para>
|
|
|
|
<para><varname>Type</varname> encodes the session type. It's one of <literal>unspecified</literal> (for
|
|
cron PAM sessions and suchlike), <literal>tty</literal> (for text logins) or
|
|
<literal>x11</literal>/<literal>mir</literal>/<literal>wayland</literal> (for graphical logins).</para>
|
|
|
|
<para><varname>Class</varname> encodes the session class. It's one of <literal>user</literal> (for
|
|
normal user sessions), <literal>greeter</literal> (for display manager pseudo-sessions),
|
|
<literal>lock-screen</literal> (for display lock screens).</para>
|
|
|
|
<para><varname>Active</varname> is a boolean that is true if the session is active, i.e. currently in the
|
|
foreground. This field is semi-redundant due to State.</para>
|
|
|
|
<para><varname>State</varname> encodes the session state and one of <literal>online</literal>,
|
|
<literal>active</literal>, <literal>closing</literal>. See
|
|
<citerefentry><refentrytitle>sd_session_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
for more information about the states.</para>
|
|
|
|
<para><varname>IdleHint</varname>, <varname>IdleSinceHint</varname>,
|
|
<varname>IdleSinceHintMonotonic</varname> encapsulate the idle hint state of this session, similarly to
|
|
how the respective properties on the manager object do it for the whole system.</para>
|
|
|
|
<para><varname>LockedHint</varname> shows the locked hint state of this session, as set by
|
|
<function>SetLockedHint()</function> described above.</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Versioning</title>
|
|
|
|
<para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
|
|
the usual interface versioning guidelines</ulink>.</para>
|
|
</refsect1>
|
|
</refentry>
|