1ORG.FREEDESKTOP.HOME1(5)     org.freedesktop.home1    ORG.FREEDESKTOP.HOME1(5)
2
3
4

NAME

6       org.freedesktop.home1 - The D-Bus interface of systemd-homed
7

INTRODUCTION

9       systemd-homed.service(8) is a system service which may be used to
10       create, remove, change or inspect home areas. This page describes the
11       D-Bus interface.
12

THE MANAGER OBJECT

14       The service exposes the following interfaces on the Manager object on
15       the bus:
16
17           node /org/freedesktop/home1 {
18             interface org.freedesktop.home1.Manager {
19               methods:
20                 GetHomeByName(in  s user_name,
21                               out u uid,
22                               out s home_state,
23                               out u gid,
24                               out s real_name,
25                               out s home_directory,
26                               out s shell,
27                               out o bus_path);
28                 GetHomeByUID(in  u uid,
29                              out s user_name,
30                              out s home_state,
31                              out u gid,
32                              out s real_name,
33                              out s home_directory,
34                              out s shell,
35                              out o bus_path);
36                 GetUserRecordByName(in  s user_name,
37                                     out s user_record,
38                                     out b incomplete,
39                                     out o bus_path);
40                 GetUserRecordByUID(in  u uid,
41                                    out s user_record,
42                                    out b incomplete,
43                                    out o bus_path);
44                 ListHomes(out a(susussso) home_areas);
45                 @org.freedesktop.systemd1.Privileged("true")
46                 ActivateHome(in  s user_name,
47                              in  s secret);
48                 @org.freedesktop.systemd1.Privileged("true")
49                 DeactivateHome(in  s user_name);
50                 RegisterHome(in  s user_record);
51                 UnregisterHome(in  s user_name);
52                 CreateHome(in  s user_record);
53                 RealizeHome(in  s user_name,
54                             in  s secret);
55                 RemoveHome(in  s user_name);
56                 @org.freedesktop.systemd1.Privileged("true")
57                 FixateHome(in  s user_name,
58                            in  s secret);
59                 AuthenticateHome(in  s user_name,
60                                  in  s secret);
61                 UpdateHome(in  s user_record);
62                 ResizeHome(in  s user_name,
63                            in  t size,
64                            in  s secret);
65                 ChangePasswordHome(in  s user_name,
66                                    in  s new_secret,
67                                    in  s old_secret);
68                 @org.freedesktop.systemd1.Privileged("true")
69                 LockHome(in  s user_name);
70                 @org.freedesktop.systemd1.Privileged("true")
71                 UnlockHome(in  s user_name,
72                            in  s secret);
73                 AcquireHome(in  s user_name,
74                             in  s secret,
75                             in  b please_suspend,
76                             out h send_fd);
77                 @org.freedesktop.systemd1.Privileged("true")
78                 RefHome(in  s user_name,
79                         in  b please_suspend,
80                         out h send_fd);
81                 @org.freedesktop.systemd1.Privileged("true")
82                 ReleaseHome(in  s user_name);
83                 @org.freedesktop.systemd1.Privileged("true")
84                 LockAllHomes();
85                 @org.freedesktop.systemd1.Privileged("true")
86                 DeactivateAllHomes();
87                 @org.freedesktop.systemd1.Privileged("true")
88                 Rebalance();
89               properties:
90                 readonly a(sso) AutoLogin = [...];
91             };
92             interface org.freedesktop.DBus.Peer { ... };
93             interface org.freedesktop.DBus.Introspectable { ... };
94             interface org.freedesktop.DBus.Properties { ... };
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   Methods
126       GetHomeByName() returns basic user information (a minimal subset of the
127       full user record), provided a user name. The information supplied more
128       or less matches what getpwnam(3) returns: the numeric UID and GID, the
129       real name, home directory and shell. In addition it returns a state
130       identifier describing the state the user's home directory is in, as
131       well as a bus path referring to the bus object encapsulating the user
132       record and home directory. This object implements the
133       org.freedesktop.home1.Home interface documented below.
134
135       GetHomeByUID() is similar to GetHomeByName() but acquires the
136       information based on the numeric UID of the user.
137
138       GetUserRecordByName() is also similar to GetHomeByName() but returns
139       the full JSON user record data instead of the broken down records. An
140       additional returned boolean indicates whether the record is complete or
141       not. A record is considered complete when its "privileged" section is
142       included, and incomplete if it was removed (see JSON User Records[1]
143       for details about the various sections of a user record). Generally,
144       only privileged clients and clients running under the identity of the
145       user itself get access to the "privileged" section and will thus see
146       complete records.
147
148       GetUserRecordByUID() is similar to GetUserRecordByName() but returns
149       the user record matching the specified numeric UID.
150
151       ListHomes() returns an array of all locally managed users. The array
152       contains the same fields GetHomeByName() returns: user name, numeric
153       UID, state, numeric GID, real name, home directory, shell and bus path
154       of the matching bus object.
155
156       ActivateHome() activates (i.e. mounts) the home directory of the
157       specified user. The second argument shall contain a user record
158       consisting only of a "secret" section (all other sections should be
159       stripped, see JSON User Records[1] for details), and should contain
160       only the secret credentials necessary for unlocking the home directory.
161       Typically a client would invoke this function first with an entirely
162       empty record (which is possibly sufficient if single-factor
163       authentication with a plugged-in security token is configured), and
164       would then retry with a record populated with more information,
165       depending on the returned error code, in case more credentials are
166       necessary. This function is synchronous and returns only after the home
167       directory was fully activated (or the operation failed), which might
168       take some time. Clients must be prepared for that, and typically should
169       extend the D-Bus method call timeout accordingly. This method is
170       equivalent to the Activate() method on the org.freedesktop.home1.Home
171       interface documented below, but may be called on the manager object and
172       takes a user name as additional argument, instead.
173
174       DeactivateHome() deactivates (i.e. unmounts) the home directory of the
175       specified user. It is equivalent to the Deactivate() method on the
176       org.freedesktop.home1.Home interface documented below.
177
178       RegisterHome() registers a new home directory locally. It receives the
179       JSON user record as only argument (which typically excludes the
180       "secret" section). Registering a home directory just makes the user
181       record known to the system, it does not create a home directory or such
182       (which is expected to exist already, or created later). This operation
183       is useful to register home directories locally that are not located
184       where systemd-homed.service would find them automatically.
185
186       UnregisterHome() unregisters an existing home directory. It takes a
187       user name as argument and undoes what RegisterHome() does. It does not
188       attempt to remove the home directory itself, it just unregisters it
189       with the local system. Note that if the home directory is placed where
190       systemd-homed.service looks for home directories anyway this call will
191       only undo fixation (see below), but the record will remain known to
192       systemd-homed.service and be listed among known records. Since the user
193       record is embedded into the home directory this operation generally
194       does not discard data belonging to the user or their record. This
195       method is equivalent to Unregister() on the org.freedesktop.home1.Home
196       interface.
197
198       CreateHome() registers and creates a new home directory. This takes a
199       fully specified JSON user record as argument (including the "secret"
200       section). This registers the user record locally and creates a home
201       directory matching it, depending on the settings specified in the
202       record in combination with local configuration.
203
204       RealizeHome() creates a home directory whose user record is already
205       registered locally. This takes a user name plus a user record
206       consisting only of the "secret" section. Invoking RegisterHome()
207       followed by RealizeHome() is mostly equivalent to calling CreateHome(),
208       except that the latter combines the two in atomic fashion. This method
209       is equivalent to Realize() on the org.freedesktop.home1.Home interface.
210
211       RemoveHome() unregisters a user record locally, and removes the home
212       directory belonging to it, if it is accessible. It takes a user name as
213       argument. This method is equivalent to Remove() on the
214       org.freedesktop.home1.Home interface.
215
216       FixateHome() "fixates" an automatically discovered home directory.
217       systemd-homed.service automatically discovers home directories dropped
218       in our plugged in and adds them to the runtime list of user records it
219       manages. A user record discovered that way may be "fixated", in which
220       case it is copied out of the home directory, onto persistent storage,
221       to fixate the UID/GID assignment of the record, and extract additional
222       (typically previously encrypted) user record data from the home
223       directory. A home directory mus be fixated before it can be logged
224       into. This method call takes a user name and a JSON user record
225       consisting only of the "secret" section as argument. This method is
226       equivalent to Fixate() on the org.freedesktop.home1.Home interface.
227
228       AuthenticateHome() checks passwords or other authentication credentials
229       associated with the home directory. It takes a user name and a JSON
230       user record consisting only of the "secret" section as argument. Note
231       that many of the other method calls authenticate the user first, in
232       order to execute some other operation. This method call only
233       authenticates and executes no further operation. Like ActivateHome() it
234       is usually first invoked with an empty JSON user record, which is then
235       populated for subsequent tries with additional authentication data
236       supplied. This method is equivalent to Authenticate() on the
237       org.freedesktop.home1.Home interface.
238
239       UpdateHome() updates a locally registered user record. Takes a fully
240       specified JSON user record as argument (including the "secret"
241       section). A user with a matching name and realm must be registered
242       locally already, and the last change timestamp of the newly supplied
243       record must be newer than the previously existing user record. Note
244       this operation updates the user record only, it does not propagate
245       passwords/authentication tokens from the user record to the storage
246       back-end, or resizes the storage back-end. Typically a home directory
247       is first updated, and then the password of the underlying storage
248       updated using ChangePasswordHome() as well as the storage resized using
249       ResizeHome(). This method is equivalent to Update() on the
250       org.freedesktop.home1.Home interface.
251
252       ResizeHome() resizes the storage associated with a user record. Takes a
253       user name, a disk size in bytes and a user record consisting only of
254       the "secret" section as argument. If the size is specified as
255       UINT64_MAX the storage is resized to the size already specified in the
256       user record. Typically, if the user record is updated using
257       UpdateHome() above this is used to propagate the size configured
258       there-in down to the underlying storage back-end. This method is
259       equivalent to Resize() on the org.freedesktop.home1.Home interface.
260
261       ChangePasswordHome() changes the passwords/authentication tokens of a
262       home directory. Takes a user name, and two JSON user record objects,
263       each consisting only of the "secret" section, for the old and for the
264       new passwords/authentication tokens. If the user record with the new
265       passwords/authentication token data is specified as empty the existing
266       user record's settings are propagated down to the home directory
267       storage. This is typically used after a user record is updated using
268       UpdateHome() in order to propagate the secrets/authentication tokens
269       down to the storage. This method is equivalent to ChangePassword() on
270       the org.freedesktop.home1.Home interface.
271
272       LockHome() temporarily suspends access to a home directory, flushing
273       out any cryptographic keys from memory. This is only supported on some
274       back-ends, and usually done during system suspend, in order to
275       effectively secure home directories while the system is sleeping. Takes
276       a user name as single argument. If an application attempts to access a
277       home directory while it is locked it will typically freeze until the
278       home directory is unlocked again. This method is equivalent to Lock()
279       on the org.freedesktop.home1.Home interface.
280
281       UnlockHome() undoes the effect of LockHome(). Takes a user name and a
282       user record consisting only of the "secret" section as arguments. This
283       method is equivalent to Unlock() on the org.freedesktop.home1.Home
284       interface.
285
286       AcquireHome() activates or unlocks a home directory in a reference
287       counted mode of operation. Takes a user name and user record consisting
288       only of "secret" section as argument. If the home directory is not
289       active yet, it is activated. If it is currently locked it is unlocked.
290       After completion a reference to the activation/unlocking of the home
291       directory is returned via a file descriptor. When the last client which
292       acquired such a file descriptor closes it the home directory is
293       automatically deactivated again. This method is typically invoked when
294       a user logs in, and the file descriptor is held until the user logs out
295       again, thus ensuring the user's home directory can be unmounted
296       automatically again in a robust fashion, when the user logs out. The
297       third argument is a boolean which indicates whether the client invoking
298       the call is able to automatically re-authenticate when the system comes
299       back from suspending. It should be set by all clients that implement a
300       secure lock screen running outside of the user's context, that is
301       brought up when the system comes back from suspend and can be used to
302       re-acquire the credentials to unlock the user's home directory. If a
303       home directory has at least one client with an open reference to the
304       home directory that does not support this it is not suspended
305       automatically at system suspend, otherwise it is. This method is
306       equivalent to Acquire() on the org.freedesktop.home1.Home interface.
307
308       RefHome() is similar to AcquireHome() but takes no user record with
309       "secret" section, i.e. will take an additional reference to an already
310       activated/unlocked home directory without attempting to activate/unlock
311       it itself. It will fail if the home directory is not already activated.
312       This method is equivalent to Ref() on the org.freedesktop.home1.Home
313       interface.
314
315       ReleaseHome() releases a home directory again, if all file descriptors
316       referencing it are already closed, that where acquired through
317       AcquireHome() or RefHome(). Note that this call does not actually cause
318       the deactivation of the home directory (which happens automatically
319       when the last referencing file descriptor is closed), but is simply a
320       synchronization mechanism that allows delaying of the user session's
321       termination until any triggered deactivation is completed. This method
322       is equivalent to Release() on the org.freedesktop.home1.Home interface.
323
324       LockAllHomes() locks all active home directories that only have
325       references that opted into automatic suspending during system suspend.
326       This is usually invoked automatically shortly before system suspend.
327
328       DeactivateAllHomes() deactivates all home areas that are currently
329       active. This is usually invoked automatically shortly before system
330       shutdown.
331
332       Rebalance() synchronously rebalances free disk space between home
333       areas. This only executes an operation if at least one home area using
334       the LUKS2 backend is active and has rebalancing enabled, and is
335       otherwise a NOP.
336
337   Properties
338       AutoLogin exposes an array of structures consisting of user name, seat
339       name and object path of an home directory object. All locally managed
340       users that have the "autoLogin" field set are listed here, with the
341       seat name they are associated with. A display manager may watch this
342       property and pre-fill the login screen with the users exposed this way.
343

THE HOME OBJECT

345           node /org/freedesktop/home1/home {
346             interface org.freedesktop.home1.Home {
347               methods:
348                 @org.freedesktop.systemd1.Privileged("true")
349                 Activate(in  s secret);
350                 @org.freedesktop.systemd1.Privileged("true")
351                 Deactivate();
352                 Unregister();
353                 Realize(in  s secret);
354                 Remove();
355                 @org.freedesktop.systemd1.Privileged("true")
356                 Fixate(in  s secret);
357                 Authenticate(in  s secret);
358                 Update(in  s user_record);
359                 Resize(in  t size,
360                        in  s secret);
361                 ChangePassword(in  s new_secret,
362                                in  s old_secret);
363                 @org.freedesktop.systemd1.Privileged("true")
364                 Lock();
365                 @org.freedesktop.systemd1.Privileged("true")
366                 Unlock(in  s secret);
367                 @org.freedesktop.systemd1.Privileged("true")
368                 Acquire(in  s secret,
369                         in  b please_suspend,
370                         out h send_fd);
371                 @org.freedesktop.systemd1.Privileged("true")
372                 Ref(in  b please_suspend,
373                     out h send_fd);
374                 @org.freedesktop.systemd1.Privileged("true")
375                 Release();
376               properties:
377                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
378                 readonly s UserName = '...';
379                 readonly u UID = ...;
380                 readonly (suusss) UnixRecord = ...;
381                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
382                 readonly s State = '...';
383                 @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates")
384                 readonly (sb) UserRecord = ...;
385             };
386             interface org.freedesktop.DBus.Peer { ... };
387             interface org.freedesktop.DBus.Introspectable { ... };
388             interface org.freedesktop.DBus.Properties { ... };
389             interface org.freedesktop.DBus.ObjectManager { ... };
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   Methods
417       Activate(), Deactivate(), Unregister(), Realize(), Remove(), Fixate(),
418       Authenticate(), Update(), Resize(), ChangePassword(), Lock(), Unlock(),
419       Acquire(), Ref(), Release() operate like their matching counterparts on
420       the org.freedesktop.home1.Manager interface (see above). The main
421       difference is that they are methods of the home directory objects, and
422       hence carry no additional user name parameter. Which of the two flavors
423       of methods to call depends on the handles to the user known on the
424       client side: if only the user name is known, it's preferable to use the
425       methods on the manager object since they operate with user names only.
426       If however the home object path was already acquired some way it is
427       preferable to operate on the org.freedesktop.home1.Home objects
428       instead.
429
430   Properties
431       UserName contains the user name of the user account/home directory.
432
433       UID contains the numeric UNIX UID of the user account.
434
435       UnixRecord contains a structure encapsulating the six fields a struct
436       passwd typically contains (the password field is suppressed).
437
438       State exposes the current state home the home directory.
439
440       UserRecord contains the full JSON user record string of the user
441       account.
442

VERSIONING

444       These D-Bus interfaces follow the usual interface versioning
445       guidelines[2].
446

SEE ALSO

448       systemd(1), systemd-homed.service(8), homectl(1)
449

NOTES

451        1. JSON User Records
452           https://systemd.io/USER_RECORD
453
454        2. the usual interface versioning guidelines
455           http://0pointer.de/blog/projects/versioning-dbus.html
456
457
458
459systemd 251                                           ORG.FREEDESKTOP.HOME1(5)
Impressum