Debian Codegraph @

upstream/debian-trixie/man5/org.freedesktop.login1.5

raw
1 '\" t
2 .TH "ORG\&.FREEDESKTOP\&.LOGIN1" "5" "" "systemd 257.13" "org.freedesktop.login1"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 org.freedesktop.login1 \- The D\-Bus interface of systemd\-logind
24 .SH "INTRODUCTION"
25 .PP
26 \fBsystemd-logind.service\fR(8)
27 is a system service that keeps track of user logins and seats\&.
28 .PP
29 The daemon provides both a C library interface as well as a D\-Bus interface\&. The library interface may be used to introspect and watch the state of user logins and seats\&. The bus interface provides the same functionality but in addition may also be used to make changes to the system state\&. For more information please consult
30 \fBsd-login\fR(3)\&.
31 .SH "THE MANAGER OBJECT"
32 .PP
33 The service exposes the following interfaces on the Manager object on the bus:
34 .sp
35 .if n \{\
36 .RS 4
37 .\}
38 .nf
39 node /org/freedesktop/login1 {
40 interface org\&.freedesktop\&.login1\&.Manager {
41 methods:
42 GetSession(in s session_id,
43 out o object_path);
44 GetSessionByPID(in u pid,
45 out o object_path);
46 GetUser(in u uid,
47 out o object_path);
48 GetUserByPID(in u pid,
49 out o object_path);
50 GetSeat(in s seat_id,
51 out o object_path);
52 ListSessions(out a(susso) sessions);
53 ListSessionsEx(out a(sussussbto) sessions);
54 ListUsers(out a(uso) users);
55 ListSeats(out a(so) seats);
56 ListInhibitors(out a(ssssuu) inhibitors);
57 @org\&.freedesktop\&.systemd1\&.Privileged("true")
58 CreateSession(in u uid,
59 in u pid,
60 in s service,
61 in s type,
62 in s class,
63 in s desktop,
64 in s seat_id,
65 in u vtnr,
66 in s tty,
67 in s display,
68 in b remote,
69 in s remote_user,
70 in s remote_host,
71 in a(sv) properties,
72 out s session_id,
73 out o object_path,
74 out s runtime_path,
75 out h fifo_fd,
76 out u uid,
77 out s seat_id,
78 out u vtnr,
79 out b existing);
80 @org\&.freedesktop\&.systemd1\&.Privileged("true")
81 CreateSessionWithPIDFD(in u uid,
82 in h pidfd,
83 in s service,
84 in s type,
85 in s class,
86 in s desktop,
87 in s seat_id,
88 in u vtnr,
89 in s tty,
90 in s display,
91 in b remote,
92 in s remote_user,
93 in s remote_host,
94 in t flags,
95 in a(sv) properties,
96 out s session_id,
97 out o object_path,
98 out s runtime_path,
99 out h fifo_fd,
100 out u uid,
101 out s seat_id,
102 out u vtnr,
103 out b existing);
104 ReleaseSession(in s session_id);
105 ActivateSession(in s session_id);
106 ActivateSessionOnSeat(in s session_id,
107 in s seat_id);
108 LockSession(in s session_id);
109 UnlockSession(in s session_id);
110 LockSessions();
111 UnlockSessions();
112 KillSession(in s session_id,
113 in s whom,
114 in i signal_number);
115 KillUser(in u uid,
116 in i signal_number);
117 TerminateSession(in s session_id);
118 TerminateUser(in u uid);
119 TerminateSeat(in s seat_id);
120 SetUserLinger(in u uid,
121 in b enable,
122 in b interactive);
123 AttachDevice(in s seat_id,
124 in s sysfs_path,
125 in b interactive);
126 FlushDevices(in b interactive);
127 PowerOff(in b interactive);
128 PowerOffWithFlags(in t flags);
129 Reboot(in b interactive);
130 RebootWithFlags(in t flags);
131 Halt(in b interactive);
132 HaltWithFlags(in t flags);
133 Suspend(in b interactive);
134 SuspendWithFlags(in t flags);
135 Hibernate(in b interactive);
136 HibernateWithFlags(in t flags);
137 HybridSleep(in b interactive);
138 HybridSleepWithFlags(in t flags);
139 SuspendThenHibernate(in b interactive);
140 SuspendThenHibernateWithFlags(in t flags);
141 Sleep(in t flags);
142 CanPowerOff(out s result);
143 CanReboot(out s result);
144 CanHalt(out s result);
145 CanSuspend(out s result);
146 CanHibernate(out s result);
147 CanHybridSleep(out s result);
148 CanSuspendThenHibernate(out s result);
149 CanSleep(out s result);
150 ScheduleShutdown(in s type,
151 in t usec);
152 CancelScheduledShutdown(out b cancelled);
153 Inhibit(in s what,
154 in s who,
155 in s why,
156 in s mode,
157 out h pipe_fd);
158 CanRebootParameter(out s result);
159 SetRebootParameter(in s parameter);
160 CanRebootToFirmwareSetup(out s result);
161 SetRebootToFirmwareSetup(in b enable);
162 CanRebootToBootLoaderMenu(out s result);
163 SetRebootToBootLoaderMenu(in t timeout);
164 CanRebootToBootLoaderEntry(out s result);
165 SetRebootToBootLoaderEntry(in s boot_loader_entry);
166 SetWallMessage(in s wall_message,
167 in b enable);
168 signals:
169 SecureAttentionKey(s seat_id,
170 o object_path);
171 SessionNew(s session_id,
172 o object_path);
173 SessionRemoved(s session_id,
174 o object_path);
175 UserNew(u uid,
176 o object_path);
177 UserRemoved(u uid,
178 o object_path);
179 SeatNew(s seat_id,
180 o object_path);
181 SeatRemoved(s seat_id,
182 o object_path);
183 PrepareForShutdown(b start);
184 PrepareForShutdownWithMetadata(b start,
185 a{sv} metadata);
186 PrepareForSleep(b start);
187 properties:
188 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
189 @org\&.freedesktop\&.systemd1\&.Privileged("true")
190 readwrite b EnableWallMessages = \&.\&.\&.;
191 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
192 @org\&.freedesktop\&.systemd1\&.Privileged("true")
193 readwrite s WallMessage = \*(Aq\&.\&.\&.\*(Aq;
194 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
195 readonly u NAutoVTs = \&.\&.\&.;
196 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
197 readonly as KillOnlyUsers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.];
198 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
199 readonly as KillExcludeUsers = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.];
200 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
201 readonly b KillUserProcesses = \&.\&.\&.;
202 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
203 readonly s RebootParameter = \*(Aq\&.\&.\&.\*(Aq;
204 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
205 readonly b RebootToFirmwareSetup = \&.\&.\&.;
206 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
207 readonly t RebootToBootLoaderMenu = \&.\&.\&.;
208 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
209 readonly s RebootToBootLoaderEntry = \*(Aq\&.\&.\&.\*(Aq;
210 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
211 readonly as BootLoaderEntries = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.];
212 readonly b IdleHint = \&.\&.\&.;
213 readonly t IdleSinceHint = \&.\&.\&.;
214 readonly t IdleSinceHintMonotonic = \&.\&.\&.;
215 readonly s BlockInhibited = \*(Aq\&.\&.\&.\*(Aq;
216 readonly s BlockWeakInhibited = \*(Aq\&.\&.\&.\*(Aq;
217 readonly s DelayInhibited = \*(Aq\&.\&.\&.\*(Aq;
218 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
219 readonly t InhibitDelayMaxUSec = \&.\&.\&.;
220 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
221 readonly t UserStopDelayUSec = \&.\&.\&.;
222 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
223 readonly as SleepOperation = [\*(Aq\&.\&.\&.\*(Aq, \&.\&.\&.];
224 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
225 readonly s HandlePowerKey = \*(Aq\&.\&.\&.\*(Aq;
226 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
227 readonly s HandlePowerKeyLongPress = \*(Aq\&.\&.\&.\*(Aq;
228 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
229 readonly s HandleRebootKey = \*(Aq\&.\&.\&.\*(Aq;
230 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
231 readonly s HandleRebootKeyLongPress = \*(Aq\&.\&.\&.\*(Aq;
232 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
233 readonly s HandleSuspendKey = \*(Aq\&.\&.\&.\*(Aq;
234 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
235 readonly s HandleSuspendKeyLongPress = \*(Aq\&.\&.\&.\*(Aq;
236 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
237 readonly s HandleHibernateKey = \*(Aq\&.\&.\&.\*(Aq;
238 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
239 readonly s HandleHibernateKeyLongPress = \*(Aq\&.\&.\&.\*(Aq;
240 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
241 readonly s HandleLidSwitch = \*(Aq\&.\&.\&.\*(Aq;
242 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
243 readonly s HandleLidSwitchExternalPower = \*(Aq\&.\&.\&.\*(Aq;
244 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
245 readonly s HandleLidSwitchDocked = \*(Aq\&.\&.\&.\*(Aq;
246 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
247 readonly s HandleSecureAttentionKey = \*(Aq\&.\&.\&.\*(Aq;
248 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
249 readonly t HoldoffTimeoutUSec = \&.\&.\&.;
250 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
251 readonly s IdleAction = \*(Aq\&.\&.\&.\*(Aq;
252 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
253 readonly t IdleActionUSec = \&.\&.\&.;
254 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
255 readonly b PreparingForShutdown = \&.\&.\&.;
256 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
257 readonly a{sv} PreparingForShutdownWithMetadata = [\&.\&.\&.];
258 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
259 readonly b PreparingForSleep = \&.\&.\&.;
260 readonly (st) ScheduledShutdown = \&.\&.\&.;
261 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
262 readonly s DesignatedMaintenanceTime = \*(Aq\&.\&.\&.\*(Aq;
263 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
264 readonly b Docked = \&.\&.\&.;
265 readonly b LidClosed = \&.\&.\&.;
266 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
267 readonly b OnExternalPower = \&.\&.\&.;
268 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
269 readonly b RemoveIPC = \&.\&.\&.;
270 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
271 readonly t RuntimeDirectorySize = \&.\&.\&.;
272 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
273 readonly t RuntimeDirectoryInodesMax = \&.\&.\&.;
274 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
275 readonly t InhibitorsMax = \&.\&.\&.;
276 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
277 readonly t NCurrentInhibitors = \&.\&.\&.;
278 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
279 readonly t SessionsMax = \&.\&.\&.;
280 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
281 readonly t NCurrentSessions = \&.\&.\&.;
282 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
283 readonly t StopIdleSessionUSec = \&.\&.\&.;
284 };
285 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
286 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
287 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
288 };
289 .fi
290 .if n \{\
291 .RE
292 .\}
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417 .SS "Methods"
418 .PP
419 \fBGetSession()\fR
420 may be used to get the session object path for the session with the specified ID\&. Similarly,
421 \fBGetUser()\fR
422 and
423 \fBGetSeat()\fR
424 get the user and seat objects, respectively\&.
425 \fBGetSessionByPID()\fR
426 and
427 \fBGetUserByPID()\fR
428 get the session/user object the specified PID belongs to if there is any\&.
429 .PP
430 \fBListSessions()\fR
431 returns an array of all current sessions\&. The structures in the array consist of the following fields:
432 \fIsession id\fR,
433 \fIuser id\fR,
434 \fIuser name\fR,
435 \fIseat id\fR, and
436 \fIsession object path\fR\&. If a session does not have a seat attached, the seat id field will be an empty string\&.
437 .PP
438 \fBListSessionsEx()\fR
439 returns an array of all current sessions with more metadata than
440 \fBListSessions()\fR\&. The structures in the array consist of the following fields:
441 \fIsession id\fR,
442 \fIuser id\fR,
443 \fIuser name\fR,
444 \fIseat id\fR,
445 \fIleader pid\fR,
446 \fIsession class\fR,
447 \fItty name\fR,
448 \fIidle hint\fR,
449 \fIidle hint monotonic timestamp\fR, and
450 \fIsession object path\fR\&.
451 \fItty\fR
452 and
453 \fIseat id\fR
454 fields could be empty, if the session has no associated tty or session has no seat attached, respectively\&.
455 .PP
456 \fBListUsers()\fR
457 returns an array of all currently logged in users\&. The structures in the array consist of the following fields: user id, user name, user object path\&.
458 .PP
459 \fBListSeats()\fR
460 returns an array of all currently available seats\&. The structure in the array consists of the following fields: seat id, seat object path\&.
461 .PP
462 \fBListInhibitors()\fR
463 lists all currently active inhibitors\&. It returns an array of structures consisting of
464 \fIwhat\fR,
465 \fIwho\fR,
466 \fIwhy\fR,
467 \fImode\fR,
468 \fIuid\fR
469 (user ID), and
470 \fIpid\fR
471 (process ID)\&.
472 .PP
473 \fBCreateSession()\fR,
474 \fBCreateSessionWithPIDFD()\fR, and
475 \fBReleaseSession()\fR
476 may be used to open or close login sessions\&. These calls should
477 \fInever\fR
478 be invoked directly by clients\&. Creating/closing sessions is exclusively the job of PAM and its
479 \fBpam_systemd\fR(8)
480 module\&.
481 .PP
482 \fBActivateSession()\fR
483 brings the session with the specified ID into the foreground\&.
484 \fBActivateSessionOnSeat()\fR
485 does the same, but only if the seat id matches\&.
486 .PP
487 \fBLockSession()\fR
488 asks the session with the specified ID to activate the screen lock\&.
489 \fBUnlockSession()\fR
490 asks the session with the specified ID to remove an active screen lock, if there is any\&. This is implemented by sending out the Lock() and Unlock() signals from the respective session object which session managers are supposed to listen on\&.
491 .PP
492 \fBLockSessions()\fR
493 asks all sessions to activate their screen locks\&. This may be used to lock access to the entire machine in one action\&. Similarly,
494 \fBUnlockSessions()\fR
495 asks all sessions to deactivate their screen locks\&.
496 .PP
497 \fBKillSession()\fR
498 may be used to send a Unix signal to one or all processes of a session\&. As arguments it takes the session id, either the string
499 "leader"
500 or
501 "all"
502 and a signal number\&. If
503 "leader"
504 is passed only the session
505 "leader"
506 is killed\&. If
507 "all"
508 is passed all processes of the session are killed\&.
509 .PP
510 \fBKillUser()\fR
511 may be used to send a Unix signal to all processes of a user\&. As arguments it takes the user id and a signal number\&.
512 .PP
513 \fBTerminateSession()\fR,
514 \fBTerminateUser()\fR,
515 \fBTerminateSeat()\fR
516 may be used to forcibly terminate one specific session, all processes of a user, and all sessions attached to a specific seat, respectively\&. The session, user, and seat are identified by their respective IDs\&.
517 .PP
518 \fBSetUserLinger()\fR
519 enables or disables user lingering\&. If enabled, the runtime directory of a user is kept around and they may continue to run processes while logged out\&. If disabled, the runtime directory goes away as soon as they log out\&.
520 \fBSetUserLinger()\fR
521 expects three arguments: the UID, a boolean whether to enable/disable and a boolean controlling the
522 \m[blue]\fBpolkit\fR\m[]\&\s-2\u[1]\d\s+2
523 authorization interactivity (see below)\&. Note that the user linger state is persistently stored on disk\&.
524 .PP
525 \fBAttachDevice()\fR
526 may be used to assign a specific device to a specific seat\&. The device is identified by its
527 /sys/
528 path and must be eligible for seat assignments\&.
529 \fBAttachDevice()\fR
530 takes three arguments: the seat id, the sysfs path, and a boolean for controlling polkit interactivity (see below)\&. Device assignments are persistently stored on disk\&. To create a new seat, simply specify a previously unused seat id\&. For more information about the seat assignment logic see
531 \fBsd-login\fR(3)\&.
532 .PP
533 \fBFlushDevices()\fR
534 removes all explicit seat assignments for devices, resetting all assignments to the automatic defaults\&. The only argument it takes is the polkit interactivity boolean (see below)\&.
535 .PP
536 \fBPowerOff()\fR,
537 \fBReboot()\fR,
538 \fBHalt()\fR,
539 \fBSuspend()\fR, and
540 \fBHibernate()\fR
541 result in the system being powered off, rebooted, halted (shut down without turning off power), suspended (the system state is saved to RAM and the CPU is turned off), or hibernated (the system state is saved to disk and the machine is powered down)\&.
542 \fBHybridSleep()\fR
543 results in the system entering a hybrid\-sleep mode, i\&.e\&. the system is both hibernated and suspended\&.
544 \fBSuspendThenHibernate()\fR
545 results in the system being suspended, then later woken using an RTC timer and hibernated\&. The only argument is the polkit interactivity boolean
546 \fIinteractive\fR
547 (see below)\&. The main purpose of these calls is that they enforce polkit policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged users\&. They also enforce inhibition locks for non\-privileged users\&.
548 \fBSleep()\fR
549 automatically selects the most suitable sleep operation supported by the machine\&. The candidate sleep operations to check for support can be configured through
550 \fISleepOperation=\fR
551 setting in
552 \fBlogind.conf\fR(5)\&. UIs should expose these calls as the primary mechanism to poweroff/reboot/suspend/hibernate the machine\&. Methods
553 \fBPowerOffWithFlags()\fR,
554 \fBRebootWithFlags()\fR,
555 \fBHaltWithFlags()\fR,
556 \fBSuspendWithFlags()\fR,
557 \fBHibernateWithFlags()\fR,
558 \fBHybridSleepWithFlags()\fR,
559 \fBSuspendThenHibernateWithFlags()\fR, and
560 \fBSleep()\fR
561 take
562 \fIflags\fR
563 to allow for extendability, defined as follows:
564 .sp
565 .if n \{\
566 .RS 4
567 .\}
568 .nf
569 #define SD_LOGIND_ROOT_CHECK_INHIBITORS (UINT64_C(1) << 0)
570 #define SD_LOGIND_KEXEC_REBOOT (UINT64_C(1) << 1)
571 #define SD_LOGIND_SOFT_REBOOT (UINT64_C(1) << 2)
572 #define SD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP (UINT64_C(1) << 3)
573 #define SD_LOGIND_SKIP_INHIBITORS (UINT64_C(1) << 4)
574 .fi
575 .if n \{\
576 .RE
577 .\}
578 .PP
579 When the
580 \fIflags\fR
581 is 0 then these methods behave just like the versions without flags\&. Since systemd version 257 active inhibitors are honoured by default for privileged users too\&.
582 \fBSD_LOGIND_ROOT_CHECK_INHIBITORS\fR
583 (0x01) now only applies to weak inhibitors, to request that they honoured for privileged users too, since they ignore them by default\&. A new flag
584 \fBSD_LOGIND_SKIP_INHIBITORS\fR
585 (0x04) can be specified to bypass all types of inhibitors\&. When
586 \fBSD_LOGIND_KEXEC_REBOOT\fR
587 (0x02) is set, then
588 \fBRebootWithFlags()\fR
589 performs a kexec reboot if kexec kernel is loaded\&. When
590 \fBSD_LOGIND_SOFT_REBOOT\fR
591 (0x04) is set, or
592 \fBSD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP\fR
593 (0x08) is set and a new root file system has been set up on
594 "/run/nextroot/", then
595 \fBRebootWithFlags()\fR
596 performs a userspace reboot only\&.
597 \fBSD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP\fR
598 and
599 \fBSD_LOGIND_KEXEC_REBOOT\fR
600 can be combined, with soft\-reboot having precedence\&.
601 .PP
602 \fBSetRebootParameter()\fR
603 sets a parameter for a subsequent reboot operation\&. See the description of
604 \fBreboot\fR
605 in
606 \fBsystemctl\fR(1)
607 and
608 \fBreboot\fR(2)
609 for more information\&.
610 .PP
611 \fBSetRebootToFirmwareSetup()\fR,
612 \fBSetRebootToBootLoaderMenu()\fR, and
613 \fBSetRebootToBootLoaderEntry()\fR
614 configure the action to be taken from the boot loader after a reboot: respectively entering firmware setup mode, the boot loader menu, or a specific boot loader entry\&. See
615 \fBsystemctl\fR(1)
616 for the corresponding command line interface\&.
617 .PP
618 \fBCanPowerOff()\fR,
619 \fBCanReboot()\fR,
620 \fBCanHalt()\fR,
621 \fBCanSuspend()\fR,
622 \fBCanHibernate()\fR,
623 \fBCanHybridSleep()\fR,
624 \fBCanSuspendThenHibernate()\fR,
625 \fBCanSleep()\fR,
626 \fBCanRebootParameter()\fR,
627 \fBCanRebootToFirmwareSetup()\fR,
628 \fBCanRebootToBootLoaderMenu()\fR, and
629 \fBCanRebootToBootLoaderEntry()\fR
630 test whether the system supports the respective operation and whether the calling user is allowed to execute it\&. Returns one of
631 "na",
632 "yes",
633 "no", and
634 "challenge"\&. If
635 "na"
636 is returned, the operation is not available because hardware, kernel, or drivers do not support it\&. If
637 "yes"
638 is returned, the operation is supported and the user may execute the operation without further authentication\&. If
639 "no"
640 is returned, the operation is available but the user is not allowed to execute the operation\&. If
641 "challenge"
642 is returned, the operation is available but only after authorization\&.
643 .PP
644 \fBScheduleShutdown()\fR
645 schedules a shutdown operation
646 \fItype\fR
647 at time
648 \fIusec\fR
649 in microseconds since the UNIX epoch\&. Alternatively, if
650 \fIusec\fR
651 "UINT64_MAX"
652 and a maintenance window is configured,
653 systemd\-logind
654 will use the next time of the maintenance window instead\&.
655 \fItype\fR
656 can be one of
657 "poweroff",
658 "dry\-poweroff",
659 "reboot",
660 "dry\-reboot",
661 "halt", and
662 "dry\-halt"\&. (The
663 "dry\-"
664 variants do not actually execute the shutdown action\&.)
665 \fBCancelScheduledShutdown()\fR
666 cancels a scheduled shutdown\&. The output parameter
667 \fIcancelled\fR
668 is true if a shutdown operation was scheduled\&.
669 .PP
670 \fBSetWallMessage()\fR
671 sets the wall message (the message that will be sent out to all terminals and stored in a
672 \fButmp\fR(5)
673 record) for a subsequent scheduled shutdown operation\&. The parameter
674 \fIwall_message\fR
675 specifies the shutdown reason (and may be empty) which will be included in the shutdown message\&. The parameter
676 \fIenable\fR
677 specifies whether to print a wall message on shutdown\&.
678 .PP
679 \fBInhibit()\fR
680 creates an inhibition lock\&. It takes four parameters:
681 \fIwhat\fR,
682 \fIwho\fR,
683 \fIwhy\fR, and
684 \fImode\fR\&.
685 \fIwhat\fR
686 is one or more of
687 "shutdown",
688 "sleep",
689 "idle",
690 "handle\-power\-key",
691 "handle\-suspend\-key",
692 "handle\-hibernate\-key",
693 "handle\-lid\-switch", separated by colons, for inhibiting poweroff/reboot, suspend/hibernate, the automatic idle logic, or hardware key handling\&.
694 \fIwho\fR
695 should be a short human readable string identifying the application taking the lock\&.
696 \fIwhy\fR
697 should be a short human readable string identifying the reason why the lock is taken\&. Finally,
698 \fImode\fR
699 is either
700 "block"
701 or
702 "delay"
703 which encodes whether the inhibit shall be consider mandatory or whether it should just delay the operation to a certain maximum time, while the
704 "block\-weak"
705 and variants will create an inhibitor that is automatically ignored in some circumstances\&. The method returns a file descriptor\&. The lock is released the moment this file descriptor and all its duplicates are closed\&. For more information on the inhibition logic see
706 \m[blue]\fBInhibitor Locks\fR\m[]\&\s-2\u[2]\d\s+2\&.
707 .SS "Signals"
708 .PP
709 Whenever the inhibition state or idle hint changes,
710 \fBPropertyChanged\fR
711 signals are sent out to clients which have subscribed\&.
712 .PP
713 The
714 \fBSecureAttentionKey()\fR
715 signal is sent when the user presses Ctrl+Alt+Shift+Esc to request the login manager to display the greeter, for instance in the case of a deadlocked compositor\&.
716 .PP
717 The
718 \fBSessionNew()\fR,
719 \fBSessionRemoved()\fR,
720 \fBUserNew()\fR,
721 \fBUserRemoved()\fR,
722 \fBSeatNew()\fR, and
723 \fBSeatRemoved()\fR
724 signals are sent each time a session is created or removed, a user logs in or out, or a seat is added or removed\&. They each contain the ID of the object plus the object path\&.
725 .PP
726 The
727 \fBPrepareForShutdown()\fR,
728 \fBPrepareForShutdownWithMetadata()\fR, and
729 \fBPrepareForSleep()\fR
730 signals are sent right before (with the argument
731 "true") or after (with the argument
732 "false") the system goes down for reboot/poweroff and suspend/hibernate, respectively\&. This may be used by applications to save data on disk, release memory, or do other jobs that should be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks\&. After completion of this work they should release their inhibition locks in order to not delay the operation any further\&. For more information see
733 \m[blue]\fBInhibitor Locks\fR\m[]\&\s-2\u[2]\d\s+2\&. The
734 \fBPrepareForShutdownWithMetadata()\fR
735 signal additionally sends a list of key/value pair metadata fields\&. Currently it sends a
736 \fItype\fR
737 string which defines the type of shutdown\&. The type can be one of
738 "power\-off",
739 "reboot",
740 "halt",
741 "kexec"
742 or
743 "soft\-reboot"\&. This signal is sent first, followed by
744 \fBPrepareForShutdown()\fR
745 (for backward compatibility)\&.
746 .SS "Properties"
747 .PP
748 Most properties simply reflect the configuration, see
749 \fBlogind.conf\fR(5)\&. This includes:
750 \fINAutoVTs\fR,
751 \fIKillOnlyUsers\fR,
752 \fIKillExcludeUsers\fR,
753 \fIKillUserProcesses\fR,
754 \fIIdleAction\fR,
755 \fIInhibitDelayMaxUSec\fR,
756 \fIInhibitorsMax\fR,
757 \fIUserStopDelayUSec\fR,
758 \fIHandlePowerKey\fR,
759 \fIHandleSuspendKey\fR,
760 \fIHandleHibernateKey\fR,
761 \fIHandleLidSwitch\fR,
762 \fIHandleLidSwitchExternalPower\fR,
763 \fIHandleLidSwitchDocked\fR,
764 \fIIdleActionUSec\fR,
765 \fIHoldoffTimeoutUSec\fR,
766 \fIRemoveIPC\fR,
767 \fIRuntimeDirectorySize\fR,
768 \fIRuntimeDirectoryInodesMax\fR,
769 \fIInhibitorsMax\fR, and
770 \fISessionsMax\fR\&.
771 .PP
772 The
773 \fIIdleHint\fR
774 property reflects the idle hint state of the system\&. If the system is idle it might get into automatic suspend or shutdown depending on the configuration\&.
775 .PP
776 \fIIdleSinceHint\fR
777 and
778 \fIIdleSinceHintMonotonic\fR
779 encode the timestamps of the last change of the idle hint boolean, in
780 \fBCLOCK_REALTIME\fR
781 and
782 \fBCLOCK_MONOTONIC\fR
783 timestamps, respectively, in microseconds since the epoch\&.
784 .PP
785 The
786 \fIBlockInhibited\fR,
787 \fIBlockWeakInhibited\fR, and
788 \fIDelayInhibited\fR
789 properties encode the currently active locks of the respective modes\&. They are colon separated lists of
790 "shutdown",
791 "sleep", and
792 "idle"
793 (see above)\&.
794 .PP
795 \fINCurrentSessions\fR
796 and
797 \fINCurrentInhibitors\fR
798 contain the number of currently registered sessions and inhibitors\&.
799 .PP
800 The
801 \fIBootLoaderEntries\fR
802 property contains a list of boot loader entries\&. This includes boot loader entries defined in configuration and any additional loader entries reported by the boot loader\&. See
803 \fBsystemd-boot\fR(7)
804 for more information\&.
805 .PP
806 The
807 \fIPreparingForShutdown\fR
808 and
809 \fIPreparingForSleep\fR
810 boolean properties are true during the interval between the two
811 \fBPrepareForShutdown()\fR
812 and
813 \fBPrepareForSleep()\fR
814 signals respectively\&. The
815 \fIPreparingForShutdownWithMetadata\fR
816 property provides a list of key/value pair metadata fields\&. Currently it lists a
817 \fIpreparing\fR
818 boolean that corresponds to the
819 \fIPreparingForShutdown\fR
820 property, and, if a shutdown is being prepared, it will also contain a
821 \fItype\fR
822 string which defines the type of shutdown\&. The type can be one of
823 "power\-off",
824 "reboot",
825 "halt",
826 "kexec"
827 or
828 "soft\-reboot"\&. Note that these properties do not send out
829 \fBPropertyChanged\fR
830 signals\&.
831 .PP
832 The
833 \fIRebootParameter\fR
834 property shows the value set with the
835 \fBSetRebootParameter()\fR
836 method described above\&.
837 .PP
838 \fIScheduledShutdown\fR
839 shows the value pair set with the
840 \fBScheduleShutdown()\fR
841 method described above\&.
842 .PP
843 \fIRebootToFirmwareSetup\fR,
844 \fIRebootToBootLoaderMenu\fR, and
845 \fIRebootToBootLoaderEntry\fR
846 are true when the resprective post\-reboot operation was selected with
847 \fBSetRebootToFirmwareSetup()\fR,
848 \fBSetRebootToBootLoaderMenu()\fR, or
849 \fBSetRebootToBootLoaderEntry()\fR\&.
850 .PP
851 The
852 \fIWallMessage\fR
853 and
854 \fIEnableWallMessages\fR
855 properties reflect the shutdown reason and wall message enablement switch which can be set with the
856 \fBSetWallMessage()\fR
857 method described above\&.
858 .PP
859 \fIDocked\fR
860 is true if the machine is connected to a dock\&.
861 \fILidClosed\fR
862 is true when the lid (of a laptop) is closed\&.
863 \fIOnExternalPower\fR
864 is true when the machine is connected to an external power supply\&.
865 .SS "Security"
866 .PP
867 A number of operations are protected via the polkit privilege system\&.
868 \fBSetUserLinger()\fR
869 requires the
870 org\&.freedesktop\&.login1\&.set\-user\-linger
871 privilege\&.
872 \fBAttachDevice()\fR
873 requires
874 org\&.freedesktop\&.login1\&.attach\-device
875 and
876 \fBFlushDevices()\fR
877 requires
878 org\&.freedesktop\&.login1\&.flush\-devices\&.
879 \fBPowerOff()\fR,
880 \fBReboot()\fR,
881 \fBHalt()\fR,
882 \fBSuspend()\fR,
883 \fBHibernate()\fR
884 require
885 org\&.freedesktop\&.login1\&.power\-off,
886 org\&.freedesktop\&.login1\&.power\-off\-multiple\-sessions,
887 org\&.freedesktop\&.login1\&.power\-off\-ignore\-inhibit,
888 org\&.freedesktop\&.login1\&.reboot,
889 org\&.freedesktop\&.login1\&.reboot\-multiple\-sessions,
890 org\&.freedesktop\&.login1\&.reboot\-ignore\-inhibit,
891 org\&.freedesktop\&.login1\&.halt,
892 org\&.freedesktop\&.login1\&.halt\-multiple\-sessions,
893 org\&.freedesktop\&.login1\&.halt\-ignore\-inhibit,
894 org\&.freedesktop\&.login1\&.suspend,
895 org\&.freedesktop\&.login1\&.suspend\-multiple\-sessions,
896 org\&.freedesktop\&.login1\&.suspend\-ignore\-inhibit,
897 org\&.freedesktop\&.login1\&.hibernate,
898 org\&.freedesktop\&.login1\&.hibernate\-multiple\-sessions,
899 org\&.freedesktop\&.login1\&.hibernate\-ignore\-inhibit, respectively depending on whether there are other sessions around or active inhibits are present\&.
900 \fBHybridSleep()\fR
901 and
902 \fBSuspendThenHibernate()\fR
903 use the same privileges as
904 \fBHibernate()\fR\&.
905 \fBSleep()\fR
906 uses the inhibits of the auto\-selected sleep operation\&.
907 \fBSetRebootParameter()\fR
908 requires
909 org\&.freedesktop\&.login1\&.set\-reboot\-parameter\&.
910 .PP
911 \fBSetRebootToFirmwareSetup()\fR
912 requires
913 org\&.freedesktop\&.login1\&.set\-reboot\-to\-firmware\-setup\&.
914 \fBSetRebootToBootLoaderMenu()\fR
915 requires
916 org\&.freedesktop\&.login1\&.set\-reboot\-to\-boot\-loader\-menu\&.
917 \fBSetRebootToBootLoaderEntry()\fR
918 requires
919 org\&.freedesktop\&.login1\&.set\-reboot\-to\-boot\-loader\-entry\&.
920 .PP
921 \fBScheduleShutdown()\fR
922 and
923 \fBCancelScheduledShutdown()\fR
924 require the same privileges (listed above) as the immediate poweroff/reboot/halt operations\&.
925 .PP
926 \fBInhibit()\fR
927 is protected via one of
928 org\&.freedesktop\&.login1\&.inhibit\-block\-shutdown,
929 org\&.freedesktop\&.login1\&.inhibit\-delay\-shutdown,
930 org\&.freedesktop\&.login1\&.inhibit\-block\-sleep,
931 org\&.freedesktop\&.login1\&.inhibit\-delay\-sleep,
932 org\&.freedesktop\&.login1\&.inhibit\-block\-idle,
933 org\&.freedesktop\&.login1\&.inhibit\-handle\-power\-key,
934 org\&.freedesktop\&.login1\&.inhibit\-handle\-suspend\-key,
935 org\&.freedesktop\&.login1\&.inhibit\-handle\-hibernate\-key,
936 org\&.freedesktop\&.login1\&.inhibit\-handle\-lid\-switch
937 depending on the lock type and mode taken\&.
938 .PP
939 The
940 \fIinteractive\fR
941 boolean parameters can be used to control whether polkit should interactively ask the user for authentication credentials if required\&.
942 .SH "SEAT OBJECTS"
943 .sp
944 .if n \{\
945 .RS 4
946 .\}
947 .nf
948 node /org/freedesktop/login1/seat/seat0 {
949 interface org\&.freedesktop\&.login1\&.Seat {
950 methods:
951 Terminate();
952 ActivateSession(in s session_id);
953 SwitchTo(in u vtnr);
954 SwitchToNext();
955 SwitchToPrevious();
956 properties:
957 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
958 readonly s Id = \*(Aq\&.\&.\&.\*(Aq;
959 readonly (so) ActiveSession = \&.\&.\&.;
960 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
961 readonly b CanTTY = \&.\&.\&.;
962 readonly b CanGraphical = \&.\&.\&.;
963 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
964 readonly a(so) Sessions = [\&.\&.\&.];
965 readonly b IdleHint = \&.\&.\&.;
966 readonly t IdleSinceHint = \&.\&.\&.;
967 readonly t IdleSinceHintMonotonic = \&.\&.\&.;
968 };
969 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
970 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
971 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
972 };
973 .fi
974 .if n \{\
975 .RE
976 .\}
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991 .SS "Methods"
992 .PP
993 \fBTerminate()\fR
994 and
995 \fBActivateSession()\fR
996 work similarly to
997 \fBTerminateSeat()\fR
998 and
999 \fBActivationSessionOnSeat()\fR
1000 on the Manager object\&.
1001 .PP
1002 \fBSwitchTo()\fR
1003 switches to the session on the virtual terminal
1004 \fIvtnr\fR\&.
1005 \fBSwitchToNext()\fR
1006 and
1007 \fBSwitchToPrevious()\fR
1008 switch to, respectively, the next and previous sessions on the seat in the order of virtual terminals\&. If there is no active session, they switch to, respectively, the first and last session on the seat\&.
1009 .SS "Signals"
1010 .PP
1011 Whenever
1012 \fBActiveSession\fR,
1013 \fBSessions\fR,
1014 \fBCanGraphical\fR,
1015 \fBCanTTY\fR, or the idle state changes,
1016 \fBPropertyChanged\fR
1017 signals are sent out to clients which have subscribed\&.
1018 .PP
1019 Signals are only emitted on objects referencing a specific seat ID, not on the
1020 "/org/freedesktop/login1/seat/self"
1021 or
1022 "/org/freedesktop/login1/seat/auto"
1023 convenience objects, as they can only be dereferenced relative to a method caller\&.
1024 .SS "Properties"
1025 .PP
1026 The
1027 \fIId\fR
1028 property encodes the ID of the seat\&.
1029 .PP
1030 \fIActiveSession\fR
1031 encodes the currently active session if there is one\&. It is a structure consisting of the session id and the object path\&.
1032 .PP
1033 \fICanTTY\fR
1034 encodes whether the session is suitable for text logins, and
1035 \fICanGraphical\fR
1036 whether it is suitable for graphical sessions\&.
1037 .PP
1038 The
1039 \fISessions\fR
1040 property is an array of all current sessions of this seat, each encoded in a structure consisting of the ID and the object path\&.
1041 .PP
1042 The
1043 \fIIdleHint\fR,
1044 \fIIdleSinceHint\fR, and
1045 \fIIdleSinceHintMonotonic\fR
1046 properties encode the idle state, similarly to the ones exposed on the
1047 Manager
1048 object, but specific for this seat\&.
1049 .SH "USER OBJECTS"
1050 .sp
1051 .if n \{\
1052 .RS 4
1053 .\}
1054 .nf
1055 node /org/freedesktop/login1/user/_1000 {
1056 interface org\&.freedesktop\&.login1\&.User {
1057 methods:
1058 Terminate();
1059 Kill(in i signal_number);
1060 properties:
1061 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1062 readonly u UID = \&.\&.\&.;
1063 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1064 readonly u GID = \&.\&.\&.;
1065 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1066 readonly s Name = \*(Aq\&.\&.\&.\*(Aq;
1067 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1068 readonly t Timestamp = \&.\&.\&.;
1069 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1070 readonly t TimestampMonotonic = \&.\&.\&.;
1071 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1072 readonly s RuntimePath = \*(Aq\&.\&.\&.\*(Aq;
1073 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1074 readonly s Service = \*(Aq\&.\&.\&.\*(Aq;
1075 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1076 readonly s Slice = \*(Aq\&.\&.\&.\*(Aq;
1077 readonly (so) Display = \&.\&.\&.;
1078 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
1079 readonly s State = \*(Aq\&.\&.\&.\*(Aq;
1080 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
1081 readonly a(so) Sessions = [\&.\&.\&.];
1082 readonly b IdleHint = \&.\&.\&.;
1083 readonly t IdleSinceHint = \&.\&.\&.;
1084 readonly t IdleSinceHintMonotonic = \&.\&.\&.;
1085 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
1086 readonly b Linger = \&.\&.\&.;
1087 };
1088 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
1089 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
1090 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
1091 };
1092 .fi
1093 .if n \{\
1094 .RE
1095 .\}
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114 .SS "Methods"
1115 .PP
1116 \fBTerminate()\fR
1117 and
1118 \fBKill()\fR
1119 work similarly to the
1120 \fBTerminateUser()\fR
1121 and
1122 \fBKillUser()\fR
1123 methods on the manager object\&.
1124 .SS "Signals"
1125 .PP
1126 Whenever
1127 \fISessions\fR
1128 or the idle state changes,
1129 \fBPropertyChanged\fR
1130 signals are sent out to clients which have subscribed\&.
1131 .PP
1132 Signals are only emitted on objects referencing a specific UID, not on the
1133 "/org/freedesktop/login1/user/self"
1134 convenience object, as
1135 \fIself\fR
1136 can only be dereferenced relative to a method caller\&.
1137 .SS "Properties"
1138 .PP
1139 The
1140 \fIUID\fR
1141 and
1142 \fIGID\fR
1143 properties encode the Unix UID and primary GID of the user\&.
1144 .PP
1145 The
1146 \fIName\fR
1147 property encodes the user name\&.
1148 .PP
1149 \fITimestamp\fR
1150 and
1151 \fITimestampMonotonic\fR
1152 encode the login time of the user in microseconds since the epoch, in the
1153 \fBCLOCK_REALTIME\fR
1154 and
1155 \fBCLOCK_MONOTONIC\fR
1156 clocks, respectively\&.
1157 .PP
1158 \fIRuntimePath\fR
1159 encodes the runtime path of the user, i\&.e\&.
1160 \fI$XDG_RUNTIME_DIR\fR\&. For details see the
1161 \m[blue]\fBXDG Basedir Specification\fR\m[]\&\s-2\u[3]\d\s+2\&.
1162 .PP
1163 \fIService\fR
1164 contains the unit name of the user systemd service of this user\&. Each logged in user is assigned a user service that runs a user systemd instance\&. This is usually an instance of
1165 user@\&.service\&.
1166 .PP
1167 \fISlice\fR
1168 contains the unit name of the user systemd slice of this user\&. Each logged in user gets a private slice\&.
1169 .PP
1170 \fIDisplay\fR
1171 encodes which graphical session should be used as the primary UI display for the user\&. It is a structure encoding the session ID and the object path of the session to use\&.
1172 .PP
1173 \fIState\fR
1174 encodes the user state and is one of
1175 "offline",
1176 "lingering",
1177 "online",
1178 "active", or
1179 "closing"\&. See
1180 \fBsd_uid_get_state\fR(3)
1181 for more information about the states\&.
1182 .PP
1183 \fISessions\fR
1184 is an array of structures encoding all current sessions of the user\&. Each structure consists of the ID and object path\&.
1185 .PP
1186 The
1187 \fIIdleHint\fR,
1188 \fIIdleSinceHint\fR, and
1189 \fIIdleSinceHintMonotonic\fR
1190 properties encode the idle hint state of the user, similarly to the
1191 Manager\*(Aqs properties, but specific for this user\&.
1192 .PP
1193 The
1194 \fILinger\fR
1195 property shows whether lingering is enabled for this user\&.
1196 .SH "SESSION OBJECTS"
1197 .sp
1198 .if n \{\
1199 .RS 4
1200 .\}
1201 .nf
1202 node /org/freedesktop/login1/session/1 {
1203 interface org\&.freedesktop\&.login1\&.Session {
1204 methods:
1205 Terminate();
1206 Activate();
1207 Lock();
1208 Unlock();
1209 SetIdleHint(in b idle);
1210 SetLockedHint(in b locked);
1211 Kill(in s whom,
1212 in i signal_number);
1213 TakeControl(in b force);
1214 ReleaseControl();
1215 SetType(in s type);
1216 SetClass(in s class);
1217 SetDisplay(in s display);
1218 SetTTY(in h tty_fd);
1219 TakeDevice(in u major,
1220 in u minor,
1221 out h fd,
1222 out b inactive);
1223 ReleaseDevice(in u major,
1224 in u minor);
1225 PauseDeviceComplete(in u major,
1226 in u minor);
1227 SetBrightness(in s subsystem,
1228 in s name,
1229 in u brightness);
1230 signals:
1231 PauseDevice(u major,
1232 u minor,
1233 s type);
1234 ResumeDevice(u major,
1235 u minor,
1236 h fd);
1237 Lock();
1238 Unlock();
1239 properties:
1240 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1241 readonly s Id = \*(Aq\&.\&.\&.\*(Aq;
1242 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1243 readonly (uo) User = \&.\&.\&.;
1244 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1245 readonly s Name = \*(Aq\&.\&.\&.\*(Aq;
1246 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1247 readonly t Timestamp = \&.\&.\&.;
1248 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1249 readonly t TimestampMonotonic = \&.\&.\&.;
1250 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1251 readonly u VTNr = \&.\&.\&.;
1252 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1253 readonly (so) Seat = \&.\&.\&.;
1254 readonly s TTY = \*(Aq\&.\&.\&.\*(Aq;
1255 readonly s Display = \*(Aq\&.\&.\&.\*(Aq;
1256 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1257 readonly b Remote = \&.\&.\&.;
1258 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1259 readonly s RemoteHost = \*(Aq\&.\&.\&.\*(Aq;
1260 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1261 readonly s RemoteUser = \*(Aq\&.\&.\&.\*(Aq;
1262 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1263 readonly s Service = \*(Aq\&.\&.\&.\*(Aq;
1264 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1265 readonly s Desktop = \*(Aq\&.\&.\&.\*(Aq;
1266 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1267 readonly s Scope = \*(Aq\&.\&.\&.\*(Aq;
1268 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1269 readonly u Leader = \&.\&.\&.;
1270 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1271 readonly u Audit = \&.\&.\&.;
1272 readonly s Type = \*(Aq\&.\&.\&.\*(Aq;
1273 readonly s Class = \*(Aq\&.\&.\&.\*(Aq;
1274 readonly b Active = \&.\&.\&.;
1275 readonly s State = \*(Aq\&.\&.\&.\*(Aq;
1276 readonly b IdleHint = \&.\&.\&.;
1277 readonly t IdleSinceHint = \&.\&.\&.;
1278 readonly t IdleSinceHintMonotonic = \&.\&.\&.;
1279 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1280 readonly b CanIdle = \&.\&.\&.;
1281 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1282 readonly b CanLock = \&.\&.\&.;
1283 readonly b LockedHint = \&.\&.\&.;
1284 };
1285 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
1286 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
1287 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
1288 };
1289 .fi
1290 .if n \{\
1291 .RE
1292 .\}
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342 .SS "Methods"
1343 .PP
1344 \fBTerminate()\fR,
1345 \fBActivate()\fR,
1346 \fBLock()\fR,
1347 \fBUnlock()\fR, and
1348 \fBKill()\fR
1349 work similarly to the respective calls on the
1350 Manager
1351 object\&.
1352 .PP
1353 \fBSetIdleHint()\fR
1354 is called by the session object to update the idle state of the session whenever it changes\&.
1355 .PP
1356 \fBTakeControl()\fR
1357 allows a process to take exclusive managed device access\-control for that session\&. Only one D\-Bus connection can be a controller for a given session at any time\&. If the
1358 \fIforce\fR
1359 argument is set (root only), an existing controller is kicked out and replaced\&. Otherwise, this method fails if there is already a controller\&. Note that this method is limited to D\-Bus users with the effective UID set to the user of the session or root\&.
1360 .PP
1361 \fBReleaseControl()\fR
1362 drops control of a given session\&. Closing the D\-Bus connection implicitly releases control as well\&. See
1363 \fBTakeControl()\fR
1364 for more information\&. This method also releases all devices for which the controller requested ownership via
1365 \fBTakeDevice()\fR\&.
1366 .PP
1367 \fBSetType()\fR
1368 allows the type of the session to be changed dynamically\&. It can only be called by session\*(Aqs current controller\&. If
1369 \fBTakeControl()\fR
1370 has not been called, this method will fail\&. In addition, the session type will be reset to its original value once control is released, either by calling
1371 \fBReleaseControl()\fR
1372 or closing the D\-Bus connection\&. This should help prevent a session from entering an inconsistent state, for example if the controller crashes\&. The only argument
1373 \fItype\fR
1374 is the new session type\&.
1375 .PP
1376 \fBSetClass()\fR
1377 allows the caller to change the class of the session dynamically\&. It may only be called by session\*(Aqs owening user\&. Currently, this call may be exclusively used to change the class from
1378 "user\-incomplete"
1379 to
1380 "user"\&. The call is synchronous, and will return only once the user\*(Aqs service manager has successfully been started, if necessary\&. The only argument
1381 \fItype\fR
1382 is the new session type\&.
1383 .PP
1384 \fBSetDisplay()\fR
1385 allows the display name of the graphical session to be changed\&. This is useful if the display server is started as part of the session\&. It can only be called by session\*(Aqs current controller\&. If
1386 \fBTakeControl()\fR
1387 has not been called, this method will fail\&. The only argument
1388 \fIdisplay\fR
1389 is the new display name\&.
1390 .PP
1391 \fBSetTTY()\fR
1392 allows the device name of the session to be changed\&. This is useful if the tty device is only known after authentication\&. It can only be called by session\*(Aqs current controller\&. If
1393 \fBTakeControl()\fR
1394 has not been called, this method will fail\&. The only argument
1395 \fItty_fd\fR
1396 is a file handle to the new tty device\&.
1397 .PP
1398 \fBTakeDevice()\fR
1399 allows a session controller to get a file descriptor for a specific device\&. Pass in the major and minor numbers of the character device and
1400 systemd\-logind
1401 will return a file descriptor for the device\&. Only a limited set of device\-types is currently supported (but may be extended)\&.
1402 systemd\-logind
1403 automatically mutes the file descriptor if the session is inactive and resumes it once the session is activated again\&. This guarantees that a session can only access session devices if the session is active\&. Note that this revoke/resume mechanism is asynchronous and may happen at any given time\&. This only works on devices that are attached to the seat of the given session\&. A process is not required to have direct access to the device node\&.
1404 systemd\-logind
1405 only requires you to be the active session controller (see
1406 \fBTakeControl()\fR)\&. Also note that any device can only be requested once\&. As long as you do not release it, further
1407 \fBTakeDevice()\fR
1408 calls will fail\&.
1409 .PP
1410 \fBReleaseDevice()\fR
1411 releases a device again (see
1412 \fBTakeDevice()\fR)\&. This is also implicitly done by
1413 \fBReleaseControl()\fR
1414 or when closing the D\-Bus connection\&.
1415 .PP
1416 \fBPauseDeviceComplete()\fR
1417 allows a session controller to synchronously pause a device after receiving a
1418 \fBPauseDevice(\fR\fB"pause"\fR\fB)\fR
1419 signal\&. Forced signals (or after an internal timeout) are automatically completed by
1420 systemd\-logind
1421 asynchronously\&.
1422 .PP
1423 \fBSetLockedHint()\fR
1424 may be used to set the "locked hint" to
1425 \fIlocked\fR, i\&.e\&. information whether the session is locked\&. This is intended to be used by the desktop environment to tell
1426 \fBsystemd\-logind\fR
1427 when the session is locked and unlocked\&.
1428 .PP
1429 \fBSetBrightness()\fR
1430 may be used to set the display brightness\&. This is intended to be used by the desktop environment and allows unprivileged programs to access hardware settings in a controlled way\&. The
1431 \fIsubsystem\fR
1432 parameter specifies a kernel subsystem, either
1433 "backlight"
1434 or
1435 "leds"\&. The
1436 \fIname\fR
1437 parameter specifies a device name under the specified subsystem\&. The
1438 \fIbrightness\fR
1439 parameter specifies the brightness\&. The range is defined by individual drivers, see
1440 /sys/class/\fIsubsystem\fR/\fIname\fR/max_brightness\&.
1441 .SS "Signals"
1442 .PP
1443 The active session controller exclusively gets
1444 \fBPauseDevice()\fR
1445 and
1446 \fBResumeDevice()\fR
1447 events for any device it requested via
1448 \fBTakeDevice()\fR\&. They notify the controller whenever a device is paused or resumed\&. A device is never resumed if its session is inactive\&. Also note that
1449 \fBPauseDevice()\fR
1450 signals are sent before the
1451 \fBPropertyChanged\fR
1452 signal for the
1453 \fBActive\fR
1454 state\&. The inverse is true for
1455 \fBResumeDevice()\fR\&. A device may remain paused for unknown reasons even though the
1456 Session
1457 is active\&.
1458 .PP
1459 A
1460 \fBPauseDevice()\fR
1461 signal carries the major and minor numbers and a string describing the type as arguments\&.
1462 \fBforce\fR
1463 means the device was already paused by
1464 systemd\-logind
1465 and the signal is only an asynchronous notification\&.
1466 \fBpause\fR
1467 means
1468 systemd\-logind
1469 grants you a limited amount of time to pause the device\&. You must respond to this via
1470 \fBPauseDeviceComplete()\fR\&. This synchronous pausing mechanism is used for backwards\-compatibility to VTs and
1471 systemd\-logind
1472 is free to not make use of it\&. It is also free to send a forced
1473 \fBPauseDevice()\fR
1474 if you do not respond in a timely manner (or for any other reason)\&.
1475 \fBgone\fR
1476 means the device was unplugged from the system and you will no longer get any notifications about it\&. There is no need to call
1477 \fBReleaseDevice()\fR\&. You may call
1478 \fBTakeDevice()\fR
1479 again if a new device is assigned the major+minor combination\&.
1480 .PP
1481 \fBResumeDevice()\fR
1482 is sent whenever a session is active and a device is resumed\&. It carries the major/minor numbers as arguments and provides a new open file descriptor\&. You should switch to the new descriptor and close the old one\&. They are not guaranteed to have the same underlying open file descriptor in the kernel (except for a limited set of device types)\&.
1483 .PP
1484 Whenever
1485 \fBActive\fR
1486 or the idle state changes,
1487 \fBPropertyChanged\fR
1488 signals are sent out to clients which have subscribed\&.
1489 .PP
1490 \fBLock()\fR/\fBUnlock()\fR
1491 is sent when the session is asked to be screen\-locked/unlocked\&. A session manager of the session should listen to this signal and act accordingly\&. This signal is sent out as a result of the
1492 \fBLock()\fR
1493 and
1494 \fBUnlock()\fR
1495 methods, respectively\&.
1496 .PP
1497 Signals are only emitted on objects referencing a specific session ID, not on the
1498 "/org/freedesktop/login1/session/self"
1499 or
1500 "/org/freedesktop/login1/session/auto"
1501 convenience objects, as they can only be dereferenced relative to a method caller\&.
1502 .SS "Properties"
1503 .PP
1504 \fIId\fR
1505 encodes the session ID\&.
1506 .PP
1507 \fIUser\fR
1508 encodes the user ID of the user this session belongs to\&. This is a structure consisting of the Unix UID and the object path\&.
1509 .PP
1510 \fIName\fR
1511 encodes the user name\&.
1512 .PP
1513 \fITimestamp\fR
1514 and
1515 \fITimestampMonotonic\fR
1516 encode the microseconds since the epoch when the session was created, in
1517 \fBCLOCK_REALTIME\fR
1518 or
1519 \fBCLOCK_MONOTONIC\fR, respectively\&.
1520 .PP
1521 \fIVTNr\fR
1522 encodes the virtual terminal number of the session if there is any, 0 otherwise\&.
1523 .PP
1524 \fISeat\fR
1525 encodes the seat this session belongs to if there is any\&. This is a structure consisting of the ID and the seat object path\&.
1526 .PP
1527 \fITTY\fR
1528 encodes the kernel TTY path of the session if this is a text login\&. If not this is an empty string\&.
1529 .PP
1530 \fIDisplay\fR
1531 encodes the X11 display name if this is a graphical login\&. If not, this is an empty string\&.
1532 .PP
1533 \fIRemote\fR
1534 encodes whether the session is local or remote\&.
1535 .PP
1536 \fIRemoteHost\fR
1537 and
1538 \fIRemoteUser\fR
1539 encode the remote host and user if this is a remote session, or an empty string otherwise\&.
1540 .PP
1541 \fIService\fR
1542 encodes the PAM service name that registered the session\&.
1543 .PP
1544 \fIDesktop\fR
1545 describes the desktop environment running in the session (if known)\&.
1546 .PP
1547 \fIScope\fR
1548 contains the systemd scope unit name of this session\&.
1549 .PP
1550 \fILeader\fR
1551 encodes the PID of the process that registered the session\&.
1552 .PP
1553 \fIAudit\fR
1554 encodes the Kernel Audit session ID of the session if auditing is available\&.
1555 .PP
1556 \fIType\fR
1557 encodes the session type\&. It\*(Aqs one of
1558 "unspecified"
1559 (for cron PAM sessions and suchlike),
1560 "tty"
1561 (for text logins),
1562 "web"
1563 (for web\-based logins), or
1564 "x11"/"mir"/"wayland"
1565 (for graphical logins)\&.
1566 .PP
1567 \fIClass\fR
1568 encodes the session class\&. It\*(Aqs one of
1569 "user"
1570 (for normal user sessions),
1571 "greeter"
1572 (for display manager pseudo\-sessions), or
1573 "lock\-screen"
1574 (for display lock screens)\&.
1575 .PP
1576 \fIActive\fR
1577 is a boolean that is true if the session is active, i\&.e\&. currently in the foreground\&. This field is semi\-redundant due to
1578 \fIState\fR\&.
1579 .PP
1580 \fIState\fR
1581 encodes the session state and one of
1582 "online",
1583 "active", or
1584 "closing"\&. See
1585 \fBsd_session_get_state\fR(3)
1586 for more information about the states\&.
1587 .PP
1588 \fIIdleHint\fR,
1589 \fIIdleSinceHint\fR, and
1590 \fIIdleSinceHintMonotonic\fR
1591 encapsulate the idle hint state of this session, similarly to how the respective properties on the manager object do it for the whole system\&.
1592 .PP
1593 \fILockedHint\fR
1594 shows the locked hint state of this session, as set by the
1595 \fBSetLockedHint()\fR
1596 method described above\&.
1597 .PP
1598 \fICanIdle\fR
1599 indicates whether the session supports the idle hint concept\&. Similarly,
1600 \fICanLock\fR
1601 indicates whether the session supports the screen lock concept\&.
1602 .SH "EXAMPLES"
1603 .PP
1604 \fBExample\ \&1.\ \&Introspect the logind manager on the bus\fR
1605 .sp
1606 .if n \{\
1607 .RS 4
1608 .\}
1609 .nf
1610 $ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.login1 \e
1611 \-\-object\-path /org/freedesktop/login1
1612 .fi
1613 .if n \{\
1614 .RE
1615 .\}
1616 .PP
1617 or
1618 .sp
1619 .if n \{\
1620 .RS 4
1621 .\}
1622 .nf
1623 $ busctl introspect org\&.freedesktop\&.login1 /org/freedesktop/login1
1624 .fi
1625 .if n \{\
1626 .RE
1627 .\}
1628 .PP
1629 \fBExample\ \&2.\ \&Introspect the default seat on the bus\fR
1630 .sp
1631 .if n \{\
1632 .RS 4
1633 .\}
1634 .nf
1635 $ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.login1 \e
1636 \-\-object\-path /org/freedesktop/login1/seat/seat0
1637 .fi
1638 .if n \{\
1639 .RE
1640 .\}
1641 .PP
1642 or
1643 .sp
1644 .if n \{\
1645 .RS 4
1646 .\}
1647 .nf
1648 $ busctl introspect org\&.freedesktop\&.login1 /org/freedesktop/login1/seat/seat0
1649 .fi
1650 .if n \{\
1651 .RE
1652 .\}
1653 .PP
1654 Seat
1655 "seat0"
1656 is the default seat, so it\*(Aqll be present unless local configuration is made to reassign all devices to a different seat\&. The list of seats and users can be acquired with
1657 \fBloginctl list\-sessions\fR\&.
1658 .PP
1659 \fBExample\ \&3.\ \&Introspect a single user on the bus\fR
1660 .sp
1661 .if n \{\
1662 .RS 4
1663 .\}
1664 .nf
1665 $ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.login1 \e
1666 \-\-object\-path /org/freedesktop/login1/user/_1000
1667 .fi
1668 .if n \{\
1669 .RE
1670 .\}
1671 .PP
1672 or
1673 .sp
1674 .if n \{\
1675 .RS 4
1676 .\}
1677 .nf
1678 $ busctl introspect org\&.freedesktop\&.login1 /org/freedesktop/login1/user/_1000
1679 .fi
1680 .if n \{\
1681 .RE
1682 .\}
1683 .PP
1684 \fBExample\ \&4.\ \&Introspect org\&.freedesktop\&.login1\&.Session on the bus\fR
1685 .sp
1686 .if n \{\
1687 .RS 4
1688 .\}
1689 .nf
1690 $ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.login1 \e
1691 \-\-object\-path /org/freedesktop/login1/session/45
1692 .fi
1693 .if n \{\
1694 .RE
1695 .\}
1696 .PP
1697 or
1698 .sp
1699 .if n \{\
1700 .RS 4
1701 .\}
1702 .nf
1703 $ busctl introspect org\&.freedesktop\&.login1 /org/freedesktop/login1/session/45
1704 .fi
1705 .if n \{\
1706 .RE
1707 .\}
1708 .SH "VERSIONING"
1709 .PP
1710 These D\-Bus interfaces follow
1711 \m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[4]\d\s+2\&.
1712 .SH "HISTORY"
1713 .SS "The Manager Object"
1714 .PP
1715 \fIHandlePowerKeyLongPress\fR,
1716 \fIHandleRebootKey\fR,
1717 \fIHandleRebootKeyLongPress\fR,
1718 \fIHandleSuspendKeyLongPress\fR, and
1719 \fIHandleHibernateKeyLongPress\fR
1720 were added in version 251\&.
1721 .PP
1722 \fIStopIdleSessionUSec\fR
1723 was added in version 252\&.
1724 .PP
1725 \fBPrepareForShutdownWithMetadata()\fR
1726 and
1727 \fBCreateSessionWithPIDFD()\fR
1728 were added in version 255\&.
1729 .PP
1730 \fBSleep()\fR,
1731 \fBCanSleep()\fR,
1732 \fISleepOperation\fR, and
1733 \fBListSessionsEx()\fR
1734 were added in version 256\&.
1735 .PP
1736 \fIHandleSecureAttentionKey\fR,
1737 \fBSecureAttentionKey()\fR,
1738 \fIPreparingForShutdownWithMetadata\fR,
1739 \fIDesignatedMaintenanceTime\fR,
1740 \fICanIdle\fR,
1741 \fICanLock\fR, and
1742 \fIBlockWeakInhibited\fR
1743 were added in version 257\&.
1744 .SS "Session Objects"
1745 .PP
1746 \fBSetDisplay()\fR
1747 was added in version 252\&.
1748 .PP
1749 \fBSetTTY()\fR
1750 was added in version 254\&.
1751 .PP
1752 \fBSetClass()\fR
1753 was added in version 256\&.
1754 .SH "SEE ALSO"
1755 .PP
1756 \fBsystemd\fR(1), \fBsystemd-logind.service\fR(8), \fBloginctl\fR(1)
1757 .SH "NOTES"
1758 .IP " 1." 4
1759 polkit
1760 .RS 4
1761 \%https://www.freedesktop.org/software/polkit/docs/latest/
1762 .RE
1763 .IP " 2." 4
1764 Inhibitor Locks
1765 .RS 4
1766 \%https://systemd.io/INHIBITOR_LOCKS
1767 .RE
1768 .IP " 3." 4
1769 XDG Basedir Specification
1770 .RS 4
1771 \%https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
1772 .RE
1773 .IP " 4." 4
1774 the usual interface versioning guidelines
1775 .RS 4
1776 \%https://0pointer.de/blog/projects/versioning-dbus.html
1777 .RE