org.freedesktop.login1 — The D-Bus interface of systemd-logind
systemd-logind.service(8) is a system service that keeps track of user logins and seats.
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).
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 = ...; @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 = ...; @org.freedesktop.DBus.Property.EmitsChangedSignal("const") readonly t StopIdleSessionUSec = ...; }; interface org.freedesktop.DBus.Peer { ... }; interface org.freedesktop.DBus.Introspectable { ... }; interface org.freedesktop.DBus.Properties { ... }; };
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.
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.
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.
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.
ListSeats()
returns an array of all currently available seats. The
structure in the array consists of the following fields: seat id, seat object path.
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).
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.
ActivateSession()
brings the session with the specified ID into the
foreground. ActivateSessionOnSeat()
does the same, but only if the seat id
matches.
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.
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.
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.
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.
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.
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
authorization interactivity (see below). Note that the user linger state is persistently
stored on disk.
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).
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).
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)
When the flags
is 0 then these methods behave just like the versions without
flags. Since systemd version 257 active inhibitors are honoured by default for privileged users too.
SD_LOGIND_ROOT_CHECK_INHIBITORS
(0x01) now only applies to weak inhibitors, to
request that they honoured for privileged users too, since they ignore them by default. A new flag
SD_LOGIND_SKIP_INHIBITORS
(0x04) can be specified to bypass all types of
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.
SetRebootParameter()
sets a parameter for a subsequent reboot operation.
See the description of reboot in
systemctl(1) and
reboot(2)
for more information.
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.
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
", and
"challenge
". 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.
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.
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.
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.
Whenever the inhibition state or idle hint changes, PropertyChanged
signals are sent out to which clients can subscribe.
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.
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.
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. 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).
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
.
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.
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.
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).
NCurrentSessions
and NCurrentInhibitors
contain the number
of currently registered sessions and inhibitors.
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.
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.
The RebootParameter
property shows the value set with the
SetRebootParameter()
method described above.
ScheduledShutdown
shows the value pair set with the
ScheduleShutdown()
method described above.
RebootToFirmwareSetup
, RebootToBootLoaderMenu
, and
RebootToBootLoaderEntry
are true when the resprective post-reboot operation was
selected with SetRebootToFirmwareSetup()
,
SetRebootToBootLoaderMenu()
, or
SetRebootToBootLoaderEntry()
.
The WallMessage
and EnableWallMessages
properties reflect the
shutdown reason and wall message enablement switch which can be set with the
SetWallMessage()
method described above.
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.
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
.
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
.
ScheduleShutdown()
and CancelScheduledShutdown()
require
the same privileges (listed above) as the immediate poweroff/reboot/halt operations.
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.
The interactive
boolean parameters can be used to control whether polkit
should interactively ask the user for authentication credentials if required.
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 { ... }; };
Terminate()
and ActivateSession()
work similarly to
TerminateSeat()
and ActivationSessionOnSeat()
on the Manager
object.
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.
Whenever ActiveSession
, Sessions
,
CanGraphical
, CanTTY
,
or the idle state changes, PropertyChanged
signals are sent out to which clients
can subscribe.
The Id
property encodes the ID of the seat.
ActiveSession
encodes the currently active session if there is one. It is a
structure consisting of the session id and the object path.
CanTTY
encodes whether the session is suitable for text logins, and
CanGraphical
whether it is suitable for graphical sessions.
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.
The IdleHint
, IdleSinceHint
, and
IdleSinceHintMonotonic
properties encode the idle state, similarly to the ones
exposed on the Manager
object, but specific for this seat.
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 { ... }; };
Terminate()
and Kill()
work similarly to the
TerminateUser()
and KillUser()
methods on the manager
object.
Whenever Sessions
or the idle state changes,
PropertyChanged
signals are sent out to which clients can subscribe.
The UID
and GID
properties encode the Unix UID and primary
GID of the user.
The Name
property encodes the user name.
Timestamp
and TimestampMonotonic
encode the login time of
the user in microseconds since the epoch, in the CLOCK_REALTIME
and
CLOCK_MONOTONIC
clocks, respectively.
RuntimePath
encodes the runtime path of the user,
i.e. $XDG_RUNTIME_DIR
. For details see the
XDG Basedir Specification
.
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
.
Slice
contains the unit name of the user systemd slice of this user. Each
logged in user gets a private slice.
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.
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.
Sessions
is an array of structures encoding all current sessions of the
user. Each structure consists of the ID and object path.
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.
The Linger
property shows whether lingering is enabled for this user.
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 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 = ...; 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 { ... }; };
Terminate()
, Activate()
, Lock()
,
Unlock()
, and Kill()
work similarly to the respective calls on
the Manager
object.
SetIdleHint()
is called by the session object to update the idle state
of the session whenever it changes.
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.
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()
.
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.
SetClass()
allows the caller to change the class of the session dynamically.
It may only be called by session's owening 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.
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.
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.
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 don't release it, further TakeDevice()
calls
will fail.
ReleaseDevice()
releases a device again (see
TakeDevice()
). This is also implicitly done by
ReleaseControl()
or when closing the D-Bus connection.
PauseDeviceComplete()
allows a session controller to synchronously pause a
device after receiving a PauseDevice("
signal. Forced
signals (or after an internal timeout) are automatically completed by
pause
")systemd-logind
asynchronously.
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.
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
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.
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 don't 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.
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).
Whenever Active
or the idle state changes,
PropertyChanged
signals are sent out to which clients can subscribe.
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.
Id
encodes the session ID.
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.
Name
encodes the user name.
Timestamp
and TimestampMonotonic
encode the microseconds
since the epoch when the session was created, in CLOCK_REALTIME
or
CLOCK_MONOTONIC
, respectively.
VTNr
encodes the virtual terminal number of the session if there is any, 0
otherwise.
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.
TTY
encodes the kernel TTY path of the session if this is a text login. If not
this is an empty string.
Display
encodes the X11 display name if this is a graphical login. If not,
this is an empty string.
Remote
encodes whether the session is local or remote.
RemoteHost
and RemoteUser
encode the remote host and user
if this is a remote session, or an empty string otherwise.
Service
encodes the PAM service name that registered the session.
Desktop
describes the desktop environment running in the session (if
known).
Scope
contains the systemd scope unit name of this session.
Leader
encodes the PID of the process that registered the session.
Audit
encodes the Kernel Audit session ID of the session if auditing is
available.
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).
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).
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
.
State
encodes the session state and one of "online
",
"active
", or "closing
". See
sd_session_get_state(3)
for more information about the states.
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.
LockedHint
shows the locked hint state of this session, as set by the
SetLockedHint()
method described above.
CanIdle
indicates whether the session supports the idle hint
concept. Similarly, CanLock
indicates whether the session supports the screen lock
concept.
Example 1. Introspect the logind manager on the bus
$ gdbus introspect --system --dest org.freedesktop.login1 \ --object-path /org/freedesktop/login1
or
$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1
Example 2. Introspect the default seat on the bus
$ gdbus introspect --system --dest org.freedesktop.login1 \ --object-path /org/freedesktop/login1/seat/seat0
or
$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/seat/seat0
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.
Example 3. Introspect a single user on the bus
$ gdbus introspect --system --dest org.freedesktop.login1 \ --object-path /org/freedesktop/login1/user/_1000
or
$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/user/_1000
Example 4. Introspect org.freedesktop.login1.Session
on the bus
$ gdbus introspect --system --dest org.freedesktop.login1 \ --object-path /org/freedesktop/login1/session/45
or
$ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/session/45
HandlePowerKeyLongPress
,
HandleRebootKey
,
HandleRebootKeyLongPress
,
HandleSuspendKeyLongPress
, and
HandleHibernateKeyLongPress
were added in version 251.
StopIdleSessionUSec
was added in version 252.
PrepareForShutdownWithMetadata()
and
CreateSessionWithPIDFD()
were added in version 255.
Sleep()
,
CanSleep()
,
SleepOperation
, and
ListSessionsEx()
were added in version 256.
HandleSecureAttentionKey
, SecureAttentionKey()
,
PreparingForShutdownWithMetadata
, DesignatedMaintenanceTime
,
CanIdle
, CanLock
,
and BlockWeakInhibited
were added in version 257.
SetDisplay()
was added in version 252.
SetTTY()
was added in version 254.
SetClass()
was added in version 256.