1ORG.FREEDESKTOP.HOME1(5) org.freedesktop.home1 ORG.FREEDESKTOP.HOME1(5)
2
6 org.freedesktop.home1 - The D-Bus interface of systemd-homed
7
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
14 The service exposes the following interfaces on the Manager object on
15 the bus:
16 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 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 GetHomeByUID() is similar to GetHomeByName() but acquires the
136 information based on the numeric UID of the user.
137 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 GetUserRecordByUID() is similar to GetUserRecordByName() but returns
149 the user record matching the specified numeric UID.
150 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 DeactivateAllHomes() deactivates all home areas that are currently
337 active. This is usually invoked automatically shortly before system
338 shutdown.
339 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 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
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 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 Properties
439 UserName contains the user name of the user account/home directory.
440 UID contains the numeric UNIX UID of the user account.
442 UnixRecord contains a structure encapsulating the six fields a struct
444 passwd typically contains (the password field is suppressed).
445 State exposes the current state home the home directory.
447 UserRecord contains the full JSON user record string of the user
449 account.
450
452 These D-Bus interfaces follow the usual interface versioning
453 guidelines[2].
454
456 systemd(1), systemd-homed.service(8), homectl(1)
457
459 1. JSON User Records
460 https://systemd.io/USER_RECORD
461 2. the usual interface versioning guidelines
463 https://0pointer.de/blog/projects/versioning-dbus.html
464systemd 254 ORG.FREEDESKTOP.HOME1(5)