path: root/man/org.freedesktop.login1.xml

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
<!-- SPDX-License-Identifier: LGPL-2.1+ -->

<refentry id="org.freedesktop.login1" conditional='ENABLE_LOGIND'
    xmlns:xi="http://www.w3.org/2001/XInclude">
  <refentryinfo>
    <title>org.freedesktop.login1</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>org.freedesktop.login1</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>org.freedesktop.login1</refname>
    <refpurpose>The D-Bus interface of systemd-logind</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Introduction</title>

    <para><citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    is a system service that keeps track of user logins and seats in various ways.</para>

    <para>The daemon provides both a C library interface as well as a D-Bus interface. The library interface
    may be used to introspect and watch the state of user logins and seats. The bus interface provides the
    same, but in addition may also be used to make changes to system state. For more information please
    consult <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
    </para>
  </refsect1>

  <refsect1>
    <title>The Manager Object</title>

    <para>The service exposes the following interfaces on the Manager object on the bus:</para>

    <programlisting>
$ gdbus introspect --system \
        --dest org.freedesktop.login1 \
        --object-path /org/freedesktop/login1
node /org/freedesktop/login1 {
  interface org.freedesktop.login1.Manager {
    methods:
      GetSession(in  s session_id,
                 out o object_path);
      GetSessionByPID(in  u pid,
                      out o object_path);
      GetUser(in  u uid,
              out o object_path);
      GetUserByPID(in  u pid,
                   out o object_path);
      GetSeat(in  s seat_id,
              out o object_path);
      ListSessions(out a(susso) session_list);
      ListUsers(out a(uso) user_list);
      ListSeats(out a(so) seat_list);
      ListInhibitors(out a(ssssuu) inhibitor_list);
      CreateSession(in  u uid,
                    in  u pid,
                    in  s service,
                    in  s type,
                    in  s class,
                    in  s desktop,
                    in  s seat_id,
                    in  u vtnr,
                    in  s tty,
                    in  s display,
                    in  b remote,
                    in  s remote_user,
                    in  s remote_host,
                    in  a(sv) properties,
                    out s session_id,
                    out o object_path,
                    out s runtime_path,
                    out h fifo_fd,
                    out u uid,
                    out s seat_id,
                    out u vtnr,
                    out b existing);
      ReleaseSession(in  s session_id);
      ActivateSession(in  s session_id);
      ActivateSessionOnSeat(in  s session_id,
                            in  s seat_id);
      LockSession(in  s session_id);
      UnlockSession(in  s session_id);
      LockSessions();
      UnlockSessions();
      KillSession(in  s session_id,
                  in  s who,
                  in  i signo);
      KillUser(in  u uid,
               in  i signo);
      TerminateSession(in  s session_id);
      TerminateUser(in  u uid);
      TerminateSeat(in  s seat_id);
      SetUserLinger(in  u uid,
                    in  b linger,
                    in  b interactive);
      AttachDevice(in  s seat_id,
                   in  s sysfs,
                   in  b interactive);
      FlushDevices(in  b interactive);
      PowerOff(in  b interactive);
      Reboot(in  b interactive);
      Suspend(in  b interactive);
      Hibernate(in  b interactive);
      HybridSleep(in  b interactive);
      CanPowerOff(out s result);
      CanReboot(out s result);
      CanSuspend(out s result);
      CanHibernate(out s result);
      CanHybridSleep(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);
      CanRebootToFirmwareSetup(out s result);
      SetRebootToFirmwareSetup(in  b enable);
      SetWallMessage(in  s wall_message,
                     in  b enable);
    signals:
      SessionNew(s session_id,
                 o object_path);
      SessionRemoved(s session_id,
                     o object_path);
      UserNew(u uid,
              o object_path);
      UserRemoved(u uid,
                  o object_path);
      SeatNew(s seat_id,
              o object_path);
      SeatRemoved(s seat_id,
                  o object_path);
      PrepareForShutdown(b start);
      PrepareForSleep(b start);
    properties:
      readwrite b EnableWallMessages = false;
      readwrite s WallMessage = '';
      readonly u NAutoVTs = 6;
      readonly as KillOnlyUsers = [];
      readonly as KillExcludeUsers = ['root'];
      readonly b KillUserProcesses = false;
      readonly b RebootToFirmwareSetup = false;
      readonly b IdleHint = false;
      readonly t IdleSinceHint = 0;
      readonly t IdleSinceHintMonotonic = 0;
      readonly s BlockInhibited = 'handle-power-key:handle-suspend-key:handle-hibernate-key';
      readonly s DelayInhibited = 'sleep';
      readonly t InhibitDelayMaxUSec = 5000000;
      readonly s HandlePowerKey = 'poweroff';
      readonly s HandleSuspendKey = 'suspend';
      readonly s HandleHibernateKey = 'hibernate';
      readonly s HandleLidSwitch = 'suspend';
      readonly s HandleLidSwitchDocked = 'ignore';
      readonly t HoldoffTimeoutUSec = 30000000;
      readonly s IdleAction = 'ignore';
      readonly t IdleActionUSec = 1800000000;
      readonly b PreparingForShutdown = false;
      readonly b PreparingForSleep = false;
      readonly (st) ScheduledShutdown = ('', 0);
      readonly b Docked = false;
  };
  interface org.freedesktop.DBus.Peer {
  };
  interface org.freedesktop.DBus.Introspectable {
  };
  interface org.freedesktop.DBus.Properties {
  };
};
    </programlisting>

    <refsect2>
      <title>Security</title>

      <para>A number of operations are protected via the PolicyKit privilege
      system. <function>SetUserLinger()</function> requires the
      <interfacename>org.freedesktop.login1.set-user-linger</interfacename>
      privilege. <function>AttachDevice()</function> requires
      <interfacename>org.freedesktop.login1.attach-device</interfacename> and
      <function>FlushDevices()</function>
      <interfacename>org.freedesktop.login1.flush-devices</interfacename>. <function>PowerOff()</function>,
      <function>Reboot()</function>, <function>Suspend()</function>, <function>Hibernate()</function>,
      <function>HybridSleep()</function> require
      <interfacename>org.freedesktop.login1.power-off</interfacename>,
      <interfacename>org.freedesktop.login1.power-off-multiple-sessions</interfacename>,
      <interfacename>org.freedesktop.login1.power-off-ignore-inhibit</interfacename>,
      <interfacename>org.freedesktop.login1.reboot</interfacename>,
      <interfacename>org.freedesktop.login1.reboot-multiple-sessions</interfacename>,
      <interfacename>org.freedesktop.login1.reboot-ignore-inhibit</interfacename>,
      <interfacename>org.freedesktop.login1.suspend</interfacename>,
      <interfacename>org.freedesktop.login1.suspend-multiple-sessions</interfacename>,
      <interfacename>org.freedesktop.login1.suspend-ignore-inhibit</interfacename>,
      <interfacename>org.freedesktop.login1.hibernate</interfacename>,
      <interfacename>org.freedesktop.login1.hibernate-multiple-sessions</interfacename>,
      respectively.
      <interfacename>org.freedesktop.login1.hibernate-ignore-inhibit</interfacename>, depending whether
      there are other sessions around or active inhibits. <function>Inhibit()</function> is protected via
      either one of <interfacename>org.freedesktop.login1.inhibit-block-shutdown</interfacename>,
      <interfacename>org.freedesktop.login1.inhibit-delay-shutdown</interfacename>,
      <interfacename>org.freedesktop.login1.inhibit-block-sleep</interfacename>,
      <interfacename>org.freedesktop.login1.inhibit-delay-sleep</interfacename>,
      <interfacename>org.freedesktop.login1.inhibit-block-idle</interfacename>,
      <interfacename>org.freedesktop.login1.inhibit-handle-power-key</interfacename>,
      <interfacename>org.freedesktop.login1.inhibit-handle-suspend-key</interfacename>,
      <interfacename>org.freedesktop.login1.inhibit-handle-hibernate-key</interfacename>,
      <interfacename>org.freedesktop.login1.inhibit-handle-lid-switch</interfacename> depending on the lock
      type and mode taken.</para>

      <para>The <varname>user_interaction</varname> boolean parameters can be used to control whether
      PolicyKit should interactively ask the user for authentication credentials if it needs to.</para>
    </refsect2>

    <refsect2>
      <title>Methods</title>

      <para><function>GetSession()</function> may be used to get the session object path for the session with
      the specified ID. Similarly, <function>GetUser()</function> and <function>GetSeat()</function> get the
      user and seat objects, respectively. <function>GetSessionByPID()</function> and
      <function>GetUserByPID()</function> get the session/user object the specified PID belongs to if there
      is any.</para>

      <para><function>ListSessions()</function> returns an array with all current sessions. The structures in
      the array consist of the following fields: session id, user id, user name, seat id, session object
      path. If a session does not have a seat attached the seat id field will be an empty string.</para>

      <para><function>ListUsers()</function> returns an array with all currently logged in users. The
      structures in the array consist of the following fields: user id, user name, user object path.</para>

      <para><function>ListSeats()</function> returns an array with all currently available seats. The
      structure in the array consists of the following fields: seat id, seat object path.</para>

      <para><function>CreateSession()</function> and <function>ReleaseSession()</function> may be used to
      open or close login sessions. These calls should <emphasis>never</emphasis> be invoked directly by
      clients. Creating/closing sessions is exclusively the job of PAM and its
      <citerefentry><refentrytitle>pam_systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      module.</para>

      <para><function>ActivateSession()</function> brings the session with the specified ID into the
      foreground. <function>ActivateSessionOnSeat()</function> does the same, but only if the seat id
      matches.</para>

      <para><function>LockSession()</function> asks the session with the specified ID to activate the screen
      lock. <function>UnlockSession()</function> asks the session with the specified ID to remove an active
      screen lock, if there is any. This is implemented by sending out the Lock() and Unlock() signals from
      the respective session object which session managers are supposed to listen on.</para>

      <para><function>LockSessions()</function> asks all sessions to activate the screen locks. This may be
      used to lock any access to the machine in one action. Similarly, <function>UnlockSessions()</function>
      asks all sessions to deactivate their screen locks.</para>

      <para><function>KillSession()</function> may be used to send a Unix signal to one or all processes of a
      session. As arguments it takes the session id, either the string <literal>leader</literal> or
      <literal>all</literal> and a signal number. If <literal>leader</literal> is passed only the session
      <literal>leader</literal> is killed. If <literal>all</literal> is passed all processes of the session
      are killed.</para>

      <para><function>KillUser()</function> may be used to send a Unix signal to all processes of a user. As
      argument it takes the user id and a signal number.</para>

      <para><function>TerminateSession()</function>, <function>TerminateUser()</function>,
      <function>TerminateSeat()</function> may be used to forcibly terminate one specific session, all
      processes of a user, and all sessions attached to a specific seat, respectively. The session, user,
      and seat are identified by their respective IDs.</para>

      <para><function>SetUserLinger()</function> enables or disables user lingering. If enabled the runtime
      directory of a user is kept around and he may continue to run processes while he is logged out. If
      disabled the runtime directory goes away as soon as he logs out. Expects three arguments: the UID, a
      boolean whether to enable/disable and a boolean controlling the PolicyKit authorization interactivity
      (see above). Note that the user linger state is persistently stored on disk.</para>

      <para><function>AttachDevice()</function> may be used to assign a specific device to a specific
      seat. The device is identified by its /sys path, and must be eligible for seat assignments. Takes three
      arguments: the seat id, the sysfs path, and a boolean for controlling PolicyKit interactivity (see
      above). Device assignments are persistently stored to disk. To create a new seat, simply specify a
      previously unused seat id. For more information about the seat assignment logic see
      <ulink url="https://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat for Linux</ulink>.
      </para>

      <para><function>FlushDevices()</function> removes all explicit seat assignments for devices, resetting
      all assignments to the automatic defaults. The only argument this takes is the PolicyKit interactivity
      boolean (see above).</para>

      <para><function>PowerOff()</function>, <function>Reboot()</function>, <function>Suspend()</function>,
      <function>Hibernate()</function>, <function>HybridSleep()</function> results in the system being
      powered off, rebooted, suspend, hibernated or hibernated+suspended. The only argument is the PolicyKit
      interactivity boolean (see above). The main purpose of these calls is that they enforce PolicyKit
      policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged users. They
      also enforce inhibition locks. UIs should expose these calls as primary mechanism to
      poweroff/reboot/suspend/hibernate/hybrid-sleep the machine.</para>

      <para><function>CanPowerOff()</function>, <function>CanReboot()</function>,
      <function>CanSuspend()</function>, <function>CanHibernate()</function>,
      <function>CanHybridSleep()</function> tests whether the system supports the respective operation and
      whether the calling user is eligible for the desired operation. Returns one of <literal>na</literal>,
      <literal>yes</literal>, <literal>no</literal> or <literal>challenge</literal>. If <literal>na</literal>
      is returned the operation is not available because hardware, kernel or drivers do not support it. If
      <literal>yes</literal> is returned the operation is supported and the user may execute the operation
      without further authentication. If <literal>no</literal> is returned the operation is available but the
      user is not allowed to execute the operation. If <literal>challenge</literal> is returned the operation
      is available, but only after authorization.</para>

      <para><function>Inhibit()</function> creates an inhibition lock. It takes four parameters:
      <varname>What</varname>, <varname>Who</varname>, <varname>Why</varname>, and
      <varname>Mode</varname>. <varname>What</varname> is one or more of <literal>shutdown</literal>,
      <literal>sleep</literal>, <literal>idle</literal>, <literal>handle-power-key</literal>,
      <literal>handle-suspend-key</literal>, <literal>handle-hibernate-key</literal>,
      <literal>handle-lid-switch</literal>, separated by colons, for inhibiting poweroff/reboot,
      suspend/hibernate, the automatic idle logic, or hardware key handling. <varname>Who</varname> should be
      a short human readable string identifying the application taking the lock. <varname>Why</varname>
      should be a short human readable string identifying the reason why the lock is taken. Finally,
      <varname>Mode</varname> is either <literal>block</literal> or <literal>delay</literal> which encodes
      whether the inhibit shall be consider mandatory or whether it should just delay the operation to a
      certain maximum time. The call returns a file descriptor. The lock is released the moment this file
      descriptor (and all its duplicates) are closed. For more information on the inhibition logic see
      <ulink url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks</ulink>.
      </para>

      <para><function>ListInhibitors()</function> lists all currently active inhibitors. Returns an array of
      structures consisting of what, who, why, mode, user ID and process ID.</para>
    </refsect2>

    <refsect2>
      <title>Signals</title>

      <para>Whenever the inhibition state or idle hint changes daemon <function>PropertyChanged</function>
      signals are sent out to which clients can subscribe.</para>

      <para>The <function>SessionNew()</function>, <function>SessionRemoved()</function>,
      <function>UserNew()</function>, <function>UserRemoved()</function>, <function>SeatNew()</function>,
      <function>SeatRemoved()</function> signals are sent each time a session is created or removed, a user
      logs in or out, or a seat is added or removed. They each contain the ID of the object plus the object
      path.</para>

      <para>The <function>PrepareForShutdown()</function> and <function>PrepareForSleep()</function> signals
      are sent right before (with the argument <literal>true</literal>) and after (with the argument
      <literal>false</literal>) the system goes down for reboot/poweroff and suspend/hibernate,
      respetively. This may be used by applications to save data on disk, release memory, or do other jobs
      that shall be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks. After
      completion of this work they should release their inhibition locks in order not to delay the operation
      any further. For more information see
      <ulink url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks</ulink>.
      </para>
    </refsect2>

    <refsect2>
      <title>Properties</title>

      <para>Most properties simply reflect the configuration stored in logind.conf. For more information,
      see
      <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
      </para>

      <para>The <function>IdleHint</function> property reflects the idle hint state of the system. If the
      system is idle it might get into automatic suspend or shutdown, depending on configuration.</para>

      <para><function>IdleSinceHint</function> and <function>IdleSinceHintMonotonic</function> encode the
      timestamps of the last change of the idle hint boolean, in <constant>CLOCK_REALTIME</constant> and
      <constant>CLOCK_MONOTONIC</constant> timestamps, respectively, in microseconds since the epoch.</para>

      <para>The <function>BlockInhibited</function> and <function>DelayInhibited</function> properties encode
      the currently active locks of the respective modes. They are colon separated lists of
      <literal>shutdown</literal>, <literal>sleep</literal>, <literal>idle</literal> (see above).</para>

      <para>The <function>PreparingForShutdown</function> and <function>PreparingForSleep</function> boolean
      properties are true between the time when the two <function>PrepareForShutdown</function> and
      <function>PrepareForSleep</function> signals are sent, respectively. Note that these properties do not
      send out <function>PropertyChanged</function> signals.</para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Seat Objects</title>

    <programlisting>
