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+ -->
6 <refentry id=
"org.freedesktop.login1" conditional='ENABLE_LOGIND'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
9 <title>org.freedesktop.login1
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>org.freedesktop.login1
</refentrytitle>
15 <manvolnum>5</manvolnum>
19 <refname>org.freedesktop.login1
</refname>
20 <refpurpose>The D-Bus interface of systemd-logind
</refpurpose>
24 <title>Introduction
</title>
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>
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>.
37 <title>The Manager Object
</title>
39 <para>The service exposes the following interfaces on the Manager object on the bus:
</para>
41 <programlisting executable=
"systemd-logind" node=
"/org/freedesktop/login1" interface=
"org.freedesktop.login1.Manager">
42 node /org/freedesktop/login1 {
43 interface org.freedesktop.login1.Manager {
45 GetSession(in s session_id,
47 GetSessionByPID(in u pid,
51 GetUserByPID(in u pid,
55 ListSessions(out a(susso) sessions);
56 ListUsers(out a(uso) users);
57 ListSeats(out a(so) seats);
58 ListInhibitors(out a(ssssuu) inhibitors);
59 CreateSession(in u uid,
81 ReleaseSession(in s session_id);
82 ActivateSession(in s session_id);
83 ActivateSessionOnSeat(in s session_id,
85 LockSession(in s session_id);
86 UnlockSession(in s session_id);
89 KillSession(in s session_id,
94 TerminateSession(in s session_id);
95 TerminateUser(in u uid);
96 TerminateSeat(in s seat_id);
97 SetUserLinger(in u uid,
100 AttachDevice(in s seat_id,
103 FlushDevices(in b interactive);
104 PowerOff(in b interactive);
105 Reboot(in b interactive);
106 Halt(in b interactive);
107 Suspend(in b interactive);
108 Hibernate(in b interactive);
109 HybridSleep(in b interactive);
110 SuspendThenHibernate(in b interactive);
111 CanPowerOff(out s result);
112 CanReboot(out s result);
113 CanHalt(out s result);
114 CanSuspend(out s result);
115 CanHibernate(out s result);
116 CanHybridSleep(out s result);
117 CanSuspendThenHibernate(out s result);
118 ScheduleShutdown(in s type,
120 CancelScheduledShutdown(out b cancelled);
126 CanRebootParameter(out s result);
127 SetRebootParameter(in s parameter);
128 CanRebootToFirmwareSetup(out s result);
129 SetRebootToFirmwareSetup(in b enable);
130 CanRebootToBootLoaderMenu(out s result);
131 SetRebootToBootLoaderMenu(in t timeout);
132 CanRebootToBootLoaderEntry(out s result);
133 SetRebootToBootLoaderEntry(in s boot_loader_entry);
134 SetWallMessage(in s wall_message,
137 SessionNew(s session_id,
139 SessionRemoved(s session_id,
147 SeatRemoved(s seat_id,
149 PrepareForShutdown(b start);
150 PrepareForSleep(b start);
152 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
153 @org.freedesktop.systemd1.Privileged(
"true")
154 readwrite b EnableWallMessages = ...;
155 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
156 @org.freedesktop.systemd1.Privileged(
"true")
157 readwrite s WallMessage = '...';
158 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
159 readonly u NAutoVTs = ...;
160 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
161 readonly as KillOnlyUsers = ['...', ...];
162 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
163 readonly as KillExcludeUsers = ['...', ...];
164 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
165 readonly b KillUserProcesses = ...;
166 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
167 readonly s RebootParameter = '...';
168 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
169 readonly b RebootToFirmwareSetup = ...;
170 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
171 readonly t RebootToBootLoaderMenu = ...;
172 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
173 readonly s RebootToBootLoaderEntry = '...';
174 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
175 readonly as BootLoaderEntries = ['...', ...];
176 readonly b IdleHint = ...;
177 readonly t IdleSinceHint = ...;
178 readonly t IdleSinceHintMonotonic = ...;
179 readonly s BlockInhibited = '...';
180 readonly s DelayInhibited = '...';
181 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
182 readonly t InhibitDelayMaxUSec = ...;
183 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
184 readonly t UserStopDelayUSec = ...;
185 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
186 readonly s HandlePowerKey = '...';
187 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
188 readonly s HandleSuspendKey = '...';
189 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
190 readonly s HandleHibernateKey = '...';
191 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
192 readonly s HandleLidSwitch = '...';
193 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
194 readonly s HandleLidSwitchExternalPower = '...';
195 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
196 readonly s HandleLidSwitchDocked = '...';
197 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
198 readonly t HoldoffTimeoutUSec = ...;
199 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
200 readonly s IdleAction = '...';
201 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
202 readonly t IdleActionUSec = ...;
203 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
204 readonly b PreparingForShutdown = ...;
205 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
206 readonly b PreparingForSleep = ...;
207 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
208 readonly (st) ScheduledShutdown = ...;
209 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
210 readonly b Docked = ...;
211 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
212 readonly b LidClosed = ...;
213 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
214 readonly b OnExternalPower = ...;
215 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
216 readonly b RemoveIPC = ...;
217 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
218 readonly t RuntimeDirectorySize = ...;
219 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
220 readonly t RuntimeDirectoryInodesMax = ...;
221 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
222 readonly t InhibitorsMax = ...;
223 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
224 readonly t NCurrentInhibitors = ...;
225 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
226 readonly t SessionsMax = ...;
227 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
228 readonly t NCurrentSessions = ...;
230 interface org.freedesktop.DBus.Peer { ... };
231 interface org.freedesktop.DBus.Introspectable { ... };
232 interface org.freedesktop.DBus.Properties { ... };
236 <!--Autogenerated cross-references for systemd.directives, do not edit-->
238 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.login1.Manager"/>
240 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.login1.Manager"/>
242 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetSession()"/>
244 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetSessionByPID()"/>
246 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetUser()"/>
248 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetUserByPID()"/>
250 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetSeat()"/>
252 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ListSessions()"/>
254 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ListUsers()"/>
256 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ListSeats()"/>
258 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ListInhibitors()"/>
260 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CreateSession()"/>
262 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ReleaseSession()"/>
264 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ActivateSession()"/>
266 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ActivateSessionOnSeat()"/>
268 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"LockSession()"/>
270 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"UnlockSession()"/>
272 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"LockSessions()"/>
274 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"UnlockSessions()"/>
276 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"KillSession()"/>
278 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"KillUser()"/>
280 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"TerminateSession()"/>
282 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"TerminateUser()"/>
284 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"TerminateSeat()"/>
286 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetUserLinger()"/>
288 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"AttachDevice()"/>
290 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"FlushDevices()"/>
292 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"PowerOff()"/>
294 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Reboot()"/>
296 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Halt()"/>
298 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Suspend()"/>
300 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Hibernate()"/>
302 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"HybridSleep()"/>
304 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SuspendThenHibernate()"/>
306 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CanPowerOff()"/>
308 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CanReboot()"/>
310 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CanHalt()"/>
312 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CanSuspend()"/>
314 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CanHibernate()"/>
316 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CanHybridSleep()"/>
318 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CanSuspendThenHibernate()"/>
320 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ScheduleShutdown()"/>
322 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CancelScheduledShutdown()"/>
324 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Inhibit()"/>
326 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CanRebootParameter()"/>
328 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetRebootParameter()"/>
330 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CanRebootToFirmwareSetup()"/>
332 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetRebootToFirmwareSetup()"/>
334 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CanRebootToBootLoaderMenu()"/>
336 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetRebootToBootLoaderMenu()"/>
338 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CanRebootToBootLoaderEntry()"/>
340 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetRebootToBootLoaderEntry()"/>
342 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetWallMessage()"/>
344 <variablelist class=
"dbus-signal" generated=
"True" extra-ref=
"SessionNew"/>
346 <variablelist class=
"dbus-signal" generated=
"True" extra-ref=
"SessionRemoved"/>
348 <variablelist class=
"dbus-signal" generated=
"True" extra-ref=
"UserNew"/>
350 <variablelist class=
"dbus-signal" generated=
"True" extra-ref=
"UserRemoved"/>
352 <variablelist class=
"dbus-signal" generated=
"True" extra-ref=
"SeatNew"/>
354 <variablelist class=
"dbus-signal" generated=
"True" extra-ref=
"SeatRemoved"/>
356 <variablelist class=
"dbus-signal" generated=
"True" extra-ref=
"PrepareForShutdown"/>
358 <variablelist class=
"dbus-signal" generated=
"True" extra-ref=
"PrepareForSleep"/>
360 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"EnableWallMessages"/>
362 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"WallMessage"/>
364 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"NAutoVTs"/>
366 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"KillOnlyUsers"/>
368 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"KillExcludeUsers"/>
370 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"KillUserProcesses"/>
372 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"RebootParameter"/>
374 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"RebootToFirmwareSetup"/>
376 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"RebootToBootLoaderMenu"/>
378 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"RebootToBootLoaderEntry"/>
380 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"BootLoaderEntries"/>
382 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleHint"/>
384 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleSinceHint"/>
386 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleSinceHintMonotonic"/>
388 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"BlockInhibited"/>
390 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"DelayInhibited"/>
392 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"InhibitDelayMaxUSec"/>
394 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"UserStopDelayUSec"/>
396 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"HandlePowerKey"/>
398 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"HandleSuspendKey"/>
400 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"HandleHibernateKey"/>
402 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"HandleLidSwitch"/>
404 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"HandleLidSwitchExternalPower"/>
406 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"HandleLidSwitchDocked"/>
408 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"HoldoffTimeoutUSec"/>
410 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleAction"/>
412 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleActionUSec"/>
414 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"PreparingForShutdown"/>
416 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"PreparingForSleep"/>
418 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"ScheduledShutdown"/>
420 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Docked"/>
422 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"LidClosed"/>
424 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"OnExternalPower"/>
426 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"RemoveIPC"/>
428 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"RuntimeDirectorySize"/>
430 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"RuntimeDirectoryInodesMax"/>
432 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"InhibitorsMax"/>
434 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"NCurrentInhibitors"/>
436 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"SessionsMax"/>
438 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"NCurrentSessions"/>
440 <!--End of Autogenerated section-->
443 <title>Methods
</title>
445 <para><function>GetSession()
</function> may be used to get the session object path for the session with
446 the specified ID. Similarly,
<function>GetUser()
</function> and
<function>GetSeat()
</function> get the
447 user and seat objects, respectively.
<function>GetSessionByPID()
</function> and
448 <function>GetUserByPID()
</function> get the session/user object the specified PID belongs to if there
451 <para><function>ListSessions()
</function> returns an array of all current sessions. The structures in
452 the array consist of the following fields: session id, user id, user name, seat id, session object
453 path. If a session does not have a seat attached, the seat id field will be an empty string.
</para>
455 <para><function>ListUsers()
</function> returns an array of all currently logged in users. The
456 structures in the array consist of the following fields: user id, user name, user object path.
</para>
458 <para><function>ListSeats()
</function> returns an array of all currently available seats. The
459 structure in the array consists of the following fields: seat id, seat object path.
</para>
461 <para><function>ListInhibitors()
</function> lists all currently active inhibitors. It returns an array of
462 structures consisting of
<varname>what
</varname>,
<varname>who
</varname>,
<varname>why
</varname>,
463 <varname>mode
</varname>,
<varname>uid
</varname> (user ID), and
<varname>pid
</varname> (process ID).
</para>
465 <para><function>CreateSession()
</function> and
<function>ReleaseSession()
</function> may be used to
466 open or close login sessions. These calls should
<emphasis>never
</emphasis> be invoked directly by
467 clients. Creating/closing sessions is exclusively the job of PAM and its
468 <citerefentry><refentrytitle>pam_systemd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
471 <para><function>ActivateSession()
</function> brings the session with the specified ID into the
472 foreground.
<function>ActivateSessionOnSeat()
</function> does the same, but only if the seat id
475 <para><function>LockSession()
</function> asks the session with the specified ID to activate the screen
476 lock.
<function>UnlockSession()
</function> asks the session with the specified ID to remove an active
477 screen lock, if there is any. This is implemented by sending out the Lock() and Unlock() signals from
478 the respective session object which session managers are supposed to listen on.
</para>
480 <para><function>LockSessions()
</function> asks all sessions to activate their screen locks. This may be
481 used to lock access to the entire machine in one action. Similarly,
<function>UnlockSessions()
</function>
482 asks all sessions to deactivate their screen locks.
</para>
484 <para><function>KillSession()
</function> may be used to send a Unix signal to one or all processes of a
485 session. As arguments it takes the session id, either the string
<literal>leader
</literal> or
486 <literal>all
</literal> and a signal number. If
<literal>leader
</literal> is passed only the session
487 <literal>leader
</literal> is killed. If
<literal>all
</literal> is passed all processes of the session
490 <para><function>KillUser()
</function> may be used to send a Unix signal to all processes of a user. As
491 arguments it takes the user id and a signal number.
</para>
493 <para><function>TerminateSession()
</function>,
<function>TerminateUser()
</function>,
494 <function>TerminateSeat()
</function> may be used to forcibly terminate one specific session, all
495 processes of a user, and all sessions attached to a specific seat, respectively. The session, user,
496 and seat are identified by their respective IDs.
</para>
498 <para><function>SetUserLinger()
</function> enables or disables user lingering. If enabled, the runtime
499 directory of a user is kept around and they may continue to run processes while logged out. If
500 disabled, the runtime directory goes away as soon as they log out.
<function>SetUserLinger()
</function>
501 expects three arguments: the UID, a boolean whether to enable/disable and a boolean controlling the
502 <ulink url=
"https://www.freedesktop.org/software/polkit/docs/latest/">polkit
</ulink>
503 authorization interactivity (see below). Note that the user linger state is persistently
504 stored on disk.
</para>
506 <para><function>AttachDevice()
</function> may be used to assign a specific device to a specific
507 seat. The device is identified by its
<filename>/sys/
</filename> path and must be eligible for seat
508 assignments.
<function>AttachDevice()
</function> takes three arguments: the seat id, the sysfs path,
509 and a boolean for controlling polkit interactivity (see below). Device assignments are persistently
510 stored on disk. To create a new seat, simply specify a previously unused seat id. For more information
511 about the seat assignment logic see
512 <citerefentry><refentrytitle>sd-login
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
514 <para><function>FlushDevices()
</function> removes all explicit seat assignments for devices, resetting
515 all assignments to the automatic defaults. The only argument it takes is the polkit interactivity
516 boolean (see below).
</para>
518 <para><function>PowerOff()
</function>,
<function>Reboot()
</function>,
<function>Halt()
</function>,
519 <function>Suspend()
</function>, and
<function>Hibernate()
</function> result in the system being powered
520 off, rebooted, halted (shut down without turning off power), suspended (the system state is
521 saved to RAM and the CPU is turned off), or hibernated (the system state is saved to disk and
522 the machine is powered down).
<function>HybridSleep()
</function> results in the system entering a
523 hybrid-sleep mode, i.e. the system is both hibernated and suspended.
524 <function>SuspendThenHibernate()
</function> results in the system being suspended, then later woken
525 using an RTC timer and hibernated. The only argument is the polkit interactivity boolean
526 <varname>interactive
</varname> (see below). The main purpose of these calls is that they enforce
527 polkit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged
528 users. They also enforce inhibition locks. UIs should expose these calls as the primary mechanism to
529 poweroff/reboot/suspend/hibernate the machine.
</para>
531 <para><function>SetRebootParameter()
</function> sets a parameter for a subsequent reboot operation.
532 See the description of
<command>reboot
</command> in
533 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
534 <citerefentry project=
"man-pages"><refentrytitle>reboot
</refentrytitle><manvolnum>2</manvolnum></citerefentry>
535 for more information.
</para>
537 <para><function>SetRebootToFirmwareSetup()
</function>,
538 <function>SetRebootToBootLoaderMenu()
</function>, and
<function>SetRebootToBootLoaderEntry()
</function>
539 configure the action to be taken from the boot loader after a reboot: respectively entering firmware
540 setup mode, the boot loader menu, or a specific boot loader entry. See
541 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for the
542 corresponding command line interface.
</para>
544 <para><function>CanPowerOff()
</function>,
<function>CanReboot()
</function>,
545 <function>CanHalt()
</function>,
<function>CanSuspend()
</function>,
<function>CanHibernate()
</function>,
546 <function>CanHybridSleep()
</function>,
<function>CanSuspendThenHibernate()
</function>,
547 <function>CanRebootParameter()
</function>,
<function>CanRebootToFirmwareSetup()
</function>,
548 <function>CanRebootToBootLoaderMenu()
</function>, and
549 <function>CanRebootToBootLoaderEntry()
</function> test whether the system supports the respective
550 operation and whether the calling user is allowed to execute it. Returns one of
<literal>na
</literal>,
551 <literal>yes
</literal>,
<literal>no
</literal>, and
<literal>challenge
</literal>. If
552 <literal>na
</literal> is returned, the operation is not available because hardware, kernel, or drivers
553 do not support it. If
<literal>yes
</literal> is returned, the operation is supported and the user may
554 execute the operation without further authentication. If
<literal>no
</literal> is returned, the
555 operation is available but the user is not allowed to execute the operation. If
556 <literal>challenge
</literal> is returned, the operation is available but only after
557 authorization.
</para>
559 <para><function>ScheduleShutdown()
</function> schedules a shutdown operation
<varname>type
</varname> at
560 time
<varname>usec
</varname> in microseconds since the UNIX epoch.
<varname>type
</varname> can be one
561 of
<literal>poweroff
</literal>,
<literal>dry-poweroff
</literal>,
<literal>reboot
</literal>,
562 <literal>dry-reboot
</literal>,
<literal>halt
</literal>, and
<literal>dry-halt
</literal>. (The
563 <literal>dry-
</literal> variants do not actually execute the shutdown action.)
564 <function>CancelScheduledShutdown()
</function> cancels a scheduled shutdown. The output parameter
565 <varname>cancelled
</varname> is true if a shutdown operation was scheduled.
</para>
567 <para><function>SetWallMessage()
</function> sets the wall message (the message that will be sent out to
568 all terminals and stored in a
569 <citerefentry project=
"man-pages"><refentrytitle>utmp
</refentrytitle><manvolnum>5</manvolnum></citerefentry> record) for a
570 subsequent scheduled shutdown operation. The parameter
<varname>wall_message
</varname> specifies the
571 shutdown reason (and may be empty) which will be included in the shutdown message. The parameter
572 <varname>enable
</varname> specifies whether to print a wall message on shutdown.
</para>
574 <para><function>Inhibit()
</function> creates an inhibition lock. It takes four parameters:
575 <varname>what
</varname>,
<varname>who
</varname>,
<varname>why
</varname>, and
576 <varname>mode
</varname>.
<varname>what
</varname> is one or more of
<literal>shutdown
</literal>,
577 <literal>sleep
</literal>,
<literal>idle
</literal>,
<literal>handle-power-key
</literal>,
578 <literal>handle-suspend-key
</literal>,
<literal>handle-hibernate-key
</literal>,
579 <literal>handle-lid-switch
</literal>, separated by colons, for inhibiting poweroff/reboot,
580 suspend/hibernate, the automatic idle logic, or hardware key handling.
<varname>who
</varname> should be
581 a short human readable string identifying the application taking the lock.
<varname>why
</varname>
582 should be a short human readable string identifying the reason why the lock is taken. Finally,
583 <varname>mode
</varname> is either
<literal>block
</literal> or
<literal>delay
</literal> which encodes
584 whether the inhibit shall be consider mandatory or whether it should just delay the operation to a
585 certain maximum time. The method returns a file descriptor. The lock is released the moment this file
586 descriptor and all its duplicates are closed. For more information on the inhibition logic see
587 <ulink url=
"http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks
</ulink>.
592 <title>Signals
</title>
594 <para>Whenever the inhibition state or idle hint changes,
<function>PropertyChanged
</function>
595 signals are sent out to which clients can subscribe.
</para>
597 <para>The
<function>SessionNew
</function>,
<function>SessionRemoved
</function>,
598 <function>UserNew
</function>,
<function>UserRemoved
</function>,
<function>SeatNew
</function>, and
599 <function>SeatRemoved
</function> signals are sent each time a session is created or removed, a user
600 logs in or out, or a seat is added or removed. They each contain the ID of the object plus the object
603 <para>The
<function>PrepareForShutdown()
</function> and
<function>PrepareForSleep()
</function> signals
604 are sent right before (with the argument
<literal>true
</literal>) or after (with the argument
605 <literal>false
</literal>) the system goes down for reboot/poweroff and suspend/hibernate,
606 respectively. This may be used by applications to save data on disk, release memory, or do other jobs
607 that should be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks. After
608 completion of this work they should release their inhibition locks in order to not delay the operation
609 any further. For more information see
610 <ulink url=
"http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Locks
</ulink>.
615 <title>Properties
</title>
617 <para>Most properties simply reflect the configuration, see
618 <citerefentry><refentrytitle>logind.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>. This
619 includes:
<varname>NAutoVTs
</varname>,
<varname>KillOnlyUsers
</varname>,
620 <varname>KillExcludeUsers
</varname>,
<varname>KillUserProcesses
</varname>,
<varname>IdleAction
</varname>,
621 <varname>InhibitDelayMaxUSec
</varname>,
622 <varname>InhibitorsMax
</varname>,
623 <varname>UserStopDelayUSec
</varname>,
624 <varname>HandlePowerKey
</varname>,
<varname>HandleSuspendKey
</varname>,
625 <varname>HandleHibernateKey
</varname>,
<varname>HandleLidSwitch
</varname>,
626 <varname>HandleLidSwitchExternalPower
</varname>,
<varname>HandleLidSwitchDocked
</varname>,
627 <varname>IdleActionUSec
</varname>,
<varname>HoldoffTimeoutUSec
</varname>,
628 <varname>RemoveIPC
</varname>,
<varname>RuntimeDirectorySize
</varname>,
629 <varname>RuntimeDirectoryInodesMax
</varname>,
<varname>InhibitorsMax
</varname>, and
630 <varname>SessionsMax
</varname>.
633 <para>The
<varname>IdleHint
</varname> property reflects the idle hint state of the system. If the
634 system is idle it might get into automatic suspend or shutdown depending on the configuration.
</para>
636 <para><varname>IdleSinceHint
</varname> and
<varname>IdleSinceHintMonotonic
</varname> encode the
637 timestamps of the last change of the idle hint boolean, in
<constant>CLOCK_REALTIME
</constant> and
638 <constant>CLOCK_MONOTONIC
</constant> timestamps, respectively, in microseconds since the epoch.
</para>
640 <para>The
<varname>BlockInhibited
</varname> and
<varname>DelayInhibited
</varname> properties encode
641 the currently active locks of the respective modes. They are colon separated lists of
642 <literal>shutdown
</literal>,
<literal>sleep
</literal>, and
<literal>idle
</literal> (see above).
</para>
644 <para><varname>NCurrentSessions
</varname> and
<varname>NCurrentInhibitors
</varname> contain the number
645 of currently registered sessions and inhibitors.
</para>
647 <para>The
<varname>BootLoaderEntries
</varname> property contains a list of boot loader entries.
648 This includes boot loader entries defined in configuration and any additional loader entries
649 reported by the boot loader. See
650 <citerefentry><refentrytitle>systemd-boot
</refentrytitle><manvolnum>7</manvolnum></citerefentry>
651 for more information.
</para>
653 <para>The
<varname>PreparingForShutdown
</varname> and
<varname>PreparingForSleep
</varname> boolean
654 properties are true during the interval between the two
<function>PrepareForShutdown
</function> and
655 <function>PrepareForSleep
</function> signals respectively. Note that these properties do not
656 send out
<function>PropertyChanged
</function> signals.
</para>
658 <para>The
<varname>RebootParameter
</varname> property shows the value set with the
659 <function>SetRebootParameter()
</function> method described above.
</para>
661 <para><varname>ScheduledShutdown
</varname> shows the value pair set with the
662 <function>ScheduleShutdown()
</function> method described above.
</para>
664 <para><varname>RebootToFirmwareSetup
</varname>,
<varname>RebootToBootLoaderMenu
</varname>, and
665 <varname>RebootToBootLoaderEntry
</varname> are true when the resprective post-reboot operation was
666 selected with
<function>SetRebootToFirmwareSetup
</function>,
667 <function>SetRebootToBootLoaderMenu
</function>, or
668 <function>SetRebootToBootLoaderEntry
</function>.
</para>
670 <para>The
<varname>WallMessage
</varname> and
<varname>EnableWallMessages
</varname> properties reflect the
671 shutdown reason and wall message enablement switch which can be set with the
672 <function>SetWallMessage()
</function> method described above.
</para>
674 <para><varname>Docked
</varname> is true if the machine is connected to a dock.
675 <varname>LidClosed
</varname> is true when the lid (of a laptop) is closed.
676 <varname>OnExternalPower
</varname> is true when the machine is connected to an external power supply.
681 <title>Security
</title>
683 <para>A number of operations are protected via the polkit privilege
684 system.
<function>SetUserLinger()
</function> requires the
685 <interfacename>org.freedesktop.login1.set-user-linger
</interfacename>
686 privilege.
<function>AttachDevice()
</function> requires
687 <interfacename>org.freedesktop.login1.attach-device
</interfacename> and
688 <function>FlushDevices()
</function> requires
689 <interfacename>org.freedesktop.login1.flush-devices
</interfacename>.
<function>PowerOff()
</function>,
690 <function>Reboot()
</function>,
<function>Halt()
</function>,
<function>Suspend()
</function>,
691 <function>Hibernate()
</function> require
692 <interfacename>org.freedesktop.login1.power-off
</interfacename>,
693 <interfacename>org.freedesktop.login1.power-off-multiple-sessions
</interfacename>,
694 <interfacename>org.freedesktop.login1.power-off-ignore-inhibit
</interfacename>,
695 <interfacename>org.freedesktop.login1.reboot
</interfacename>,
696 <interfacename>org.freedesktop.login1.reboot-multiple-sessions
</interfacename>,
697 <interfacename>org.freedesktop.login1.reboot-ignore-inhibit
</interfacename>,
698 <interfacename>org.freedesktop.login1.halt
</interfacename>,
699 <interfacename>org.freedesktop.login1.halt-multiple-sessions
</interfacename>,
700 <interfacename>org.freedesktop.login1.halt-ignore-inhibit
</interfacename>,
701 <interfacename>org.freedesktop.login1.suspend
</interfacename>,
702 <interfacename>org.freedesktop.login1.suspend-multiple-sessions
</interfacename>,
703 <interfacename>org.freedesktop.login1.suspend-ignore-inhibit
</interfacename>,
704 <interfacename>org.freedesktop.login1.hibernate
</interfacename>,
705 <interfacename>org.freedesktop.login1.hibernate-multiple-sessions
</interfacename>,
706 <interfacename>org.freedesktop.login1.hibernate-ignore-inhibit
</interfacename>,
707 respectively depending on whether there are other sessions around or active inhibits are present.
708 <function>HybridSleep()
</function> and
<function>SuspendThenHibernate()
</function>
709 use the same privileges as
<function>Hibernate()
</function>.
710 <function>SetRebootParameter()
</function> requires
711 <interfacename>org.freedesktop.login1.set-reboot-parameter
</interfacename>.
</para>
713 <para><function>SetRebootToFirmwareSetup
</function> requires
714 <interfacename>org.freedesktop.login1.set-reboot-to-firmware-setup
</interfacename>.
715 <function>SetRebootToBootLoaderMenu
</function> requires
716 <interfacename>org.freedesktop.login1.set-reboot-to-boot-loader-menu
</interfacename>.
717 <function>SetRebootToBootLoaderEntry
</function> requires
718 <interfacename>org.freedesktop.login1.set-reboot-to-boot-loader-entry
</interfacename>.
721 <para><function>ScheduleShutdown
</function> and
<function>CancelScheduledShutdown
</function> require
722 the same privileges (listed above) as the immediate poweroff/reboot/halt operations.
</para>
724 <para><function>Inhibit()
</function> is protected via one of
725 <interfacename>org.freedesktop.login1.inhibit-block-shutdown
</interfacename>,
726 <interfacename>org.freedesktop.login1.inhibit-delay-shutdown
</interfacename>,
727 <interfacename>org.freedesktop.login1.inhibit-block-sleep
</interfacename>,
728 <interfacename>org.freedesktop.login1.inhibit-delay-sleep
</interfacename>,
729 <interfacename>org.freedesktop.login1.inhibit-block-idle
</interfacename>,
730 <interfacename>org.freedesktop.login1.inhibit-handle-power-key
</interfacename>,
731 <interfacename>org.freedesktop.login1.inhibit-handle-suspend-key
</interfacename>,
732 <interfacename>org.freedesktop.login1.inhibit-handle-hibernate-key
</interfacename>,
733 <interfacename>org.freedesktop.login1.inhibit-handle-lid-switch
</interfacename> depending on the lock
734 type and mode taken.
</para>
736 <para>The
<varname>interactive
</varname> boolean parameters can be used to control whether polkit
737 should interactively ask the user for authentication credentials if required.
</para>
742 <title>Seat Objects
</title>
744 <programlisting executable=
"systemd-logind" node=
"/org/freedesktop/login1/seat/seat0" interface=
"org.freedesktop.login1.Seat">
745 node /org/freedesktop/login1/seat/seat0 {
746 interface org.freedesktop.login1.Seat {
749 ActivateSession(in s session_id);
754 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
755 readonly s Id = '...';
756 readonly (so) ActiveSession = ...;
757 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
758 readonly b CanTTY = ...;
759 readonly b CanGraphical = ...;
760 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
761 readonly a(so) Sessions = [...];
762 readonly b IdleHint = ...;
763 readonly t IdleSinceHint = ...;
764 readonly t IdleSinceHintMonotonic = ...;
766 interface org.freedesktop.DBus.Peer { ... };
767 interface org.freedesktop.DBus.Introspectable { ... };
768 interface org.freedesktop.DBus.Properties { ... };
772 <!--Autogenerated cross-references for systemd.directives, do not edit-->
774 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.login1.Seat"/>
776 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.login1.Seat"/>
778 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Terminate()"/>
780 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ActivateSession()"/>
782 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SwitchTo()"/>
784 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SwitchToNext()"/>
786 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SwitchToPrevious()"/>
788 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Id"/>
790 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"ActiveSession"/>
792 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"CanTTY"/>
794 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"CanGraphical"/>
796 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Sessions"/>
798 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleHint"/>
800 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleSinceHint"/>
802 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleSinceHintMonotonic"/>
804 <!--End of Autogenerated section-->
807 <title>Methods
</title>
809 <para><function>Terminate()
</function> and
<function>ActivateSession()
</function> work similar to
810 TerminateSeat(), ActivationSessionOnSeat() on the Manager object.
</para>
812 <para><function>SwitchTo()
</function> switches to the session on the virtual terminal
813 <varname>vtnr
</varname>.
<function>SwitchToNext()
</function> and
814 <function>SwitchToPrevious()
</function> switch to, respectively, the next and previous sessions on the
815 seat in the order of virtual terminals. If there is no active session, they switch to, respectively,
816 the first and last session on the seat.
</para>
820 <title>Signals
</title>
822 <para>Whenever
<function>ActiveSession
</function>,
<function>Sessions
</function>,
823 <function>CanGraphical
</function>,
<function>CanTTY
</function>,
824 or the idle state changes,
<function>PropertyChanged
</function> signals are sent out to which clients
825 can subscribe.
</para>
829 <title>Properties
</title>
831 <para>The
<varname>Id
</varname> property encodes the ID of the seat.
</para>
833 <para><varname>ActiveSession
</varname> encodes the currently active session if there is one. It is a
834 structure consisting of the session id and the object path.
</para>
836 <para><varname>CanTTY
</varname> encodes whether the session is suitable for text logins, and
837 <varname>CanGraphical
</varname> whether it is suitable for graphical sessions.
</para>
839 <para>The
<varname>Sessions
</varname> property is an array of all current sessions of this seat, each
840 encoded in a structure consisting of the ID and the object path.
</para>
842 <para>The
<varname>IdleHint
</varname>,
<varname>IdleSinceHint
</varname>, and
843 <varname>IdleSinceHintMonotonic
</varname> properties encode the idle state, similar to the ones exposed
844 on the
<interfacename>Manager
</interfacename> object, but specific for this seat.
</para>
849 <title>User Objects
</title>
851 <programlisting executable=
"systemd-logind" node=
"/org/freedesktop/login1/user/_1000" interface=
"org.freedesktop.login1.User">
852 node /org/freedesktop/login1/user/_1000 {
853 interface org.freedesktop.login1.User {
856 Kill(in i signal_number);
858 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
859 readonly u UID = ...;
860 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
861 readonly u GID = ...;
862 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
863 readonly s Name = '...';
864 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
865 readonly t Timestamp = ...;
866 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
867 readonly t TimestampMonotonic = ...;
868 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
869 readonly s RuntimePath = '...';
870 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
871 readonly s Service = '...';
872 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
873 readonly s Slice = '...';
874 readonly (so) Display = ...;
875 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
876 readonly s State = '...';
877 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
878 readonly a(so) Sessions = [...];
879 readonly b IdleHint = ...;
880 readonly t IdleSinceHint = ...;
881 readonly t IdleSinceHintMonotonic = ...;
882 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
883 readonly b Linger = ...;
885 interface org.freedesktop.DBus.Peer { ... };
886 interface org.freedesktop.DBus.Introspectable { ... };
887 interface org.freedesktop.DBus.Properties { ... };
891 <!--Autogenerated cross-references for systemd.directives, do not edit-->
893 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.login1.User"/>
895 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.login1.User"/>
897 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Terminate()"/>
899 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Kill()"/>
901 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"UID"/>
903 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"GID"/>
905 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Name"/>
907 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Timestamp"/>
909 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"TimestampMonotonic"/>
911 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"RuntimePath"/>
913 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Service"/>
915 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Slice"/>
917 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Display"/>
919 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"State"/>
921 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Sessions"/>
923 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleHint"/>
925 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleSinceHint"/>
927 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleSinceHintMonotonic"/>
929 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Linger"/>
931 <!--End of Autogenerated section-->
934 <title>Methods
</title>
936 <para><function>Terminate()
</function> and
<function>Kill()
</function> work similar to the
937 <function>TerminateUser()
</function> and
<function>KillUser()
</function> methods on the manager
942 <title>Signals
</title>
944 <para>Whenever
<varname>Sessions
</varname> or the idle state changes,
945 <function>PropertyChanged
</function> signals are sent out to which clients can subscribe.
</para>
949 <title>Properties
</title>
951 <para>The
<varname>UID
</varname> and
<varname>GID
</varname> properties encode the Unix UID and primary
952 GID of the user.
</para>
954 <para>The
<varname>Name
</varname> property encodes the user name.
</para>
956 <para><varname>Timestamp
</varname> and
<varname>TimestampMonotonic
</varname> encode the login time of
957 the user in microseconds since the epoch, in the
<constant>CLOCK_REALTIME
</constant> and
958 <constant>CLOCK_MONOTONIC
</constant> clocks, respectively.
</para>
960 <para><varname>RuntimePath
</varname> encodes the runtime path of the user,
961 i.e.
<varname>$XDG_RUNTIME_DIR
</varname>. For details see the
962 <ulink url=
"https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">
963 XDG Basedir Specification
966 <para><varname>Service
</varname> contains the unit name of the user systemd service of this
967 user. Each logged in user is assigned a user service that runs a user systemd instance. This is
968 usually an instance of
<filename>user@.service
</filename>.
</para>
970 <para><varname>Slice
</varname> contains the unit name of the user systemd slice of this user. Each
971 logged in user gets a private slice.
</para>
973 <para><varname>Display
</varname> encodes which graphical session should be used as the primary UI display
974 for the user. It is a structure encoding the session ID and the object path of the session to use.
</para>
976 <para><varname>State
</varname> encodes the user state and is one of
<literal>offline
</literal>,
977 <literal>lingering
</literal>,
<literal>online
</literal>,
<literal>active
</literal>, or
978 <literal>closing
</literal>. See
979 <citerefentry><refentrytitle>sd_uid_get_state
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
980 for more information about the states.
</para>
982 <para><varname>Sessions
</varname> is an array of structures encoding all current sessions of the
983 user. Each structure consists of the ID and object path.
</para>
985 <para>The
<varname>IdleHint
</varname>,
<varname>IdleSinceHint
</varname>, and
986 <varname>IdleSinceHintMonotonic
</varname> properties encode the idle hint state of the user, similar to
987 the
<interfacename>Manager
</interfacename>'s properties, but specific for this user.
</para>
989 <para>The
<varname>Linger
</varname> property shows whether lingering is enabled for this user.
</para>
994 <title>Session Objects
</title>
996 <programlisting executable=
"systemd-logind" node=
"/org/freedesktop/login1/session/1" interface=
"org.freedesktop.login1.Session">
997 node /org/freedesktop/login1/session/
1 {
998 interface org.freedesktop.login1.Session {
1004 SetIdleHint(in b idle);
1005 SetLockedHint(in b locked);
1007 in i signal_number);
1008 TakeControl(in b force);
1011 TakeDevice(in u major,
1015 ReleaseDevice(in u major,
1017 PauseDeviceComplete(in u major,
1019 SetBrightness(in s subsystem,
1023 PauseDevice(u major,
1026 ResumeDevice(u major,
1032 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1033 readonly s Id = '...';
1034 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1035 readonly (uo) User = ...;
1036 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1037 readonly s Name = '...';
1038 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1039 readonly t Timestamp = ...;
1040 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1041 readonly t TimestampMonotonic = ...;
1042 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1043 readonly u VTNr = ...;
1044 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1045 readonly (so) Seat = ...;
1046 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1047 readonly s TTY = '...';
1048 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1049 readonly s Display = '...';
1050 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1051 readonly b Remote = ...;
1052 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1053 readonly s RemoteHost = '...';
1054 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1055 readonly s RemoteUser = '...';
1056 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1057 readonly s Service = '...';
1058 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1059 readonly s Desktop = '...';
1060 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1061 readonly s Scope = '...';
1062 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1063 readonly u Leader = ...;
1064 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1065 readonly u Audit = ...;
1066 readonly s Type = '...';
1067 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
1068 readonly s Class = '...';
1069 readonly b Active = ...;
1070 readonly s State = '...';
1071 readonly b IdleHint = ...;
1072 readonly t IdleSinceHint = ...;
1073 readonly t IdleSinceHintMonotonic = ...;
1074 readonly b LockedHint = ...;
1076 interface org.freedesktop.DBus.Peer { ... };
1077 interface org.freedesktop.DBus.Introspectable { ... };
1078 interface org.freedesktop.DBus.Properties { ... };
1082 <!--Autogenerated cross-references for systemd.directives, do not edit-->
1084 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.login1.Session"/>
1086 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.login1.Session"/>
1088 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Terminate()"/>
1090 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Activate()"/>
1092 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Lock()"/>
1094 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Unlock()"/>
1096 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetIdleHint()"/>
1098 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetLockedHint()"/>
1100 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Kill()"/>
1102 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"TakeControl()"/>
1104 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ReleaseControl()"/>
1106 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetType()"/>
1108 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"TakeDevice()"/>
1110 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ReleaseDevice()"/>
1112 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"PauseDeviceComplete()"/>
1114 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"SetBrightness()"/>
1116 <variablelist class=
"dbus-signal" generated=
"True" extra-ref=
"PauseDevice"/>
1118 <variablelist class=
"dbus-signal" generated=
"True" extra-ref=
"ResumeDevice"/>
1120 <variablelist class=
"dbus-signal" generated=
"True" extra-ref=
"Lock"/>
1122 <variablelist class=
"dbus-signal" generated=
"True" extra-ref=
"Unlock"/>
1124 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Id"/>
1126 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"User"/>
1128 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Name"/>
1130 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Timestamp"/>
1132 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"TimestampMonotonic"/>
1134 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"VTNr"/>
1136 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Seat"/>
1138 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"TTY"/>
1140 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Display"/>
1142 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Remote"/>
1144 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"RemoteHost"/>
1146 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"RemoteUser"/>
1148 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Service"/>
1150 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Desktop"/>
1152 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Scope"/>
1154 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Leader"/>
1156 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Audit"/>
1158 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Type"/>
1160 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Class"/>
1162 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"Active"/>
1164 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"State"/>
1166 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleHint"/>
1168 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleSinceHint"/>
1170 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"IdleSinceHintMonotonic"/>
1172 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"LockedHint"/>
1174 <!--End of Autogenerated section-->
1177 <title>Methods
</title>
1179 <para><function>Terminate()
</function>,
<function>Activate()
</function>,
<function>Lock()
</function>,
1180 <function>Unlock()
</function>, and
<function>Kill()
</function> work similarly to the respective calls on
1181 the
<interfacename>Manager
</interfacename> object.
</para>
1183 <para><function>SetIdleHint()
</function> is called by the session object to update the idle state
1184 of the session whenever it changes.
</para>
1186 <para><function>TakeControl()
</function> allows a process to take exclusive managed device
1187 access-control for that session. Only one D-Bus connection can be a controller for a given session at any
1188 time. If the
<varname>force
</varname> argument is set (root only), an existing controller is kicked
1189 out and replaced. Otherwise, this method fails if there is already a controller. Note that this method is
1190 limited to D-Bus users with the effective UID set to the user of the session or root.
</para>
1192 <para><function>ReleaseControl()
</function> drops control of a given session. Closing the D-Bus
1193 connection implicitly releases control as well. See
<function>TakeControl()
</function> for more
1194 information. This method also releases all devices for which the controller requested ownership via
1195 <function>TakeDevice()
</function>.
</para>
1197 <para><function>SetType()
</function> allows the type of the session to be changed dynamically. It can
1198 only be called by session's current controller. If
<function>TakeControl()
</function> has not been
1199 called, this method will fail. In addition, the session type will be reset to its original value once
1200 control is released, either by calling
<function>ReleaseControl()
</function> or closing the D-Bus
1201 connection. This should help prevent a session from entering an inconsistent state, for example if the
1202 controller crashes. The only argument
<varname>type
</varname> is the new session type.
</para>
1204 <para><function>TakeDevice()
</function> allows a session controller to get a file descriptor for a
1205 specific device. Pass in the major and minor numbers of the character device and
1206 <filename>systemd-logind
</filename> will return a file descriptor for the device. Only a limited set of
1207 device-types is currently supported (but may be extended).
<filename>systemd-logind
</filename>
1208 automatically mutes the file descriptor if the session is inactive and resumes it once the session is
1209 activated again. This guarantees that a session can only access session devices if the session is
1210 active. Note that this revoke/resume mechanism is asynchronous and may happen at any given time. This
1211 only works on devices that are attached to the seat of the given session. A process is not required to
1212 have direct access to the device node.
<filename>systemd-logind
</filename> only requires you to be the
1213 active session controller (see
<function>TakeControl()
</function>). Also note that any device can only
1214 be requested once. As long as you don't release it, further
<function>TakeDevice()
</function> calls
1217 <para><function>ReleaseDevice()
</function> releases a device again (see
1218 <function>TakeDevice()
</function>). This is also implicitly done by
1219 <function>ReleaseControl()
</function> or when closing the D-Bus connection.
</para>
1221 <para><function>PauseDeviceComplete()
</function> allows a session controller to synchronously pause a
1222 device after receiving a
<function>PauseDevice(
<literal>pause
</literal>)
</function> signal. Forced
1223 signals (or after an internal timeout) are automatically completed by
1224 <filename>systemd-logind
</filename> asynchronously.
</para>
1226 <para><function>SetLockedHint()
</function> may be used to set the
"locked hint" to
1227 <varname>locked
</varname>, i.e. information whether the session is locked. This is intended to be used
1228 by the desktop environment to tell
<command>systemd-logind
</command> when the session is locked and
1231 <para><function>SetBrightness()
</function> may be used to set the display brightness. This is intended
1232 to be used by the desktop environment and allows unprivileged programs to access hardware settings in
1233 a controlled way. The
<varname>subsystem
</varname> parameter specifies a kernel subsystem, either
1234 <literal>backlight
</literal> or
<literal>leds
</literal>. The
<varname>name
</varname> parameter
1235 specifies a device name under the specified subsystem. The
<varname>brightness
</varname> parameter
1236 specifies the brightness. The range is defined by individual drivers, see
1237 <filename>/sys/class/
<varname>subsystem
</varname>/
<varname>name
</varname>/max_brightness
</filename>.
1242 <title>Signals
</title>
1244 <para>The active session controller exclusively gets
<function>PauseDevice
</function> and
1245 <function>ResumeDevice
</function> events for any device it requested via
1246 <function>TakeDevice()
</function>. They notify the controller whenever a device is paused or resumed. A
1247 device is never resumed if its session is inactive. Also note that
<function>PauseDevice
</function>
1248 signals are sent before the
<function>PropertyChanged
</function> signal for the
1249 <function>Active
</function> state. The inverse is true for
<function>ResumeDevice
</function>. A device
1250 may remain paused for unknown reasons even though the
<interfacename>Session
</interfacename> is active.
1253 <para>A
<function>PauseDevice
</function> signal carries the major and minor numbers and a string describing the
1254 type as arguments.
<function>force
</function> means the device was already paused by
1255 <filename>systemd-logind
</filename> and the signal is only an asynchronous
1256 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
1257 <function>PauseDeviceComplete()
</function>. This synchronous pausing mechanism is used for
1258 backwards-compatibility to VTs and
<filename>systemd-logind
</filename> is free to not make use of
1259 it. It is also free to send a forced
<function>PauseDevice
</function> if you don't respond in a timely
1260 manner (or for any other reason).
<function>gone
</function> means the device was unplugged from the
1261 system and you will no longer get any notifications about it. There is no need to call
1262 <function>ReleaseDevice()
</function>. You may call
<function>TakeDevice()
</function> again if a new
1263 device is assigned the major+minor combination.
</para>
1265 <para><function>ResumeDevice
</function> is sent whenever a session is active and a device is
1266 resumed. It carries the major/minor numbers as arguments and provides a new open file descriptor. You should
1267 switch to the new descriptor and close the old one. They are not guaranteed to have the same underlying
1268 open file descriptor in the kernel (except for a limited set of device types).
</para>
1270 <para>Whenever
<function>Active
</function> or the idle state changes,
1271 <function>PropertyChanged
</function> signals are sent out to which clients can subscribe.
</para>
1273 <para><function>Lock
</function>/
<function>Unlock
</function> is sent when the session is asked to be
1274 screen-locked/unlocked. A session manager of the session should listen to this signal and act
1275 accordingly. This signal is sent out as a result of the
<function>Lock()
</function> and
1276 <function>Unlock()
</function> methods, respectively.
</para>
1280 <title>Properties
</title>
1282 <para><varname>Id
</varname> encodes the session ID.
</para>
1284 <para><varname>User
</varname> encodes the user ID of the user this session belongs to. This is a
1285 structure consisting of the Unix UID and the object path.
</para>
1287 <para><varname>Name
</varname> encodes the user name.
</para>
1289 <para><varname>Timestamp
</varname> and
<varname>TimestampMonotonic
</varname> encode the microseconds
1290 since the epoch when the session was created, in
<constant>CLOCK_REALTIME
</constant> or
1291 <constant>CLOCK_MONOTONIC
</constant>, respectively.
</para>
1293 <para><varname>VTNr
</varname> encodes the virtual terminal number of the session if there is any,
0
1296 <para><varname>Seat
</varname> encodes the seat this session belongs to if there is any. This is a
1297 structure consisting of the ID and the seat object path.
</para>
1299 <para><varname>TTY
</varname> encodes the kernel TTY path of the session if this is a text login. If not
1300 this is an empty string.
</para>
1302 <para><varname>Display
</varname> encodes the X11 display name if this is a graphical login. If not,
1303 this is an empty string.
</para>
1305 <para><varname>Remote
</varname> encodes whether the session is local or remote.
</para>
1307 <para><varname>RemoteHost
</varname> and
<varname>RemoteUser
</varname> encode the remote host and user
1308 if this is a remote session, or an empty string otherwise.
</para>
1310 <para><varname>Service
</varname> encodes the PAM service name that registered the session.
</para>
1312 <para><varname>Desktop
</varname> describes the desktop environment running in the session (if
1315 <para><varname>Scope
</varname> contains the systemd scope unit name of this session.
</para>
1317 <para><varname>Leader
</varname> encodes the PID of the process that registered the session.
</para>
1319 <para><varname>Audit
</varname> encodes the Kernel Audit session ID of the session if auditing is
1322 <para><varname>Type
</varname> encodes the session type. It's one of
<literal>unspecified
</literal> (for
1323 cron PAM sessions and suchlike),
<literal>tty
</literal> (for text logins) or
1324 <literal>x11
</literal>/
<literal>mir
</literal>/
<literal>wayland
</literal> (for graphical logins).
</para>
1326 <para><varname>Class
</varname> encodes the session class. It's one of
<literal>user
</literal> (for
1327 normal user sessions),
<literal>greeter
</literal> (for display manager pseudo-sessions), or
1328 <literal>lock-screen
</literal> (for display lock screens).
</para>
1330 <para><varname>Active
</varname> is a boolean that is true if the session is active, i.e. currently in the
1331 foreground. This field is semi-redundant due to
<varname>State
</varname>.
</para>
1333 <para><varname>State
</varname> encodes the session state and one of
<literal>online
</literal>,
1334 <literal>active
</literal>, or
<literal>closing
</literal>. See
1335 <citerefentry><refentrytitle>sd_session_get_state
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
1336 for more information about the states.
</para>
1338 <para><varname>IdleHint
</varname>,
<varname>IdleSinceHint
</varname>, and
1339 <varname>IdleSinceHintMonotonic
</varname> encapsulate the idle hint state of this session, similarly to
1340 how the respective properties on the manager object do it for the whole system.
</para>
1342 <para><varname>LockedHint
</varname> shows the locked hint state of this session, as set by the
1343 <function>SetLockedHint()
</function> method described above.
</para>
1348 <title>Examples
</title>
1351 <title>Introspect
<interfacename>org.freedesktop.login1.Manager
</interfacename> on the bus
</title>
1353 <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \
1354 --object-path /org/freedesktop/login1
1359 <title>Introspect
<interfacename>org.freedesktop.login1.Seat
</interfacename> on the bus
</title>
1361 <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \
1362 --object-path /org/freedesktop/login1/seat/seat0
1367 <title>Introspect
<interfacename>org.freedesktop.login1.User
</interfacename> on the bus
</title>
1369 <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \
1370 --object-path /org/freedesktop/login1/user/_1000
1375 <title>Introspect
<interfacename>org.freedesktop.login1.Session
</interfacename> on the bus
</title>
1377 <programlisting>$ gdbus introspect --system --dest org.freedesktop.login1 \
1378 --object-path /org/freedesktop/login1/session/
45
1384 <title>Versioning
</title>
1386 <para>These D-Bus interfaces follow
<ulink url=
"http://0pointer.de/blog/projects/versioning-dbus.html">
1387 the usual interface versioning guidelines
</ulink>.
</para>