man/org.freedesktop.login1.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="org.freedesktop.login1" conditional='ENABLE_LOGIND'
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8   <refentryinfo>
   9     <title>org.freedesktop.login1</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>org.freedesktop.login1</refentrytitle>
  15     <manvolnum>5</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>org.freedesktop.login1</refname>
  20     <refpurpose>The D-Bus interface of systemd-logind</refpurpose>
  21   </refnamediv>
  22
  23   <refsect1>
  24     <title>Introduction</title>
  25
  26     <para><citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  27     is a system service that keeps track of user logins and seats.</para>
  28
  29     <para>The daemon provides both a C library interface as well as a D-Bus interface. The library interface
  30     may be used to introspect and watch the state of user logins and seats. The bus interface provides the
  31     same functionality but in addition may also be used to make changes to the system state. For more information please
  32     consult <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  33     </para>
  34   </refsect1>
  35
  36   <refsect1>
  37     <title>The Manager Object</title>
  38
  39     <para>The service exposes the following interfaces on the Manager object on the bus:</para>
  40
  41     <programlisting>
  42 $ gdbus introspect --system \
  43         --dest org.freedesktop.login1 \
  44         --object-path /org/freedesktop/login1
  45
  46 node /org/freedesktop/login1 {
  47   interface org.freedesktop.login1.Manager {
  48     methods:
  49       GetSession(in  s session_id,
  50                  out o object_path);
  51       GetSessionByPID(in  u pid,
  52                       out o object_path);
  53       GetUser(in  u uid,
  54               out o object_path);
  55       GetUserByPID(in  u pid,
  56                    out o object_path);
  57       GetSeat(in  s seat_id,
  58               out o object_path);
  59       ListSessions(out a(susso) sessions);
  60       ListUsers(out a(uso) users);
  61       ListSeats(out a(so) seats);
  62       ListInhibitors(out a(ssssuu) inhibitors);
  63       CreateSession(in  u uid,
  64                     in  u pid,
  65                     in  s service,
  66                     in  s type,
  67                     in  s class,
  68                     in  s desktop,
  69                     in  s seat_id,
  70                     in  u vtnr,
  71                     in  s tty,
  72                     in  s display,
  73                     in  b remote,
  74                     in  s remote_user,
  75                     in  s remote_host,
  76                     in  a(sv) properties,
  77                     out s session_id,
  78                     out o object_path,
  79                     out s runtime_path,
  80                     out h fifo_fd,
  81                     out u uid,
  82                     out s seat_id,
  83                     out u vtnr,
  84                     out b existing);
  85       ReleaseSession(in  s session_id);
  86       ActivateSession(in  s session_id);
  87       ActivateSessionOnSeat(in  s session_id,
  88                             in  s seat_id);
  89       LockSession(in  s session_id);
  90       UnlockSession(in  s session_id);
  91       LockSessions();
  92       UnlockSessions();
  93       KillSession(in  s session_id,
  94                   in  s who,
  95                   in  i signal_number);
  96       KillUser(in  u uid,
  97                in  i signal_number);
  98       TerminateSession(in  s session_id);
  99       TerminateUser(in  u uid);
 100       TerminateSeat(in  s seat_id);
 101       SetUserLinger(in  u uid,
 102                     in  b enable,
 103                     in  b interactive);
 104       AttachDevice(in  s seat_id,
 105                    in  s sysfs_path,
 106                    in  b interactive);
 107       FlushDevices(in  b interactive);
 108       PowerOff(in  b interactive);
 109       Reboot(in  b interactive);
 110       Halt(in  b interactive);
 111       Suspend(in  b interactive);
 112       Hibernate(in  b interactive);
 113       HybridSleep(in  b interactive);
 114       SuspendThenHibernate(in  b interactive);
 115       CanPowerOff(out s result);
 116       CanReboot(out s result);
 117       CanHalt(out s result);
 118       CanSuspend(out s result);
 119       CanHibernate(out s result);
 120       CanHybridSleep(out s result);
 121       CanSuspendThenHibernate(out s result);
 122       ScheduleShutdown(in  s type,
 123                        in  t usec);
 124       CancelScheduledShutdown(out b cancelled);
 125       Inhibit(in  s what,
 126               in  s who,
 127               in  s why,
 128               in  s mode,
 129               out h pipe_fd);
 130       CanRebootParameter(out s result);
 131       SetRebootParameter(in  s parameter);
 132       CanRebootToFirmwareSetup(out s result);
 133       SetRebootToFirmwareSetup(in  b enable);
 134       CanRebootToBootLoaderMenu(out s result);
 135       SetRebootToBootLoaderMenu(in  t timeout);
 136       CanRebootToBootLoaderEntry(out s result);
 137       SetRebootToBootLoaderEntry(in  s boot_loader_entry);
 138       SetWallMessage(in  s wall_message,
 139                      in  b enable);
 140     signals:
 141       SessionNew(s session_id,
 142                  o object_path);
 143       SessionRemoved(s session_id,
 144                      o object_path);
 145       UserNew(u uid,
 146               o object_path);
 147       UserRemoved(u uid,
 148                   o object_path);
 149       SeatNew(s seat_id,
 150               o object_path);
 151       SeatRemoved(s seat_id,
 152                   o object_path);
 153       PrepareForShutdown(b start);
 154       PrepareForSleep(b start);
 155     properties:
 156       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 157       @org.freedesktop.systemd1.Privileged("true")
 158       readwrite b EnableWallMessages = ...;
 159       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 160       @org.freedesktop.systemd1.Privileged("true")
 161       readwrite s WallMessage = '...';
 162       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 163       readonly u NAutoVTs = ...;
 164       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 165       readonly as KillOnlyUsers = ['...', ...];
 166       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 167       readonly as KillExcludeUsers = ['...', ...];
 168       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 169       readonly b KillUserProcesses = ...;
 170       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 171       readonly s RebootParameter = '...';
 172       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 173       readonly b RebootToFirmwareSetup = ...;
 174       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 175       readonly t RebootToBootLoaderMenu = ...;
 176       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 177       readonly s RebootToBootLoaderEntry = '...';
 178       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 179       readonly as BootLoaderEntries = ['...', ...];
 180       readonly b IdleHint = ...;
 181       readonly t IdleSinceHint = ...;
 182       readonly t IdleSinceHintMonotonic = ...;
 183       readonly s BlockInhibited = '...';
 184       readonly s DelayInhibited = '...';
 185       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 186       readonly t InhibitDelayMaxUSec = ...;
 187       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 188       readonly t UserStopDelayUSec = ...;
 189       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 190       readonly s HandlePowerKey = '...';
 191       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 192       readonly s HandleSuspendKey = '...';
 193       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 194       readonly s HandleHibernateKey = '...';
 195       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 196       readonly s HandleLidSwitch = '...';
 197       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 198       readonly s HandleLidSwitchExternalPower = '...';
 199       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 200       readonly s HandleLidSwitchDocked = '...';
 201       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 202       readonly t HoldoffTimeoutUSec = ...;
 203       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 204       readonly s IdleAction = '...';
 205       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 206       readonly t IdleActionUSec = ...;
 207       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 208       readonly b PreparingForShutdown = ...;
 209       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 210       readonly b PreparingForSleep = ...;
 211       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 212       readonly (st) ScheduledShutdown = ...;
 213       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 214       readonly b Docked = ...;
 215       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 216       readonly b LidClosed = ...;
 217       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 218       readonly b OnExternalPower = ...;
 219       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 220       readonly b RemoveIPC = ...;
 221       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 222       readonly t RuntimeDirectorySize = ...;
 223       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 224       readonly t InhibitorsMax = ...;
 225       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 226       readonly t NCurrentInhibitors = ...;
 227       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 228       readonly t SessionsMax = ...;
 229       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 230       readonly t NCurrentSessions = ...;
 231   };
 232   interface org.freedesktop.DBus.Peer { ... };
 233   interface org.freedesktop.DBus.Introspectable { ... };
 234   interface org.freedesktop.DBus.Properties { ... };
 235 };
 236     </programlisting>
 237
 238     <refsect2>
 239       <title>Methods</title>
 240
 241       <para><function>GetSession()</function> may be used to get the session object path for the session with
 242       the specified ID. Similarly, <function>GetUser()</function> and <function>GetSeat()</function> get the
 243       user and seat objects, respectively. <function>GetSessionByPID()</function> and
 244       <function>GetUserByPID()</function> get the session/user object the specified PID belongs to if there
 245       is any.</para>
 246
 247       <para><function>ListSessions()</function> returns an array of all current sessions. The structures in
 248       the array consist of the following fields: session id, user id, user name, seat id, session object
 249       path. If a session does not have a seat attached, the seat id field will be an empty string.</para>
 250
 251       <para><function>ListUsers()</function> returns an array of all currently logged in users. The
 252       structures in the array consist of the following fields: user id, user name, user object path.</para>
 253
 254       <para><function>ListSeats()</function> returns an array of all currently available seats. The
 255       structure in the array consists of the following fields: seat id, seat object path.</para>
 256
 257       <para><function>ListInhibitors()</function> lists all currently active inhibitors. It returns an array of
 258       structures consisting of <varname>what</varname>, <varname>who</varname>, <varname>why</varname>,
 259       <varname>mode</varname>, <varname>uid</varname> (user ID), and <varname>pid</varname> (process ID).</para>
 260
 261       <para><function>CreateSession()</function> and <function>ReleaseSession()</function> may be used to
 262       open or close login sessions. These calls should <emphasis>never</emphasis> be invoked directly by
 263       clients. Creating/closing sessions is exclusively the job of PAM and its
 264       <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 265       module.</para>
 266
 267       <para><function>ActivateSession()</function> brings the session with the specified ID into the
 268       foreground. <function>ActivateSessionOnSeat()</function> does the same, but only if the seat id
 269       matches.</para>
 270
 271       <para><function>LockSession()</function> asks the session with the specified ID to activate the screen
 272       lock. <function>UnlockSession()</function> asks the session with the specified ID to remove an active
 273       screen lock, if there is any. This is implemented by sending out the Lock() and Unlock() signals from
 274       the respective session object which session managers are supposed to listen on.</para>
 275
 276       <para><function>LockSessions()</function> asks all sessions to activate their screen locks. This may be
 277       used to lock access to the entire machine in one action. Similarly, <function>UnlockSessions()</function>
 278       asks all sessions to deactivate their screen locks.</para>
 279
 280       <para><function>KillSession()</function> may be used to send a Unix signal to one or all processes of a
 281       session. As arguments it takes the session id, either the string <literal>leader</literal> or
 282       <literal>all</literal> and a signal number. If <literal>leader</literal> is passed only the session
 283       <literal>leader</literal> is killed. If <literal>all</literal> is passed all processes of the session
 284       are killed.</para>
 285
 286       <para><function>KillUser()</function> may be used to send a Unix signal to all processes of a user. As
 287       arguments it takes the user id and a signal number.</para>
 288
 289       <para><function>TerminateSession()</function>, <function>TerminateUser()</function>,
 290       <function>TerminateSeat()</function> may be used to forcibly terminate one specific session, all
 291       processes of a user, and all sessions attached to a specific seat, respectively. The session, user,
 292       and seat are identified by their respective IDs.</para>
 293
 294       <para><function>SetUserLinger()</function> enables or disables user lingering. If enabled, the runtime
 295       directory of a user is kept around and he may continue to run processes while he is logged out. If
 296       disabled, the runtime directory goes away as soon as they log out. <function>SetUserLinger()</function>
 297       expects three arguments: the UID, a boolean whether to enable/disable and a boolean controlling the
 298       PolicyKit authorization interactivity (see below). Note that the user linger state is persistently
 299       stored on disk.</para>
 300
 301       <para><function>AttachDevice()</function> may be used to assign a specific device to a specific
 302       seat. The device is identified by its /sys path and must be eligible for seat assignments. <function>AttachDevice()</function> takes three
 303       arguments: the seat id, the sysfs path, and a boolean for controlling PolicyKit interactivity (see
 304       below). Device assignments are persistently stored on disk. To create a new seat, simply specify a
 305       previously unused seat id. For more information about the seat assignment logic see
 306       <ulink url="https://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat for Linux</ulink>.
 307       </para>
 308
 309       <para><function>FlushDevices()</function> removes all explicit seat assignments for devices, resetting
 310       all assignments to the automatic defaults. The only argument it takes is the PolicyKit interactivity
 311       boolean (see below).</para>
 312
 313       <para><function>PowerOff()</function>, <function>Reboot()</function>, <function>Halt()</function>,
 314       <function>Suspend()</function>, and <function>Hibernate()</function> result in the system being powered
 315       off, rebooted, halted (shut down without turning off power), suspended (the system state is
 316       saved to RAM and the CPU is turned off), or hibernated (the system state is saved to disk and
 317       the machine is powered down). <function>HybridSleep()</function> results in the system entering a
 318       hybrid-sleep mode, i.e. the system is both hibernated and suspended.
 319       <function>SuspendThenHibernate()</function> results in the system being suspended, then later woken
 320       using an RTC timer and hibernated. The only argument is the PolicyKit interactivity boolean
 321       <varname>interactive</varname> (see below). The main purpose of these calls is that they enforce
 322       PolicyKit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged
 323       users. They also enforce inhibition locks. UIs should expose these calls as the primary mechanism to
 324       poweroff/reboot/suspend/hibernate the machine.</para>
 325
 326       <para><function>SetRebootParameter()</function> sets a parameter for a subsequent reboot operation.
 327       See the description of <command>reboot</command> in
 328       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
 329       <citerefentry project="man-pages"><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 330       for more information.</para>
 331
 332       <para><function>SetRebootToFirmwareSetup()</function>,
 333       <function>SetRebootToBootLoaderMenu()</function>, and <function>SetRebootToBootLoaderEntry()</function>
 334       configure the action to be taken from the boot loader after a reboot: respectively entering firmware
 335       setup mode, the boot loader menu, or a specific boot loader entry. See
 336       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for the
 337       corresponding command line interface.</para>
 338
 339       <para><function>CanPowerOff()</function>, <function>CanReboot()</function>,
 340       <function>CanHalt()</function>, <function>CanSuspend()</function>, <function>CanHibernate()</function>,
 341       <function>CanHybridSleep()</function>, <function>CanSuspendThenHibernate()</function>,
 342       <function>CanRebootParameter()</function>, <function>CanRebootToFirmwareSetup()</function>,
 343       <function>CanRebootToBootLoaderMenu()</function>, and
 344       <function>CanRebootToBootLoaderEntry()</function> test whether the system supports the respective
 345       operation and whether the calling user is allowed to execute it. Returns one of <literal>na</literal>,
 346       <literal>yes</literal>, <literal>no</literal>, and <literal>challenge</literal>. If
 347       <literal>na</literal> is returned, the operation is not available because hardware, kernel, or drivers
 348       do not support it. If <literal>yes</literal> is returned, the operation is supported and the user may
 349       execute the operation without further authentication. If <literal>no</literal> is returned, the
 350       operation is available but the user is not allowed to execute the operation. If
 351       <literal>challenge</literal> is returned, the operation is available but only after
 352       authorization.</para>
 353
 354       <para><function>ScheduleShutdown()</function> schedules a shutdown operation <varname>type</varname> at
 355       time <varname>usec</varname> in microseconds since the UNIX epoch. <varname>type</varname> can be one
 356       of <literal>poweroff</literal>, <literal>dry-poweroff</literal>, <literal>reboot</literal>,
 357       <literal>dry-reboot</literal>, <literal>halt</literal>, and <literal>dry-halt</literal>. (The
 358       <literal>dry-</literal> variants do not actually execute the shutdown action.)
 359       <function>CancelScheduledShutdown()</function> cancels a scheduled shutdown. The output parameter
 360       <varname>cancelled</varname> is true if a shutdown operation was scheduled.</para>
 361
 362       <para><function>SetWallMessage()</function> sets the wall message (the message that will be sent out to
 363       all terminals and stored in a
 364       <citerefentry><refentrytitle>utmp</refentrytitle><manvolnum>5</manvolnum></citerefentry> record) for a
 365       subsequent scheduled shutdown operation. The parameter <varname>wall_message</varname> specifies the
 366       shutdown reason (and may be empty) which will be included in the shutdown message. The parameter
 367       <varname>enable</varname> specifies whether to print a wall message on shutdown.</para>
 368
 369       <para><function>Inhibit()</function> creates an inhibition lock. It takes four parameters:
 370       <varname>what</varname>, <varname>who</varname>, <varname>why</varname>, and
 371       <varname>mode</varname>. <varname>what</varname> is one or more of <literal>shutdown</literal>,
 372       <literal>sleep</literal>, <literal>idle</literal>, <literal>handle-power-key</literal>,
 373       <literal>handle-suspend-key</literal>, <literal>handle-hibernate-key</literal>,
 374       <literal>handle-lid-switch</literal>, separated by colons, for inhibiting poweroff/reboot,
 375       suspend/hibernate, the automatic idle logic, or hardware key handling. <varname>who</varname> should be
 376       a short human readable string identifying the application taking the lock. <varname>why</varname>
 377       should be a short human readable string identifying the reason why the lock is taken. Finally,
 378       <varname>mode</varname> is either <literal>block</literal> or <literal>delay</literal> which encodes
 379       whether the inhibit shall be consider mandatory or whether it should just delay the operation to a
 380       certain maximum time. The method returns a file descriptor. The lock is released the moment this file
 381       descriptor and all its duplicates are closed. For more information on the inhibition logic see
 382       <ulink url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks</ulink>.
 383       </para>
 384     </refsect2>
 385
 386     <refsect2>
 387       <title>Signals</title>
 388
 389       <para>Whenever the inhibition state or idle hint changes, <function>PropertyChanged</function>
 390       signals are sent out to which clients can subscribe.</para>
 391
 392       <para>The <function>SessionNew</function>, <function>SessionRemoved</function>,
 393       <function>UserNew</function>, <function>UserRemoved</function>, <function>SeatNew</function>, and
 394       <function>SeatRemoved</function> signals are sent each time a session is created or removed, a user
 395       logs in or out, or a seat is added or removed. They each contain the ID of the object plus the object
 396       path.</para>
 397
 398       <para>The <function>PrepareForShutdown()</function> and <function>PrepareForSleep()</function> signals
 399       are sent right before (with the argument <literal>true</literal>) or after (with the argument
 400       <literal>false</literal>) the system goes down for reboot/poweroff and suspend/hibernate,
 401       respectively. This may be used by applications to save data on disk, release memory, or do other jobs
 402       that should be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks. After
 403       completion of this work they should release their inhibition locks in order to not delay the operation
 404       any further. For more information see
 405       <ulink url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks</ulink>.
 406       </para>
 407     </refsect2>
 408
 409     <refsect2>
 410       <title>Properties</title>
 411
 412       <para>Most properties simply reflect the configuration, see
 413       <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
 414       includes: <varname>NAutoVTs</varname>, <varname>KillOnlyUsers</varname>,
 415       <varname>KillExcludeUsers</varname>, <varname>KillUserProcesses</varname>, <varname>IdleAction</varname>,
 416       <varname>InhibitDelayMaxUSec</varname>,
 417       <varname>InhibitorsMax</varname>,
 418       <varname>UserStopDelayUSec</varname>,
 419       <varname>HandlePowerKey</varname>, <varname>HandleSuspendKey</varname>,
 420       <varname>HandleHibernateKey</varname>, <varname>HandleLidSwitch</varname>,
 421       <varname>HandleLidSwitchExternalPower</varname>, <varname>HandleLidSwitchDocked</varname>,
 422       <varname>IdleActionUSec</varname>, <varname>HoldoffTimeoutUSec</varname>,
 423       <varname>RemoveIPC</varname>, <varname>RuntimeDirectorySize</varname>,
 424       <varname>InhibitorsMax</varname>, and <varname>SessionsMax</varname>.
 425       </para>
 426
 427       <para>The <varname>IdleHint</varname> property reflects the idle hint state of the system. If the
 428       system is idle it might get into automatic suspend or shutdown depending on the configuration.</para>
 429
 430       <para><varname>IdleSinceHint</varname> and <varname>IdleSinceHintMonotonic</varname> encode the
 431       timestamps of the last change of the idle hint boolean, in <constant>CLOCK_REALTIME</constant> and
 432       <constant>CLOCK_MONOTONIC</constant> timestamps, respectively, in microseconds since the epoch.</para>
 433
 434       <para>The <varname>BlockInhibited</varname> and <varname>DelayInhibited</varname> properties encode
 435       the currently active locks of the respective modes. They are colon separated lists of
 436       <literal>shutdown</literal>, <literal>sleep</literal>, and <literal>idle</literal> (see above).</para>
 437
 438       <para><varname>NCurrentSessions</varname> and <varname>NCurrentInhibitors</varname> contain the number
 439       of currently registered sessions and inhibitors.</para>
 440
 441       <para>The <varname>BootLoaderEntries</varname> property contains a list of boot loader entries.
 442       This includes boot loader entries defined in configuration and any additional loader entries
 443       reported by the boot loader. See
 444       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 445       for more information.</para>
 446
 447       <para>The <varname>PreparingForShutdown</varname> and <varname>PreparingForSleep</varname> boolean
 448       properties are true during the interval between the two <function>PrepareForShutdown</function> and
 449       <function>PrepareForSleep</function> signals respectively. Note that these properties do not
 450       send out <function>PropertyChanged</function> signals.</para>
 451
 452       <para>The <varname>RebootParameter</varname> property shows the value set with the
 453       <function>SetRebootParameter()</function> method described above.</para>
 454
 455       <para><varname>ScheduledShutdown</varname> shows the value pair set with the
 456       <function>ScheduleShutdown()</function> method described above.</para>
 457
 458       <para><varname>RebootToFirmwareSetup</varname>, <varname>RebootToBootLoaderMenu</varname>, and
 459       <varname>RebootToBootLoaderEntry</varname> are true when the resprective post-reboot operation was
 460       selected with <function>SetRebootToFirmwareSetup</function>,
 461       <function>SetRebootToBootLoaderMenu</function>, or
 462       <function>SetRebootToBootLoaderEntry</function>.</para>
 463
 464       <para>The <varname>WallMessage</varname> and <varname>EnableWallMessages</varname> properties reflect the
 465       shutdown reason and wall message enablement switch which can be set with the
 466       <function>SetWallMessage()</function> method described above.</para>
 467
 468       <para><varname>Docked</varname> is true if the machine is connected to a dock.
 469       <varname>LidClosed</varname> is true when the lid (of a laptop) is closed.
 470       <varname>OnExternalPower</varname> is true when the machine is connected to an external power supply.
 471       </para>
 472     </refsect2>
 473
 474     <refsect2>
 475       <title>Security</title>
 476
 477       <para>A number of operations are protected via the PolicyKit privilege
 478       system. <function>SetUserLinger()</function> requires the
 479       <interfacename>org.freedesktop.login1.set-user-linger</interfacename>
 480       privilege. <function>AttachDevice()</function> requires
 481       <interfacename>org.freedesktop.login1.attach-device</interfacename> and
 482       <function>FlushDevices()</function> requires
 483       <interfacename>org.freedesktop.login1.flush-devices</interfacename>. <function>PowerOff()</function>,
 484       <function>Reboot()</function>, <function>Halt()</function>, <function>Suspend()</function>,
 485       <function>Hibernate()</function> require
 486       <interfacename>org.freedesktop.login1.power-off</interfacename>,
 487       <interfacename>org.freedesktop.login1.power-off-multiple-sessions</interfacename>,
 488       <interfacename>org.freedesktop.login1.power-off-ignore-inhibit</interfacename>,
 489       <interfacename>org.freedesktop.login1.reboot</interfacename>,
 490       <interfacename>org.freedesktop.login1.reboot-multiple-sessions</interfacename>,
 491       <interfacename>org.freedesktop.login1.reboot-ignore-inhibit</interfacename>,
 492       <interfacename>org.freedesktop.login1.halt</interfacename>,
 493       <interfacename>org.freedesktop.login1.halt-multiple-sessions</interfacename>,
 494       <interfacename>org.freedesktop.login1.halt-ignore-inhibit</interfacename>,
 495       <interfacename>org.freedesktop.login1.suspend</interfacename>,
 496       <interfacename>org.freedesktop.login1.suspend-multiple-sessions</interfacename>,
 497       <interfacename>org.freedesktop.login1.suspend-ignore-inhibit</interfacename>,
 498       <interfacename>org.freedesktop.login1.hibernate</interfacename>,
 499       <interfacename>org.freedesktop.login1.hibernate-multiple-sessions</interfacename>,
 500       <interfacename>org.freedesktop.login1.hibernate-ignore-inhibit</interfacename>,
 501       respectively depending on whether there are other sessions around or active inhibits are present.
 502       <function>HybridSleep()</function> and <function>SuspendThenHibernate()</function>
 503       use the same privileges as <function>Hibernate()</function>.
 504       <function>SetRebootParameter()</function> requires
 505       <interfacename>org.freedesktop.login1.set-reboot-parameter</interfacename>.</para>
 506
 507       <para><function>SetRebootToFirmwareSetup</function> requires
 508       <interfacename>org.freedesktop.login1.set-reboot-to-firmware-setup</interfacename>.
 509       <function>SetRebootToBootLoaderMenu</function> requires
 510       <interfacename>org.freedesktop.login1.set-reboot-to-boot-loader-menu</interfacename>.
 511       <function>SetRebootToBootLoaderEntry</function> requires
 512       <interfacename>org.freedesktop.login1.set-reboot-to-boot-loader-entry</interfacename>.
 513       </para>
 514
 515       <para><function>ScheduleShutdown</function> and <function>CancelScheduledShutdown</function> require
 516       the same privileges (listed above) as the immediate poweroff/reboot/halt operations.</para>
 517
 518       <para><function>Inhibit()</function> is protected via one of
 519       <interfacename>org.freedesktop.login1.inhibit-block-shutdown</interfacename>,
 520       <interfacename>org.freedesktop.login1.inhibit-delay-shutdown</interfacename>,
 521       <interfacename>org.freedesktop.login1.inhibit-block-sleep</interfacename>,
 522       <interfacename>org.freedesktop.login1.inhibit-delay-sleep</interfacename>,
 523       <interfacename>org.freedesktop.login1.inhibit-block-idle</interfacename>,
 524       <interfacename>org.freedesktop.login1.inhibit-handle-power-key</interfacename>,
 525       <interfacename>org.freedesktop.login1.inhibit-handle-suspend-key</interfacename>,
 526       <interfacename>org.freedesktop.login1.inhibit-handle-hibernate-key</interfacename>,
 527       <interfacename>org.freedesktop.login1.inhibit-handle-lid-switch</interfacename> depending on the lock
 528       type and mode taken.</para>
 529
 530       <para>The <varname>interactive</varname> boolean parameters can be used to control whether PolicyKit
 531       should interactively ask the user for authentication credentials if required.</para>
 532     </refsect2>
 533   </refsect1>
 534
 535   <refsect1>
 536     <title>Seat Objects</title>
 537
 538     <programlisting>
 539 $ gdbus introspect --system --dest org.freedesktop.login1 \
 540       --object-path /org/freedesktop/login1/seat/seat0
 541
 542 node /org/freedesktop/login1/seat/seat0 {
 543   interface org.freedesktop.login1.Seat {
 544     methods:
 545       Terminate();
 546       ActivateSession(in  s session_id);
 547       SwitchTo(in  u vtnr);
 548       SwitchToNext();
 549       SwitchToPrevious();
 550     properties:
 551       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 552       readonly s Id = '...';
 553       readonly (so) ActiveSession = ...;
 554       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 555       readonly b CanMultiSession = ...;
 556       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 557       readonly b CanTTY = ...;
 558       readonly b CanGraphical = ...;
 559       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 560       readonly a(so) Sessions = [...];
 561       readonly b IdleHint = ...;
 562       readonly t IdleSinceHint = ...;
 563       readonly t IdleSinceHintMonotonic = ...;
 564   };
 565   interface org.freedesktop.DBus.Peer { ... };
 566   interface org.freedesktop.DBus.Introspectable { ... };
 567   interface org.freedesktop.DBus.Properties { ... };
 568 };
 569     </programlisting>
 570
 571     <refsect2>
 572       <title>Methods</title>
 573
 574       <para><function>Terminate()</function> and <function>ActivateSession()</function> work similar to
 575       TerminateSeat(), ActivationSessionOnSeat() on the Manager object.</para>
 576
 577       <para><function>SwitchTo()</function> switches to the session on the virtual terminal
 578       <varname>vtnr</varname>. <function>SwitchToNext()</function> and
 579       <function>SwitchToPrevious()</function> switch to, respectively, the next and previous sessions on the
 580       seat in the order of virtual terminals. If there is no active session, they switch to, respectively,
 581       the first and last session on the seat.</para>
 582     </refsect2>
 583
 584     <refsect2>
 585       <title>Signals</title>
 586
 587       <para>Whenever <function>ActiveSession</function>, <function>Sessions</function>,
 588       <function>CanGraphical</function>, <function>CanMultiSession</function> and <function>CanTTY</function>
 589       or the idle state changes, <function>PropertyChanged</function> signals are sent out to which clients
 590       can subscribe.</para>
 591     </refsect2>
 592
 593     <refsect2>
 594       <title>Properties</title>
 595
 596       <para>The <varname>Id</varname> property encodes the ID of the seat.</para>
 597
 598       <para><varname>ActiveSession</varname> encodes the currently active session if there is one. It is a
 599       structure consisting of the session id and the object path.</para>
 600
 601       <para><varname>CanMultiSession</varname> encodes whether the session is multi-session capable,
 602       <varname>CanTTY</varname> whether it is suitable for text logins, <varname>CanGraphical</varname>
 603       whether it is suitable for graphical sessions.</para>
 604
 605       <para>The <varname>Sessions</varname> property is an array of all current sessions of this seat, each
 606       encoded in a structure consisting of the ID and the object path.</para>
 607
 608       <para>The <varname>IdleHint</varname>, <varname>IdleSinceHint</varname>, and
 609       <varname>IdleSinceHint</varname> properties encode the idle state, similar to the one exposed on the
 610       Manager object, but specific for this seat.</para>
 611     </refsect2>
 612   </refsect1>
 613
 614   <refsect1>
 615     <title>User Objects</title>
 616
 617     <programlisting>
 618 $ gdbus introspect --system --dest org.freedesktop.login1 \
 619         --object-path /org/freedesktop/login1/user/_1000
 620
 621 node /org/freedesktop/login1/user/_1000 {
 622   interface org.freedesktop.login1.User {
 623     methods:
 624       Terminate();
 625       Kill(in  i signal_number);
 626     properties:
 627       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 628       readonly u UID = ...;
 629       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 630       readonly u GID = ...;
 631       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 632       readonly s Name = '...';
 633       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 634       readonly t Timestamp = ...;
 635       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 636       readonly t TimestampMonotonic = ...;
 637       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 638       readonly s RuntimePath = '...';
 639       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 640       readonly s Service = '...';
 641       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 642       readonly s Slice = '...';
 643       readonly (so) Display = ...;
 644       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 645       readonly s State = '...';
 646       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 647       readonly a(so) Sessions = [...];
 648       readonly b IdleHint = ...;
 649       readonly t IdleSinceHint = ...;
 650       readonly t IdleSinceHintMonotonic = ...;
 651       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 652       readonly b Linger = ...;
 653   };
 654   interface org.freedesktop.DBus.Peer { ... };
 655   interface org.freedesktop.DBus.Introspectable { ... };
 656   interface org.freedesktop.DBus.Properties { ... };
 657 };
 658     </programlisting>
 659
 660     <refsect2>
 661       <title>Methods</title>
 662
 663       <para><function>Terminate()</function> and <function>Kill()</function> work similar to the
 664       <function>TerminateUser()</function> and <function>KillUser()</function> methods on the manager
 665       object.</para>
 666     </refsect2>
 667
 668     <refsect2>
 669       <title>Signals</title>
 670
 671       <para>Whenever <varname>Sessions</varname> or the idle state changes,
 672       <function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para>
 673     </refsect2>
 674
 675     <refsect2>
 676       <title>Properties</title>
 677
 678       <para>The <varname>UID</varname> and <varname>GID</varname> properties encode the Unix UID and primary
 679       GID of the user.</para>
 680
 681       <para>The <varname>Name</varname> property encodes the user name.</para>
 682
 683       <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> encode the login time of
 684       the user in microseconds since the epoch, in the <constant>CLOCK_REALTIME</constant> and
 685       <constant>CLOCK_MONOTONIC</constant> clocks, respectively.</para>
 686
 687       <para><varname>RuntimePath</varname> encodes the runtime path of the user,
 688       i.e. <varname>$XDG_RUNTIME_DIR</varname>. For details see the
 689       <ulink url="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">
 690         XDG Basedir Specification
 691       </ulink>.</para>
 692
 693       <para><varname>Service</varname> contains the unit name of the user systemd service of this
 694       user. Each logged in user is assigned a user service that runs a user systemd instance. This is
 695       usually an instance of <filename>user@.service</filename>.</para>
 696
 697       <para><varname>Slice</varname> contains the unit name of the user systemd slice of this user. Each
 698       logged in user gets a private slice.</para>
 699
 700       <para><varname>Display</varname> encodes which graphical session should be used as the primary UI display
 701       for the user. It is a structure encoding the session ID and the object path of the session to use.</para>
 702
 703       <para><varname>State</varname> encodes the user state and is one of <literal>offline</literal>,
 704       <literal>lingering</literal>, <literal>online</literal>, <literal>active</literal>, or
 705       <literal>closing</literal>. See
 706       <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 707       for more information about the states.</para>
 708
 709       <para><varname>Sessions</varname> is an array of structures encoding all current sessions of the
 710       user. Each structure consists of the ID and object path.</para>
 711
 712       <para>The <varname>IdleHint</varname>, <varname>IdleSinceHint</varname>, and
 713       <varname>IdleSinceHintMonotonic</varname> properties encode the idle hint state of the user, similar to
 714       the <interfacename>Manager</interfacename>'s properties, but specific for this user.</para>
 715
 716       <para>The <varname>Linger</varname> property shows whether lingering is enabled for this user.</para>
 717     </refsect2>
 718   </refsect1>
 719
 720   <refsect1>
 721     <title>Session Objects</title>
 722
 723     <programlisting>
 724 $ gdbus introspect --system --dest org.freedesktop.login1 \
 725         --object-path /org/freedesktop/login1/session/45
 726
 727 node /org/freedesktop/login1/session/45 {
 728   interface org.freedesktop.login1.Session {
 729     methods:
 730       Terminate();
 731       Activate();
 732       Lock();
 733       Unlock();
 734       SetIdleHint(in  b idle);
 735       SetLockedHint(in  b locked);
 736       Kill(in  s who,
 737            in  i signal_number);
 738       TakeControl(in  b force);
 739       ReleaseControl();
 740       TakeDevice(in  u major,
 741                  in  u minor,
 742                  out h fd,
 743                  out b inactive);
 744       ReleaseDevice(in  u major,
 745                     in  u minor);
 746       PauseDeviceComplete(in  u major,
 747                           in  u minor);
 748       SetBrightness(in  s subsystem,
 749                     in  s name,
 750                     in  u brightness);
 751     signals:
 752       PauseDevice(u major,
 753                   u minor,
 754                   s type);
 755       ResumeDevice(u major,
 756                    u minor,
 757                    h fd);
 758       Lock();
 759       Unlock();
 760     properties:
 761       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 762       readonly s Id = '...';
 763       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 764       readonly (uo) User = ...;
 765       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 766       readonly s Name = '...';
 767       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 768       readonly t Timestamp = ...;
 769       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 770       readonly t TimestampMonotonic = ...;
 771       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 772       readonly u VTNr = ...;
 773       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 774       readonly (so) Seat = ...;
 775       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 776       readonly s TTY = '...';
 777       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 778       readonly s Display = '...';
 779       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 780       readonly b Remote = ...;
 781       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 782       readonly s RemoteHost = '...';
 783       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 784       readonly s RemoteUser = '...';
 785       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 786       readonly s Service = '...';
 787       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 788       readonly s Desktop = '...';
 789       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 790       readonly s Scope = '...';
 791       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 792       readonly u Leader = ...;
 793       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 794       readonly u Audit = ...;
 795       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 796       readonly s Type = '...';
 797       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 798       readonly s Class = '...';
 799       readonly b Active = ...;
 800       readonly s State = '...';
 801       readonly b IdleHint = ...;
 802       readonly t IdleSinceHint = ...;
 803       readonly t IdleSinceHintMonotonic = ...;
 804       readonly b LockedHint = ...;
 805   };
 806   interface org.freedesktop.DBus.Peer { ... };
 807   interface org.freedesktop.DBus.Introspectable { ... };
 808   interface org.freedesktop.DBus.Properties { ... };
 809 };
 810     </programlisting>
 811
 812     <refsect2>
 813       <title>Methods</title>
 814
 815       <para><function>Terminate()</function>, <function>Activate()</function>, <function>Lock()</function>,
 816       <function>Unlock()</function>, and <function>Kill()</function> work similarly to the respective calls on
 817       the <interfacename>Manager</interfacename> object.</para>
 818
 819       <para><function>SetIdleHint()</function> is called by the session object to update the idle state
 820       of the session whenever it changes.</para>
 821
 822       <para><function>TakeControl()</function> allows a process to take exclusive managed device
 823       access-control for that session. Only one D-Bus connection can be a controller for a given session at any
 824       time. If the <varname>force</varname> argument is set (root only), an existing controller is kicked
 825       out and replaced. Otherwise, this method fails if there is already a controller. Note that this method is
 826       limited to D-Bus users with the effective UID set to the user of the session or root.</para>
 827
 828       <para><function>ReleaseControl()</function> drops control of a given session. Closing the
 829       D-Bus connection implicitly releases control as well. See <function>TakeControl()</function> for more information. This
 830       method also releases all devices for which the controller requested ownership via <function>TakeDevice()</function>.
 831       </para>
 832
 833       <para><function>TakeDevice()</function> allows a session controller to get a file descriptor for a
 834       specific device. Pass in the major and minor numbers of the character device and
 835       <filename>systemd-logind</filename> will return a file descriptor for the device. Only a limited set of
 836       device-types is currently supported (but may be extended). <filename>systemd-logind</filename>
 837       automatically mutes the file descriptor if the session is inactive and resumes it once the session is
 838       activated again. This guarantees that a session can only access session devices if the session is
 839       active. Note that this revoke/resume mechanism is asynchronous and may happen at any given time.  This
 840       only works on devices that are attached to the seat of the given session. A process is not required to
 841       have direct access to the device node. <filename>systemd-logind</filename> only requires you to be the
 842       active session controller (see <function>TakeControl()</function>). Also note that any device can only
 843       be requested once. As long as you don't release it, further <function>TakeDevice()</function> calls
 844       will fail.</para>
 845
 846       <para><function>ReleaseDevice()</function> releases a device again (see
 847       <function>TakeDevice()</function>). This is also implicitly done by
 848       <function>ReleaseControl()</function> or when closing the D-Bus connection.</para>
 849
 850       <para><function>PauseDeviceComplete()</function> allows a session controller to synchronously pause a
 851       device after receiving a <function>PauseDevice(<literal>pause</literal>)</function> signal. Forced
 852       signals (or after an internal timeout) are automatically completed by
 853       <filename>systemd-logind</filename> asynchronously.</para>
 854
 855       <para><function>SetLockedHint()</function> may be used to set the "idle hint" to
 856       <varname>locked</varname>, i.e. information whether the session is locked. This is intended to be used
 857       by the desktop environment to tell <command>systemd-logind</command> when the session is locked and
 858       unlocked.</para>
 859
 860       <para><function>SetBrightness()</function> may be used to set the display brightness. This is intended
 861       to be used by the desktop environment and allows unprivileged programs to access hardware settings in
 862       a controlled way. The <varname>subsystem</varname> parameter specifies a kernel subsystem, either
 863       <literal>backlight</literal> or <literal>leds</literal>. The <varname>name</varname> parameter
 864       specifies a device name under the specified subsystem. The <varname>brightness</varname> parameter
 865       specifies the brightness. The range is defined by individual drivers, see
 866       <filename>/sys/class/<varname>subsystem</varname>/<varname>name</varname>/max_brightness</filename>.
 867       </para>
 868     </refsect2>
 869
 870     <refsect2>
 871       <title>Signals</title>
 872
 873       <para>The active session controller exclusively gets <function>PauseDevice</function> and
 874       <function>ResumeDevice</function> events for any device it requested via
 875       <function>TakeDevice()</function>. They notify the controller whenever a device is paused or resumed. A
 876       device is never resumed if its session is inactive. Also note that <function>PauseDevice</function>
 877       signals are sent before the <function>PropertyChanged</function> signal for the
 878       <function>Active</function> state. The inverse is true for <function>ResumeDevice</function>. A device
 879       may remain paused for unknown reasons even though the <interfacename>Session</interfacename> is active.
 880       </para>
 881
 882       <para>A <function>PauseDevice</function> signal carries the major and minor numbers and a string describing the
 883       type as arguments. <function>force</function> means the device was already paused by
 884       <filename>systemd-logind</filename> and the signal is only an asynchronous
 885       notification. <function>pause</function> means <filename>systemd-logind</filename> grants you a limited amount of time to pause the device. You must respond to this via
 886       <function>PauseDeviceComplete()</function>. This synchronous pausing mechanism is used for
 887       backwards-compatibility to VTs and <filename>systemd-logind</filename> is free to not make use of
 888       it. It is also free to send a forced <function>PauseDevice</function> if you don't respond in a timely
 889       manner (or for any other reason). <function>gone</function> means the device was unplugged from the
 890       system and you will no longer get any notifications about it. There is no need to call
 891       <function>ReleaseDevice()</function>. You may call <function>TakeDevice()</function> again if a new
 892       device is assigned the major+minor combination.</para>
 893
 894       <para><function>ResumeDevice</function> is sent whenever a session is active and a device is
 895       resumed. It carries the major/minor numbers as arguments and provides a new open file descriptor. You should
 896       switch to the new descriptor and close the old one. They are not guaranteed to have the same underlying
 897       open file descriptor in the kernel (except for a limited set of device types).</para>
 898
 899       <para>Whenever <function>Active</function> or the idle state changes,
 900       <function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para>
 901
 902       <para><function>Lock</function>/<function>Unlock</function> is sent when the session is asked to be
 903       screen-locked/unlocked. A session manager of the session should listen to this signal and act
 904       accordingly. This signal is sent out as a result of the <function>Lock()</function> and
 905       <function>Unlock()</function> methods, respectively.</para>
 906     </refsect2>
 907
 908     <refsect2>
 909       <title>Properties</title>
 910
 911       <para><varname>Id</varname> encodes the session ID.</para>
 912
 913       <para><varname>User</varname> encodes the user ID of the user this session belongs to. This is a
 914       structure consisting of the Unix UID and the object path.</para>
 915
 916       <para><varname>Name</varname> encodes the user name.</para>
 917
 918       <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> encode the microseconds
 919       since the epoch when the session was created, in <constant>CLOCK_REALTIME</constant> or
 920       <constant>CLOCK_MONOTONIC</constant>, respectively.</para>
 921
 922       <para><varname>VTNr</varname> encodes the virtual terminal number of the session if there is any, 0
 923       otherwise.</para>
 924
 925       <para><varname>Seat</varname> encodes the seat this session belongs to if there is any. This is a
 926       structure consisting of the ID and the seat object path.</para>
 927
 928       <para><varname>TTY</varname> encodes the kernel TTY path of the session if this is a text login. If not
 929       this is an empty string.</para>
 930
 931       <para><varname>Display</varname> encodes the X11 display name if this is a graphical login. If not,
 932       this is an empty string.</para>
 933
 934       <para><varname>Remote</varname> encodes whether the session is local or remote.</para>
 935
 936       <para><varname>RemoteHost</varname> and <varname>RemoteUser</varname> encode the remote host and user
 937       if this is a remote session, or an empty string otherwise.</para>
 938
 939       <para><varname>Service</varname> encodes the PAM service name that registered the session.</para>
 940
 941       <para><varname>Desktop</varname> describes the desktop environment running in the session (if
 942       known).</para>
 943
 944       <para><varname>Scope</varname> contains the systemd scope unit name of this session.</para>
 945
 946       <para><varname>Leader</varname> encodes the PID of the process that registered the session.</para>
 947
 948       <para><varname>Audit</varname> encodes the Kernel Audit session ID of the session if auditing is
 949       available.</para>
 950
 951       <para><varname>Type</varname> encodes the session type. It's one of <literal>unspecified</literal> (for
 952       cron PAM sessions and suchlike), <literal>tty</literal> (for text logins) or
 953       <literal>x11</literal>/<literal>mir</literal>/<literal>wayland</literal> (for graphical logins).</para>
 954
 955       <para><varname>Class</varname> encodes the session class. It's one of <literal>user</literal> (for
 956       normal user sessions), <literal>greeter</literal> (for display manager pseudo-sessions), or
 957       <literal>lock-screen</literal> (for display lock screens).</para>
 958
 959       <para><varname>Active</varname> is a boolean that is true if the session is active, i.e. currently in the
 960       foreground. This field is semi-redundant due to <varname>State</varname>.</para>
 961
 962       <para><varname>State</varname> encodes the session state and one of <literal>online</literal>,
 963       <literal>active</literal>, or <literal>closing</literal>. See
 964       <citerefentry><refentrytitle>sd_session_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 965       for more information about the states.</para>
 966
 967       <para><varname>IdleHint</varname>, <varname>IdleSinceHint</varname>, and
 968       <varname>IdleSinceHintMonotonic</varname> encapsulate the idle hint state of this session, similarly to
 969       how the respective properties on the manager object do it for the whole system.</para>
 970
 971       <para><varname>LockedHint</varname> shows the locked hint state of this session, as set by the
 972       <function>SetLockedHint()</function> method described above.</para>
 973     </refsect2>
 974   </refsect1>
 975
 976   <refsect1>
 977     <title>Versioning</title>
 978
 979     <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
 980     the usual interface versioning guidelines</ulink>.</para>
 981   </refsect1>
 982 </refentry>