$ gdbus introspect --system --dest org.freedesktop.login1 \
      --object-path /org/freedesktop/login1/seat/seat0
node /org/freedesktop/login1/seat/seat0 {
  interface org.freedesktop.login1.Seat {
    methods:
      Terminate();
      ActivateSession(in  s session_id);
      SwitchTo(in  u vtnr);
      SwitchToNext();
      SwitchToPrevious();
    properties:
      readonly s Id = 'seat0';
      readonly (so) ActiveSession = ('', '/');
      readonly b CanMultiSession = true;
      readonly b CanTTY = true;
      readonly b CanGraphical = true;
      readonly a(so) Sessions = [('c1', '/org/freedesktop/login1/session/c1')];
      readonly b IdleHint = true;
      readonly t IdleSinceHint = 1389368976087311;
      readonly t IdleSinceHintMonotonic = 48213948;
  };
  interface org.freedesktop.DBus.Properties {
  };
  interface org.freedesktop.DBus.Peer {
  };
  interface org.freedesktop.DBus.Introspectable {
  };
};
    </programlisting>

    <refsect2>
      <title>Methods</title>

      <para><function>Terminate()</function> and <function>ActivateSession()</function> work similar to
      TerminateSeat(), ActivationSessionOnSeat() on the Manager object.</para>
    </refsect2>

    <refsect2>
      <title>Signals</title>

      <para>Whenever <function>ActiveSession</function>, <function>Sessions</function>,
      <function>CanGraphical</function>, <function>CanMultiSession</function> and <function>CanTTY</function>
      or the idle state changes <function>PropertyChanged</function> signals are sent out to which clients
      can subscribe.</para>
    </refsect2>

    <refsect2>
      <title>Properties</title>

      <para>The <varname>Id</varname> property encodes the ID of the seat.</para>

      <para><varname>ActiveSession</varname> encodes the currently active session if there is one. It is a
      structure consisting of session id and object path.</para>

      <para><varname>CanMultiSession</varname> encodes whether the session is multi-session capable, CanTTY
      whether it is suitable for text logins, CanGraphical whether it is suitable for graphical sessions.</para>

      <para>The <varname>Sessions</varname> array is an array of all current sessions of this seat, each
      encoded in a structure consisting of the ID and the object path.</para>

      <para>The <varname>IdleHint</varname>, <varname>IdleSinceHint</varname>,
      <varname>IdleSinceHint</varname> properties encode the idle state, similar to the one exposed on the
      Manager object, but specific for this seat.</para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>User Objects</title>

    <programlisting>
