summaryrefslogtreecommitdiff
path: root/Software/systemd/logind.mdwn
blob: 578d8cb417b8886966394ebfd2ef1ceceb553300 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
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
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]]

# logind

systemd 30 and newer include systemd-logind. This is a tiny daemon that manages user logins and seats in various ways.

See [[systemd-logind(8).service|http://www.freedesktop.org/software/systemd/man/systemd-logind.service.html]] for more information. Please consult [[Multi-Seat on Linux|http://www.freedesktop.org/wiki/Software/systemd/multiseat]] for more information on the basic concepts.

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 or seat. The bus interface provides the same but in addition may also be used to make changes to system state. For more information please consult the man pages: [[sd-login(7)|http://www.freedesktop.org/software/systemd/man/sd-login.html]]

If you are interested in writing a display manager that makes use of logind, please have look at [[Writing Display Managers|http://www.freedesktop.org/wiki/Software/systemd/writing-display-managers]].  If you are interested in writing a desktop environment that makes use of logind, please have look at [[Writing Desktop Environments|http://www.freedesktop.org/wiki/Software/systemd/writing-desktop-environments]].

The inhibition logic is documented in [[Inhibitor Locks|http://www.freedesktop.org/wiki/Software/systemd/inhibit]].

## The Manager Object

The service exposes the following interfaces on the Manager object on the bus:

    $ gdbus introspect --system --dest org.freedesktop.login1 --object-path /org/freedesktop/login1
    node /org/freedesktop/login1 {
      interface org.freedesktop.login1.Manager {
        methods:
          GetSession(in  s arg_0,
                     out o arg_1);
          GetSessionByPID(in  u arg_0,
                          out o arg_1);
          GetUser(in  u arg_0,
                  out o arg_1);
          GetUserByPID(in  u arg_0,
                       out o arg_1);
          GetSeat(in  s arg_0,
                  out o arg_1);
          ListSessions(out a(susso) arg_0);
          ListUsers(out a(uso) arg_0);
          ListSeats(out a(so) arg_0);
          ListInhibitors(out a(ssssuu) arg_0);
          @org.freedesktop.systemd1.Privileged("true")
          CreateSession(in  u arg_0,
                        in  u arg_1,
                        in  s arg_2,
                        in  s arg_3,
                        in  s arg_4,
                        in  s arg_5,
                        in  u arg_6,
                        in  s arg_7,
                        in  s arg_8,
                        in  b arg_9,
                        in  s arg_10,
                        in  s arg_11,
                        in  a(sv) arg_12,
                        out s arg_13,
                        out o arg_14,
                        out s arg_15,
                        out h arg_16,
                        out u arg_17,
                        out s arg_18,
                        out u arg_19,
                        out b arg_20);
          @org.freedesktop.systemd1.Privileged("true")
          ReleaseSession(in  s arg_0);
          ActivateSession(in  s arg_0);
          ActivateSessionOnSeat(in  s arg_0,
                                in  s arg_1);
          @org.freedesktop.systemd1.Privileged("true")
          LockSession(in  s arg_0);
          @org.freedesktop.systemd1.Privileged("true")
          UnlockSession(in  s arg_0);
          @org.freedesktop.systemd1.Privileged("true")
          LockSessions();
          @org.freedesktop.systemd1.Privileged("true")
          UnlockSessions();
          @org.freedesktop.systemd1.Privileged("true")
          KillSession(in  s arg_0,
                      in  s arg_1,
                      in  i arg_2);
          @org.freedesktop.systemd1.Privileged("true")
          KillUser(in  u arg_0,
                   in  i arg_1);
          @org.freedesktop.systemd1.Privileged("true")
          TerminateSession(in  s arg_0);
          @org.freedesktop.systemd1.Privileged("true")
          TerminateUser(in  u arg_0);
          @org.freedesktop.systemd1.Privileged("true")
          TerminateSeat(in  s arg_0);
          SetUserLinger(in  u arg_0,
                        in  b arg_1,
                        in  b arg_2);
          AttachDevice(in  s arg_0,
                       in  s arg_1,
                       in  b arg_2);
          FlushDevices(in  b arg_0);
          PowerOff(in  b arg_0);
          Reboot(in  b arg_0);
          Suspend(in  b arg_0);
          Hibernate(in  b arg_0);
          HybridSleep(in  b arg_0);
          CanPowerOff(out s arg_0);
          CanReboot(out s arg_0);
          CanSuspend(out s arg_0);
          CanHibernate(out s arg_0);
          CanHybridSleep(out s arg_0);
          Inhibit(in  s arg_0,
                  in  s arg_1,
                  in  s arg_2,
                  in  s arg_3,
                  out h arg_4);
        signals:
          SessionNew(s arg_0,
                     o arg_1);
          SessionRemoved(s arg_0,
                         o arg_1);
          UserNew(u arg_0,
                  o arg_1);
          UserRemoved(u arg_0,
                      o arg_1);
          SeatNew(s arg_0,
                  o arg_1);
          SeatRemoved(s arg_0,
                      o arg_1);
          PrepareForShutdown(b arg_0);
          PrepareForSleep(b arg_0);
        properties:
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly u NAutoVTs = 6;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly as KillOnlyUsers = [];
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly as KillExcludeUsers = ['root'];
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly b KillUserProcesses = false;
          readonly b IdleHint = false;
          readonly t IdleSinceHint = 0;
          readonly t IdleSinceHintMonotonic = 0;
          readonly s BlockInhibited = 'handle-power-key:handle-suspend-key:handle-hibernate-key';
          readonly s DelayInhibited = 'sleep';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly t InhibitDelayMaxUSec = 5000000;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s HandlePowerKey = 'poweroff';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s HandleSuspendKey = 'suspend';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s HandleHibernateKey = 'hibernate';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s HandleLidSwitch = 'suspend';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s IdleAction = 'ignore';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly t IdleActionUSec = 1800000000;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
          readonly b PreparingForShutdown = false;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
          readonly b PreparingForSleep = false;
      };
      interface org.freedesktop.DBus.Peer {
        ...
      };
      interface org.freedesktop.DBus.Introspectable {
        ...
      };
      interface org.freedesktop.DBus.Properties {
        ...      
      };
    };

### Security

A number of operations are protected via the PolicyKit privilege system. SetUserLinger() requires the _org.freedesktop.login1.set-user-linger_ privilege. AttachDevice() requires _org.freedesktop.login1.attach-device_ and FlushDevices() _org.freedesktop.login1.flush-devices_. PowerOff(), Reboot(), Suspend(), Hibernate(), HybridSleep() require _org.freedesktop.login1.power-off_, _org.freedesktop.login1.power-off-multiple-sessions_, _org.freedesktop.login1.power-off-ignore-inhibit_, _org.freedesktop.login1.reboot_, _org.freedesktop.login1.reboot-multiple-sessions_, _org.freedesktop.login1.reboot-ignore-inhibit_, _org.freedesktop.login1.suspend_, _org.freedesktop.login1.suspend-multiple-sessions_, _org.freedesktop.login1.suspend-ignore-inhibit_, _org.freedesktop.login1.hibernate_, _org.freedesktop.login1.hibernate-multiple-sessions_ resp. _org.freedesktop.login1.hibernate-ignore-inhibit_, depending whether there are other sessions around or active inhibits. Inhibit() is protected via either one of _org.freedesktop.login1.inhibit-block-shutdown_, _org.freedesktop.login1.inhibit-delay-shutdown_,  _org.freedesktop.login1.inhibit-block-sleep_, _org.freedesktop.login1.inhibit-delay-sleep_, _org.freedesktop.login1.inhibit-block-idle_, _org.freedesktop.login1.inhibit-handle-power-key_, _org.freedesktop.login1.inhibit-handle-suspend-key_, _org.freedesktop.login1.inhibit-handle-hibernate-key_, _org.freedesktop.login1.inhibit-handle-lid-switch_ depending on the lock type and mode taken.

The user_interaction boolean parameters can be used to control whether PolicyKit should interactively ask the user for authentication credentials if it needs to.

### Methods

**GetSession()** may be used to get the session object path for the session with the specified ID. Similar, **GetUser()** and **GetSeat()** get the user resp. seat objects. **GetSessionByPID()** and **GetUserByPID()** get the session/user object the specified PID belongs to if there is any.

**ListSessions()** returns an array with all current sessions. The structures in the array consist of the following fields: session id, user id, user name, seat id, session object path. If a session does not have a seat attached the seat id field will be an empty string.

**ListUsers()** returns an array with all currently logged in users. The structures in the array consist of the following fields: user id, user name, user object path.

**ListSeats()** returns an array with all currently available seats. The structure in the array consists of the following fields: seat id, seat object path.

**CreateSession()** and **ReleaseSession()** may be used to open or close login sessions. These calls should _never_ be invoked directly by clients. Creating/closing sessions is exclusively the job of PAM and its pam_systemd module.

**ActivateSession()** brings the session with the specified ID into the foreground. **ActivateSessionOnSeat()** does the same, but only if the seat id matches.

**LockSession()** asks the session with the specified ID to activate the screen lock. **UnlockSession()** 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.

**LockSessions()** asks all sessions to activate the screen locks. This may be used to lock any access to the machine in one action. Similar, **UnlockSessions()** asks all sessions to deactivate their screen locks.

**KillSession()** 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 "leader" or "all" and a signal number. If "leader" is passed only the session "leader" is killed. If "all" is passed all processes of the session are killed.

**KillUser()** may be used to send a Unix signal to all processes of a user. As argument it takes the user id and a signal number.

**TerminateSession()**, **TerminateUser()**, **TerminateSeat()** may be used to forcibly terminate one specific session, all processes of a user, resp. all sessions attached to a specific seat. The session, user, seat is identified by their respective IDs.

**SetUserLinger()** enables or disables user lingering. If enabled the runtime directory of a user is kept around and he may continue to run processes while he is logged out. If disabled the runtime directory goes away as soon as he logs out. Expects three arguments: the UID, a boolean whether to enable/disable and a boolean controlling the PolicyKit authorization interactivity (see above). Note that the user linger state is persistently stored on disk.

**AttachDevice()** may be used to assign a specific device to a specific seat. The device is identified by its /sys path, and must be eligible for seat assignments. Takes three arguments: the seat id, the sysfs path, and a boolean for controlling PolicyKit interactivity (see above). Device assignments are persistently stored to disk. To create a new seat, simply specify a previously unused seat id. For more information about the seat assignment logic see [[Multi-Seat for Linux|http://www.freedesktop.org/wiki/Software/systemd/multiseat]].

**FlushDevices()** removes all explicit seat assignments for devices, resetting all assignments to the automatic defaults. The only argument this takes is the PolicyKit interactivity boolean (see above).

**PowerOff()**, **Reboot()**, **Suspend()**, **Hibernate()**, **HybridSleep()** results in the system being powered off, rebooted, suspend, hibernated or hibernated+suspended. The only argument is the PolicyKit interactivity boolean (see above). The main purpose of these calls is that they enforce [[PolicyKit|PolicyKit]] policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged users. They also enforce inhibition locks. UIs should expose these calls as primary mechanism to poweroff/reboot/suspend/hibernate/hybrid-sleep the machine.

**CanPowerOff()**, **CanReboot()**, **CanSuspend()**, **CanHibernate()**, **CanHybridSleep()** tests whether the system supports the respective operation and whether the calling user is eligible for the desired operation. Returns one of "na", "yes", "no" or "challenge". If "na" is returned the operation is not available because hardware, kernel or drivers do not support it. If "yes" is returned the operation is supported and the user may execute the operation without further authentication. If "no" is returned the operation is available but the user is not allowed to execute the operation. If "challenge" is returned the operation is available, but only after authorization.

**Inhibit()** creates an inhibition lock. It takes four parameters: What, Who, Why and Mode. "What" is one or more of "shutdown", "sleep", "idle", "handle-power-key", "handle-suspend-key", "handle-hibernate-key", "handle-lid-switch", separated by colons, for inhibiting poweroff/reboot, suspend/hibernate, the automatic idle logic, or hardware key handling. "Who" should be a short human readable string identifying the application taking the lock. "Why" should be a short human readable string identifying the reason why the lock is taken. Finally, "Mode" is either "block" or "delay" which encodes whether the inhibit shall be consider mandatory or whether it should just delay the operation to a certain maximum time. The call 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 [[Inhibitor Locks|http://www.freedesktop.org/wiki/Software/systemd/inhibit]].

**ListInhibitors()** lists all currently active inhibitors. Returns an array of structures consisting of what, who, why, mode, user ID and process ID.

### Signals

Whenever the inhibition state or idle hint changes daemon **PropertyChanged** signals are sent out to which clients can subscribe.

The **SessionNew()**, **SessionRemoved()**, **UserNew()**, **UserRemoved()**, **SeatNew()**, **SeatRemoved()** 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.

The **PrepareForShutdown()** resp. **PrepareForSleep()** signals are sent right before (with the argument True) and after (with the argument False) the system goes down for reboot/poweroff, resp. suspend/hibernate. This may be used by applications for saving data on disk, releasing memory or doing other jobs that shall 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 not to delay the operation any further. For more information see [[Inhibitor Locks|http://www.freedesktop.org/wiki/Software/systemd/inhibit]].

### Properties

Most properties simply reflect the configuration stored in logind.conf. For more information, see: [[logind.conf(5)|http://www.freedesktop.org/software/systemd/man/logind.conf.html]]

The **IdleHint** property reflects the idle hint state of the system. If the system is idle it might get into automatic suspend or shutdown, depending on configuration.

**IdleSinceHint** and **IdleSinceHintMonotonic** encode the timestamps of the last change of the idle hint boolean, in CLOCK_REALTIME resp. CLOCK_MONOTONIC timestamps in usec since the epoch.

The **BlockInhibited** and **DelayInhibited** properties encode the currently active locks of the respective modes. They are colon separated lists of "shutdown", "sleep", "idle" (see above).

The **PreparingForShutdown** and **PreparingForSleep** boolean properties are true between the two PrepareForShutdown resp. PrepareForSleep signals are sent. Note that these properties do not send out PropertyChanged signals.

## Seat Objects

    $ gdbus introspect --system --dest org.freedesktop.login1 --object-path /org/freedesktop/login1/seat/seat0
    node /org/freedesktop/login1/seat/seat0 {
      interface org.freedesktop.login1.Seat {
        methods:
          @org.freedesktop.systemd1.Privileged("true")
          Terminate();
          ActivateSession(in  s arg_0);
        signals:
        properties:
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s Id = 'seat0';
          readonly (so) ActiveSession = ('', '/');
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly b CanMultiSession = true;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly b CanTTY = true;
          readonly b CanGraphical = true;
          readonly a(so) Sessions = [('c1', '/org/freedesktop/login1/session/c1')];
          readonly b IdleHint = true;
          readonly t IdleSinceHint = 1389368976087311;
          readonly t IdleSinceHintMonotonic = 48213948;
      };
      interface org.freedesktop.DBus.Properties {
        ...
      };
      interface org.freedesktop.DBus.Peer {
        ...
      };
      interface org.freedesktop.DBus.Introspectable {
        ...
      };
    };

### Methods

**Terminate()** and **ActivateSession()** work similar to TerminateSeat(), ActivationSessionOnSeat() on the Manager object.

### Signals

Whenever **ActiveSession**, **Sessions**, **CanGraphical**, **CanMultiSession** and **CanTTY** or the idle state changes **PropertyChanged** signals are sent out to which clients can subscribe.

### Properties

The **Id** property encodes the ID of the seat.

**ActiveSession** encodes the currently active session if there is one. It is a structure consisting of session id and object path.

**CanMultiSession** encodes whether the session is multi-session capable, CanTTY whether it is suitable for text logins, CanGraphical whether it is suitable for graphical sessions.

The **Sessions** array is an array of all current sessions of this seat, each encoded in a structure consisting of the ID and the object path.

The **IdleHint**, **IdleSinceHint**, **IdleSinceHint** properties encode the idle state, similar to the one exposed on the Manager object, but specific for this seat.

## User Objects

    $ gdbus introspect --system --dest org.freedesktop.login1 --object-path /org/freedesktop/login1/user/_1000
    node /org/freedesktop/login1/user/_1000 {
      interface org.freedesktop.login1.User {
        methods:
          @org.freedesktop.systemd1.Privileged("true")
          Terminate();
          @org.freedesktop.systemd1.Privileged("true")
          Kill(in  i arg_0);
        signals:
        properties:
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly u UID = 1000;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly u GID = 1000;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s Name = 'test';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly t Timestamp = 1389368964102424;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly t TimestampMonotonic = 36229061;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s RuntimePath = '/run/user/1000';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s Service = 'user@1000.service';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s Slice = 'user-1000.slice';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly (so) Display = ('', '/');
          @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
          readonly s State = 'active';
          readonly a(so) Sessions = [('28', '/org/freedesktop/login1/session/_328'), ('3', '/org/freedesktop/login1/session/_33')];
          readonly b IdleHint = false;
          readonly t IdleSinceHint = 0;
          readonly t IdleSinceHintMonotonic = 0;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
          readonly b Linger = false;
      };
      interface org.freedesktop.DBus.Properties {
        ...
      };
      interface org.freedesktop.DBus.Peer {
        ...
      };
      interface org.freedesktop.DBus.Introspectable {
        ...
      };
    };

### Methods

**Terminate()** and **Kill()** work similar to the TerminateUser() resp. KillUser() calls on the manager object.

### Signals

Whenever **Sessions** or the idle state changes **PropertyChanged** signals are sent out to which clients can subscribe.

### Properties

The **UID** and **GID** properties encode the Unix UID and primary GID of the user.

The **Name** property encodes the user name.

**Timestamp** and **TimestampMonotonic** encode the login time of the user in usec since the epoch, in the CLOCK_REALTIME resp. CLOCK_MONOTONIC clocks.

**RuntimePath** encodes the runtime path of the user, i.e. $XDG_RUNTIME_DIR, for details see the [[XDG Basedir Specification|http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html]].

**Service** contains the name of the user systemd service unit name of this user. Each logged in user gets a user service unit assigned that runs a user systemd instance. This is usually an instance of user@.service.

**Slice** contains the name of the user systemd slice unit name of this user. Each logged in user gets a private slice.

**Display** encodes which graphical session should be used as primary UI display for the use. It is a structure encoding session ID and object path of the session to use.

**State** encodes the user state, one of "offline", "lingering", "online", "active", "closing". See [[sd_uid_get_state(3)|http://www.freedesktop.org/software/systemd/man/sd_uid_get_state.html]] for more information about the states.

**Sessions** is an array of structures encoding all current sessions of the user. Each structure consists of ID and object path.

The **IdleHint**, **IdleSinceHint**, **IdleSinceHintMonotonic** properties encode the idle hint state of the user, similar to the Manager's properties, but specific for this user.

## Session Objects

    $ gdbus introspect --system --dest org.freedesktop.login1 --object-path /org/freedesktop/login1/session/3
    node /org/freedesktop/login1/session/3 {
      interface org.freedesktop.login1.Session {
        methods:
          @org.freedesktop.systemd1.Privileged("true")
          Terminate();
          Activate();
          @org.freedesktop.systemd1.Privileged("true")
          Lock();
          @org.freedesktop.systemd1.Privileged("true")
          Unlock();
          SetIdleHint(in  b arg_0);
          @org.freedesktop.systemd1.Privileged("true")
          Kill(in  s arg_0,
               in  i arg_1);
          TakeControl(in  b arg_0);
          ReleaseControl();
          TakeDevice(in  u arg_0,
                     in  u arg_1,
                     out h arg_2,
                     out b arg_3);
          ReleaseDevice(in  u arg_0,
                        in  u arg_1);
          PauseDeviceComplete(in  u arg_0,
                              in  u arg_1);
        signals:
          PauseDevice(u arg_0,
                      u arg_1,
                      s arg_2);
          ResumeDevice(u arg_0,
                       u arg_1,
                       h arg_2);
          Lock();
          Unlock();
        properties:
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s Id = '3';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly (uo) User = (1000, '/org/freedesktop/login1/user/_1000');
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s Name = 'test';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly t Timestamp = 1389370644734067;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly t TimestampMonotonic = 72063381;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly u VTNr = 0;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly (so) Seat = ('', '/');
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s TTY = '';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s Display = '';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly b Remote = true;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s RemoteHost = '129.174.150.217';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s RemoteUser = '';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s Service = 'sshd';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s Scope = 'session-3.scope';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly u Leader = 1854;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly u Audit = 3;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s Type = 'tty';
          @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
          readonly s Class = 'user';
          readonly b Active = true;
          @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
          readonly s State = 'active';
          readonly b IdleHint = false;
          readonly t IdleSinceHint = 0;
          readonly t IdleSinceHintMonotonic = 0;
      };
      interface org.freedesktop.DBus.Properties {
        ...
      };
      interface org.freedesktop.DBus.Peer {
        ...
      };
      interface org.freedesktop.DBus.Introspectable {
        ...
      };
    };

### Methods

**Terminate()**, **Activate()**, **Lock()**, **Unlock()**, **Kill()** work similar to the respective calls on the Manager object.

**SetIdleHint()** shall be called by the session object to update the idle state of the session, whenever it changes.

**TakeControl()** allows a process to take exclusive managed device access-control for that session. Only one dbus-connection can be a controller for a given session at a time. If the **force** argument is set (root only), an existing controller is kicked out and replaced. Otherwise, this call fails if there is already a controller.
Note that this call is limited to dbus-users with the effective UID set to the User of the Session or root.

**ReleaseControl()** drops control of a given session again. Closing the dbus-connection implicitly releases control, too. See **TakeControl()** for more. This also releases all devices for the controller that were requested via **TakeDevice()**.

**TakeDevice()** 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 logind will return a file-descriptor for the device. Only a limited set of device-types is currently supported (but may be extended). logind automatically mutes the file-descriptor if the session is inactive and resumes it once the session gets active 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. logind only requires you to be the active session controller (see **TakeControl()**). Also note that any device can only be requested once. As long as you don't release it, further **TakeDevice()** calls will fail.

**ReleaseDevice()** releases a device again (see **TakeDevice()**). This is also implicitly done by **ReleaseControl()** or when closing the dbus-connection.

**PauseDeviceComplete()** allows a session-controller to synchronously pause a device after receiving a **PauseDevice("pause")** signal. Forced signals (or after an internal timeout) are automatically completed by logind asynchronously.

### Signals

The active session-controller exclusively gets **PauseDevice** and **ResumeDevice** events for any device it requested via **TakeDevice()**. They notify the controller whenever a device is paused or resumed. A device is never resumed if a session is inactive. Also note that **PauseDevice** signals are sent before the **PropertyChanged** signal for the **Active** state. The inverse is true for **ResumeDevice**. A device may remain paused for unknown reasons even though the Session is active.
A **PauseDevice** signal carries the major/minor as arguments and a string describing the type. **force** means the device got paused by logind already and this is only an asynchronous notification. **pause** means logind tries to pause the device and grants you limited amount of time to pause it. You must respond to this via **PauseDeviceComplete()**. This synchronous pausing-mechanism is used for backwards-compatibility to VTs and logind is free to not make use of it. It is also free to send a forced **PauseDevice** if you don't respond in a timely manner (or for any other reason). **gone** means the device was unplugged from the system and you will no longer get any notifications about it. There is no reason to call **ReleaseDevice()**. You may call **TakeDevice()** again if a new device gets the major+minor combination assigned.
**ResumeDevice** is sent whenever a session is active and a device is resumed. It carries the major/minor 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).

Whenever **Active** or the idle state changes **PropertyChanged** signals are sent out to which clients can subscribe.

**Lock** (resp. **Unlock**) is sent when the session is asked to be screen-locked/screen-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 **Lock()** resp. **Unlock()** methods.

### Properties

**Id** encodes the session ID.

**User** encodes the user ID of the user this session belongs to. This is a structure encoding the Unix UID and the object path.

**Name** encodes the user name.

**Timestamp** and **TimestampMonotonic** encode the usec timestamp since the epoch when the session was created, in CLOCK_REALTIME resp. CLOCK_MONOTONIC.

**VTNr** encodes the virtual terminal number of the session if there is any, 0 otherwise.

**Seat** encodes the seat this session belongs to, if there is any. This is a structure consisting of the ID and the seat object path.

**TTY** encodes the kernel TTY path of the session if this is a text login. If not this is an empty string.

**Display** encodes the X11 display name if this is a graphical login. If not this is an empty string.

**Remote** encodes whether the session is local or remote.

**RemoteHost** and **RemoteUser** encode the remote host and user if this is a remote session, or an empty string otherwise.

**Service** encodes the PAM service name that registered the session.

**Scope** contains the systemd scope unit name of this session.

**Leader** encodes the PID of the process that registered the session.

**Audit** encodes the Kernel Audit session ID of the session, if auditing is available.

**Type** encodes the session type. It's one of "unspecified" (for cron PAM sessions and suchlike), "tty" (for text logins) or "x11" (for graphical logins).

**Class** encodes the session class. It's one of "user" (for normal user sessions), "greeter" (for display manager pseudo-sessions), "lock-screen" (for display lock screens).

**Active** is a boolean that is true if the session is active, i.e. currently in the foreground. This field is semi-redundant due to State.

**State** encodes the session state and one of "online", "active", "closing". See [[sd_session_get_state(3)|http://www.freedesktop.org/software/systemd/man/sd_session_is_active.html]] for more information about the states.

**IdleHint**, **IdleSinceHint**, **IdleSinceHintMonotonic** encapsulate the idle hint state of this session, similar to how the respective properties on the manager object do it for the whole system.

---

These D-Bus interfaces follow [[the usual interface versioning guidelines|http://0pointer.de/blog/projects/versioning-dbus.html]].