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. Background: depending on the backend the user's
270       authentication credentials are stored at multiple places: the user
271       record kept on the host, the user record kept in the home directory and
272       the encrypted LUKS volume slot. If the home directory is used on a
273       different machined temporarily, and the password is changed there, and
274       then is moved back to the original host, the passwords of the three
275       might get out of sync. By issuing ChangePasswordHome() the three
276       locations are updated to match the newest information. This method is
277       equivalent to ChangePassword() on the org.freedesktop.home1.Home
278       interface.
279
280       LockHome() temporarily suspends access to a home directory, flushing
281       out any cryptographic keys from memory. This is only supported on some
282       back-ends, and usually done during system suspend, in order to
283       effectively secure home directories while the system is sleeping. Takes
284       a user name as single argument. If an application attempts to access a
285       home directory while it is locked it will typically freeze until the
286       home directory is unlocked again. This method is equivalent to Lock()
287       on the org.freedesktop.home1.Home interface.
288
289       UnlockHome() undoes the effect of LockHome(). Takes a user name and a
290       user record consisting only of the "secret" section as arguments. This
291       method is equivalent to Unlock() on the org.freedesktop.home1.Home
292       interface.
293
294       AcquireHome() activates or unlocks a home directory in a reference
295       counted mode of operation. Takes a user name and user record consisting
296       only of "secret" section as argument. If the home directory is not
297       active yet, it is activated. If it is currently locked it is unlocked.
298       After completion a reference to the activation/unlocking of the home
299       directory is returned via a file descriptor. When the last client which
300       acquired such a file descriptor closes it the home directory is
301       automatically deactivated again. This method is typically invoked when
302       a user logs in, and the file descriptor is held until the user logs out
303       again, thus ensuring the user's home directory can be unmounted
304       automatically again in a robust fashion, when the user logs out. The
305       third argument is a boolean which indicates whether the client invoking
306       the call is able to automatically re-authenticate when the system comes
307       back from suspending. It should be set by all clients that implement a
308       secure lock screen running outside of the user's context, that is
309       brought up when the system comes back from suspend and can be used to
310       re-acquire the credentials to unlock the user's home directory. If a
311       home directory has at least one client with an open reference to the
312       home directory that does not support this it is not suspended
313       automatically at system suspend, otherwise it is. This method is
314       equivalent to Acquire() on the org.freedesktop.home1.Home interface.
315
316       RefHome() is similar to AcquireHome() but takes no user record with
317       "secret" section, i.e. will take an additional reference to an already
318       activated/unlocked home directory without attempting to activate/unlock
319       it itself. It will fail if the home directory is not already activated.
320       This method is equivalent to Ref() on the org.freedesktop.home1.Home
321       interface.
322
323       ReleaseHome() releases a home directory again, if all file descriptors
324       referencing it are already closed, that where acquired through
325       AcquireHome() or RefHome(). Note that this call does not actually cause
326       the deactivation of the home directory (which happens automatically
327       when the last referencing file descriptor is closed), but is simply a
328       synchronization mechanism that allows delaying of the user session's
329       termination until any triggered deactivation is completed. This method
330       is equivalent to Release() on the org.freedesktop.home1.Home interface.
331
332       LockAllHomes() locks all active home directories that only have
333       references that opted into automatic suspending during system suspend.
334       This is usually invoked automatically shortly before system suspend.
335
336       DeactivateAllHomes() deactivates all home areas that are currently
337       active. This is usually invoked automatically shortly before system
338       shutdown.
339
340       Rebalance() synchronously rebalances free disk space between home
341       areas. This only executes an operation if at least one home area using
342       the LUKS2 backend is active and has rebalancing enabled, and is
343       otherwise a NOP.
344
345   Properties
346       AutoLogin exposes an array of structures consisting of user name, seat
347       name and object path of an home directory object. All locally managed
348       users that have the "autoLogin" field set are listed here, with the
349       seat name they are associated with. A display manager may watch this
350       property and pre-fill the login screen with the users exposed this way.
351

THE HOME OBJECT

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

VERSIONING

452       These D-Bus interfaces follow the usual interface versioning
453       guidelines[2].
454

SEE ALSO

456       systemd(1), systemd-homed.service(8), homectl(1)
457

NOTES

459        1. JSON User Records
460           https://systemd.io/USER_RECORD
461
462        2. the usual interface versioning guidelines
463           https://0pointer.de/blog/projects/versioning-dbus.html
464
465
466
467systemd 254                                           ORG.FREEDESKTOP.HOME1(5)
Impressum