$ gdbus introspect --system --dest org.freedesktop.login1 \
        --object-path /org/freedesktop/login1/user/_1000

node /org/freedesktop/login1/user/_1000 {
  interface org.freedesktop.login1.User {
    methods:
      Terminate();
      Kill(in  i signo);
    properties:
      readonly u UID = 1000;
      readonly u GID = 1000;
      readonly s Name = 'test';
      readonly t Timestamp = 1389368964102424;
      readonly t TimestampMonotonic = 36229061;
      readonly s RuntimePath = '/run/user/1000';
      readonly s Service = 'user@1000.service';
      readonly s Slice = 'user-1000.slice';
      readonly (so) Display = ('', '/');
      readonly s State = 'active';
      readonly a(so) Sessions = [('28', '/org/freedesktop/login1/session/_328'), ('3', '/org/freedesktop/login1/session/_33')];
      readonly b IdleHint = false;
      readonly t IdleSinceHint = 0;
      readonly t IdleSinceHintMonotonic = 0;
      readonly b Linger = false;
  };
  interface org.freedesktop.DBus.Properties {
  };
  interface org.freedesktop.DBus.Peer {
  };
  interface org.freedesktop.DBus.Introspectable {
  };
};
    </programlisting>

    <refsect2>
      <title>Methods</title>

      <para><function>Terminate()</function> and <function>Kill()</function> work similar to the
      <function>TerminateUser()</function> and <function>KillUser()</function> calls on the manager
      object.</para>
    </refsect2>

    <refsect2>
      <title>Signals</title>

      <para>Whenever <varname>Sessions</varname> or the idle state changes
      <function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para>
    </refsect2>

    <refsect2>
      <title>Properties</title>

      <para>The <varname>UID</varname> and <varname>GID</varname> properties encode the Unix UID and primary
      GID of the user.</para>

      <para>The <varname>Name</varname> property encodes the user name.</para>

      <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> encode the login time of
      the user in usec since the epoch, in the <constant>CLOCK_REALTIME</constant> and
      <constant>CLOCK_MONOTONIC</constant> clocks, respectively.</para>

      <para><varname>RuntimePath</varname> encodes the runtime path of the user,
      i.e. <varname>$XDG_RUNTIME_DIR</varname>, for details see the
      <ulink url="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">
        XDG Basedir Specification
      </ulink>.</para>

      <para><varname>Service</varname> contains the name of the user systemd service unit name of this
      user. Each logged in user gets a user service unit assigned that runs a user systemd instance. This is
      usually an instance of <filename>user@.service</filename>.</para>

      <para><varname>Slice</varname> contains the name of the user systemd slice unit name of this user. Each
      logged in user gets a private slice.</para>

      <para><varname>Display</varname> encodes which graphical session should be used as primary UI display
      for the use. It is a structure encoding session ID and object path of the session to use.</para>

      <para><varname>State</varname> encodes the user state, one of <literal>offline</literal>,
      <literal>lingering</literal>, <literal>online</literal>, <literal>active</literal>,
      <literal>closing</literal>. See
      <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>
      for more information about the states.</para>

      <para><varname>Sessions</varname> is an array of structures encoding all current sessions of the
      user. Each structure consists of ID and object path.</para>

      <para>The <varname>IdleHint</varname>, <varname>IdleSinceHint</varname>,
      <varname>IdleSinceHintMonotonic</varname> properties encode the idle hint state of the user, similar to
      the <interfacename>Manager</interfacename>'s properties, but specific for this user.</para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Session Objects</title>

    <programlisting>
