diff options
author | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2020-04-06 20:42:12 +0200 |
---|---|---|
committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2020-04-12 19:48:01 +0200 |
commit | 44fd44f1cf07826dce0688f1caf9000c24aa90c8 (patch) | |
tree | f4836d057ff2b79c6f0c961c6313514f0b392c4d | |
parent | 9fac14980df8dcce922e1fe8856a88b09590d2c3 (diff) | |
download | systemd-44fd44f1cf07826dce0688f1caf9000c24aa90c8.tar.gz |
man: import org.freedesktop.login1(3) from the wiki
-rw-r--r-- | man/org.freedesktop.login1.xml | 767 | ||||
-rw-r--r-- | man/rules/meson.build | 1 | ||||
-rw-r--r-- | man/systemd-logind.service.xml | 14 |
3 files changed, 778 insertions, 4 deletions
diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml new file mode 100644 index 0000000000..2910693865 --- /dev/null +++ b/man/org.freedesktop.login1.xml @@ -0,0 +1,767 @@ +<?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> diff --git a/man/rules/meson.build b/man/rules/meson.build index 9cdfe5d291..4e57b94bbf 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -44,6 +44,7 @@ manpages = [ ['nss-mymachines', '8', ['libnss_mymachines.so.2'], 'ENABLE_NSS_MYMACHINES'], ['nss-resolve', '8', ['libnss_resolve.so.2'], 'ENABLE_NSS_RESOLVE'], ['nss-systemd', '8', ['libnss_systemd.so.2'], 'ENABLE_NSS_SYSTEMD'], + ['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'], ['os-release', '5', [], ''], ['pam_systemd', '8', [], 'HAVE_PAM'], ['pam_systemd_home', '8', [], 'ENABLE_PAM_HOME'], diff --git a/man/systemd-logind.service.xml b/man/systemd-logind.service.xml index a66c53d076..87ee607c6c 100644 --- a/man/systemd-logind.service.xml +++ b/man/systemd-logind.service.xml @@ -78,14 +78,20 @@ for information about the basic concepts of logind such as users, sessions and seats.</para> - <para>See the <ulink - url="https://www.freedesktop.org/wiki/Software/systemd/logind"> - logind D-Bus API Documentation</ulink> for information about the - APIs <filename>systemd-logind</filename> provides.</para> + <para>See + <citerefentry><refentrytitle>org.freedesktop.login1</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for for information about the D-Bus APIs <filename>systemd-logind</filename> provides.</para> <para>For more information on the inhibition logic see the <ulink url="https://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Lock Developer Documentation</ulink>.</para> + + <para>If you are interested in writing a display manager that makes use of logind, please have look at + <ulink url="https://www.freedesktop.org/wiki/Software/systemd/writing-display-managers">Writing Display + Manager</ulink>. + If you are interested in writing a desktop environment that makes use of logind, please have look at + <ulink url="http://www.freedesktop.org/wiki/Software/systemd/writing-desktop-environments">Writing + Desktop Environments</ulink>.</para> </refsect1> <refsect1> |