1ORG.FREEDESKTOP.LOGIN1(5) org.freedesktop.login1 ORG.FREEDESKTOP.LOGIN1(5)
2
6 org.freedesktop.login1 - The D-Bus interface of systemd-logind
7
9 systemd-logind.service(8) is a system service that keeps track of user
10 logins and seats.
11 The daemon provides both a C library interface as well as a D-Bus
13 interface. The library interface may be used to introspect and watch
14 the state of user logins and seats. The bus interface provides the same
15 functionality but in addition may also be used to make changes to the
16 system state. For more information please consult sd-login(3).
17
19 The service exposes the following interfaces on the Manager object on
20 the bus:
21 node /org/freedesktop/login1 {
23 interface org.freedesktop.login1.Manager {
24 methods:
25 GetSession(in s session_id,
26 out o object_path);
27 GetSessionByPID(in u pid,
28 out o object_path);
29 GetUser(in u uid,
30 out o object_path);
31 GetUserByPID(in u pid,
32 out o object_path);
33 GetSeat(in s seat_id,
34 out o object_path);
35 ListSessions(out a(susso) sessions);
36 ListUsers(out a(uso) users);
37 ListSeats(out a(so) seats);
38 ListInhibitors(out a(ssssuu) inhibitors);
39 @org.freedesktop.systemd1.Privileged("true")
40 CreateSession(in u uid,
41 in u pid,
42 in s service,
43 in s type,
44 in s class,
45 in s desktop,
46 in s seat_id,
47 in u vtnr,
48 in s tty,
49 in s display,
50 in b remote,
51 in s remote_user,
52 in s remote_host,
53 in a(sv) properties,
54 out s session_id,
55 out o object_path,
56 out s runtime_path,
57 out h fifo_fd,
58 out u uid,
59 out s seat_id,
60 out u vtnr,
61 out b existing);
62 @org.freedesktop.systemd1.Privileged("true")
63 ReleaseSession(in s session_id);
64 ActivateSession(in s session_id);
65 ActivateSessionOnSeat(in s session_id,
66 in s seat_id);
67 LockSession(in s session_id);
68 UnlockSession(in s session_id);
69 LockSessions();
70 UnlockSessions();
71 KillSession(in s session_id,
72 in s who,
73 in i signal_number);
74 KillUser(in u uid,
75 in i signal_number);
76 TerminateSession(in s session_id);
77 TerminateUser(in u uid);
78 TerminateSeat(in s seat_id);
79 SetUserLinger(in u uid,
80 in b enable,
81 in b interactive);
82 AttachDevice(in s seat_id,
83 in s sysfs_path,
84 in b interactive);
85 FlushDevices(in b interactive);
86 PowerOff(in b interactive);
87 PowerOffWithFlags(in t flags);
88 Reboot(in b interactive);
89 RebootWithFlags(in t flags);
90 Halt(in b interactive);
91 HaltWithFlags(in t flags);
92 Suspend(in b interactive);
93 SuspendWithFlags(in t flags);
94 Hibernate(in b interactive);
95 HibernateWithFlags(in t flags);
96 HybridSleep(in b interactive);
97 HybridSleepWithFlags(in t flags);
98 SuspendThenHibernate(in b interactive);
99 SuspendThenHibernateWithFlags(in t flags);
100 CanPowerOff(out s result);
101 CanReboot(out s result);
102 CanHalt(out s result);
103 CanSuspend(out s result);
104 CanHibernate(out s result);
105 CanHybridSleep(out s result);
106 CanSuspendThenHibernate(out s result);
107 ScheduleShutdown(in s type,
108 in t usec);
109 CancelScheduledShutdown(out b cancelled);
110 Inhibit(in s what,
111 in s who,
112 in s why,
113 in s mode,
114 out h pipe_fd);
115 CanRebootParameter(out s result);
116 SetRebootParameter(in s parameter);
117 CanRebootToFirmwareSetup(out s result);
118 SetRebootToFirmwareSetup(in b enable);
119 CanRebootToBootLoaderMenu(out s result);
120 SetRebootToBootLoaderMenu(in t timeout);
121 CanRebootToBootLoaderEntry(out s result);
122 SetRebootToBootLoaderEntry(in s boot_loader_entry);
123 SetWallMessage(in s wall_message,
124 in b enable);
125 signals:
126 SessionNew(s session_id,
127 o object_path);
128 SessionRemoved(s session_id,
129 o object_path);
130 UserNew(u uid,
131 o object_path);
132 UserRemoved(u uid,
133 o object_path);
134 SeatNew(s seat_id,
135 o object_path);
136 SeatRemoved(s seat_id,
137 o object_path);
138 PrepareForShutdown(b start);
139 PrepareForSleep(b start);
140 properties:
141 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
142 @org.freedesktop.systemd1.Privileged("true")
143 readwrite b EnableWallMessages = ...;
144 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
145 @org.freedesktop.systemd1.Privileged("true")
146 readwrite s WallMessage = '...';
147 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
148 readonly u NAutoVTs = ...;
149 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
150 readonly as KillOnlyUsers = ['...', ...];
151 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
152 readonly as KillExcludeUsers = ['...', ...];
153 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
154 readonly b KillUserProcesses = ...;
155 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
156 readonly s RebootParameter = '...';
157 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
158 readonly b RebootToFirmwareSetup = ...;
159 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
160 readonly t RebootToBootLoaderMenu = ...;
161 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
162 readonly s RebootToBootLoaderEntry = '...';
163 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
164 readonly as BootLoaderEntries = ['...', ...];
165 readonly b IdleHint = ...;
166 readonly t IdleSinceHint = ...;
167 readonly t IdleSinceHintMonotonic = ...;
168 readonly s BlockInhibited = '...';
169 readonly s DelayInhibited = '...';
170 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
171 readonly t InhibitDelayMaxUSec = ...;
172 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
173 readonly t UserStopDelayUSec = ...;
174 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
175 readonly s HandlePowerKey = '...';
176 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
177 readonly s HandlePowerKeyLongPress = '...';
178 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
179 readonly s HandleRebootKey = '...';
180 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
181 readonly s HandleRebootKeyLongPress = '...';
182 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
183 readonly s HandleSuspendKey = '...';
184 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
185 readonly s HandleSuspendKeyLongPress = '...';
186 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
187 readonly s HandleHibernateKey = '...';
188 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
189 readonly s HandleHibernateKeyLongPress = '...';
190 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
191 readonly s HandleLidSwitch = '...';
192 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
193 readonly s HandleLidSwitchExternalPower = '...';
194 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
195 readonly s HandleLidSwitchDocked = '...';
196 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
197 readonly t HoldoffTimeoutUSec = ...;
198 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
199 readonly s IdleAction = '...';
200 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
201 readonly t IdleActionUSec = ...;
202 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
203 readonly b PreparingForShutdown = ...;
204 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
205 readonly b PreparingForSleep = ...;
206 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
207 readonly (st) ScheduledShutdown = ...;
208 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
209 readonly b Docked = ...;
210 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
211 readonly b LidClosed = ...;
212 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
213 readonly b OnExternalPower = ...;
214 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
215 readonly b RemoveIPC = ...;
216 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
217 readonly t RuntimeDirectorySize = ...;
218 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
219 readonly t RuntimeDirectoryInodesMax = ...;
220 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
221 readonly t InhibitorsMax = ...;
222 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
223 readonly t NCurrentInhibitors = ...;
224 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
225 readonly t SessionsMax = ...;
226 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
227 readonly t NCurrentSessions = ...;
228 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
229 readonly t StopIdleSessionUSec = ...;
230 };
231 interface org.freedesktop.DBus.Peer { ... };
232 interface org.freedesktop.DBus.Introspectable { ... };
233 interface org.freedesktop.DBus.Properties { ... };
234 };
235 Methods
351 GetSession() may be used to get the session object path for the session
352 with the specified ID. Similarly, GetUser() and GetSeat() get the user
353 and seat objects, respectively. GetSessionByPID() and GetUserByPID()
354 get the session/user object the specified PID belongs to if there is
355 any.
356 ListSessions() returns an array of all current sessions. The structures
358 in the array consist of the following fields: session id, user id, user
359 name, seat id, session object path. If a session does not have a seat
360 attached, the seat id field will be an empty string.
361 ListUsers() returns an array of all currently logged in users. The
363 structures in the array consist of the following fields: user id, user
364 name, user object path.
365 ListSeats() returns an array of all currently available seats. The
367 structure in the array consists of the following fields: seat id, seat
368 object path.
369 ListInhibitors() lists all currently active inhibitors. It returns an
371 array of structures consisting of what, who, why, mode, uid (user ID),
372 and pid (process ID).
373 CreateSession() and ReleaseSession() may be used to open or close login
375 sessions. These calls should never be invoked directly by clients.
376 Creating/closing sessions is exclusively the job of PAM and its
377 pam_systemd(8) module.
378 ActivateSession() brings the session with the specified ID into the
380 foreground. ActivateSessionOnSeat() does the same, but only if the
381 seat id matches.
382 LockSession() asks the session with the specified ID to activate the
384 screen lock. UnlockSession() asks the session with the specified ID to
385 remove an active screen lock, if there is any. This is implemented by
386 sending out the Lock() and Unlock() signals from the respective session
387 object which session managers are supposed to listen on.
388 LockSessions() asks all sessions to activate their screen locks. This
390 may be used to lock access to the entire machine in one action.
391 Similarly, UnlockSessions() asks all sessions to deactivate their
392 screen locks.
393 KillSession() may be used to send a Unix signal to one or all processes
395 of a session. As arguments it takes the session id, either the string
396 "leader" or "all" and a signal number. If "leader" is passed only the
397 session "leader" is killed. If "all" is passed all processes of the
398 session are killed.
399 KillUser() may be used to send a Unix signal to all processes of a
401 user. As arguments it takes the user id and a signal number.
402 TerminateSession(), TerminateUser(), TerminateSeat() may be used to
404 forcibly terminate one specific session, all processes of a user, and
405 all sessions attached to a specific seat, respectively. The session,
406 user, and seat are identified by their respective IDs.
407 SetUserLinger() enables or disables user lingering. If enabled, the
409 runtime directory of a user is kept around and they may continue to run
410 processes while logged out. If disabled, the runtime directory goes
411 away as soon as they log out. SetUserLinger() expects three arguments:
412 the UID, a boolean whether to enable/disable and a boolean controlling
413 the polkit[1] authorization interactivity (see below). Note that the
414 user linger state is persistently stored on disk.
415 AttachDevice() may be used to assign a specific device to a specific
417 seat. The device is identified by its /sys/ path and must be eligible
418 for seat assignments. AttachDevice() takes three arguments: the seat
419 id, the sysfs path, and a boolean for controlling polkit interactivity
420 (see below). Device assignments are persistently stored on disk. To
421 create a new seat, simply specify a previously unused seat id. For more
422 information about the seat assignment logic see sd-login(3).
423 FlushDevices() removes all explicit seat assignments for devices,
425 resetting all assignments to the automatic defaults. The only argument
426 it takes is the polkit interactivity boolean (see below).
427 PowerOff(), Reboot(), Halt(), Suspend(), and Hibernate() result in the
429 system being powered off, rebooted, halted (shut down without turning
430 off power), suspended (the system state is saved to RAM and the CPU is
431 turned off), or hibernated (the system state is saved to disk and the
432 machine is powered down). HybridSleep() results in the system entering
433 a hybrid-sleep mode, i.e. the system is both hibernated and suspended.
434 SuspendThenHibernate() results in the system being suspended, then
435 later woken using an RTC timer and hibernated. The only argument is the
436 polkit interactivity boolean interactive (see below). The main purpose
437 of these calls is that they enforce polkit policy and hence allow
438 powering off/rebooting/suspending/hibernating even by unprivileged
439 users. They also enforce inhibition locks for non-privileged users. UIs
440 should expose these calls as the primary mechanism to
441 poweroff/reboot/suspend/hibernate the machine. Methods
442 PowerOffWithFlags(), RebootWithFlags(), HaltWithFlags(),
443 SuspendWithFlags(), HibernateWithFlags(), HybridSleepWithFlags() and
444 SuspendThenHibernateWithFlags() add flags to allow for extendability,
445 defined as follows:
446 #define SD_LOGIND_ROOT_CHECK_INHIBITORS (UINT64_C(1) << 0)
448 #define SD_LOGIND_KEXEC_REBOOT (UINT64_C(1) << 1)
449 #define SD_LOGIND_SOFT_REBOOT (UINT64_C(1) << 2)
450 When the flags is 0 then these methods behave just like the versions
453 without flags. When SD_LOGIND_ROOT_CHECK_INHIBITORS (0x01) is set,
454 active inhibitors are honoured for privileged users too. When
455 SD_LOGIND_KEXEC_REBOOT (0x02) is set, then RebootWithFlags() performs a
456 kexec reboot if kexec kernel is loaded. When SD_LOGIND_SOFT_REBOOT
457 (0x04) is set, then RebootWithFlags() performs a userspace reboot only.
458 SetRebootParameter() sets a parameter for a subsequent reboot
460 operation. See the description of reboot in systemctl(1) and reboot(2)
461 for more information.
462 SetRebootToFirmwareSetup(), SetRebootToBootLoaderMenu(), and
464 SetRebootToBootLoaderEntry() configure the action to be taken from the
465 boot loader after a reboot: respectively entering firmware setup mode,
466 the boot loader menu, or a specific boot loader entry. See systemctl(1)
467 for the corresponding command line interface.
468 CanPowerOff(), CanReboot(), CanHalt(), CanSuspend(), CanHibernate(),
470 CanHybridSleep(), CanSuspendThenHibernate(), CanRebootParameter(),
471 CanRebootToFirmwareSetup(), CanRebootToBootLoaderMenu(), and
472 CanRebootToBootLoaderEntry() test whether the system supports the
473 respective operation and whether the calling user is allowed to execute
474 it. Returns one of "na", "yes", "no", and "challenge". If "na" is
475 returned, the operation is not available because hardware, kernel, or
476 drivers do not support it. If "yes" is returned, the operation is
477 supported and the user may execute the operation without further
478 authentication. If "no" is returned, the operation is available but the
479 user is not allowed to execute the operation. If "challenge" is
480 returned, the operation is available but only after authorization.
481 ScheduleShutdown() schedules a shutdown operation type at time usec in
483 microseconds since the UNIX epoch. type can be one of "poweroff",
484 "dry-poweroff", "reboot", "dry-reboot", "halt", and "dry-halt". (The
485 "dry-" variants do not actually execute the shutdown action.)
486 CancelScheduledShutdown() cancels a scheduled shutdown. The output
487 parameter cancelled is true if a shutdown operation was scheduled.
488 SetWallMessage() sets the wall message (the message that will be sent
490 out to all terminals and stored in a utmp(5) record) for a subsequent
491 scheduled shutdown operation. The parameter wall_message specifies the
492 shutdown reason (and may be empty) which will be included in the
493 shutdown message. The parameter enable specifies whether to print a
494 wall message on shutdown.
495 Inhibit() creates an inhibition lock. It takes four parameters: what,
497 who, why, and mode. what is one or more of "shutdown", "sleep",
498 "idle", "handle-power-key", "handle-suspend-key",
499 "handle-hibernate-key", "handle-lid-switch", separated by colons, for
500 inhibiting poweroff/reboot, suspend/hibernate, the automatic idle
501 logic, or hardware key handling. who should be a short human readable
502 string identifying the application taking the lock. why should be a
503 short human readable string identifying the reason why the lock is
504 taken. Finally, mode is either "block" or "delay" which encodes whether
505 the inhibit shall be consider mandatory or whether it should just delay
506 the operation to a certain maximum time. The method returns a file
507 descriptor. The lock is released the moment this file descriptor and
508 all its duplicates are closed. For more information on the inhibition
509 logic see Inhibitor Locks[2].
510 Signals
512 Whenever the inhibition state or idle hint changes, PropertyChanged
513 signals are sent out to which clients can subscribe.
514 The SessionNew, SessionRemoved, UserNew, UserRemoved, SeatNew, and
516 SeatRemoved signals are sent each time a session is created or removed,
517 a user logs in or out, or a seat is added or removed. They each contain
518 the ID of the object plus the object path.
519 The PrepareForShutdown() and PrepareForSleep() signals are sent right
521 before (with the argument "true") or after (with the argument "false")
522 the system goes down for reboot/poweroff and suspend/hibernate,
523 respectively. This may be used by applications to save data on disk,
524 release memory, or do other jobs that should be done shortly before
525 shutdown/sleep, in conjunction with delay inhibitor locks. After
526 completion of this work they should release their inhibition locks in
527 order to not delay the operation any further. For more information see
528 Inhibitor Locks[2].
529 Properties
531 Most properties simply reflect the configuration, see logind.conf(5).
532 This includes: NAutoVTs, KillOnlyUsers, KillExcludeUsers,
533 KillUserProcesses, IdleAction, InhibitDelayMaxUSec, InhibitorsMax,
534 UserStopDelayUSec, HandlePowerKey, HandleSuspendKey,
535 HandleHibernateKey, HandleLidSwitch, HandleLidSwitchExternalPower,
536 HandleLidSwitchDocked, IdleActionUSec, HoldoffTimeoutUSec, RemoveIPC,
537 RuntimeDirectorySize, RuntimeDirectoryInodesMax, InhibitorsMax, and
538 SessionsMax.
539 The IdleHint property reflects the idle hint state of the system. If
541 the system is idle it might get into automatic suspend or shutdown
542 depending on the configuration.
543 IdleSinceHint and IdleSinceHintMonotonic encode the timestamps of the
545 last change of the idle hint boolean, in CLOCK_REALTIME and
546 CLOCK_MONOTONIC timestamps, respectively, in microseconds since the
547 epoch.
548 The BlockInhibited and DelayInhibited properties encode the currently
550 active locks of the respective modes. They are colon separated lists of
551 "shutdown", "sleep", and "idle" (see above).
552 NCurrentSessions and NCurrentInhibitors contain the number of currently
554 registered sessions and inhibitors.
555 The BootLoaderEntries property contains a list of boot loader entries.
557 This includes boot loader entries defined in configuration and any
558 additional loader entries reported by the boot loader. See systemd-
559 boot(7) for more information.
560 The PreparingForShutdown and PreparingForSleep boolean properties are
562 true during the interval between the two PrepareForShutdown and
563 PrepareForSleep signals respectively. Note that these properties do not
564 send out PropertyChanged signals.
565 The RebootParameter property shows the value set with the
567 SetRebootParameter() method described above.
568 ScheduledShutdown shows the value pair set with the ScheduleShutdown()
570 method described above.
571 RebootToFirmwareSetup, RebootToBootLoaderMenu, and
573 RebootToBootLoaderEntry are true when the resprective post-reboot
574 operation was selected with SetRebootToFirmwareSetup,
575 SetRebootToBootLoaderMenu, or SetRebootToBootLoaderEntry.
576 The WallMessage and EnableWallMessages properties reflect the shutdown
578 reason and wall message enablement switch which can be set with the
579 SetWallMessage() method described above.
580 Docked is true if the machine is connected to a dock. LidClosed is
582 true when the lid (of a laptop) is closed. OnExternalPower is true
583 when the machine is connected to an external power supply.
584 Security
586 A number of operations are protected via the polkit privilege system.
587 SetUserLinger() requires the org.freedesktop.login1.set-user-linger
588 privilege. AttachDevice() requires
589 org.freedesktop.login1.attach-device and FlushDevices() requires
590 org.freedesktop.login1.flush-devices. PowerOff(), Reboot(), Halt(),
591 Suspend(), Hibernate() require org.freedesktop.login1.power-off,
592 org.freedesktop.login1.power-off-multiple-sessions,
593 org.freedesktop.login1.power-off-ignore-inhibit,
594 org.freedesktop.login1.reboot,
595 org.freedesktop.login1.reboot-multiple-sessions,
596 org.freedesktop.login1.reboot-ignore-inhibit,
597 org.freedesktop.login1.halt,
598 org.freedesktop.login1.halt-multiple-sessions,
599 org.freedesktop.login1.halt-ignore-inhibit,
600 org.freedesktop.login1.suspend,
601 org.freedesktop.login1.suspend-multiple-sessions,
602 org.freedesktop.login1.suspend-ignore-inhibit,
603 org.freedesktop.login1.hibernate,
604 org.freedesktop.login1.hibernate-multiple-sessions,
605 org.freedesktop.login1.hibernate-ignore-inhibit, respectively depending
606 on whether there are other sessions around or active inhibits are
607 present. HybridSleep() and SuspendThenHibernate() use the same
608 privileges as Hibernate(). SetRebootParameter() requires
609 org.freedesktop.login1.set-reboot-parameter.
610 SetRebootToFirmwareSetup requires
612 org.freedesktop.login1.set-reboot-to-firmware-setup.
613 SetRebootToBootLoaderMenu requires
614 org.freedesktop.login1.set-reboot-to-boot-loader-menu.
615 SetRebootToBootLoaderEntry requires
616 org.freedesktop.login1.set-reboot-to-boot-loader-entry.
617 ScheduleShutdown and CancelScheduledShutdown require the same
619 privileges (listed above) as the immediate poweroff/reboot/halt
620 operations.
621 Inhibit() is protected via one of
623 org.freedesktop.login1.inhibit-block-shutdown,
624 org.freedesktop.login1.inhibit-delay-shutdown,
625 org.freedesktop.login1.inhibit-block-sleep,
626 org.freedesktop.login1.inhibit-delay-sleep,
627 org.freedesktop.login1.inhibit-block-idle,
628 org.freedesktop.login1.inhibit-handle-power-key,
629 org.freedesktop.login1.inhibit-handle-suspend-key,
630 org.freedesktop.login1.inhibit-handle-hibernate-key,
631 org.freedesktop.login1.inhibit-handle-lid-switch depending on the lock
632 type and mode taken.
633 The interactive boolean parameters can be used to control whether
635 polkit should interactively ask the user for authentication credentials
636 if required.
637
639 node /org/freedesktop/login1/seat/seat0 {
640 interface org.freedesktop.login1.Seat {
641 methods:
642 Terminate();
643 ActivateSession(in s session_id);
644 SwitchTo(in u vtnr);
645 SwitchToNext();
646 SwitchToPrevious();
647 properties:
648 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
649 readonly s Id = '...';
650 readonly (so) ActiveSession = ...;
651 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
652 readonly b CanTTY = ...;
653 readonly b CanGraphical = ...;
654 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
655 readonly a(so) Sessions = [...];
656 readonly b IdleHint = ...;
657 readonly t IdleSinceHint = ...;
658 readonly t IdleSinceHintMonotonic = ...;
659 };
660 interface org.freedesktop.DBus.Peer { ... };
661 interface org.freedesktop.DBus.Introspectable { ... };
662 interface org.freedesktop.DBus.Properties { ... };
663 };
664 Methods
681 Terminate() and ActivateSession() work similarly to TerminateSeat() and
682 ActivationSessionOnSeat() on the Manager object.
683 SwitchTo() switches to the session on the virtual terminal vtnr.
685 SwitchToNext() and SwitchToPrevious() switch to, respectively, the next
686 and previous sessions on the seat in the order of virtual terminals. If
687 there is no active session, they switch to, respectively, the first and
688 last session on the seat.
689 Signals
691 Whenever ActiveSession, Sessions, CanGraphical, CanTTY, or the idle
692 state changes, PropertyChanged signals are sent out to which clients
693 can subscribe.
694 Properties
696 The Id property encodes the ID of the seat.
697 ActiveSession encodes the currently active session if there is one. It
699 is a structure consisting of the session id and the object path.
700 CanTTY encodes whether the session is suitable for text logins, and
702 CanGraphical whether it is suitable for graphical sessions.
703 The Sessions property is an array of all current sessions of this seat,
705 each encoded in a structure consisting of the ID and the object path.
706 The IdleHint, IdleSinceHint, and IdleSinceHintMonotonic properties
708 encode the idle state, similarly to the ones exposed on the Manager
709 object, but specific for this seat.
710
712 node /org/freedesktop/login1/user/_1000 {
713 interface org.freedesktop.login1.User {
714 methods:
715 Terminate();
716 Kill(in i signal_number);
717 properties:
718 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
719 readonly u UID = ...;
720 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
721 readonly u GID = ...;
722 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
723 readonly s Name = '...';
724 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
725 readonly t Timestamp = ...;
726 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
727 readonly t TimestampMonotonic = ...;
728 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
729 readonly s RuntimePath = '...';
730 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
731 readonly s Service = '...';
732 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
733 readonly s Slice = '...';
734 readonly (so) Display = ...;
735 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
736 readonly s State = '...';
737 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
738 readonly a(so) Sessions = [...];
739 readonly b IdleHint = ...;
740 readonly t IdleSinceHint = ...;
741 readonly t IdleSinceHintMonotonic = ...;
742 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
743 readonly b Linger = ...;
744 };
745 interface org.freedesktop.DBus.Peer { ... };
746 interface org.freedesktop.DBus.Introspectable { ... };
747 interface org.freedesktop.DBus.Properties { ... };
748 };
749 Methods
770 Terminate() and Kill() work similarly to the TerminateUser() and
771 KillUser() methods on the manager object.
772 Signals
774 Whenever Sessions or the idle state changes, PropertyChanged signals
775 are sent out to which clients can subscribe.
776 Properties
778 The UID and GID properties encode the Unix UID and primary GID of the
779 user.
780 The Name property encodes the user name.
782 Timestamp and TimestampMonotonic encode the login time of the user in
784 microseconds since the epoch, in the CLOCK_REALTIME and CLOCK_MONOTONIC
785 clocks, respectively.
786 RuntimePath encodes the runtime path of the user, i.e.
788 $XDG_RUNTIME_DIR. For details see the XDG Basedir Specification[3].
789 Service contains the unit name of the user systemd service of this
791 user. Each logged in user is assigned a user service that runs a user
792 systemd instance. This is usually an instance of user@.service.
793 Slice contains the unit name of the user systemd slice of this user.
795 Each logged in user gets a private slice.
796 Display encodes which graphical session should be used as the primary
798 UI display for the user. It is a structure encoding the session ID and
799 the object path of the session to use.
800 State encodes the user state and is one of "offline", "lingering",
802 "online", "active", or "closing". See sd_uid_get_state(3) for more
803 information about the states.
804 Sessions is an array of structures encoding all current sessions of the
806 user. Each structure consists of the ID and object path.
807 The IdleHint, IdleSinceHint, and IdleSinceHintMonotonic properties
809 encode the idle hint state of the user, similarly to the Manager's
810 properties, but specific for this user.
811 The Linger property shows whether lingering is enabled for this user.
813
815 node /org/freedesktop/login1/session/1 {
816 interface org.freedesktop.login1.Session {
817 methods:
818 Terminate();
819 Activate();
820 Lock();
821 Unlock();
822 SetIdleHint(in b idle);
823 SetLockedHint(in b locked);
824 Kill(in s who,
825 in i signal_number);
826 TakeControl(in b force);
827 ReleaseControl();
828 SetType(in s type);
829 SetDisplay(in s display);
830 SetTTY(in h tty_fd);
831 TakeDevice(in u major,
832 in u minor,
833 out h fd,
834 out b inactive);
835 ReleaseDevice(in u major,
836 in u minor);
837 PauseDeviceComplete(in u major,
838 in u minor);
839 SetBrightness(in s subsystem,
840 in s name,
841 in u brightness);
842 signals:
843 PauseDevice(u major,
844 u minor,
845 s type);
846 ResumeDevice(u major,
847 u minor,
848 h fd);
849 Lock();
850 Unlock();
851 properties:
852 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
853 readonly s Id = '...';
854 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
855 readonly (uo) User = ...;
856 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
857 readonly s Name = '...';
858 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
859 readonly t Timestamp = ...;
860 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
861 readonly t TimestampMonotonic = ...;
862 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
863 readonly u VTNr = ...;
864 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
865 readonly (so) Seat = ...;
866 readonly s TTY = '...';
867 readonly s Display = '...';
868 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
869 readonly b Remote = ...;
870 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
871 readonly s RemoteHost = '...';
872 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
873 readonly s RemoteUser = '...';
874 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
875 readonly s Service = '...';
876 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
877 readonly s Desktop = '...';
878 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
879 readonly s Scope = '...';
880 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
881 readonly u Leader = ...;
882 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
883 readonly u Audit = ...;
884 readonly s Type = '...';
885 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
886 readonly s Class = '...';
887 readonly b Active = ...;
888 readonly s State = '...';
889 readonly b IdleHint = ...;
890 readonly t IdleSinceHint = ...;
891 readonly t IdleSinceHintMonotonic = ...;
892 readonly b LockedHint = ...;
893 };
894 interface org.freedesktop.DBus.Peer { ... };
895 interface org.freedesktop.DBus.Introspectable { ... };
896 interface org.freedesktop.DBus.Properties { ... };
897 };
898 Methods
947 Terminate(), Activate(), Lock(), Unlock(), and Kill() work similarly to
948 the respective calls on the Manager object.
949 SetIdleHint() is called by the session object to update the idle state
951 of the session whenever it changes.
952 TakeControl() allows a process to take exclusive managed device
954 access-control for that session. Only one D-Bus connection can be a
955 controller for a given session at any time. If the force argument is
956 set (root only), an existing controller is kicked out and replaced.
957 Otherwise, this method fails if there is already a controller. Note
958 that this method is limited to D-Bus users with the effective UID set
959 to the user of the session or root.
960 ReleaseControl() drops control of a given session. Closing the D-Bus
962 connection implicitly releases control as well. See TakeControl() for
963 more information. This method also releases all devices for which the
964 controller requested ownership via TakeDevice().
965 SetType() allows the type of the session to be changed dynamically. It
967 can only be called by session's current controller. If TakeControl()
968 has not been called, this method will fail. In addition, the session
969 type will be reset to its original value once control is released,
970 either by calling ReleaseControl() or closing the D-Bus connection.
971 This should help prevent a session from entering an inconsistent state,
972 for example if the controller crashes. The only argument type is the
973 new session type.
974 SetDisplay() allows the display name of the graphical session to be
976 changed. This is useful if the display server is started as part of the
977 session. It can only be called by session's current controller. If
978 TakeControl() has not been called, this method will fail. The only
979 argument display is the new display name.
980 SetTTY() allows the device name of the session to be changed. This is
982 useful if the tty device is only known after authentication. It can
983 only be called by session's current controller. If TakeControl() has
984 not been called, this method will fail. The only argument tty_fd is a
985 file handle to the new tty device.
986 TakeDevice() allows a session controller to get a file descriptor for a
988 specific device. Pass in the major and minor numbers of the character
989 device and systemd-logind will return a file descriptor for the device.
990 Only a limited set of device-types is currently supported (but may be
991 extended). systemd-logind automatically mutes the file descriptor if
992 the session is inactive and resumes it once the session is activated
993 again. This guarantees that a session can only access session devices
994 if the session is active. Note that this revoke/resume mechanism is
995 asynchronous and may happen at any given time. This only works on
996 devices that are attached to the seat of the given session. A process
997 is not required to have direct access to the device node.
998 systemd-logind only requires you to be the active session controller
999 (see TakeControl()). Also note that any device can only be requested
1000 once. As long as you don't release it, further TakeDevice() calls will
1001 fail.
1002 ReleaseDevice() releases a device again (see TakeDevice()). This is
1004 also implicitly done by ReleaseControl() or when closing the D-Bus
1005 connection.
1006 PauseDeviceComplete() allows a session controller to synchronously
1008 pause a device after receiving a PauseDevice("pause") signal. Forced
1009 signals (or after an internal timeout) are automatically completed by
1010 systemd-logind asynchronously.
1011 SetLockedHint() may be used to set the "locked hint" to locked, i.e.
1013 information whether the session is locked. This is intended to be used
1014 by the desktop environment to tell systemd-logind when the session is
1015 locked and unlocked.
1016 SetBrightness() may be used to set the display brightness. This is
1018 intended to be used by the desktop environment and allows unprivileged
1019 programs to access hardware settings in a controlled way. The subsystem
1020 parameter specifies a kernel subsystem, either "backlight" or "leds".
1021 The name parameter specifies a device name under the specified
1022 subsystem. The brightness parameter specifies the brightness. The range
1023 is defined by individual drivers, see
1024 /sys/class/subsystem/name/max_brightness.
1025 Signals
1027 The active session controller exclusively gets PauseDevice and
1028 ResumeDevice events for any device it requested via TakeDevice(). They
1029 notify the controller whenever a device is paused or resumed. A device
1030 is never resumed if its session is inactive. Also note that PauseDevice
1031 signals are sent before the PropertyChanged signal for the Active
1032 state. The inverse is true for ResumeDevice. A device may remain paused
1033 for unknown reasons even though the Session is active.
1034 A PauseDevice signal carries the major and minor numbers and a string
1036 describing the type as arguments. force means the device was already
1037 paused by systemd-logind and the signal is only an asynchronous
1038 notification. pause means systemd-logind grants you a limited amount
1039 of time to pause the device. You must respond to this via
1040 PauseDeviceComplete(). This synchronous pausing mechanism is used for
1041 backwards-compatibility to VTs and systemd-logind is free to not make
1042 use of it. It is also free to send a forced PauseDevice if you don't
1043 respond in a timely manner (or for any other reason). gone means the
1044 device was unplugged from the system and you will no longer get any
1045 notifications about it. There is no need to call ReleaseDevice(). You
1046 may call TakeDevice() again if a new device is assigned the major+minor
1047 combination.
1048 ResumeDevice is sent whenever a session is active and a device is
1050 resumed. It carries the major/minor numbers as arguments and provides a
1051 new open file descriptor. You should switch to the new descriptor and
1052 close the old one. They are not guaranteed to have the same underlying
1053 open file descriptor in the kernel (except for a limited set of device
1054 types).
1055 Whenever Active or the idle state changes, PropertyChanged signals are
1057 sent out to which clients can subscribe.
1058 Lock/Unlock is sent when the session is asked to be
1060 screen-locked/unlocked. A session manager of the session should listen
1061 to this signal and act accordingly. This signal is sent out as a result
1062 of the Lock() and Unlock() methods, respectively.
1063 Properties
1065 Id encodes the session ID.
1066 User encodes the user ID of the user this session belongs to. This is a
1068 structure consisting of the Unix UID and the object path.
1069 Name encodes the user name.
1071 Timestamp and TimestampMonotonic encode the microseconds since the
1073 epoch when the session was created, in CLOCK_REALTIME or
1074 CLOCK_MONOTONIC, respectively.
1075 VTNr encodes the virtual terminal number of the session if there is
1077 any, 0 otherwise.
1078 Seat encodes the seat this session belongs to if there is any. This is
1080 a structure consisting of the ID and the seat object path.
1081 TTY encodes the kernel TTY path of the session if this is a text login.
1083 If not this is an empty string.
1084 Display encodes the X11 display name if this is a graphical login. If
1086 not, this is an empty string.
1087 Remote encodes whether the session is local or remote.
1089 RemoteHost and RemoteUser encode the remote host and user if this is a
1091 remote session, or an empty string otherwise.
1092 Service encodes the PAM service name that registered the session.
1094 Desktop describes the desktop environment running in the session (if
1096 known).
1097 Scope contains the systemd scope unit name of this session.
1099 Leader encodes the PID of the process that registered the session.
1101 Audit encodes the Kernel Audit session ID of the session if auditing is
1103 available.
1104 Type encodes the session type. It's one of "unspecified" (for cron PAM
1106 sessions and suchlike), "tty" (for text logins) or
1107 "x11"/"mir"/"wayland" (for graphical logins).
1108 Class encodes the session class. It's one of "user" (for normal user
1110 sessions), "greeter" (for display manager pseudo-sessions), or
1111 "lock-screen" (for display lock screens).
1112 Active is a boolean that is true if the session is active, i.e.
1114 currently in the foreground. This field is semi-redundant due to State.
1115 State encodes the session state and one of "online", "active", or
1117 "closing". See sd_session_get_state(3) for more information about the
1118 states.
1119 IdleHint, IdleSinceHint, and IdleSinceHintMonotonic encapsulate the
1121 idle hint state of this session, similarly to how the respective
1122 properties on the manager object do it for the whole system.
1123 LockedHint shows the locked hint state of this session, as set by the
1125 SetLockedHint() method described above.
1126
1128 Example 1. Introspect the logind manager on the bus
1129 $ gdbus introspect --system --dest org.freedesktop.login1 \
1131 --object-path /org/freedesktop/login1
1132 or
1135 $ busctl introspect org.freedesktop.login1 /org/freedesktop/login1
1137 Example 2. Introspect the default seat on the bus
1140 $ gdbus introspect --system --dest org.freedesktop.login1 \
1142 --object-path /org/freedesktop/login1/seat/seat0
1143 or
1146 $ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/seat/seat0
1148 Seat "seat0" is the default seat, so it'll be present unless local
1151 configuration is made to reassign all devices to a different seat. The
1152 list of seats and users can be acquired with loginctl list-sessions.
1153 Example 3. Introspect a single user on the bus
1155 $ gdbus introspect --system --dest org.freedesktop.login1 \
1157 --object-path /org/freedesktop/login1/user/_1000
1158 or
1161 $ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/user/_1000
1163 Example 4. Introspect org.freedesktop.login1.Session on the bus
1166 $ gdbus introspect --system --dest org.freedesktop.login1 \
1168 --object-path /org/freedesktop/login1/session/45
1169 or
1172 $ busctl introspect org.freedesktop.login1 /org/freedesktop/login1/session/45
1174
1177 These D-Bus interfaces follow the usual interface versioning
1178 guidelines[4].
1179
1181 1. polkit
1182 https://www.freedesktop.org/software/polkit/docs/latest/
1183 2. Inhibitor Locks
1185 https://www.freedesktop.org/wiki/Software/systemd/inhibit
1186 3. XDG Basedir Specification
1188 https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
1189 4. the usual interface versioning guidelines
1191 https://0pointer.de/blog/projects/versioning-dbus.html
1192systemd 254 ORG.FREEDESKTOP.LOGIN1(5)