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 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 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 GetHomeByUID() is similar to GetHomeByName() but acquires the
124 information based on the numeric UID of the user.
125 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 GetUserRecordByUID() is similar to GetUserRecordByName() but returns
137 the user record matching the specified numeric UID.
138 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 DeactivateAllHomes() deactivates all home areas that are currently
317 active. This is usually invoked automatically shortly before system
318 shutdown.
319 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
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 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 Properties
406 UserName contains the user name of the user account/home directory.
407 UID contains the numeric UNIX UID of the user account.
409 UnixRecord contains a structure encapsulating the six fields a struct
411 passwd typically contains (the password field is suppressed).
412 State exposes the current state home the home directory.
414 UserRecord contains the full JSON user record string of the user
416 account.
417
419 These D-Bus interfaces follow the usual interface versioning
420 guidelines[2].
421
423 systemd(1), systemd-homed.service(8), homectl(1)
424
426 1. JSON User Records
427 https://systemd.io/USER_RECORD
428 2. the usual interface versioning guidelines
430 http://0pointer.de/blog/projects/versioning-dbus.html
431systemd 248 ORG.FREEDESKTOP.HOME1(5)