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 CreateSession(in u uid,
40 in u pid,
41 in s service,
42 in s type,
43 in s class,
44 in s desktop,
45 in s seat_id,
46 in u vtnr,
47 in s tty,
48 in s display,
49 in b remote,
50 in s remote_user,
51 in s remote_host,
52 in a(sv) properties,
53 out s session_id,
54 out o object_path,
55 out s runtime_path,
56 out h fifo_fd,
57 out u uid,
58 out s seat_id,
59 out u vtnr,
60 out b existing);
61 ReleaseSession(in s session_id);
62 ActivateSession(in s session_id);
63 ActivateSessionOnSeat(in s session_id,
64 in s seat_id);
65 LockSession(in s session_id);
66 UnlockSession(in s session_id);
67 LockSessions();
68 UnlockSessions();
69 KillSession(in s session_id,
70 in s who,
71 in i signal_number);
72 KillUser(in u uid,
73 in i signal_number);
74 TerminateSession(in s session_id);
75 TerminateUser(in u uid);
76 TerminateSeat(in s seat_id);
77 SetUserLinger(in u uid,
78 in b enable,
79 in b interactive);
80 AttachDevice(in s seat_id,
81 in s sysfs_path,
82 in b interactive);
83 FlushDevices(in b interactive);
84 PowerOff(in b interactive);
85 PowerOffWithFlags(in t flags);
86 Reboot(in b interactive);
87 RebootWithFlags(in t flags);
88 Halt(in b interactive);
89 HaltWithFlags(in t flags);
90 Suspend(in b interactive);
91 SuspendWithFlags(in t flags);
92 Hibernate(in b interactive);
93 HibernateWithFlags(in t flags);
94 HybridSleep(in b interactive);
95 HybridSleepWithFlags(in t flags);
96 SuspendThenHibernate(in b interactive);
97 SuspendThenHibernateWithFlags(in t flags);
98 CanPowerOff(out s result);
99 CanReboot(out s result);
100 CanHalt(out s result);
101 CanSuspend(out s result);
102 CanHibernate(out s result);
103 CanHybridSleep(out s result);
104 CanSuspendThenHibernate(out s result);
105 ScheduleShutdown(in s type,
106 in t usec);
107 CancelScheduledShutdown(out b cancelled);
108 Inhibit(in s what,
109 in s who,
110 in s why,
111 in s mode,
112 out h pipe_fd);
113 CanRebootParameter(out s result);
114 SetRebootParameter(in s parameter);
115 CanRebootToFirmwareSetup(out s result);
116 SetRebootToFirmwareSetup(in b enable);
117 CanRebootToBootLoaderMenu(out s result);
118 SetRebootToBootLoaderMenu(in t timeout);
119 CanRebootToBootLoaderEntry(out s result);
120 SetRebootToBootLoaderEntry(in s boot_loader_entry);
121 SetWallMessage(in s wall_message,
122 in b enable);
123 signals:
124 SessionNew(s session_id,
125 o object_path);
126 SessionRemoved(s session_id,
127 o object_path);
128 UserNew(u uid,
129 o object_path);
130 UserRemoved(u uid,
131 o object_path);
132 SeatNew(s seat_id,
133 o object_path);
134 SeatRemoved(s seat_id,
135 o object_path);
136 PrepareForShutdown(b start);
137 PrepareForSleep(b start);
138 properties:
139 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
140 @org.freedesktop.systemd1.Privileged("true")
141 readwrite b EnableWallMessages = ...;
142 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
143 @org.freedesktop.systemd1.Privileged("true")
144 readwrite s WallMessage = '...';
145 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
146 readonly u NAutoVTs = ...;
147 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
148 readonly as KillOnlyUsers = ['...', ...];
149 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
150 readonly as KillExcludeUsers = ['...', ...];
151 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
152 readonly b KillUserProcesses = ...;
153 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
154 readonly s RebootParameter = '...';
155 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
156 readonly b RebootToFirmwareSetup = ...;
157 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
158 readonly t RebootToBootLoaderMenu = ...;
159 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
160 readonly s RebootToBootLoaderEntry = '...';
161 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
162 readonly as BootLoaderEntries = ['...', ...];
163 readonly b IdleHint = ...;
164 readonly t IdleSinceHint = ...;
165 readonly t IdleSinceHintMonotonic = ...;
166 readonly s BlockInhibited = '...';
167 readonly s DelayInhibited = '...';
168 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
169 readonly t InhibitDelayMaxUSec = ...;
170 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
171 readonly t UserStopDelayUSec = ...;
172 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
173 readonly s HandlePowerKey = '...';
174 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
175 readonly s HandleSuspendKey = '...';
176 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
177 readonly s HandleHibernateKey = '...';
178 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
179 readonly s HandleLidSwitch = '...';
180 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
181 readonly s HandleLidSwitchExternalPower = '...';
182 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
183 readonly s HandleLidSwitchDocked = '...';
184 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
185 readonly t HoldoffTimeoutUSec = ...;
186 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
187 readonly s IdleAction = '...';
188 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
189 readonly t IdleActionUSec = ...;
190 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
191 readonly b PreparingForShutdown = ...;
192 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
193 readonly b PreparingForSleep = ...;
194 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
195 readonly (st) ScheduledShutdown = ...;
196 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
197 readonly b Docked = ...;
198 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
199 readonly b LidClosed = ...;
200 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
201 readonly b OnExternalPower = ...;
202 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
203 readonly b RemoveIPC = ...;
204 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
205 readonly t RuntimeDirectorySize = ...;
206 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
207 readonly t RuntimeDirectoryInodesMax = ...;
208 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
209 readonly t InhibitorsMax = ...;
210 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
211 readonly t NCurrentInhibitors = ...;
212 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
213 readonly t SessionsMax = ...;
214 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
215 readonly t NCurrentSessions = ...;
216 };
217 interface org.freedesktop.DBus.Peer { ... };
218 interface org.freedesktop.DBus.Introspectable { ... };
219 interface org.freedesktop.DBus.Properties { ... };
220 };
221 Methods
331 GetSession() may be used to get the session object path for the session
332 with the specified ID. Similarly, GetUser() and GetSeat() get the user
333 and seat objects, respectively. GetSessionByPID() and GetUserByPID()
334 get the session/user object the specified PID belongs to if there is
335 any.
336 ListSessions() returns an array of all current sessions. The structures
338 in the array consist of the following fields: session id, user id, user
339 name, seat id, session object path. If a session does not have a seat
340 attached, the seat id field will be an empty string.
341 ListUsers() returns an array of all currently logged in users. The
343 structures in the array consist of the following fields: user id, user
344 name, user object path.
345 ListSeats() returns an array of all currently available seats. The
347 structure in the array consists of the following fields: seat id, seat
348 object path.
349 ListInhibitors() lists all currently active inhibitors. It returns an
351 array of structures consisting of what, who, why, mode, uid (user ID),
352 and pid (process ID).
353 CreateSession() and ReleaseSession() may be used to open or close login
355 sessions. These calls should never be invoked directly by clients.
356 Creating/closing sessions is exclusively the job of PAM and its
357 pam_systemd(8) module.
358 ActivateSession() brings the session with the specified ID into the
360 foreground. ActivateSessionOnSeat() does the same, but only if the
361 seat id matches.
362 LockSession() asks the session with the specified ID to activate the
364 screen lock. UnlockSession() asks the session with the specified ID to
365 remove an active screen lock, if there is any. This is implemented by
366 sending out the Lock() and Unlock() signals from the respective session
367 object which session managers are supposed to listen on.
368 LockSessions() asks all sessions to activate their screen locks. This
370 may be used to lock access to the entire machine in one action.
371 Similarly, UnlockSessions() asks all sessions to deactivate their
372 screen locks.
373 KillSession() may be used to send a Unix signal to one or all processes
375 of a session. As arguments it takes the session id, either the string
376 "leader" or "all" and a signal number. If "leader" is passed only the
377 session "leader" is killed. If "all" is passed all processes of the
378 session are killed.
379 KillUser() may be used to send a Unix signal to all processes of a
381 user. As arguments it takes the user id and a signal number.
382 TerminateSession(), TerminateUser(), TerminateSeat() may be used to
384 forcibly terminate one specific session, all processes of a user, and
385 all sessions attached to a specific seat, respectively. The session,
386 user, and seat are identified by their respective IDs.
387 SetUserLinger() enables or disables user lingering. If enabled, the
389 runtime directory of a user is kept around and they may continue to run
390 processes while logged out. If disabled, the runtime directory goes
391 away as soon as they log out. SetUserLinger() expects three arguments:
392 the UID, a boolean whether to enable/disable and a boolean controlling
393 the polkit[1] authorization interactivity (see below). Note that the
394 user linger state is persistently stored on disk.
395 AttachDevice() may be used to assign a specific device to a specific
397 seat. The device is identified by its /sys/ path and must be eligible
398 for seat assignments. AttachDevice() takes three arguments: the seat
399 id, the sysfs path, and a boolean for controlling polkit interactivity
400 (see below). Device assignments are persistently stored on disk. To
401 create a new seat, simply specify a previously unused seat id. For more
402 information about the seat assignment logic see sd-login(3).
403 FlushDevices() removes all explicit seat assignments for devices,
405 resetting all assignments to the automatic defaults. The only argument
406 it takes is the polkit interactivity boolean (see below).
407 PowerOff(), Reboot(), Halt(), Suspend(), and Hibernate() result in the
409 system being powered off, rebooted, halted (shut down without turning
410 off power), suspended (the system state is saved to RAM and the CPU is
411 turned off), or hibernated (the system state is saved to disk and the
412 machine is powered down). HybridSleep() results in the system entering
413 a hybrid-sleep mode, i.e. the system is both hibernated and suspended.
414 SuspendThenHibernate() results in the system being suspended, then
415 later woken using an RTC timer and hibernated. The only argument is the
416 polkit interactivity boolean interactive (see below). The main purpose
417 of these calls is that they enforce polkit policy and hence allow
418 powering off/rebooting/suspending/hibernating even by unprivileged
419 users. They also enforce inhibition locks for non-privileged users. UIs
420 should expose these calls as the primary mechanism to
421 poweroff/reboot/suspend/hibernate the machine. Methods
422 PowerOffWithFlags(), RebootWithFlags(), HaltWithFlags(),
423 SuspendWithFlags(), HibernateWithFlags(), HybridSleepWithFlags() and
424 SuspendThenHibernateWithFlags() add flags to allow for extendability,
425 defined as follows:
426 #define SD_LOGIND_ROOT_CHECK_INHIBITORS (UINT64_C(1) << 0)
428 #define SD_LOGIND_KEXEC_REBOOT (UINT64_C(1) << 1)
429 When the flags is 0 then these methods behave just like the versions
432 without flags. When SD_LOGIND_ROOT_CHECK_INHIBITORS (0x01) is set,
433 active inhibitors are honoured for privileged users too. When
434 SD_LOGIND_KEXEC_REBOOT (0x02) is set, then RebootWithFlags() perform
435 kexec reboot if kexec kernel is loaded.
436 SetRebootParameter() sets a parameter for a subsequent reboot
438 operation. See the description of reboot in systemctl(1) and reboot(2)
439 for more information.
440 SetRebootToFirmwareSetup(), SetRebootToBootLoaderMenu(), and
442 SetRebootToBootLoaderEntry() configure the action to be taken from the
443 boot loader after a reboot: respectively entering firmware setup mode,
444 the boot loader menu, or a specific boot loader entry. See systemctl(1)
445 for the corresponding command line interface.
446 CanPowerOff(), CanReboot(), CanHalt(), CanSuspend(), CanHibernate(),
448 CanHybridSleep(), CanSuspendThenHibernate(), CanRebootParameter(),
449 CanRebootToFirmwareSetup(), CanRebootToBootLoaderMenu(), and
450 CanRebootToBootLoaderEntry() test whether the system supports the
451 respective operation and whether the calling user is allowed to execute
452 it. Returns one of "na", "yes", "no", and "challenge". If "na" is
453 returned, the operation is not available because hardware, kernel, or
454 drivers do not support it. If "yes" is returned, the operation is
455 supported and the user may execute the operation without further
456 authentication. If "no" is returned, the operation is available but the
457 user is not allowed to execute the operation. If "challenge" is
458 returned, the operation is available but only after authorization.
459 ScheduleShutdown() schedules a shutdown operation type at time usec in
461 microseconds since the UNIX epoch. type can be one of "poweroff",
462 "dry-poweroff", "reboot", "dry-reboot", "halt", and "dry-halt". (The
463 "dry-" variants do not actually execute the shutdown action.)
464 CancelScheduledShutdown() cancels a scheduled shutdown. The output
465 parameter cancelled is true if a shutdown operation was scheduled.
466 SetWallMessage() sets the wall message (the message that will be sent
468 out to all terminals and stored in a utmp(5) record) for a subsequent
469 scheduled shutdown operation. The parameter wall_message specifies the
470 shutdown reason (and may be empty) which will be included in the
471 shutdown message. The parameter enable specifies whether to print a
472 wall message on shutdown.
473 Inhibit() creates an inhibition lock. It takes four parameters: what,
475 who, why, and mode. what is one or more of "shutdown", "sleep",
476 "idle", "handle-power-key", "handle-suspend-key",
477 "handle-hibernate-key", "handle-lid-switch", separated by colons, for
478 inhibiting poweroff/reboot, suspend/hibernate, the automatic idle
479 logic, or hardware key handling. who should be a short human readable
480 string identifying the application taking the lock. why should be a
481 short human readable string identifying the reason why the lock is
482 taken. Finally, mode is either "block" or "delay" which encodes whether
483 the inhibit shall be consider mandatory or whether it should just delay
484 the operation to a certain maximum time. The method returns a file
485 descriptor. The lock is released the moment this file descriptor and
486 all its duplicates are closed. For more information on the inhibition
487 logic see Inhibitor Locks[2].
488 Signals
490 Whenever the inhibition state or idle hint changes, PropertyChanged
491 signals are sent out to which clients can subscribe.
492 The SessionNew, SessionRemoved, UserNew, UserRemoved, SeatNew, and
494 SeatRemoved signals are sent each time a session is created or removed,
495 a user logs in or out, or a seat is added or removed. They each contain
496 the ID of the object plus the object path.
497 The PrepareForShutdown() and PrepareForSleep() signals are sent right
499 before (with the argument "true") or after (with the argument "false")
500 the system goes down for reboot/poweroff and suspend/hibernate,
501 respectively. This may be used by applications to save data on disk,
502 release memory, or do other jobs that should be done shortly before
503 shutdown/sleep, in conjunction with delay inhibitor locks. After
504 completion of this work they should release their inhibition locks in
505 order to not delay the operation any further. For more information see
506 Inhibitor Locks[2].
507 Properties
509 Most properties simply reflect the configuration, see logind.conf(5).
510 This includes: NAutoVTs, KillOnlyUsers, KillExcludeUsers,
511 KillUserProcesses, IdleAction, InhibitDelayMaxUSec, InhibitorsMax,
512 UserStopDelayUSec, HandlePowerKey, HandleSuspendKey,
513 HandleHibernateKey, HandleLidSwitch, HandleLidSwitchExternalPower,
514 HandleLidSwitchDocked, IdleActionUSec, HoldoffTimeoutUSec, RemoveIPC,
515 RuntimeDirectorySize, RuntimeDirectoryInodesMax, InhibitorsMax, and
516 SessionsMax.
517 The IdleHint property reflects the idle hint state of the system. If
519 the system is idle it might get into automatic suspend or shutdown
520 depending on the configuration.
521 IdleSinceHint and IdleSinceHintMonotonic encode the timestamps of the
523 last change of the idle hint boolean, in CLOCK_REALTIME and
524 CLOCK_MONOTONIC timestamps, respectively, in microseconds since the
525 epoch.
526 The BlockInhibited and DelayInhibited properties encode the currently
528 active locks of the respective modes. They are colon separated lists of
529 "shutdown", "sleep", and "idle" (see above).
530 NCurrentSessions and NCurrentInhibitors contain the number of currently
532 registered sessions and inhibitors.
533 The BootLoaderEntries property contains a list of boot loader entries.
535 This includes boot loader entries defined in configuration and any
536 additional loader entries reported by the boot loader. See systemd-
537 boot(7) for more information.
538 The PreparingForShutdown and PreparingForSleep boolean properties are
540 true during the interval between the two PrepareForShutdown and
541 PrepareForSleep signals respectively. Note that these properties do not
542 send out PropertyChanged signals.
543 The RebootParameter property shows the value set with the
545 SetRebootParameter() method described above.
546 ScheduledShutdown shows the value pair set with the ScheduleShutdown()
548 method described above.
549 RebootToFirmwareSetup, RebootToBootLoaderMenu, and
551 RebootToBootLoaderEntry are true when the resprective post-reboot
552 operation was selected with SetRebootToFirmwareSetup,
553 SetRebootToBootLoaderMenu, or SetRebootToBootLoaderEntry.
554 The WallMessage and EnableWallMessages properties reflect the shutdown
556 reason and wall message enablement switch which can be set with the
557 SetWallMessage() method described above.
558 Docked is true if the machine is connected to a dock. LidClosed is
560 true when the lid (of a laptop) is closed. OnExternalPower is true
561 when the machine is connected to an external power supply.
562 Security
564 A number of operations are protected via the polkit privilege system.
565 SetUserLinger() requires the org.freedesktop.login1.set-user-linger
566 privilege. AttachDevice() requires
567 org.freedesktop.login1.attach-device and FlushDevices() requires
568 org.freedesktop.login1.flush-devices. PowerOff(), Reboot(), Halt(),
569 Suspend(), Hibernate() require org.freedesktop.login1.power-off,
570 org.freedesktop.login1.power-off-multiple-sessions,
571 org.freedesktop.login1.power-off-ignore-inhibit,
572 org.freedesktop.login1.reboot,
573 org.freedesktop.login1.reboot-multiple-sessions,
574 org.freedesktop.login1.reboot-ignore-inhibit,
575 org.freedesktop.login1.halt,
576 org.freedesktop.login1.halt-multiple-sessions,
577 org.freedesktop.login1.halt-ignore-inhibit,
578 org.freedesktop.login1.suspend,
579 org.freedesktop.login1.suspend-multiple-sessions,
580 org.freedesktop.login1.suspend-ignore-inhibit,
581 org.freedesktop.login1.hibernate,
582 org.freedesktop.login1.hibernate-multiple-sessions,
583 org.freedesktop.login1.hibernate-ignore-inhibit, respectively depending
584 on whether there are other sessions around or active inhibits are
585 present. HybridSleep() and SuspendThenHibernate() use the same
586 privileges as Hibernate(). SetRebootParameter() requires
587 org.freedesktop.login1.set-reboot-parameter.
588 SetRebootToFirmwareSetup requires
590 org.freedesktop.login1.set-reboot-to-firmware-setup.
591 SetRebootToBootLoaderMenu requires
592 org.freedesktop.login1.set-reboot-to-boot-loader-menu.
593 SetRebootToBootLoaderEntry requires
594 org.freedesktop.login1.set-reboot-to-boot-loader-entry.
595 ScheduleShutdown and CancelScheduledShutdown require the same
597 privileges (listed above) as the immediate poweroff/reboot/halt
598 operations.
599 Inhibit() is protected via one of
601 org.freedesktop.login1.inhibit-block-shutdown,
602 org.freedesktop.login1.inhibit-delay-shutdown,
603 org.freedesktop.login1.inhibit-block-sleep,
604 org.freedesktop.login1.inhibit-delay-sleep,
605 org.freedesktop.login1.inhibit-block-idle,
606 org.freedesktop.login1.inhibit-handle-power-key,
607 org.freedesktop.login1.inhibit-handle-suspend-key,
608 org.freedesktop.login1.inhibit-handle-hibernate-key,
609 org.freedesktop.login1.inhibit-handle-lid-switch depending on the lock
610 type and mode taken.
611 The interactive boolean parameters can be used to control whether
613 polkit should interactively ask the user for authentication credentials
614 if required.
615
617 node /org/freedesktop/login1/seat/seat0 {
618 interface org.freedesktop.login1.Seat {
619 methods:
620 Terminate();
621 ActivateSession(in s session_id);
622 SwitchTo(in u vtnr);
623 SwitchToNext();
624 SwitchToPrevious();
625 properties:
626 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
627 readonly s Id = '...';
628 readonly (so) ActiveSession = ...;
629 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
630 readonly b CanTTY = ...;
631 readonly b CanGraphical = ...;
632 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
633 readonly a(so) Sessions = [...];
634 readonly b IdleHint = ...;
635 readonly t IdleSinceHint = ...;
636 readonly t IdleSinceHintMonotonic = ...;
637 };
638 interface org.freedesktop.DBus.Peer { ... };
639 interface org.freedesktop.DBus.Introspectable { ... };
640 interface org.freedesktop.DBus.Properties { ... };
641 };
642 Methods
659 Terminate() and ActivateSession() work similar to TerminateSeat(),
660 ActivationSessionOnSeat() on the Manager object.
661 SwitchTo() switches to the session on the virtual terminal vtnr.
663 SwitchToNext() and SwitchToPrevious() switch to, respectively, the next
664 and previous sessions on the seat in the order of virtual terminals. If
665 there is no active session, they switch to, respectively, the first and
666 last session on the seat.
667 Signals
669 Whenever ActiveSession, Sessions, CanGraphical, CanTTY, or the idle
670 state changes, PropertyChanged signals are sent out to which clients
671 can subscribe.
672 Properties
674 The Id property encodes the ID of the seat.
675 ActiveSession encodes the currently active session if there is one. It
677 is a structure consisting of the session id and the object path.
678 CanTTY encodes whether the session is suitable for text logins, and
680 CanGraphical whether it is suitable for graphical sessions.
681 The Sessions property is an array of all current sessions of this seat,
683 each encoded in a structure consisting of the ID and the object path.
684 The IdleHint, IdleSinceHint, and IdleSinceHintMonotonic properties
686 encode the idle state, similar to the ones exposed on the Manager
687 object, but specific for this seat.
688
690 node /org/freedesktop/login1/user/_1000 {
691 interface org.freedesktop.login1.User {
692 methods:
693 Terminate();
694 Kill(in i signal_number);
695 properties:
696 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
697 readonly u UID = ...;
698 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
699 readonly u GID = ...;
700 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
701 readonly s Name = '...';
702 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
703 readonly t Timestamp = ...;
704 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
705 readonly t TimestampMonotonic = ...;
706 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
707 readonly s RuntimePath = '...';
708 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
709 readonly s Service = '...';
710 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
711 readonly s Slice = '...';
712 readonly (so) Display = ...;
713 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
714 readonly s State = '...';
715 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
716 readonly a(so) Sessions = [...];
717 readonly b IdleHint = ...;
718 readonly t IdleSinceHint = ...;
719 readonly t IdleSinceHintMonotonic = ...;
720 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
721 readonly b Linger = ...;
722 };
723 interface org.freedesktop.DBus.Peer { ... };
724 interface org.freedesktop.DBus.Introspectable { ... };
725 interface org.freedesktop.DBus.Properties { ... };
726 };
727 Methods
748 Terminate() and Kill() work similar to the TerminateUser() and
749 KillUser() methods on the manager object.
750 Signals
752 Whenever Sessions or the idle state changes, PropertyChanged signals
753 are sent out to which clients can subscribe.
754 Properties
756 The UID and GID properties encode the Unix UID and primary GID of the
757 user.
758 The Name property encodes the user name.
760 Timestamp and TimestampMonotonic encode the login time of the user in
762 microseconds since the epoch, in the CLOCK_REALTIME and CLOCK_MONOTONIC
763 clocks, respectively.
764 RuntimePath encodes the runtime path of the user, i.e.
766 $XDG_RUNTIME_DIR. For details see the XDG Basedir Specification[3].
767 Service contains the unit name of the user systemd service of this
769 user. Each logged in user is assigned a user service that runs a user
770 systemd instance. This is usually an instance of user@.service.
771 Slice contains the unit name of the user systemd slice of this user.
773 Each logged in user gets a private slice.
774 Display encodes which graphical session should be used as the primary
776 UI display for the user. It is a structure encoding the session ID and
777 the object path of the session to use.
778 State encodes the user state and is one of "offline", "lingering",
780 "online", "active", or "closing". See sd_uid_get_state(3) for more
781 information about the states.
782 Sessions is an array of structures encoding all current sessions of the
784 user. Each structure consists of the ID and object path.
785 The IdleHint, IdleSinceHint, and IdleSinceHintMonotonic properties
787 encode the idle hint state of the user, similar to the Manager's
788 properties, but specific for this user.
789 The Linger property shows whether lingering is enabled for this user.
791
793 node /org/freedesktop/login1/session/1 {
794 interface org.freedesktop.login1.Session {
795 methods:
796 Terminate();
797 Activate();
798 Lock();
799 Unlock();
800 SetIdleHint(in b idle);
801 SetLockedHint(in b locked);
802 Kill(in s who,
803 in i signal_number);
804 TakeControl(in b force);
805 ReleaseControl();
806 SetType(in s type);
807 TakeDevice(in u major,
808 in u minor,
809 out h fd,
810 out b inactive);
811 ReleaseDevice(in u major,
812 in u minor);
813 PauseDeviceComplete(in u major,
814 in u minor);
815 SetBrightness(in s subsystem,
816 in s name,
817 in u brightness);
818 signals:
819 PauseDevice(u major,
820 u minor,
821 s type);
822 ResumeDevice(u major,
823 u minor,
824 h fd);
825 Lock();
826 Unlock();
827 properties:
828 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
829 readonly s Id = '...';
830 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
831 readonly (uo) User = ...;
832 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
833 readonly s Name = '...';
834 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
835 readonly t Timestamp = ...;
836 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
837 readonly t TimestampMonotonic = ...;
838 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
839 readonly u VTNr = ...;
840 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
841 readonly (so) Seat = ...;
842 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
843 readonly s TTY = '...';
844 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
845 readonly s Display = '...';
846 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
847 readonly b Remote = ...;
848 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
849 readonly s RemoteHost = '...';
850 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
851 readonly s RemoteUser = '...';
852 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
853 readonly s Service = '...';
854 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
855 readonly s Desktop = '...';
856 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
857 readonly s Scope = '...';
858 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
859 readonly u Leader = ...;
860 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
861 readonly u Audit = ...;
862 readonly s Type = '...';
863 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
864 readonly s Class = '...';
865 readonly b Active = ...;
866 readonly s State = '...';
867 readonly b IdleHint = ...;
868 readonly t IdleSinceHint = ...;
869 readonly t IdleSinceHintMonotonic = ...;
870 readonly b LockedHint = ...;
871 };
872 interface org.freedesktop.DBus.Peer { ... };
873 interface org.freedesktop.DBus.Introspectable { ... };
874 interface org.freedesktop.DBus.Properties { ... };
875 };
876 Methods
923 Terminate(), Activate(), Lock(), Unlock(), and Kill() work similarly to
924 the respective calls on the Manager object.
925 SetIdleHint() is called by the session object to update the idle state
927 of the session whenever it changes.
928 TakeControl() allows a process to take exclusive managed device
930 access-control for that session. Only one D-Bus connection can be a
931 controller for a given session at any time. If the force argument is
932 set (root only), an existing controller is kicked out and replaced.
933 Otherwise, this method fails if there is already a controller. Note
934 that this method is limited to D-Bus users with the effective UID set
935 to the user of the session or root.
936 ReleaseControl() drops control of a given session. Closing the D-Bus
938 connection implicitly releases control as well. See TakeControl() for
939 more information. This method also releases all devices for which the
940 controller requested ownership via TakeDevice().
941 SetType() allows the type of the session to be changed dynamically. It
943 can only be called by session's current controller. If TakeControl()
944 has not been called, this method will fail. In addition, the session
945 type will be reset to its original value once control is released,
946 either by calling ReleaseControl() or closing the D-Bus connection.
947 This should help prevent a session from entering an inconsistent state,
948 for example if the controller crashes. The only argument type is the
949 new session type.
950 TakeDevice() allows a session controller to get a file descriptor for a
952 specific device. Pass in the major and minor numbers of the character
953 device and systemd-logind will return a file descriptor for the device.
954 Only a limited set of device-types is currently supported (but may be
955 extended). systemd-logind automatically mutes the file descriptor if
956 the session is inactive and resumes it once the session is activated
957 again. This guarantees that a session can only access session devices
958 if the session is active. Note that this revoke/resume mechanism is
959 asynchronous and may happen at any given time. This only works on
960 devices that are attached to the seat of the given session. A process
961 is not required to have direct access to the device node.
962 systemd-logind only requires you to be the active session controller
963 (see TakeControl()). Also note that any device can only be requested
964 once. As long as you don't release it, further TakeDevice() calls will
965 fail.
966 ReleaseDevice() releases a device again (see TakeDevice()). This is
968 also implicitly done by ReleaseControl() or when closing the D-Bus
969 connection.
970 PauseDeviceComplete() allows a session controller to synchronously
972 pause a device after receiving a PauseDevice("pause") signal. Forced
973 signals (or after an internal timeout) are automatically completed by
974 systemd-logind asynchronously.
975 SetLockedHint() may be used to set the "locked hint" to locked, i.e.
977 information whether the session is locked. This is intended to be used
978 by the desktop environment to tell systemd-logind when the session is
979 locked and unlocked.
980 SetBrightness() may be used to set the display brightness. This is
982 intended to be used by the desktop environment and allows unprivileged
983 programs to access hardware settings in a controlled way. The subsystem
984 parameter specifies a kernel subsystem, either "backlight" or "leds".
985 The name parameter specifies a device name under the specified
986 subsystem. The brightness parameter specifies the brightness. The range
987 is defined by individual drivers, see
988 /sys/class/subsystem/name/max_brightness.
989 Signals
991 The active session controller exclusively gets PauseDevice and
992 ResumeDevice events for any device it requested via TakeDevice(). They
993 notify the controller whenever a device is paused or resumed. A device
994 is never resumed if its session is inactive. Also note that PauseDevice
995 signals are sent before the PropertyChanged signal for the Active
996 state. The inverse is true for ResumeDevice. A device may remain paused
997 for unknown reasons even though the Session is active.
998 A PauseDevice signal carries the major and minor numbers and a string
1000 describing the type as arguments. force means the device was already
1001 paused by systemd-logind and the signal is only an asynchronous
1002 notification. pause means systemd-logind grants you a limited amount
1003 of time to pause the device. You must respond to this via
1004 PauseDeviceComplete(). This synchronous pausing mechanism is used for
1005 backwards-compatibility to VTs and systemd-logind is free to not make
1006 use of it. It is also free to send a forced PauseDevice if you don't
1007 respond in a timely manner (or for any other reason). gone means the
1008 device was unplugged from the system and you will no longer get any
1009 notifications about it. There is no need to call ReleaseDevice(). You
1010 may call TakeDevice() again if a new device is assigned the major+minor
1011 combination.
1012 ResumeDevice is sent whenever a session is active and a device is
1014 resumed. It carries the major/minor numbers as arguments and provides a
1015 new open file descriptor. You should switch to the new descriptor and
1016 close the old one. They are not guaranteed to have the same underlying
1017 open file descriptor in the kernel (except for a limited set of device
1018 types).
1019 Whenever Active or the idle state changes, PropertyChanged signals are
1021 sent out to which clients can subscribe.
1022 Lock/Unlock is sent when the session is asked to be
1024 screen-locked/unlocked. A session manager of the session should listen
1025 to this signal and act accordingly. This signal is sent out as a result
1026 of the Lock() and Unlock() methods, respectively.
1027 Properties
1029 Id encodes the session ID.
1030 User encodes the user ID of the user this session belongs to. This is a
1032 structure consisting of the Unix UID and the object path.
1033 Name encodes the user name.
1035 Timestamp and TimestampMonotonic encode the microseconds since the
1037 epoch when the session was created, in CLOCK_REALTIME or
1038 CLOCK_MONOTONIC, respectively.
1039 VTNr encodes the virtual terminal number of the session if there is
1041 any, 0 otherwise.
1042 Seat encodes the seat this session belongs to if there is any. This is
1044 a structure consisting of the ID and the seat object path.
1045 TTY encodes the kernel TTY path of the session if this is a text login.
1047 If not this is an empty string.
1048 Display encodes the X11 display name if this is a graphical login. If
1050 not, this is an empty string.
1051 Remote encodes whether the session is local or remote.
1053 RemoteHost and RemoteUser encode the remote host and user if this is a
1055 remote session, or an empty string otherwise.
1056 Service encodes the PAM service name that registered the session.
1058 Desktop describes the desktop environment running in the session (if
1060 known).
1061 Scope contains the systemd scope unit name of this session.
1063 Leader encodes the PID of the process that registered the session.
1065 Audit encodes the Kernel Audit session ID of the session if auditing is
1067 available.
1068 Type encodes the session type. It's one of "unspecified" (for cron PAM
1070 sessions and suchlike), "tty" (for text logins) or
1071 "x11"/"mir"/"wayland" (for graphical logins).
1072 Class encodes the session class. It's one of "user" (for normal user
1074 sessions), "greeter" (for display manager pseudo-sessions), or
1075 "lock-screen" (for display lock screens).
1076 Active is a boolean that is true if the session is active, i.e.
1078 currently in the foreground. This field is semi-redundant due to State.
1079 State encodes the session state and one of "online", "active", or
1081 "closing". See sd_session_get_state(3) for more information about the
1082 states.
1083 IdleHint, IdleSinceHint, and IdleSinceHintMonotonic encapsulate the
1085 idle hint state of this session, similarly to how the respective
1086 properties on the manager object do it for the whole system.
1087 LockedHint shows the locked hint state of this session, as set by the
1089 SetLockedHint() method described above.
1090
1092 Example 1. Introspect org.freedesktop.login1.Manager on the bus
1093 $ gdbus introspect --system --dest org.freedesktop.login1 \
1095 --object-path /org/freedesktop/login1
1096 Example 2. Introspect org.freedesktop.login1.Seat on the bus
1099 $ gdbus introspect --system --dest org.freedesktop.login1 \
1101 --object-path /org/freedesktop/login1/seat/seat0
1102 Example 3. Introspect org.freedesktop.login1.User on the bus
1105 $ gdbus introspect --system --dest org.freedesktop.login1 \
1107 --object-path /org/freedesktop/login1/user/_1000
1108 Example 4. Introspect org.freedesktop.login1.Session on the bus
1111 $ gdbus introspect --system --dest org.freedesktop.login1 \
1113 --object-path /org/freedesktop/login1/session/45
1114
1117 These D-Bus interfaces follow the usual interface versioning
1118 guidelines[4].
1119
1121 1. polkit
1122 https://www.freedesktop.org/software/polkit/docs/latest/
1123 2. Inhibitor Locks
1125 http://www.freedesktop.org/wiki/Software/systemd/inhibit
1126 3. XDG Basedir Specification
1128 https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
1129 4. the usual interface versioning guidelines
1131 http://0pointer.de/blog/projects/versioning-dbus.html
1132systemd 249 ORG.FREEDESKTOP.LOGIN1(5)