| ORG.FREEDESKTOP.LOGIN1(5) | org.freedesktop.login1 | ORG.FREEDESKTOP.LOGIN1(5) |
.SH "NAME" org.freedesktop.login1 - The D-Bus interface of
systemd-logind
.SH "INTRODUCTION"
.PP systemd-logind.service(8) is a system service that keeps track of
user logins and seats.
.PP 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
functionality but in addition may also be used to make changes to the system
state. For more information please consult sd-login(3).
.SH "THE MANAGER OBJECT"
.PP The service exposes the following interfaces on the Manager object on the
bus:
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);
ListSessionsEx(out a(sussussbto) sessions);
ListUsers(out a(uso) users);
ListSeats(out a(so) seats);
ListInhibitors(out a(ssssuu) inhibitors);
@org.freedesktop.systemd1.Privileged("true")
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);
@org.freedesktop.systemd1.Privileged("true")
CreateSessionWithPIDFD(in u uid,
in h pidfd,
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 t flags,
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 whom,
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);
PowerOffWithFlags(in t flags);
Reboot(in b interactive);
RebootWithFlags(in t flags);
Halt(in b interactive);
HaltWithFlags(in t flags);
Suspend(in b interactive);
SuspendWithFlags(in t flags);
Hibernate(in b interactive);
HibernateWithFlags(in t flags);
HybridSleep(in b interactive);
HybridSleepWithFlags(in t flags);
SuspendThenHibernate(in b interactive);
SuspendThenHibernateWithFlags(in t flags);
Sleep(in t flags);
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);
CanSleep(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:
SecureAttentionKey(s seat_id,
o object_path);
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);
PrepareForShutdownWithMetadata(b start,
a{sv} metadata);
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 BlockWeakInhibited = '...';
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 as SleepOperation = ['...', ...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s HandlePowerKey = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s HandlePowerKeyLongPress = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s HandleRebootKey = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s HandleRebootKeyLongPress = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s HandleSuspendKey = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s HandleSuspendKeyLongPress = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s HandleHibernateKey = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s HandleHibernateKeyLongPress = '...';
@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 s HandleSecureAttentionKey = '...';
@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 a{sv} PreparingForShutdownWithMetadata = [...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly b PreparingForSleep = ...;
readonly (st) ScheduledShutdown = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s DesignatedMaintenanceTime = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly b Docked = ...;
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 RuntimeDirectoryInodesMax = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InhibitorsMax = ...;
readonly t NCurrentInhibitors = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t SessionsMax = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly t NCurrentSessions = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t StopIdleSessionUSec = ...;
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
.SS "Methods"
.PP GetSession() may be used to get the session object path for the
session with the specified ID. Similarly, GetUser() and
GetSeat() get the user and seat objects, respectively.
GetSessionByPID() and GetUserByPID() get the session/user
object the specified PID belongs to if there is any.
.PP ListSessions() returns an array of all current sessions. The
structures in the array consist of the following fields: session id,
user id, user name, seat id, and session object
path. If a session does not have a seat attached, the seat id field will
be an empty string.
.PP ListSessionsEx() returns an array of all current sessions with
more metadata than ListSessions(). The structures in the array
consist of the following fields: session id, user id, user
name, seat id, leader pid, session class, tty
name, idle hint, idle hint monotonic timestamp, and
session object path. tty and seat id fields could be
empty, if the session has no associated tty or session has no seat attached,
respectively.
.PP ListUsers() returns an array of all currently logged in users. The
structures in the array consist of the following fields: user id, user name,
user object path.
.PP ListSeats() returns an array of all currently available seats. The
structure in the array consists of the following fields: seat id, seat
object path.
.PP ListInhibitors() lists all currently active inhibitors. It returns
an array of structures consisting of what, who, why,
mode, uid (user ID), and pid (process ID).
.PP CreateSession(), CreateSessionWithPIDFD(), and
ReleaseSession() may be used to open or close login sessions. These
calls should never be invoked directly by clients. Creating/closing
sessions is exclusively the job of PAM and its pam_systemd(8)
module.
.PP ActivateSession() brings the session with the specified ID into
the foreground. ActivateSessionOnSeat() does the same, but only if
the seat id matches.
.PP LockSession() asks the session with the specified ID to activate
the screen lock. UnlockSession() 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.
.PP LockSessions() asks all sessions to activate their screen locks.
This may be used to lock access to the entire machine in one action.
Similarly, UnlockSessions() asks all sessions to deactivate their
screen locks.
.PP KillSession() 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 leader or all and a signal number. If leader is passed only the
session leader is killed. If all is passed all processes of the session are
killed.
.PP KillUser() may be used to send a Unix signal to all processes of a
user. As arguments it takes the user id and a signal number.
.PP TerminateSession(), TerminateUser(), TerminateSeat()
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.
.PP SetUserLinger() enables or disables user lingering. If enabled,
the runtime directory of a user is kept around and they may continue to run
processes while logged out. If disabled, the runtime directory goes away as
soon as they log out. SetUserLinger() expects three arguments: the
UID, a boolean whether to enable/disable and a boolean controlling the
polkit[1] authorization interactivity (see below). Note that the user
linger state is persistently stored on disk.
.PP AttachDevice() 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. AttachDevice() takes three arguments:
the seat id, the sysfs path, and a boolean for controlling polkit
interactivity (see below). Device assignments are persistently stored on
disk. To create a new seat, simply specify a previously unused seat id. For
more information about the seat assignment logic see sd-login(3).
.PP FlushDevices() removes all explicit seat assignments for devices,
resetting all assignments to the automatic defaults. The only argument it
takes is the polkit interactivity boolean (see below).
.PP PowerOff(), Reboot(), Halt(), Suspend(), and
Hibernate() result in the system being powered off, rebooted, halted
(shut down without turning off power), suspended (the system state is saved
to RAM and the CPU is turned off), or hibernated (the system state is saved
to disk and the machine is powered down). HybridSleep() results in
the system entering a hybrid-sleep mode, i.e. the system is both hibernated
and suspended. SuspendThenHibernate() results in the system being
suspended, then later woken using an RTC timer and hibernated. The only
argument is the polkit interactivity boolean interactive (see below).
The main purpose of these calls is that they enforce polkit policy and hence
allow powering off/rebooting/suspending/hibernating even by unprivileged
users. They also enforce inhibition locks for non-privileged users.
Sleep() automatically selects the most suitable sleep operation
supported by the machine. The candidate sleep operations to check for
support can be configured through SleepOperation= setting in
logind.conf(5). UIs should expose these calls as the primary
mechanism to poweroff/reboot/suspend/hibernate the machine. Methods
PowerOffWithFlags(), RebootWithFlags(),
HaltWithFlags(), SuspendWithFlags(),
HibernateWithFlags(), HybridSleepWithFlags(),
SuspendThenHibernateWithFlags(), and Sleep() take flags
to allow for extendability, defined as follows:
#define SD_LOGIND_ROOT_CHECK_INHIBITORS (UINT64_C(1) << 0) #define SD_LOGIND_KEXEC_REBOOT (UINT64_C(1) << 1) #define SD_LOGIND_SOFT_REBOOT (UINT64_C(1) << 2) #define SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP (UINT64_C(1) << 3) #define SD_LOGIND_SKIP_INHIBITORS (UINT64_C(1) << 4)
.PP When the flags is 0 then these methods behave just like the
versions without flags. Since systemd version 257 inhibitors of type block
are enforced on operations requested by both privileged and unprivileged
users. Previously they were honoured only by unprivileged users, excluding
the user owning the inhibitor. The latter behaviour is now available through
the block-weak inhibitor lock type. SD_LOGIND_ROOT_CHECK_INHIBITORS
(0x01) makes block-weak locks behave like regular block locks, i.e. ensures
they are honoured for any user. A flag SD_LOGIND_SKIP_INHIBITORS
(0x10) can be specified to bypass both block and block-weak inhibitors (it
has no effect on delay inhibitors). When SD_LOGIND_KEXEC_REBOOT
(0x02) is set, then RebootWithFlags() performs a kexec reboot if
kexec kernel is loaded. When SD_LOGIND_SOFT_REBOOT (0x04) is set, or
SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP (0x08) is set and a new root
file system has been set up on /run/nextroot/, then RebootWithFlags()
performs a userspace reboot only.
SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP and
SD_LOGIND_KEXEC_REBOOT can be combined, with soft-reboot having
precedence.
.PP SetRebootParameter() sets a parameter for a subsequent reboot
operation. See the description of reboot in systemctl(1) and
reboot(2) for more information.
.PP SetRebootToFirmwareSetup(), SetRebootToBootLoaderMenu(),
and SetRebootToBootLoaderEntry() configure the action to be taken
from the boot loader after a reboot: respectively entering firmware setup
mode, the boot loader menu, or a specific boot loader entry. See
systemctl(1) for the corresponding command line interface.
.PP CanPowerOff(), CanReboot(), CanHalt(),
CanSuspend(), CanHibernate(), CanHybridSleep(),
CanSuspendThenHibernate(), CanSleep(),
CanRebootParameter(), CanRebootToFirmwareSetup(),
CanRebootToBootLoaderMenu(), and CanRebootToBootLoaderEntry()
test whether the system supports the respective operation and whether the
calling user is allowed to execute it. Returns one of na, yes, no,
challenge, inhibited, inhibitor-blocked, and challenge-inhibitor-blocked. If
na is returned, the operation is not available because hardware, kernel, or
drivers do not support it. If yes is returned, the operation is supported
and the user may execute the operation without further authentication. If no
is returned, the operation is available but the user is not allowed to
execute the operation. If challenge is returned, the operation is available
but only after authorization. If inhibited is returned, the operation is
normally available without authorization but is currently inhibited. The
operation is available only if inhibitors are ignored and after
authorization. If inhibitor-blocked is returned, the operation is normally
available without authorization but is currently inhibited. While the
inhibitor remains active, the user is not allowed to execute the operation.
challenge-inhibitor-blocked is similar: the operation is normally available
after authorization but a held inhibitor disallows the user from executing
the operation.
.PP ScheduleShutdown() schedules a shutdown operation type at
time usec in microseconds since the UNIX epoch. Alternatively, if
usec UINT64_MAX and a maintenance window is configured,
systemd-logind will use the next time of the maintenance window instead.
type can be one of poweroff, dry-poweroff, reboot, dry-reboot, halt,
and dry-halt. (The dry- variants do not actually execute the shutdown
action.) CancelScheduledShutdown() cancels a scheduled shutdown. The
output parameter cancelled is true if a shutdown operation was
scheduled.
.PP Note that usec is a lower bound only: the shutdown operation is
executed as soon as possible, but not before the specified time. A timestamp
in the past is not an error, it simply means the operation is executed
immediately. This is important, since a request to shut down immediately, or
a very short time into the future, typically already refers to the past by
the time it is processed.
.PP SetWallMessage() sets the wall message (the message that will be
sent out to all terminals and stored in a utmp(5) record) for a
subsequent scheduled shutdown operation. The parameter wall_message
specifies the shutdown reason (and may be empty) which will be included in
the shutdown message. The parameter enable specifies whether to print
a wall message on shutdown.
.PP Inhibit() creates an inhibition lock. It takes four parameters:
what, who, why, and mode. what is one or
more of shutdown, sleep, idle, handle-power-key, handle-suspend-key,
handle-hibernate-key, handle-lid-switch, separated by colons, for inhibiting
poweroff/reboot, suspend/hibernate, the automatic idle logic, or hardware
key handling. who should be a short human-readable string identifying
the application taking the lock. why should be a short human-readable
string identifying the reason why the lock is taken. Finally, mode is
either block or delay which encodes whether the inhibit shall be consider
mandatory or whether it should just delay the operation to a certain maximum
time, while the block-weak and variants will create an inhibitor that is
automatically ignored in some circumstances. The method 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
Inhibitor Locks[2].
.SS "Signals"
.PP Whenever the inhibition state or idle hint changes,
PropertyChanged signals are sent out to clients which have
subscribed.
.PP The SecureAttentionKey() signal is sent when the user presses
Ctrl+Alt+Shift+Esc to request the login manager to display the greeter, for
instance in the case of a deadlocked compositor.
.PP The SessionNew(), SessionRemoved(), UserNew(),
UserRemoved(), SeatNew(), and SeatRemoved() 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.
.PP The PrepareForShutdown(), PrepareForShutdownWithMetadata(),
and PrepareForSleep() signals are sent right before (with the
argument true) or after (with the argument false) the system goes down for
reboot/poweroff and suspend/hibernate, respectively. This may be used by
applications to save data on disk, release memory, or do other jobs that
should 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 to not delay the operation any further. For more
information see Inhibitor Locks[2]. The
PrepareForShutdownWithMetadata() signal additionally sends a list of
key/value pair metadata fields. Currently it sends a type string
which defines the type of shutdown. The type can be one of power-off,
reboot, halt, kexec or soft-reboot. This signal is sent first, followed by
PrepareForShutdown() (for backward compatibility).
.SS "Properties"
.PP Most properties simply reflect the configuration, see
logind.conf(5). This includes: NAutoVTs, KillOnlyUsers,
KillExcludeUsers, KillUserProcesses, IdleAction,
InhibitDelayMaxUSec, InhibitorsMax, UserStopDelayUSec,
HandlePowerKey, HandleSuspendKey, HandleHibernateKey,
HandleLidSwitch, HandleLidSwitchExternalPower,
HandleLidSwitchDocked, IdleActionUSec,
HoldoffTimeoutUSec, RemoveIPC, RuntimeDirectorySize,
RuntimeDirectoryInodesMax, InhibitorsMax, and
SessionsMax.
.PP The IdleHint property reflects the idle hint state of the system.
If the system is idle it might get into automatic suspend or shutdown
depending on the configuration.
.PP IdleSinceHint and IdleSinceHintMonotonic encode the
timestamps of the last change of the idle hint boolean, in
CLOCK_REALTIME and CLOCK_MONOTONIC timestamps, respectively,
in microseconds since the epoch.
.PP The BlockInhibited, BlockWeakInhibited, and
DelayInhibited properties encode the currently active locks of the
respective modes. They are colon separated lists of shutdown, sleep, and
idle (see above).
.PP NCurrentSessions and NCurrentInhibitors contain the number
of currently registered sessions and inhibitors.
.PP The BootLoaderEntries 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
systemd-boot(7) for more information.
.PP The PreparingForShutdown and PreparingForSleep boolean
properties are true during the interval between the two
PrepareForShutdown() and PrepareForSleep() signals
respectively. The PreparingForShutdownWithMetadata property provides
a list of key/value pair metadata fields. Currently it lists a
preparing boolean that corresponds to the PreparingForShutdown
property, and, if a shutdown is being prepared, it will also contain a
type string which defines the type of shutdown. The type can be one
of power-off, reboot, halt, kexec or soft-reboot. Note that these properties
do not send out PropertyChanged signals.
.PP The RebootParameter property shows the value set with the
SetRebootParameter() method described above.
.PP ScheduledShutdown shows the value pair set with the
ScheduleShutdown() method described above.
.PP RebootToFirmwareSetup, RebootToBootLoaderMenu, and
RebootToBootLoaderEntry are true when the resprective post-reboot
operation was selected with SetRebootToFirmwareSetup(),
SetRebootToBootLoaderMenu(), or
SetRebootToBootLoaderEntry().
.PP The WallMessage and EnableWallMessages properties reflect
the shutdown reason and wall message enablement switch which can be set with
the SetWallMessage() method described above.
.PP Docked is true if the machine is connected to a dock.
LidClosed is true when the lid (of a laptop) is closed.
OnExternalPower is true when the machine is connected to an external
power supply.
.SS "Security"
.PP A number of operations are protected via the polkit privilege system.
SetUserLinger() requires the org.freedesktop.login1.set-user-linger
privilege. AttachDevice() requires
org.freedesktop.login1.attach-device and FlushDevices() requires
org.freedesktop.login1.flush-devices. PowerOff(), Reboot(),
Halt(), Suspend(), Hibernate() require
org.freedesktop.login1.power-off,
org.freedesktop.login1.power-off-multiple-sessions,
org.freedesktop.login1.power-off-ignore-inhibit,
org.freedesktop.login1.reboot,
org.freedesktop.login1.reboot-multiple-sessions,
org.freedesktop.login1.reboot-ignore-inhibit, org.freedesktop.login1.halt,
org.freedesktop.login1.halt-multiple-sessions,
org.freedesktop.login1.halt-ignore-inhibit, org.freedesktop.login1.suspend,
org.freedesktop.login1.suspend-multiple-sessions,
org.freedesktop.login1.suspend-ignore-inhibit,
org.freedesktop.login1.hibernate,
org.freedesktop.login1.hibernate-multiple-sessions,
org.freedesktop.login1.hibernate-ignore-inhibit, respectively depending on
whether there are other sessions around or active inhibits are present.
HybridSleep() and SuspendThenHibernate() use the same
privileges as Hibernate(). Sleep() uses the inhibits of the
auto-selected sleep operation. SetRebootParameter() requires
org.freedesktop.login1.set-reboot-parameter.
.PP SetRebootToFirmwareSetup() requires
org.freedesktop.login1.set-reboot-to-firmware-setup.
SetRebootToBootLoaderMenu() requires
org.freedesktop.login1.set-reboot-to-boot-loader-menu.
SetRebootToBootLoaderEntry() requires
org.freedesktop.login1.set-reboot-to-boot-loader-entry.
.PP ScheduleShutdown() and CancelScheduledShutdown() require
the same privileges (listed above) as the immediate poweroff/reboot/halt
operations.
.PP Inhibit() is protected via one of
org.freedesktop.login1.inhibit-block-shutdown,
org.freedesktop.login1.inhibit-delay-shutdown,
org.freedesktop.login1.inhibit-block-sleep,
org.freedesktop.login1.inhibit-delay-sleep,
org.freedesktop.login1.inhibit-block-idle,
org.freedesktop.login1.inhibit-handle-power-key,
org.freedesktop.login1.inhibit-handle-suspend-key,
org.freedesktop.login1.inhibit-handle-hibernate-key,
org.freedesktop.login1.inhibit-handle-lid-switch depending on the lock type
and mode taken.
.PP The interactive boolean parameters can be used to control whether
polkit should interactively ask the user for authentication credentials if
required.
.SH "SEAT OBJECTS"
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 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 { ... };
};
.SS "Methods"
.PP Terminate() and ActivateSession() work similarly to
TerminateSeat() and ActivationSessionOnSeat() on the Manager
object.
.PP SwitchTo() switches to the session on the virtual terminal
vtnr. SwitchToNext() and SwitchToPrevious() 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.
.SS "Signals"
.PP Whenever ActiveSession, Sessions, CanGraphical,
CanTTY, or the idle state changes, PropertyChanged signals are
sent out to clients which have subscribed.
.PP Signals are only emitted on objects referencing a specific seat ID, not
on the /org/freedesktop/login1/seat/self or
/org/freedesktop/login1/seat/auto convenience objects, as they can only be
dereferenced relative to a method caller.
.SS "Properties"
.PP The Id property encodes the ID of the seat.
.PP ActiveSession encodes the currently active session if there is
one. It is a structure consisting of the session id and the object path.
.PP CanTTY encodes whether the session is suitable for text logins,
and CanGraphical whether it is suitable for graphical sessions.
.PP The Sessions property is an array of all current sessions of this
seat, each encoded in a structure consisting of the ID and the object
path.
.PP The IdleHint, IdleSinceHint, and
IdleSinceHintMonotonic properties encode the idle state, similarly to
the ones exposed on the Manager object, but specific for this seat.
.SH "USER OBJECTS"
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 = ...;
readonly b Linger = ...;
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
.SS "Methods"
.PP Terminate() and Kill() work similarly to the
TerminateUser() and KillUser() methods on the manager
object.
.SS "Signals"
.PP Whenever Sessions or the idle state changes,
PropertyChanged signals are sent out to clients which have
subscribed.
.PP Signals are only emitted on objects referencing a specific UID, not on
the /org/freedesktop/login1/user/self convenience object, as self can
only be dereferenced relative to a method caller.
.SS "Properties"
.PP The UID and GID properties encode the Unix UID and primary
GID of the user.
.PP The Name property encodes the user name.
.PP Timestamp and TimestampMonotonic encode the login time of
the user in microseconds since the epoch, in the CLOCK_REALTIME and
CLOCK_MONOTONIC clocks, respectively.
.PP RuntimePath encodes the runtime path of the user, i.e.
$XDG_RUNTIME_DIR. For details see the XDG Basedir
Specification[3].
.PP Service contains the unit name of the user systemd service of this
user. Each logged in user is assigned a user service that runs a user
systemd instance. This is usually an instance of user@.service.
.PP Slice contains the unit name of the user systemd slice of this
user. Each logged in user gets a private slice.
.PP Display encodes which graphical session should be used as the
primary UI display for the user. It is a structure encoding the session ID
and the object path of the session to use.
.PP State encodes the user state and is one of offline, lingering,
online, active, or closing. See sd_uid_get_state(3) for more
information about the states.
.PP Sessions is an array of structures encoding all current sessions
of the user. Each structure consists of the ID and object path.
.PP The IdleHint, IdleSinceHint, and
IdleSinceHintMonotonic properties encode the idle hint state of the
user, similarly to the Manager's properties, but specific for this user.
.PP The Linger property shows whether lingering is enabled for this
user.
.SH "SESSION OBJECTS"
node /org/freedesktop/login1/session/1 {
interface org.freedesktop.login1.Session {
methods:
Terminate();
Activate();
Lock();
Unlock();
SetIdleHint(in b idle);
SetLockedHint(in b locked);
Kill(in s whom,
in i signal_number);
TakeControl(in b force);
ReleaseControl();
SetType(in s type);
SetClass(in s class);
SetDisplay(in s display);
SetTTY(in h tty_fd);
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 = ...;
readonly s TTY = '...';
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 as ExtraDeviceAccess = ['...', ...];
@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 t LeaderPIDFDId = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u Audit = ...;
readonly s Type = '...';
readonly s Class = '...';
readonly b Active = ...;
readonly s State = '...';
readonly b IdleHint = ...;
readonly t IdleSinceHint = ...;
readonly t IdleSinceHintMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly b CanIdle = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly b CanLock = ...;
readonly b LockedHint = ...;
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
.SS "Methods"
.PP Terminate(), Activate(), Lock(), Unlock(),
and Kill() work similarly to the respective calls on the Manager
object.
.PP SetIdleHint() is called by the session object to update the idle
state of the session whenever it changes.
.PP TakeControl() allows a process to take exclusive managed device
access-control for that session. Only one D-Bus connection can be a
controller for a given session at any time. If the force argument is
set (root only), an existing controller is kicked out and replaced.
Otherwise, this method fails if there is already a controller. Note that
this method is limited to D-Bus users with the effective UID set to the user
of the session or root.
.PP ReleaseControl() drops control of a given session. Closing the
D-Bus connection implicitly releases control as well. See
TakeControl() for more information. This method also releases all
devices for which the controller requested ownership via
TakeDevice().
.PP SetType() allows the type of the session to be changed
dynamically. It can only be called by session's current controller. If
TakeControl() has not been called, this method will fail. In
addition, the session type will be reset to its original value once control
is released, either by calling ReleaseControl() or closing the D-Bus
connection. This should help prevent a session from entering an inconsistent
state, for example if the controller crashes. The only argument type
is the new session type.
.PP SetClass() allows the caller to change the class of the session
dynamically. It may only be called by session's owning user. Currently, this
call may be exclusively used to change the class from user-incomplete to
user. The call is synchronous, and will return only once the user's service
manager has successfully been started, if necessary. The only argument
type is the new session type.
.PP SetDisplay() allows the display name of the graphical session to
be changed. This is useful if the display server is started as part of the
session. It can only be called by session's current controller. If
TakeControl() has not been called, this method will fail. The only
argument display is the new display name.
.PP SetTTY() allows the device name of the session to be changed. This
is useful if the tty device is only known after authentication. It can only
be called by session's current controller. If TakeControl() has not
been called, this method will fail. The only argument tty_fd is a
file handle to the new tty device.
.PP TakeDevice() 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 systemd-logind will return a file descriptor for the device. Only
a limited set of device-types is currently supported (but may be extended).
systemd-logind automatically mutes the file descriptor if the session is
inactive and resumes it once the session is activated 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. systemd-logind only requires you to be the active session controller
(see TakeControl()). Also note that any device can only be requested
once. As long as you do not release it, further TakeDevice() calls
will fail.
.PP ReleaseDevice() releases a device again (see TakeDevice()).
This is also implicitly done by ReleaseControl() or when closing the
D-Bus connection.
.PP PauseDeviceComplete() allows a session controller to synchronously
pause a device after receiving a PauseDevice(pause)
signal. Forced signals (or after an internal timeout) are automatically
completed by systemd-logind asynchronously.
.PP SetLockedHint() may be used to set the "locked hint" to
locked, i.e. information whether the session is locked. This is
intended to be used by the desktop environment to tell systemd-logind
when the session is locked and unlocked.
.PP SetBrightness() 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
subsystem parameter specifies a kernel subsystem, either backlight or
leds. The name parameter specifies a device name under the specified
subsystem. The brightness parameter specifies the brightness. The
range is defined by individual drivers, see
/sys/class/subsystem/name/max_brightness.
.SS "Signals"
.PP The active session controller exclusively gets PauseDevice() and
ResumeDevice() events for any device it requested via
TakeDevice(). They notify the controller whenever a device is paused
or resumed. A device is never resumed if its session is inactive. Also note
that PauseDevice() signals are sent before the PropertyChanged
signal for the Active state. The inverse is true for
ResumeDevice(). A device may remain paused for unknown reasons even
though the Session is active.
.PP A PauseDevice() signal carries the major and minor numbers and a
string describing the type as arguments. force means the device was
already paused by systemd-logind and the signal is only an asynchronous
notification. pause means systemd-logind grants you a limited amount
of time to pause the device. You must respond to this via
PauseDeviceComplete(). This synchronous pausing mechanism is used for
backwards-compatibility to VTs and systemd-logind is free to not make use of
it. It is also free to send a forced PauseDevice() if you do not
respond in a timely manner (or for any other reason). gone means the
device was unplugged from the system and you will no longer get any
notifications about it. There is no need to call ReleaseDevice(). You
may call TakeDevice() again if a new device is assigned the
major+minor combination.
.PP ResumeDevice() is sent whenever a session is active and a device
is resumed. It carries the major/minor numbers 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).
.PP Whenever Active or the idle state changes, PropertyChanged
signals are sent out to clients which have subscribed.
.PP Lock()/Unlock() 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
Lock() and Unlock() methods, respectively.
.PP Signals are only emitted on objects referencing a specific session ID,
not on the /org/freedesktop/login1/session/self or
/org/freedesktop/login1/session/auto convenience objects, as they can only
be dereferenced relative to a method caller.
.SS "Properties"
.PP Id encodes the session ID.
.PP User encodes the user ID of the user this session belongs to. This
is a structure consisting of the Unix UID and the object path.
.PP Name encodes the user name.
.PP Timestamp and TimestampMonotonic encode the microseconds
since the epoch when the session was created, in CLOCK_REALTIME or
CLOCK_MONOTONIC, respectively.
.PP VTNr encodes the virtual terminal number of the session if there
is any, 0 otherwise.
.PP Seat encodes the seat this session belongs to if there is any.
This is a structure consisting of the ID and the seat object path.
.PP TTY encodes the kernel TTY path of the session if this is a text
login. If not this is an empty string.
.PP Display encodes the X11 display name if this is a graphical login.
If not, this is an empty string.
.PP Remote encodes whether the session is local or remote.
.PP RemoteHost and RemoteUser encode the remote host and user
if this is a remote session, or an empty string otherwise.
.PP ExtraDeviceAccess encodes the set of additional hardware devices
that the session is granted access to. For every ID in the list, the
session is granted access to all devices tagged with xaccess-ID in
udev.
.PP Service encodes the PAM service name that registered the
session.
.PP Desktop describes the desktop environment running in the session
(if known).
.PP Scope contains the systemd scope unit name of this session.
.PP Leader encodes the PID of the process that registered the
session.
.PP LeaderPIDFDId encodes the Linux pidfd inode ID of the process that
registered the session.
.PP Audit encodes the Kernel Audit session ID of the session if
auditing is available.
.PP Type encodes the session type. It's one of unspecified (for cron
PAM sessions and suchlike), tty (for text logins), web (for web-based
logins), or x11/mir/wayland (for graphical logins).
.PP Class encodes the session class. It's one of user (for normal user
sessions), greeter (for display manager pseudo-sessions), or lock-screen
(for display lock screens).
.PP Active 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.
.PP State encodes the session state and one of online, active, or
closing. See sd_session_get_state(3) for more information about the
states.
.PP IdleHint, IdleSinceHint, and IdleSinceHintMonotonic
encapsulate the idle hint state of this session, similarly to how the
respective properties on the manager object do it for the whole system.
.PP LockedHint shows the locked hint state of this session, as set by
the SetLockedHint() method described above.
.PP CanIdle indicates whether the session supports the idle hint
concept. Similarly, CanLock indicates whether the session supports
the screen lock concept.
.SH "EXAMPLES"
.PP Example 1. Introspect the logind manager on the
bus
$ gdbus introspect --system --dest org.freedesktop.login1 \
--object-path /org/freedesktop/login1
.PP or
$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1
.PP Example 2. Introspect the default seat on the
bus
$ gdbus introspect --system --dest org.freedesktop.login1 \
--object-path /org/freedesktop/login1/seat/seat0
.PP or
$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/seat/seat0
.PP Seat seat0 is the default seat, so it'll be present unless local
configuration is made to reassign all devices to a different seat. The list
of seats and users can be acquired with loginctl list-sessions.
.PP Example 3. Introspect a single user on the bus
$ gdbus introspect --system --dest org.freedesktop.login1 \
--object-path /org/freedesktop/login1/user/_1000
.PP or
$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/user/_1000
.PP Example 4. Introspect org.freedesktop.login1.Session on
the bus
$ gdbus introspect --system --dest org.freedesktop.login1 \
--object-path /org/freedesktop/login1/session/45
.PP or
$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/session/45
.SH "VERSIONING"
.PP These D-Bus interfaces follow the usual interface versioning
guidelines[4].
.SH "HISTORY"
.SS "The Manager Object"
.PP HandlePowerKeyLongPress, HandleRebootKey,
HandleRebootKeyLongPress, HandleSuspendKeyLongPress, and
HandleHibernateKeyLongPress were added in version 251.
.PP StopIdleSessionUSec was added in version 252.
.PP PrepareForShutdownWithMetadata() and
CreateSessionWithPIDFD() were added in version 255.
.PP Sleep(), CanSleep(), SleepOperation, and
ListSessionsEx() were added in version 256.
.PP HandleSecureAttentionKey, SecureAttentionKey(),
PreparingForShutdownWithMetadata, DesignatedMaintenanceTime,
CanIdle, CanLock, and BlockWeakInhibited were added in
version 257.
.SS "Session Objects"
.PP SetDisplay() was added in version 252.
.PP SetTTY() was added in version 254.
.PP SetClass() was added in version 256.
.PP LeaderPIDFDId was added in version 258.
.PP ExtraDeviceAccess was added in version 260.
.SH "SEE ALSO"
.PP systemd(1), systemd-logind.service(8),
loginctl(1)
NOTES
- 1.
- polkit
- 2.
- Inhibitor Locks
- 3.
- XDG Basedir Specification
- 4.
- the usual interface versioning guidelines
| systemd 262.2 |