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. This method is equivalent to ChangePassword() on
270 the org.freedesktop.home1.Home interface.
271 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 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 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 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 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 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 DeactivateAllHomes() deactivates all home areas that are currently
329 active. This is usually invoked automatically shortly before system
330 shutdown.
331 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 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
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 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 Properties
431 UserName contains the user name of the user account/home directory.
432 UID contains the numeric UNIX UID of the user account.
434 UnixRecord contains a structure encapsulating the six fields a struct
436 passwd typically contains (the password field is suppressed).
437 State exposes the current state home the home directory.
439 UserRecord contains the full JSON user record string of the user
441 account.
442
444 These D-Bus interfaces follow the usual interface versioning
445 guidelines[2].
446
448 systemd(1), systemd-homed.service(8), homectl(1)
449
451 1. JSON User Records
452 https://systemd.io/USER_RECORD
453 2. the usual interface versioning guidelines
455 http://0pointer.de/blog/projects/versioning-dbus.html
456systemd 251 ORG.FREEDESKTOP.HOME1(5)