Debian Codegraph @

upstream/mageia-cauldron/man5/org.freedesktop.login1.5

raw
1 '\" t
2 .TH "ORG\&.FREEDESKTOP\&.LOGIN1" "5" "" "systemd 258.7" "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 inhibitors of type
582 "block"
583 are enforced on operations requested by both privileged and unprivileged users\&. Previously they were honoured only by unprivileged users, excluding the user owning the inhibitor\&. The latter behaviour is now available through the
584 "block\-weak"
585 inhibitor lock type\&.
586 \fBSD_LOGIND_ROOT_CHECK_INHIBITORS\fR
587 (0x01) makes
588 "block\-weak"
589 locks behave like regular
590 "block"
591 locks, i\&.e\&. ensures they are honoured for any user\&. A flag
592 \fBSD_LOGIND_SKIP_INHIBITORS\fR
593 (0x10) can be specified to bypass both
594 "block"
595 and
596 "block\-weak"
597 inhibitors (it has no effect on
598 "delay"
599 inhibitors)\&. When
600 \fBSD_LOGIND_KEXEC_REBOOT\fR
601 (0x02) is set, then
602 \fBRebootWithFlags()\fR
603 performs a kexec reboot if kexec kernel is loaded\&. When
604 \fBSD_LOGIND_SOFT_REBOOT\fR
605 (0x04) is set, or
606 \fBSD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP\fR
607 (0x08) is set and a new root file system has been set up on
608 "/run/nextroot/", then
609 \fBRebootWithFlags()\fR
610 performs a userspace reboot only\&.
611 \fBSD_LOGIND_SOFT_REBOOT_IF_NEXTROOT_SET_UP\fR
612 and
613 \fBSD_LOGIND_KEXEC_REBOOT\fR
614 can be combined, with soft\-reboot having precedence\&.
615 .PP
616 \fBSetRebootParameter()\fR
617 sets a parameter for a subsequent reboot operation\&. See the description of
618 \fBreboot\fR
619 in
620 \fBsystemctl\fR(1)
621 and
622 \fBreboot\fR(2)
623 for more information\&.
624 .PP
625 \fBSetRebootToFirmwareSetup()\fR,
626 \fBSetRebootToBootLoaderMenu()\fR, and
627 \fBSetRebootToBootLoaderEntry()\fR
628 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
629 \fBsystemctl\fR(1)
630 for the corresponding command line interface\&.
631 .PP
632 \fBCanPowerOff()\fR,
633 \fBCanReboot()\fR,
634 \fBCanHalt()\fR,
635 \fBCanSuspend()\fR,
636 \fBCanHibernate()\fR,
637 \fBCanHybridSleep()\fR,
638 \fBCanSuspendThenHibernate()\fR,
639 \fBCanSleep()\fR,
640 \fBCanRebootParameter()\fR,
641 \fBCanRebootToFirmwareSetup()\fR,
642 \fBCanRebootToBootLoaderMenu()\fR, and
643 \fBCanRebootToBootLoaderEntry()\fR
644 test whether the system supports the respective operation and whether the calling user is allowed to execute it\&. Returns one of
645 "na",
646 "yes",
647 "no", and
648 "challenge"\&. If
649 "na"
650 is returned, the operation is not available because hardware, kernel, or drivers do not support it\&. If
651 "yes"
652 is returned, the operation is supported and the user may execute the operation without further authentication\&. If
653 "no"
654 is returned, the operation is available but the user is not allowed to execute the operation\&. If
655 "challenge"
656 is returned, the operation is available but only after authorization\&.
657 .PP
658 \fBScheduleShutdown()\fR
659 schedules a shutdown operation
660 \fItype\fR
661 at time
662 \fIusec\fR
663 in microseconds since the UNIX epoch\&. Alternatively, if
664 \fIusec\fR
665 "UINT64_MAX"
666 and a maintenance window is configured,
667 systemd\-logind
668 will use the next time of the maintenance window instead\&.
669 \fItype\fR
670 can be one of
671 "poweroff",
672 "dry\-poweroff",
673 "reboot",
674 "dry\-reboot",
675 "halt", and
676 "dry\-halt"\&. (The
677 "dry\-"
678 variants do not actually execute the shutdown action\&.)
679 \fBCancelScheduledShutdown()\fR
680 cancels a scheduled shutdown\&. The output parameter
681 \fIcancelled\fR
682 is true if a shutdown operation was scheduled\&.
683 .PP
684 \fBSetWallMessage()\fR
685 sets the wall message (the message that will be sent out to all terminals and stored in a
686 \fButmp\fR(5)
687 record) for a subsequent scheduled shutdown operation\&. The parameter
688 \fIwall_message\fR
689 specifies the shutdown reason (and may be empty) which will be included in the shutdown message\&. The parameter
690 \fIenable\fR
691 specifies whether to print a wall message on shutdown\&.
692 .PP
693 \fBInhibit()\fR
694 creates an inhibition lock\&. It takes four parameters:
695 \fIwhat\fR,
696 \fIwho\fR,
697 \fIwhy\fR, and
698 \fImode\fR\&.
699 \fIwhat\fR
700 is one or more of
701 "shutdown",
702 "sleep",
703 "idle",
704 "handle\-power\-key",
705 "handle\-suspend\-key",
706 "handle\-hibernate\-key",
707 "handle\-lid\-switch", separated by colons, for inhibiting poweroff/reboot, suspend/hibernate, the automatic idle logic, or hardware key handling\&.
708 \fIwho\fR
709 should be a short human\-readable string identifying the application taking the lock\&.
710 \fIwhy\fR
711 should be a short human\-readable string identifying the reason why the lock is taken\&. Finally,
712 \fImode\fR
713 is either
714 "block"
715 or
716 "delay"
717 which encodes whether the inhibit shall be consider mandatory or whether it should just delay the operation to a certain maximum time, while the
718 "block\-weak"
719 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
720 \m[blue]\fBInhibitor Locks\fR\m[]\&\s-2\u[2]\d\s+2\&.
721 .SS "Signals"
722 .PP
723 Whenever the inhibition state or idle hint changes,
724 \fBPropertyChanged\fR
725 signals are sent out to clients which have subscribed\&.
726 .PP
727 The
728 \fBSecureAttentionKey()\fR
729 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\&.
730 .PP
731 The
732 \fBSessionNew()\fR,
733 \fBSessionRemoved()\fR,
734 \fBUserNew()\fR,
735 \fBUserRemoved()\fR,
736 \fBSeatNew()\fR, and
737 \fBSeatRemoved()\fR
738 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\&.
739 .PP
740 The
741 \fBPrepareForShutdown()\fR,
742 \fBPrepareForShutdownWithMetadata()\fR, and
743 \fBPrepareForSleep()\fR
744 signals are sent right before (with the argument
745 "true") or after (with the argument
746 "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
747 \m[blue]\fBInhibitor Locks\fR\m[]\&\s-2\u[2]\d\s+2\&. The
748 \fBPrepareForShutdownWithMetadata()\fR
749 signal additionally sends a list of key/value pair metadata fields\&. Currently it sends a
750 \fItype\fR
751 string which defines the type of shutdown\&. The type can be one of
752 "power\-off",
753 "reboot",
754 "halt",
755 "kexec"
756 or
757 "soft\-reboot"\&. This signal is sent first, followed by
758 \fBPrepareForShutdown()\fR
759 (for backward compatibility)\&.
760 .SS "Properties"
761 .PP
762 Most properties simply reflect the configuration, see
763 \fBlogind.conf\fR(5)\&. This includes:
764 \fINAutoVTs\fR,
765 \fIKillOnlyUsers\fR,
766 \fIKillExcludeUsers\fR,
767 \fIKillUserProcesses\fR,
768 \fIIdleAction\fR,
769 \fIInhibitDelayMaxUSec\fR,
770 \fIInhibitorsMax\fR,
771 \fIUserStopDelayUSec\fR,
772 \fIHandlePowerKey\fR,
773 \fIHandleSuspendKey\fR,
774 \fIHandleHibernateKey\fR,
775 \fIHandleLidSwitch\fR,
776 \fIHandleLidSwitchExternalPower\fR,
777 \fIHandleLidSwitchDocked\fR,
778 \fIIdleActionUSec\fR,
779 \fIHoldoffTimeoutUSec\fR,
780 \fIRemoveIPC\fR,
781 \fIRuntimeDirectorySize\fR,
782 \fIRuntimeDirectoryInodesMax\fR,
783 \fIInhibitorsMax\fR, and
784 \fISessionsMax\fR\&.
785 .PP
786 The
787 \fIIdleHint\fR
788 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\&.
789 .PP
790 \fIIdleSinceHint\fR
791 and
792 \fIIdleSinceHintMonotonic\fR
793 encode the timestamps of the last change of the idle hint boolean, in
794 \fBCLOCK_REALTIME\fR
795 and
796 \fBCLOCK_MONOTONIC\fR
797 timestamps, respectively, in microseconds since the epoch\&.
798 .PP
799 The
800 \fIBlockInhibited\fR,
801 \fIBlockWeakInhibited\fR, and
802 \fIDelayInhibited\fR
803 properties encode the currently active locks of the respective modes\&. They are colon separated lists of
804 "shutdown",
805 "sleep", and
806 "idle"
807 (see above)\&.
808 .PP
809 \fINCurrentSessions\fR
810 and
811 \fINCurrentInhibitors\fR
812 contain the number of currently registered sessions and inhibitors\&.
813 .PP
814 The
815 \fIBootLoaderEntries\fR
816 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
817 \fBsystemd-boot\fR(7)
818 for more information\&.
819 .PP
820 The
821 \fIPreparingForShutdown\fR
822 and
823 \fIPreparingForSleep\fR
824 boolean properties are true during the interval between the two
825 \fBPrepareForShutdown()\fR
826 and
827 \fBPrepareForSleep()\fR
828 signals respectively\&. The
829 \fIPreparingForShutdownWithMetadata\fR
830 property provides a list of key/value pair metadata fields\&. Currently it lists a
831 \fIpreparing\fR
832 boolean that corresponds to the
833 \fIPreparingForShutdown\fR
834 property, and, if a shutdown is being prepared, it will also contain a
835 \fItype\fR
836 string which defines the type of shutdown\&. The type can be one of
837 "power\-off",
838 "reboot",
839 "halt",
840 "kexec"
841 or
842 "soft\-reboot"\&. Note that these properties do not send out
843 \fBPropertyChanged\fR
844 signals\&.
845 .PP
846 The
847 \fIRebootParameter\fR
848 property shows the value set with the
849 \fBSetRebootParameter()\fR
850 method described above\&.
851 .PP
852 \fIScheduledShutdown\fR
853 shows the value pair set with the
854 \fBScheduleShutdown()\fR
855 method described above\&.
856 .PP
857 \fIRebootToFirmwareSetup\fR,
858 \fIRebootToBootLoaderMenu\fR, and
859 \fIRebootToBootLoaderEntry\fR
860 are true when the resprective post\-reboot operation was selected with
861 \fBSetRebootToFirmwareSetup()\fR,
862 \fBSetRebootToBootLoaderMenu()\fR, or
863 \fBSetRebootToBootLoaderEntry()\fR\&.
864 .PP
865 The
866 \fIWallMessage\fR
867 and
868 \fIEnableWallMessages\fR
869 properties reflect the shutdown reason and wall message enablement switch which can be set with the
870 \fBSetWallMessage()\fR
871 method described above\&.
872 .PP
873 \fIDocked\fR
874 is true if the machine is connected to a dock\&.
875 \fILidClosed\fR
876 is true when the lid (of a laptop) is closed\&.
877 \fIOnExternalPower\fR
878 is true when the machine is connected to an external power supply\&.
879 .SS "Security"
880 .PP
881 A number of operations are protected via the polkit privilege system\&.
882 \fBSetUserLinger()\fR
883 requires the
884 org\&.freedesktop\&.login1\&.set\-user\-linger
885 privilege\&.
886 \fBAttachDevice()\fR
887 requires
888 org\&.freedesktop\&.login1\&.attach\-device
889 and
890 \fBFlushDevices()\fR
891 requires
892 org\&.freedesktop\&.login1\&.flush\-devices\&.
893 \fBPowerOff()\fR,
894 \fBReboot()\fR,
895 \fBHalt()\fR,
896 \fBSuspend()\fR,
897 \fBHibernate()\fR
898 require
899 org\&.freedesktop\&.login1\&.power\-off,
900 org\&.freedesktop\&.login1\&.power\-off\-multiple\-sessions,
901 org\&.freedesktop\&.login1\&.power\-off\-ignore\-inhibit,
902 org\&.freedesktop\&.login1\&.reboot,
903 org\&.freedesktop\&.login1\&.reboot\-multiple\-sessions,
904 org\&.freedesktop\&.login1\&.reboot\-ignore\-inhibit,
905 org\&.freedesktop\&.login1\&.halt,
906 org\&.freedesktop\&.login1\&.halt\-multiple\-sessions,
907 org\&.freedesktop\&.login1\&.halt\-ignore\-inhibit,
908 org\&.freedesktop\&.login1\&.suspend,
909 org\&.freedesktop\&.login1\&.suspend\-multiple\-sessions,
910 org\&.freedesktop\&.login1\&.suspend\-ignore\-inhibit,
911 org\&.freedesktop\&.login1\&.hibernate,
912 org\&.freedesktop\&.login1\&.hibernate\-multiple\-sessions,
913 org\&.freedesktop\&.login1\&.hibernate\-ignore\-inhibit, respectively depending on whether there are other sessions around or active inhibits are present\&.
914 \fBHybridSleep()\fR
915 and
916 \fBSuspendThenHibernate()\fR
917 use the same privileges as
918 \fBHibernate()\fR\&.
919 \fBSleep()\fR
920 uses the inhibits of the auto\-selected sleep operation\&.
921 \fBSetRebootParameter()\fR
922 requires
923 org\&.freedesktop\&.login1\&.set\-reboot\-parameter\&.
924 .PP
925 \fBSetRebootToFirmwareSetup()\fR
926 requires
927 org\&.freedesktop\&.login1\&.set\-reboot\-to\-firmware\-setup\&.
928 \fBSetRebootToBootLoaderMenu()\fR
929 requires
930 org\&.freedesktop\&.login1\&.set\-reboot\-to\-boot\-loader\-menu\&.
931 \fBSetRebootToBootLoaderEntry()\fR
932 requires
933 org\&.freedesktop\&.login1\&.set\-reboot\-to\-boot\-loader\-entry\&.
934 .PP
935 \fBScheduleShutdown()\fR
936 and
937 \fBCancelScheduledShutdown()\fR
938 require the same privileges (listed above) as the immediate poweroff/reboot/halt operations\&.
939 .PP
940 \fBInhibit()\fR
941 is protected via one of
942 org\&.freedesktop\&.login1\&.inhibit\-block\-shutdown,
943 org\&.freedesktop\&.login1\&.inhibit\-delay\-shutdown,
944 org\&.freedesktop\&.login1\&.inhibit\-block\-sleep,
945 org\&.freedesktop\&.login1\&.inhibit\-delay\-sleep,
946 org\&.freedesktop\&.login1\&.inhibit\-block\-idle,
947 org\&.freedesktop\&.login1\&.inhibit\-handle\-power\-key,
948 org\&.freedesktop\&.login1\&.inhibit\-handle\-suspend\-key,
949 org\&.freedesktop\&.login1\&.inhibit\-handle\-hibernate\-key,
950 org\&.freedesktop\&.login1\&.inhibit\-handle\-lid\-switch
951 depending on the lock type and mode taken\&.
952 .PP
953 The
954 \fIinteractive\fR
955 boolean parameters can be used to control whether polkit should interactively ask the user for authentication credentials if required\&.
956 .SH "SEAT OBJECTS"
957 .sp
958 .if n \{\
959 .RS 4
960 .\}
961 .nf
962 node /org/freedesktop/login1/seat/seat0 {
963 interface org\&.freedesktop\&.login1\&.Seat {
964 methods:
965 Terminate();
966 ActivateSession(in s session_id);
967 SwitchTo(in u vtnr);
968 SwitchToNext();
969 SwitchToPrevious();
970 properties:
971 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
972 readonly s Id = \*(Aq\&.\&.\&.\*(Aq;
973 readonly (so) ActiveSession = \&.\&.\&.;
974 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
975 readonly b CanTTY = \&.\&.\&.;
976 readonly b CanGraphical = \&.\&.\&.;
977 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
978 readonly a(so) Sessions = [\&.\&.\&.];
979 readonly b IdleHint = \&.\&.\&.;
980 readonly t IdleSinceHint = \&.\&.\&.;
981 readonly t IdleSinceHintMonotonic = \&.\&.\&.;
982 };
983 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
984 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
985 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
986 };
987 .fi
988 .if n \{\
989 .RE
990 .\}
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005 .SS "Methods"
1006 .PP
1007 \fBTerminate()\fR
1008 and
1009 \fBActivateSession()\fR
1010 work similarly to
1011 \fBTerminateSeat()\fR
1012 and
1013 \fBActivationSessionOnSeat()\fR
1014 on the Manager object\&.
1015 .PP
1016 \fBSwitchTo()\fR
1017 switches to the session on the virtual terminal
1018 \fIvtnr\fR\&.
1019 \fBSwitchToNext()\fR
1020 and
1021 \fBSwitchToPrevious()\fR
1022 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\&.
1023 .SS "Signals"
1024 .PP
1025 Whenever
1026 \fBActiveSession\fR,
1027 \fBSessions\fR,
1028 \fBCanGraphical\fR,
1029 \fBCanTTY\fR, or the idle state changes,
1030 \fBPropertyChanged\fR
1031 signals are sent out to clients which have subscribed\&.
1032 .PP
1033 Signals are only emitted on objects referencing a specific seat ID, not on the
1034 "/org/freedesktop/login1/seat/self"
1035 or
1036 "/org/freedesktop/login1/seat/auto"
1037 convenience objects, as they can only be dereferenced relative to a method caller\&.
1038 .SS "Properties"
1039 .PP
1040 The
1041 \fIId\fR
1042 property encodes the ID of the seat\&.
1043 .PP
1044 \fIActiveSession\fR
1045 encodes the currently active session if there is one\&. It is a structure consisting of the session id and the object path\&.
1046 .PP
1047 \fICanTTY\fR
1048 encodes whether the session is suitable for text logins, and
1049 \fICanGraphical\fR
1050 whether it is suitable for graphical sessions\&.
1051 .PP
1052 The
1053 \fISessions\fR
1054 property is an array of all current sessions of this seat, each encoded in a structure consisting of the ID and the object path\&.
1055 .PP
1056 The
1057 \fIIdleHint\fR,
1058 \fIIdleSinceHint\fR, and
1059 \fIIdleSinceHintMonotonic\fR
1060 properties encode the idle state, similarly to the ones exposed on the
1061 Manager
1062 object, but specific for this seat\&.
1063 .SH "USER OBJECTS"
1064 .sp
1065 .if n \{\
1066 .RS 4
1067 .\}
1068 .nf
1069 node /org/freedesktop/login1/user/_1000 {
1070 interface org\&.freedesktop\&.login1\&.User {
1071 methods:
1072 Terminate();
1073 Kill(in i signal_number);
1074 properties:
1075 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1076 readonly u UID = \&.\&.\&.;
1077 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1078 readonly u GID = \&.\&.\&.;
1079 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1080 readonly s Name = \*(Aq\&.\&.\&.\*(Aq;
1081 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1082 readonly t Timestamp = \&.\&.\&.;
1083 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1084 readonly t TimestampMonotonic = \&.\&.\&.;
1085 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1086 readonly s RuntimePath = \*(Aq\&.\&.\&.\*(Aq;
1087 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1088 readonly s Service = \*(Aq\&.\&.\&.\*(Aq;
1089 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1090 readonly s Slice = \*(Aq\&.\&.\&.\*(Aq;
1091 readonly (so) Display = \&.\&.\&.;
1092 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
1093 readonly s State = \*(Aq\&.\&.\&.\*(Aq;
1094 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
1095 readonly a(so) Sessions = [\&.\&.\&.];
1096 readonly b IdleHint = \&.\&.\&.;
1097 readonly t IdleSinceHint = \&.\&.\&.;
1098 readonly t IdleSinceHintMonotonic = \&.\&.\&.;
1099 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
1100 readonly b Linger = \&.\&.\&.;
1101 };
1102 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
1103 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
1104 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
1105 };
1106 .fi
1107 .if n \{\
1108 .RE
1109 .\}
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128 .SS "Methods"
1129 .PP
1130 \fBTerminate()\fR
1131 and
1132 \fBKill()\fR
1133 work similarly to the
1134 \fBTerminateUser()\fR
1135 and
1136 \fBKillUser()\fR
1137 methods on the manager object\&.
1138 .SS "Signals"
1139 .PP
1140 Whenever
1141 \fISessions\fR
1142 or the idle state changes,
1143 \fBPropertyChanged\fR
1144 signals are sent out to clients which have subscribed\&.
1145 .PP
1146 Signals are only emitted on objects referencing a specific UID, not on the
1147 "/org/freedesktop/login1/user/self"
1148 convenience object, as
1149 \fIself\fR
1150 can only be dereferenced relative to a method caller\&.
1151 .SS "Properties"
1152 .PP
1153 The
1154 \fIUID\fR
1155 and
1156 \fIGID\fR
1157 properties encode the Unix UID and primary GID of the user\&.
1158 .PP
1159 The
1160 \fIName\fR
1161 property encodes the user name\&.
1162 .PP
1163 \fITimestamp\fR
1164 and
1165 \fITimestampMonotonic\fR
1166 encode the login time of the user in microseconds since the epoch, in the
1167 \fBCLOCK_REALTIME\fR
1168 and
1169 \fBCLOCK_MONOTONIC\fR
1170 clocks, respectively\&.
1171 .PP
1172 \fIRuntimePath\fR
1173 encodes the runtime path of the user, i\&.e\&.
1174 \fI$XDG_RUNTIME_DIR\fR\&. For details see the
1175 \m[blue]\fBXDG Basedir Specification\fR\m[]\&\s-2\u[3]\d\s+2\&.
1176 .PP
1177 \fIService\fR
1178 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
1179 user@\&.service\&.
1180 .PP
1181 \fISlice\fR
1182 contains the unit name of the user systemd slice of this user\&. Each logged in user gets a private slice\&.
1183 .PP
1184 \fIDisplay\fR
1185 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\&.
1186 .PP
1187 \fIState\fR
1188 encodes the user state and is one of
1189 "offline",
1190 "lingering",
1191 "online",
1192 "active", or
1193 "closing"\&. See
1194 \fBsd_uid_get_state\fR(3)
1195 for more information about the states\&.
1196 .PP
1197 \fISessions\fR
1198 is an array of structures encoding all current sessions of the user\&. Each structure consists of the ID and object path\&.
1199 .PP
1200 The
1201 \fIIdleHint\fR,
1202 \fIIdleSinceHint\fR, and
1203 \fIIdleSinceHintMonotonic\fR
1204 properties encode the idle hint state of the user, similarly to the
1205 Manager\*(Aqs properties, but specific for this user\&.
1206 .PP
1207 The
1208 \fILinger\fR
1209 property shows whether lingering is enabled for this user\&.
1210 .SH "SESSION OBJECTS"
1211 .sp
1212 .if n \{\
1213 .RS 4
1214 .\}
1215 .nf
1216 node /org/freedesktop/login1/session/1 {
1217 interface org\&.freedesktop\&.login1\&.Session {
1218 methods:
1219 Terminate();
1220 Activate();
1221 Lock();
1222 Unlock();
1223 SetIdleHint(in b idle);
1224 SetLockedHint(in b locked);
1225 Kill(in s whom,
1226 in i signal_number);
1227 TakeControl(in b force);
1228 ReleaseControl();
1229 SetType(in s type);
1230 SetClass(in s class);
1231 SetDisplay(in s display);
1232 SetTTY(in h tty_fd);
1233 TakeDevice(in u major,
1234 in u minor,
1235 out h fd,
1236 out b inactive);
1237 ReleaseDevice(in u major,
1238 in u minor);
1239 PauseDeviceComplete(in u major,
1240 in u minor);
1241 SetBrightness(in s subsystem,
1242 in s name,
1243 in u brightness);
1244 signals:
1245 PauseDevice(u major,
1246 u minor,
1247 s type);
1248 ResumeDevice(u major,
1249 u minor,
1250 h fd);
1251 Lock();
1252 Unlock();
1253 properties:
1254 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1255 readonly s Id = \*(Aq\&.\&.\&.\*(Aq;
1256 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1257 readonly (uo) User = \&.\&.\&.;
1258 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1259 readonly s Name = \*(Aq\&.\&.\&.\*(Aq;
1260 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1261 readonly t Timestamp = \&.\&.\&.;
1262 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1263 readonly t TimestampMonotonic = \&.\&.\&.;
1264 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1265 readonly u VTNr = \&.\&.\&.;
1266 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1267 readonly (so) Seat = \&.\&.\&.;
1268 readonly s TTY = \*(Aq\&.\&.\&.\*(Aq;
1269 readonly s Display = \*(Aq\&.\&.\&.\*(Aq;
1270 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1271 readonly b Remote = \&.\&.\&.;
1272 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1273 readonly s RemoteHost = \*(Aq\&.\&.\&.\*(Aq;
1274 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1275 readonly s RemoteUser = \*(Aq\&.\&.\&.\*(Aq;
1276 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1277 readonly s Service = \*(Aq\&.\&.\&.\*(Aq;
1278 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1279 readonly s Desktop = \*(Aq\&.\&.\&.\*(Aq;
1280 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1281 readonly s Scope = \*(Aq\&.\&.\&.\*(Aq;
1282 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1283 readonly u Leader = \&.\&.\&.;
1284 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1285 readonly t LeaderPIDFDId = \&.\&.\&.;
1286 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1287 readonly u Audit = \&.\&.\&.;
1288 readonly s Type = \*(Aq\&.\&.\&.\*(Aq;
1289 readonly s Class = \*(Aq\&.\&.\&.\*(Aq;
1290 readonly b Active = \&.\&.\&.;
1291 readonly s State = \*(Aq\&.\&.\&.\*(Aq;
1292 readonly b IdleHint = \&.\&.\&.;
1293 readonly t IdleSinceHint = \&.\&.\&.;
1294 readonly t IdleSinceHintMonotonic = \&.\&.\&.;
1295 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1296 readonly b CanIdle = \&.\&.\&.;
1297 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
1298 readonly b CanLock = \&.\&.\&.;
1299 readonly b LockedHint = \&.\&.\&.;
1300 };
1301 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
1302 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
1303 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
1304 };
1305 .fi
1306 .if n \{\
1307 .RE
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
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359 .SS "Methods"
1360 .PP
1361 \fBTerminate()\fR,
1362 \fBActivate()\fR,
1363 \fBLock()\fR,
1364 \fBUnlock()\fR, and
1365 \fBKill()\fR
1366 work similarly to the respective calls on the
1367 Manager
1368 object\&.
1369 .PP
1370 \fBSetIdleHint()\fR
1371 is called by the session object to update the idle state of the session whenever it changes\&.
1372 .PP
1373 \fBTakeControl()\fR
1374 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
1375 \fIforce\fR
1376 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\&.
1377 .PP
1378 \fBReleaseControl()\fR
1379 drops control of a given session\&. Closing the D\-Bus connection implicitly releases control as well\&. See
1380 \fBTakeControl()\fR
1381 for more information\&. This method also releases all devices for which the controller requested ownership via
1382 \fBTakeDevice()\fR\&.
1383 .PP
1384 \fBSetType()\fR
1385 allows the type of the session to be changed dynamically\&. It can only be called by session\*(Aqs current controller\&. If
1386 \fBTakeControl()\fR
1387 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
1388 \fBReleaseControl()\fR
1389 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
1390 \fItype\fR
1391 is the new session type\&.
1392 .PP
1393 \fBSetClass()\fR
1394 allows the caller to change the class of the session dynamically\&. It may only be called by session\*(Aqs owning user\&. Currently, this call may be exclusively used to change the class from
1395 "user\-incomplete"
1396 to
1397 "user"\&. The call is synchronous, and will return only once the user\*(Aqs service manager has successfully been started, if necessary\&. The only argument
1398 \fItype\fR
1399 is the new session type\&.
1400 .PP
1401 \fBSetDisplay()\fR
1402 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
1403 \fBTakeControl()\fR
1404 has not been called, this method will fail\&. The only argument
1405 \fIdisplay\fR
1406 is the new display name\&.
1407 .PP
1408 \fBSetTTY()\fR
1409 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
1410 \fBTakeControl()\fR
1411 has not been called, this method will fail\&. The only argument
1412 \fItty_fd\fR
1413 is a file handle to the new tty device\&.
1414 .PP
1415 \fBTakeDevice()\fR
1416 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
1417 systemd\-logind
1418 will return a file descriptor for the device\&. Only a limited set of device\-types is currently supported (but may be extended)\&.
1419 systemd\-logind
1420 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\&.
1421 systemd\-logind
1422 only requires you to be the active session controller (see
1423 \fBTakeControl()\fR)\&. Also note that any device can only be requested once\&. As long as you do not release it, further
1424 \fBTakeDevice()\fR
1425 calls will fail\&.
1426 .PP
1427 \fBReleaseDevice()\fR
1428 releases a device again (see
1429 \fBTakeDevice()\fR)\&. This is also implicitly done by
1430 \fBReleaseControl()\fR
1431 or when closing the D\-Bus connection\&.
1432 .PP
1433 \fBPauseDeviceComplete()\fR
1434 allows a session controller to synchronously pause a device after receiving a
1435 \fBPauseDevice(\fR\fB"pause"\fR\fB)\fR
1436 signal\&. Forced signals (or after an internal timeout) are automatically completed by
1437 systemd\-logind
1438 asynchronously\&.
1439 .PP
1440 \fBSetLockedHint()\fR
1441 may be used to set the "locked hint" to
1442 \fIlocked\fR, i\&.e\&. information whether the session is locked\&. This is intended to be used by the desktop environment to tell
1443 \fBsystemd\-logind\fR
1444 when the session is locked and unlocked\&.
1445 .PP
1446 \fBSetBrightness()\fR
1447 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
1448 \fIsubsystem\fR
1449 parameter specifies a kernel subsystem, either
1450 "backlight"
1451 or
1452 "leds"\&. The
1453 \fIname\fR
1454 parameter specifies a device name under the specified subsystem\&. The
1455 \fIbrightness\fR
1456 parameter specifies the brightness\&. The range is defined by individual drivers, see
1457 /sys/class/\fIsubsystem\fR/\fIname\fR/max_brightness\&.
1458 .SS "Signals"
1459 .PP
1460 The active session controller exclusively gets
1461 \fBPauseDevice()\fR
1462 and
1463 \fBResumeDevice()\fR
1464 events for any device it requested via
1465 \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
1466 \fBPauseDevice()\fR
1467 signals are sent before the
1468 \fBPropertyChanged\fR
1469 signal for the
1470 \fBActive\fR
1471 state\&. The inverse is true for
1472 \fBResumeDevice()\fR\&. A device may remain paused for unknown reasons even though the
1473 Session
1474 is active\&.
1475 .PP
1476 A
1477 \fBPauseDevice()\fR
1478 signal carries the major and minor numbers and a string describing the type as arguments\&.
1479 \fBforce\fR
1480 means the device was already paused by
1481 systemd\-logind
1482 and the signal is only an asynchronous notification\&.
1483 \fBpause\fR
1484 means
1485 systemd\-logind
1486 grants you a limited amount of time to pause the device\&. You must respond to this via
1487 \fBPauseDeviceComplete()\fR\&. This synchronous pausing mechanism is used for backwards\-compatibility to VTs and
1488 systemd\-logind
1489 is free to not make use of it\&. It is also free to send a forced
1490 \fBPauseDevice()\fR
1491 if you do not respond in a timely manner (or for any other reason)\&.
1492 \fBgone\fR
1493 means the device was unplugged from the system and you will no longer get any notifications about it\&. There is no need to call
1494 \fBReleaseDevice()\fR\&. You may call
1495 \fBTakeDevice()\fR
1496 again if a new device is assigned the major+minor combination\&.
1497 .PP
1498 \fBResumeDevice()\fR
1499 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)\&.
1500 .PP
1501 Whenever
1502 \fBActive\fR
1503 or the idle state changes,
1504 \fBPropertyChanged\fR
1505 signals are sent out to clients which have subscribed\&.
1506 .PP
1507 \fBLock()\fR/\fBUnlock()\fR
1508 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
1509 \fBLock()\fR
1510 and
1511 \fBUnlock()\fR
1512 methods, respectively\&.
1513 .PP
1514 Signals are only emitted on objects referencing a specific session ID, not on the
1515 "/org/freedesktop/login1/session/self"
1516 or
1517 "/org/freedesktop/login1/session/auto"
1518 convenience objects, as they can only be dereferenced relative to a method caller\&.
1519 .SS "Properties"
1520 .PP
1521 \fIId\fR
1522 encodes the session ID\&.
1523 .PP
1524 \fIUser\fR
1525 encodes the user ID of the user this session belongs to\&. This is a structure consisting of the Unix UID and the object path\&.
1526 .PP
1527 \fIName\fR
1528 encodes the user name\&.
1529 .PP
1530 \fITimestamp\fR
1531 and
1532 \fITimestampMonotonic\fR
1533 encode the microseconds since the epoch when the session was created, in
1534 \fBCLOCK_REALTIME\fR
1535 or
1536 \fBCLOCK_MONOTONIC\fR, respectively\&.
1537 .PP
1538 \fIVTNr\fR
1539 encodes the virtual terminal number of the session if there is any, 0 otherwise\&.
1540 .PP
1541 \fISeat\fR
1542 encodes the seat this session belongs to if there is any\&. This is a structure consisting of the ID and the seat object path\&.
1543 .PP
1544 \fITTY\fR
1545 encodes the kernel TTY path of the session if this is a text login\&. If not this is an empty string\&.
1546 .PP
1547 \fIDisplay\fR
1548 encodes the X11 display name if this is a graphical login\&. If not, this is an empty string\&.
1549 .PP
1550 \fIRemote\fR
1551 encodes whether the session is local or remote\&.
1552 .PP
1553 \fIRemoteHost\fR
1554 and
1555 \fIRemoteUser\fR
1556 encode the remote host and user if this is a remote session, or an empty string otherwise\&.
1557 .PP
1558 \fIService\fR
1559 encodes the PAM service name that registered the session\&.
1560 .PP
1561 \fIDesktop\fR
1562 describes the desktop environment running in the session (if known)\&.
1563 .PP
1564 \fIScope\fR
1565 contains the systemd scope unit name of this session\&.
1566 .PP
1567 \fILeader\fR
1568 encodes the PID of the process that registered the session\&.
1569 .PP
1570 \fILeaderPIDFDId\fR
1571 encodes the Linux pidfd inode ID of the process that registered the session\&.
1572 .PP
1573 \fIAudit\fR
1574 encodes the Kernel Audit session ID of the session if auditing is available\&.
1575 .PP
1576 \fIType\fR
1577 encodes the session type\&. It\*(Aqs one of
1578 "unspecified"
1579 (for cron PAM sessions and suchlike),
1580 "tty"
1581 (for text logins),
1582 "web"
1583 (for web\-based logins), or
1584 "x11"/"mir"/"wayland"
1585 (for graphical logins)\&.
1586 .PP
1587 \fIClass\fR
1588 encodes the session class\&. It\*(Aqs one of
1589 "user"
1590 (for normal user sessions),
1591 "greeter"
1592 (for display manager pseudo\-sessions), or
1593 "lock\-screen"
1594 (for display lock screens)\&.
1595 .PP
1596 \fIActive\fR
1597 is a boolean that is true if the session is active, i\&.e\&. currently in the foreground\&. This field is semi\-redundant due to
1598 \fIState\fR\&.
1599 .PP
1600 \fIState\fR
1601 encodes the session state and one of
1602 "online",
1603 "active", or
1604 "closing"\&. See
1605 \fBsd_session_get_state\fR(3)
1606 for more information about the states\&.
1607 .PP
1608 \fIIdleHint\fR,
1609 \fIIdleSinceHint\fR, and
1610 \fIIdleSinceHintMonotonic\fR
1611 encapsulate the idle hint state of this session, similarly to how the respective properties on the manager object do it for the whole system\&.
1612 .PP
1613 \fILockedHint\fR
1614 shows the locked hint state of this session, as set by the
1615 \fBSetLockedHint()\fR
1616 method described above\&.
1617 .PP
1618 \fICanIdle\fR
1619 indicates whether the session supports the idle hint concept\&. Similarly,
1620 \fICanLock\fR
1621 indicates whether the session supports the screen lock concept\&.
1622 .SH "EXAMPLES"
1623 .PP
1624 \fBExample\ \&1.\ \&Introspect the logind manager on the bus\fR
1625 .sp
1626 .if n \{\
1627 .RS 4
1628 .\}
1629 .nf
1630 $ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.login1 \e
1631 \-\-object\-path /org/freedesktop/login1
1632 .fi
1633 .if n \{\
1634 .RE
1635 .\}
1636 .PP
1637 or
1638 .sp
1639 .if n \{\
1640 .RS 4
1641 .\}
1642 .nf
1643 $ busctl introspect org\&.freedesktop\&.login1 /org/freedesktop/login1
1644 .fi
1645 .if n \{\
1646 .RE
1647 .\}
1648 .PP
1649 \fBExample\ \&2.\ \&Introspect the default seat on the bus\fR
1650 .sp
1651 .if n \{\
1652 .RS 4
1653 .\}
1654 .nf
1655 $ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.login1 \e
1656 \-\-object\-path /org/freedesktop/login1/seat/seat0
1657 .fi
1658 .if n \{\
1659 .RE
1660 .\}
1661 .PP
1662 or
1663 .sp
1664 .if n \{\
1665 .RS 4
1666 .\}
1667 .nf
1668 $ busctl introspect org\&.freedesktop\&.login1 /org/freedesktop/login1/seat/seat0
1669 .fi
1670 .if n \{\
1671 .RE
1672 .\}
1673 .PP
1674 Seat
1675 "seat0"
1676 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
1677 \fBloginctl list\-sessions\fR\&.
1678 .PP
1679 \fBExample\ \&3.\ \&Introspect a single user on the bus\fR
1680 .sp
1681 .if n \{\
1682 .RS 4
1683 .\}
1684 .nf
1685 $ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.login1 \e
1686 \-\-object\-path /org/freedesktop/login1/user/_1000
1687 .fi
1688 .if n \{\
1689 .RE
1690 .\}
1691 .PP
1692 or
1693 .sp
1694 .if n \{\
1695 .RS 4
1696 .\}
1697 .nf
1698 $ busctl introspect org\&.freedesktop\&.login1 /org/freedesktop/login1/user/_1000
1699 .fi
1700 .if n \{\
1701 .RE
1702 .\}
1703 .PP
1704 \fBExample\ \&4.\ \&Introspect org\&.freedesktop\&.login1\&.Session on the bus\fR
1705 .sp
1706 .if n \{\
1707 .RS 4
1708 .\}
1709 .nf
1710 $ gdbus introspect \-\-system \-\-dest org\&.freedesktop\&.login1 \e
1711 \-\-object\-path /org/freedesktop/login1/session/45
1712 .fi
1713 .if n \{\
1714 .RE
1715 .\}
1716 .PP
1717 or
1718 .sp
1719 .if n \{\
1720 .RS 4
1721 .\}
1722 .nf
1723 $ busctl introspect org\&.freedesktop\&.login1 /org/freedesktop/login1/session/45
1724 .fi
1725 .if n \{\
1726 .RE
1727 .\}
1728 .SH "VERSIONING"
1729 .PP
1730 These D\-Bus interfaces follow
1731 \m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[4]\d\s+2\&.
1732 .SH "HISTORY"
1733 .SS "The Manager Object"
1734 .PP
1735 \fIHandlePowerKeyLongPress\fR,
1736 \fIHandleRebootKey\fR,
1737 \fIHandleRebootKeyLongPress\fR,
1738 \fIHandleSuspendKeyLongPress\fR, and
1739 \fIHandleHibernateKeyLongPress\fR
1740 were added in version 251\&.
1741 .PP
1742 \fIStopIdleSessionUSec\fR
1743 was added in version 252\&.
1744 .PP
1745 \fBPrepareForShutdownWithMetadata()\fR
1746 and
1747 \fBCreateSessionWithPIDFD()\fR
1748 were added in version 255\&.
1749 .PP
1750 \fBSleep()\fR,
1751 \fBCanSleep()\fR,
1752 \fISleepOperation\fR, and
1753 \fBListSessionsEx()\fR
1754 were added in version 256\&.
1755 .PP
1756 \fIHandleSecureAttentionKey\fR,
1757 \fBSecureAttentionKey()\fR,
1758 \fIPreparingForShutdownWithMetadata\fR,
1759 \fIDesignatedMaintenanceTime\fR,
1760 \fICanIdle\fR,
1761 \fICanLock\fR, and
1762 \fIBlockWeakInhibited\fR
1763 were added in version 257\&.
1764 .SS "Session Objects"
1765 .PP
1766 \fBSetDisplay()\fR
1767 was added in version 252\&.
1768 .PP
1769 \fBSetTTY()\fR
1770 was added in version 254\&.
1771 .PP
1772 \fBSetClass()\fR
1773 was added in version 256\&.
1774 .PP
1775 \fILeaderPIDFDId\fR
1776 was added in version 258\&.
1777 .SH "SEE ALSO"
1778 .PP
1779 \fBsystemd\fR(1), \fBsystemd-logind.service\fR(8), \fBloginctl\fR(1)
1780 .SH "NOTES"
1781 .IP " 1." 4
1782 polkit
1783 .RS 4
1784 \%https://www.freedesktop.org/software/polkit/docs/latest/
1785 .RE
1786 .IP " 2." 4
1787 Inhibitor Locks
1788 .RS 4
1789 \%https://systemd.io/INHIBITOR_LOCKS
1790 .RE
1791 .IP " 3." 4
1792 XDG Basedir Specification
1793 .RS 4
1794 \%https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
1795 .RE
1796 .IP " 4." 4
1797 the usual interface versioning guidelines
1798 .RS 4
1799 \%https://0pointer.de/blog/projects/versioning-dbus.html
1800 .RE