Provided by: systemd_256.4-2ubuntu1_amd64 bug

NAME

       org.freedesktop.login1 - The D-Bus interface of systemd-logind

INTRODUCTION

       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 MANAGER OBJECT

       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 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);
                 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:
                 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 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 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 = ...;
                 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 { ... };
           };

   Methods
       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[1] 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)

       When the flags is 0 then these methods behave just like the versions without flags. When
       SD_LOGIND_ROOT_CHECK_INHIBITORS (0x01) is set, active inhibitors are honoured for
       privileged users too. 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.  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. 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].

   Signals
       Whenever the inhibition state or idle hint changes, PropertyChanged signals are sent out
       to which clients can subscribe.

       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[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).

   Properties
       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 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.
       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.

   Security
       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.

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 { ... };
           };

   Methods
       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.

   Signals
       Whenever ActiveSession, Sessions, CanGraphical, CanTTY, or the idle state changes,
       PropertyChanged signals are sent out to which clients can subscribe.

   Properties
       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.

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 = ...;
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
                 readonly b Linger = ...;
             };
             interface org.freedesktop.DBus.Peer { ... };
             interface org.freedesktop.DBus.Introspectable { ... };
             interface org.freedesktop.DBus.Properties { ... };
           };

   Methods
       Terminate() and Kill() work similarly to the TerminateUser() and KillUser() methods on the
       manager object.

   Signals
       Whenever Sessions or the idle state changes, PropertyChanged signals are sent out to which
       clients can subscribe.

   Properties
       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[3].

       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.

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 who,
                      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 = ...;
                 readonly b LockedHint = ...;
             };
             interface org.freedesktop.DBus.Peer { ... };
             interface org.freedesktop.DBus.Introspectable { ... };
             interface org.freedesktop.DBus.Properties { ... };
           };

   Methods
       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("pause") signal. Forced signals (or after an internal timeout) are
       automatically completed by 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.

   Signals
       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.

   Properties
       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) 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.

EXAMPLES

       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

VERSIONING

       These D-Bus interfaces follow the usual interface versioning guidelines[4].

HISTORY

   The Manager Object
       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.

   Session Objects
       SetDisplay() was added in version 252.

       SetTTY() was added in version 254.

       SetClass() was added in version 256.

NOTES

        1. polkit
           https://www.freedesktop.org/software/polkit/docs/latest/

        2. Inhibitor Locks
           https://systemd.io/INHIBITOR_LOCKS

        3. XDG Basedir Specification
           https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

        4. the usual interface versioning guidelines
           https://0pointer.de/blog/projects/versioning-dbus.html