$ gdbus introspect --system --dest org.freedesktop.login1 \
        --object-path /org/freedesktop/login1/session/3

node /org/freedesktop/login1/session/3 {
  interface org.freedesktop.login1.Session {
    methods:
      Terminate();
      Activate();
      Lock();
      Unlock();
      SetIdleHint(in  b idle);
      Kill(in  s who,
           in  i signo);
      TakeControl(in  b force);
      ReleaseControl();
      TakeDevice(in  u major,
                 in  u minor,
                 out h fd,
                 out b inactive);
      ReleaseDevice(in  u major,
                    in  u minor);
      PauseDeviceComplete(in  u major,
                          in  u minor);
    signals:
      PauseDevice(u major,
                  u minor,
                  s type);
      ResumeDevice(u major,
                   u minor,
                   h fd);
      Lock();
      Unlock();
    properties:
      readonly s Id = '3';
      readonly (uo) User = (1000, '/org/freedesktop/login1/user/_1000');
      readonly s Name = 'test';
      readonly t Timestamp = 1389370644734067;
      readonly t TimestampMonotonic = 72063381;
      readonly u VTNr = 0;
      readonly (so) Seat = ('', '/');
      readonly s TTY = '';
      readonly s Display = '';
      readonly b Remote = true;
      readonly s RemoteHost = '129.174.150.217';
      readonly s RemoteUser = '';
      readonly s Service = 'sshd';
      readonly s Desktop = '';
      readonly s Scope = 'session-3.scope';
      readonly u Leader = 1854;
      readonly u Audit = 3;
      readonly s Type = 'tty';
      readonly s Class = 'user';
      readonly b Active = true;
      readonly s State = 'active';
      readonly b IdleHint = false;
      readonly t IdleSinceHint = 0;
      readonly t IdleSinceHintMonotonic = 0;
  };
  interface org.freedesktop.DBus.Properties {
  };
  interface org.freedesktop.DBus.Peer {
  };
  interface org.freedesktop.DBus.Introspectable {
  };
};
    </programlisting>

    <refsect2>
      <title>Methods</title>

      <para><function>Terminate()</function>, <function>Activate()</function>, <function>Lock()</function>,
      <function>Unlock()</function>, <function>Kill()</function> work similarly to the respective calls on
      the <interfacename>Manager</interfacename> object.</para>

      <para><function>SetIdleHint()</function> shall be called by the session object to update the idle state
      of the session, whenever it changes.</para>

      <para><function>TakeControl()</function> allows a process to take exclusive managed device
      access-control for that session. Only one dbus-connection can be a controller for a given session at a
      time. If the <function>force</function> argument is set (root only), an existing controller is kicked
      out and replaced. Otherwise, this call fails if there is already a controller.  Note that this call is
      limited to dbus-users with the effective UID set to the User of the Session or root.</para>

      <para><function>ReleaseControl()</function> drops control of a given session again. Closing the
      dbus-connection implicitly releases control, too. See <function>TakeControl()</function> for more. This
      also releases all devices for the controller that were requested via <function>TakeDevice()</function>.
      </para>

      <para><function>TakeDevice()</function> allows a session-controller to get a file-descriptor for a
      specific device. Pass in the major and minor numbers of the character-device and
      <filename>systemd-logind</filename> will return a file-descriptor for the device. Only a limited set of
      device-types is currently supported (but may be extended). <filename>systemd-logind</filename>
      automatically mutes the file-descriptor if the session is inactive and resumes it once the session gets
      active again. This guarantees that a session can only access session-devices if the session is
      active. Note that this revoke/resume mechanism is asynchronous and may happen at any given time.  This
      only works on devices that are attached to the seat of the given session. A process is not required to
      have direct access to the device-node. <filename>systemd-logind</filename> only requires you to be the
      active session controller (see <function>TakeControl()</function>). Also note that any device can only
      be requested once. As long as you don't release it, further <function>TakeDevice()</function> calls
      will fail.</para>

      <para><function>ReleaseDevice()</function> releases a device again (see
      <function>TakeDevice()</function>). This is also implicitly done by
      <function>ReleaseControl()</function> or when closing the dbus-connection.</para>

      <para><function>PauseDeviceComplete()</function> allows a session-controller to synchronously pause a
      device after receiving a <function>PauseDevice(<literal>pause</literal>)</function> signal. Forced
      signals (or after an internal timeout) are automatically completed by
      <filename>systemd-logind</filename> asynchronously.</para>
    </refsect2>

    <refsect2>
      <title>Signals</title>

      <para>The active session-controller exclusively gets <function>PauseDevice</function> and
      <function>ResumeDevice</function> events for any device it requested via
      <function>TakeDevice()</function>. They notify the controller whenever a device is paused or resumed. A
      device is never resumed if a session is inactive. Also note that <function>PauseDevice</function>
      signals are sent before the <function>PropertyChanged</function> signal for the
      <function>Active</function> state. The inverse is true for <function>ResumeDevice</function>. A device
      may remain paused for unknown reasons even though the <interfacename>Session</interfacename> is active.
      </para>

      <para>A <function>PauseDevice</function> signal carries the major and minor and a string describing the
      type as arguments. <function>force</function> means the device got paused by
      <filename>systemd-logind</filename> already and this is only an asynchronous
      notification. <function>pause</function> means <filename>systemd-logind</filename> tries to pause the
      device and grants you limited amount of time to pause it. You must respond to this via
      <function>PauseDeviceComplete()</function>. This synchronous pausing-mechanism is used for
      backwards-compatibility to VTs and <filename>systemd-logind</filename> is free to not make use of
      it. It is also free to send a forced <function>PauseDevice</function> if you don't respond in a timely
      manner (or for any other reason). <function>gone</function> means the device was unplugged from the
      system and you will no longer get any notifications about it. There is no reason to call
      <function>ReleaseDevice()</function>. You may call <function>TakeDevice()</function> again if a new
      device gets the major+minor combination assigned.</para>

      <para><function>ResumeDevice</function> is sent whenever a session is active and a device is
      resumed. It carries the major/minor as arguments and provides a new open file-descriptor. You should
      switch to the new descriptor and close the old one. They are not guaranteed to have the same underlying
      open-file-descriptor in the kernel (except for a limited set of device types).</para>

      <para>Whenever <function>Active</function> or the idle state changes
      <function>PropertyChanged</function> signals are sent out to which clients can subscribe.</para>

      <para><function>Lock</function>/<function>Unlock</function> is sent when the session is asked to be
      screen-locked/unlocked. A session manager of the session should listen to this signal and act
      accordingly. This signal is sent out as a result of the <function>Lock()</function> and
      <function>Unlock()</function> methods, respectively.</para>
    </refsect2>

    <refsect2>
      <title>Properties</title>

      <para><varname>Id</varname> encodes the session ID.</para>

      <para><varname>User</varname> encodes the user ID of the user this session belongs to. This is a
      structure encoding the Unix UID and the object path.</para>

      <para><varname>Name</varname> encodes the user name.</para>

      <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> encode the usec timestamp
      since the epoch when the session was created, in <constant>CLOCK_REALTIME</constant> or
      <constant>CLOCK_MONOTONIC</constant>, respectively.</para>

      <para><varname>VTNr</varname> encodes the virtual terminal number of the session if there is any, 0
      otherwise.</para>

      <para><varname>Seat</varname> encodes the seat this session belongs to, if there is any. This is a
      structure consisting of the ID and the seat object path.</para>

      <para><varname>TTY</varname> encodes the kernel TTY path of the session if this is a text login. If not
      this is an empty string.</para>

      <para><varname>Display</varname> encodes the X11 display name if this is a graphical login. If not,
      this is an empty string.</para>

      <para><varname>Remote</varname> encodes whether the session is local or remote.</para>

      <para><varname>RemoteHost</varname> and <varname>RemoteUser</varname> encode the remote host and user
      if this is a remote session, or an empty string otherwise.</para>

      <para><varname>Service</varname> encodes the PAM service name that registered the session.</para>

      <para><varname>Scope</varname> contains the systemd scope unit name of this session.</para>

      <para><varname>Leader</varname> encodes the PID of the process that registered the session.</para>

      <para><varname>Audit</varname> encodes the Kernel Audit session ID of the session, if auditing is
      available.</para>

      <para><varname>Type</varname> encodes the session type. It's one of <literal>unspecified</literal> (for
      cron PAM sessions and suchlike), <literal>tty</literal> (for text logins) or
      <literal>x11</literal>/<literal>mir</literal>/<literal>wayland</literal> (for graphical logins).</para>

      <para><varname>Class</varname> encodes the session class. It's one of <literal>user</literal> (for
      normal user sessions), <literal>greeter</literal> (for display manager pseudo-sessions),
      <literal>lock-screen</literal> (for display lock screens).</para>

      <para><varname>Active</varname> is a boolean that is true if the session is active, i.e. currently in the
      foreground. This field is semi-redundant due to State.</para>

      <para><varname>State</varname> encodes the session state and one of <literal>online</literal>,
      <literal>active</literal>, <literal>closing</literal>. See
      <citerefentry><refentrytitle>sd_session_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>
      for more information about the states.</para>

      <para><varname>IdleHint</varname>, <varname>IdleSinceHint</varname>,
      <varname>IdleSinceHintMonotonic</varname> encapsulate the idle hint state of this session, similarly to
      how the respective properties on the manager object do it for the whole system.</para>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Versioning</title>

    <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
    the usual interface versioning guidelines</ulink>.</para>
  </refsect1>
</refentry>