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

THE HOME OBJECT

328           node /org/freedesktop/home1/home {
329             interface org.freedesktop.home1.Home {
330               methods:
331                 Activate(in  s secret);
332                 Deactivate();
333                 Unregister();
334                 Realize(in  s secret);
335                 Remove();
336                 Fixate(in  s secret);
337                 Authenticate(in  s secret);
338                 Update(in  s user_record);
339                 Resize(in  t size,
340                        in  s secret);
341                 ChangePassword(in  s new_secret,
342                                in  s old_secret);
343                 Lock();
344                 Unlock(in  s secret);
345                 Acquire(in  s secret,
346                         in  b please_suspend,
347                         out h send_fd);
348                 Ref(in  b please_suspend,
349                     out h send_fd);
350                 Release();
351               properties:
352                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
353                 readonly s UserName = '...';
354                 readonly u UID = ...;
355                 readonly (suusss) UnixRecord = ...;
356                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
357                 readonly s State = '...';
358                 @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates")
359                 readonly (sb) UserRecord = ...;
360             };
361             interface org.freedesktop.DBus.Peer { ... };
362             interface org.freedesktop.DBus.Introspectable { ... };
363             interface org.freedesktop.DBus.Properties { ... };
364             interface org.freedesktop.DBus.ObjectManager { ... };
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   Methods
392       Activate(), Deactivate(), Unregister(), Realize(), Remove(), Fixate(),
393       Authenticate(), Update(), Resize(), ChangePassword(), Lock(), Unlock(),
394       Acquire(), Ref(), Release() operate like their matching counterparts on
395       the org.freedesktop.home1.Manager interface (see above). The main
396       difference is that they are methods of the home directory objects, and
397       hence carry no additional user name parameter. Which of the two flavors
398       of methods to call depends on the handles to the user known on the
399       client side: if only the user name is known, it's preferable to use the
400       methods on the manager object since they operate with user names only.
401       If however the home object path was already acquired some way it is
402       preferable to operate on the org.freedesktop.home1.Home objects
403       instead.
404
405   Properties
406       UserName contains the user name of the user account/home directory.
407
408       UID contains the numeric UNIX UID of the user account.
409
410       UnixRecord contains a structure encapsulating the six fields a struct
411       passwd typically contains (the password field is suppressed).
412
413       State exposes the current state home the home directory.
414
415       UserRecord contains the full JSON user record string of the user
416       account.
417

VERSIONING

419       These D-Bus interfaces follow the usual interface versioning
420       guidelines[2].
421

SEE ALSO

423       systemd(1), systemd-homed.service(8), homectl(1)
424

NOTES

426        1. JSON User Records
427           https://systemd.io/USER_RECORD
428
429        2. the usual interface versioning guidelines
430           http://0pointer.de/blog/projects/versioning-dbus.html
431
432
433
434systemd 248                                           ORG.FREEDESKTOP.HOME1(5)
Impressum