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 properties:
78 readonly a(sso) AutoLogin = [...];
79 };
80 interface org.freedesktop.DBus.Peer { ... };
81 interface org.freedesktop.DBus.Introspectable { ... };
82 interface org.freedesktop.DBus.Properties { ... };
83 };
84 Methods
112 GetHomeByName() returns basic user information (a minimal subset of the
113 full user record), provided a user name. The information supplied more
114 or less matches what getpwnam(3) returns: the numeric UID and GID, the
115 real name, home directory and shell. In addition it returns a state
116 identifier describing the state the user's home directory is in, as
117 well as a bus path referring to the bus object encapsulating the user
118 record and home directory. This object implements the
119 org.freedesktop.home1.Home interface documented below.
120 GetHomeByUID() is similar to GetHomeByName() but acquires the
122 information based on the numeric UID of the user.
123 GetUserRecordByName() is also similar to GetHomeByName() but returns
125 the full JSON user record data instead of the broken down records. An
126 additional returned boolean indicates whether the record is complete or
127 not. A record is considered complete when its "privileged" section is
128 included, and incomplete if it was removed (see JSON User Records[1]
129 for details about the various sections of a user record). Generally,
130 only privileged clients and clients running under the identity of the
131 user itself get access to the "privileged" section and will thus see
132 complete records.
133 GetUserRecordByUID() is similar to GetUserRecordByName() but returns
135 the user record matching the specified numeric UID.
136 ListHomes() returns an array of all locally managed users. The array
138 contains the same fields GetHomeByName() returns: user name, numeric
139 UID, state, numeric GID, real name, home directory, shell and bus path
140 of the matching bus object.
141 ActivateHome() activates (i.e. mounts) the home directory of the
143 specified user. The second argument shall contain a user record
144 consisting only of a "secret" section (all other sections should be
145 stripped, see JSON User Records[1] for details), and should contain
146 only the secret credentials necessary for unlocking the home directory.
147 Typically a client would invoke this function first with an entirely
148 empty record (which is possibly sufficient if single-factor
149 authentication with a plugged-in security token is configured), and
150 would then retry with a record populated with more information,
151 depending on the returned error code, in case more credentials are
152 necessary. This function is synchronous and returns only after the home
153 directory was fully activated (or the operation failed), which might
154 take some time. Clients must be prepared for that, and typically should
155 extend the D-Bus method call timeout accordingly. This method is
156 equivalent to the Activate() method on the org.freedesktop.home1.Home
157 interface documented below, but may be called on the manager object and
158 takes a user name as additional argument, instead.
159 DeactivateHome() deactivates (i.e. unmounts) the home directory of the
161 specified user. It is equivalent to the Deactivate() method on the
162 org.freedesktop.home1.Home interface documented below.
163 RegisterHome() registers a new home directory locally. It receives the
165 JSON user record as only argument (which typically excludes the
166 "secret" section). Registering a home directory just makes the user
167 record known to the system, it does not create a home directory or such
168 (which is expected to exist already, or created later). This operation
169 is useful to register home directories locally that are not located
170 where systemd-homed.service would find them automatically.
171 UnregisterHome() unregisters an existing home directory. It takes a
173 user name as argument and undoes what RegisterHome() does. It does not
174 attempt to remove the home directory itself, it just unregisters it
175 with the local system. Note that if the home directory is placed where
176 systemd-homed.service looks for home directories anyway this call will
177 only undo fixation (see below), but the record will remain known to
178 systemd-homed.service and be listed among known records. Since the user
179 record is embedded into the home directory this operation generally
180 does not discard data belonging to the user or their record. This
181 method is equivalent to Unregister() on the org.freedesktop.home1.Home
182 interface.
183 CreateHome() registers and creates a new home directory. This takes a
185 fully specified JSON user record as argument (including the "secret"
186 section). This registers the user record locally and creates a home
187 directory matching it, depending on the settings specified in the
188 record in combination with local configuration.
189 RealizeHome() creates a home directory whose user record is already
191 registered locally. This takes a user name plus a user record
192 consisting only of the "secret" section. Invoking RegisterHome()
193 followed by RealizeHome() is mostly equivalent to calling CreateHome(),
194 except that the latter combines the two in atomic fashion. This method
195 is equivalent to Realize() on the org.freedesktop.home1.Home interface.
196 RemoveHome() unregisters a user record locally, and removes the home
198 directory belonging to it, if it is accessible. It takes a user name as
199 argument. This method is equivalent to Remove() on the
200 org.freedesktop.home1.Home interface.
201 FixateHome() "fixates" an automatically discovered home directory.
203 systemd-homed.service automatically discovers home directories dropped
204 in our plugged in and adds them to the runtime list of user records it
205 manages. A user record discovered that way may be "fixated", in which
206 case it is copied out of the home directory, onto persistent storage,
207 to fixate the UID/GID assignment of the record, and extract additional
208 (typically previously encrypted) user record data from the home
209 directory. A home directory mus be fixated before it can be logged
210 into. This method call takes a user name and a JSON user record
211 consisting only of the "secret" section as argument. This method is
212 equivalent to Fixate() on the org.freedesktop.home1.Home interface.
213 AuthenticateHome() checks passwords or other authentication credentials
215 associated with the home directory. It takes a user name and a JSON
216 user record consisting only of the "secret" section as argument. Note
217 that many of the other method calls authenticate the user first, in
218 order to execute some other operation. This method call only
219 authenticates and executes no further operation. Like ActivateHome() it
220 is usually first invoked with an empty JSON user record, which is then
221 populated for subsequent tries with additional authentication data
222 supplied. This method is equivalent to Authenticate() on the
223 org.freedesktop.home1.Home interface.
224 UpdateHome() updates a locally registered user record. Takes a fully
226 specified JSON user record as argument (including the "secret"
227 section). A user with a matching name and realm must be registered
228 locally already, and the last change timestamp of the newly supplied
229 record must be newer than the previously existing user record. Note
230 this operation updates the user record only, it does not propagate
231 passwords/authentication tokens from the user record to the storage
232 back-end, or resizes the storage back-end. Typically a home directory
233 is first updated, and then the password of the underlying storage
234 updated using ChangePasswordHome() as well as the storage resized using
235 ResizeHome(). This method is equivalent to Update() on the
236 org.freedesktop.home1.Home interface.
237 ResizeHome() resizes the storage associated with a user record. Takes a
239 user name, a disk size in bytes and a user record consisting only of
240 the "secret" section as argument. If the size is specified as
241 UINT64_MAX the storage is resized to the size already specified in the
242 user record. Typically, if the user record is updated using
243 UpdateHome() above this is used to propagate the size configured
244 there-in down to the underlying storage back-end. This method is
245 equivalent to Resize() on the org.freedesktop.home1.Home interface.
246 ChangePasswordHome() changes the passwords/authentication tokens of a
248 home directory. Takes a user name, and two JSON user record objects,
249 each consisting only of the "secret" section, for the old and for the
250 new passwords/authentication tokens. If the user record with the new
251 passwords/authentication token data is specified as empty the existing
252 user record's settings are propagated down to the home directory
253 storage. This is typically used after a user record is updated using
254 UpdateHome() in order to propagate the secrets/authentication tokens
255 down to the storage. This method is equivalent to ChangePassword() on
256 the org.freedesktop.home1.Home interface.
257 LockHome() temporarily suspends access to a home directory, flushing
259 out any cryptographic keys from memory. This is only supported on some
260 back-ends, and usually done during system suspend, in order to
261 effectively secure home directories while the system is sleeping. Takes
262 a user name as single argument. If an application attempts to access a
263 home directory while it is locked it will typically freeze until the
264 home directory is unlocked again. This method is equivalent to Lock()
265 on the org.freedesktop.home1.Home interface.
266 UnlockHome() undoes the effect of LockHome(). Takes a user name and a
268 user record consisting only of the "secret" section as arguments. This
269 method is equivalent to Unlock() on the org.freedesktop.home1.Home
270 interface.
271 AcquireHome() activates or unlocks a home directory in a reference
273 counted mode of operation. Takes a user name and user record consisting
274 only of "secret" section as argument. If the home directory is not
275 active yet, it is activated. If it is currently locked it is unlocked.
276 After completion a reference to the activation/unlocking of the home
277 directory is returned via a file descriptor. When the last client which
278 acquired such a file descriptor closes it the home directory is
279 automatically deactivated again. This method is typically invoked when
280 a user logs in, and the file descriptor is held until the user logs out
281 again, thus ensuring the user's home directory can be unmounted
282 automatically again in a robust fashion, when the user logs out. The
283 third argument is a boolean which indicates whether the client invoking
284 the call is able to automatically re-authenticate when the system comes
285 back from suspending. It should be set by all clients that implement a
286 secure lock screen running outside of the user's context, that is
287 brought up when the system comes back from suspend and can be used to
288 re-acquire the credentials to unlock the user's home directory. If a
289 home directory has at least one client with an open reference to the
290 home directory that does not support this it is not suspended
291 automatically at system suspend, otherwise it is. This method is
292 equivalent to Acquire() on the org.freedesktop.home1.Home interface.
293 RefHome() is similar to AcquireHome() but takes no user record with
295 "secret" section, i.e. will take an additional reference to an already
296 activated/unlocked home directory without attempting to activate/unlock
297 it itself. It will fail if the home directory is not already activated.
298 This method is equivalent to Ref() on the org.freedesktop.home1.Home
299 interface.
300 ReleaseHome() releases a home directory again, if all file descriptors
302 referencing it are already closed, that where acquired through
303 AcquireHome() or RefHome(). Note that this call does not actually cause
304 the deactivation of the home directory (which happens automatically
305 when the last referencing file descriptor is closed), but is simply a
306 synchronization mechanism that allows delaying of the user session's
307 termination until any triggered deactivation is completed. This method
308 is equivalent to Release() on the org.freedesktop.home1.Home interface.
309 LockAllHomes() locks all active home directories that only have
311 references that opted into automatic suspending during system suspend.
312 This is usually invoked automatically shortly before system suspend.
313 Properties
315 AutoLogin exposes an array of structures consisting of user name, seat
316 name and object path of an home directory object. All locally managed
317 users that have the "autoLogin" field set are listed here, with the
318 seat name they are associated with. A display manager may watch this
319 property and pre-fill the login screen with the users exposed this way.
320
322 node /org/freedesktop/home1/home {
323 interface org.freedesktop.home1.Home {
324 methods:
325 Activate(in s secret);
326 Deactivate();
327 Unregister();
328 Realize(in s secret);
329 Remove();
330 Fixate(in s secret);
331 Authenticate(in s secret);
332 Update(in s user_record);
333 Resize(in t size,
334 in s secret);
335 ChangePassword(in s new_secret,
336 in s old_secret);
337 Lock();
338 Unlock(in s secret);
339 Acquire(in s secret,
340 in b please_suspend,
341 out h send_fd);
342 Ref(in b please_suspend,
343 out h send_fd);
344 Release();
345 properties:
346 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
347 readonly s UserName = '...';
348 readonly u UID = ...;
349 readonly (suusss) UnixRecord = ...;
350 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
351 readonly s State = '...';
352 @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates")
353 readonly (sb) UserRecord = ...;
354 };
355 interface org.freedesktop.DBus.Peer { ... };
356 interface org.freedesktop.DBus.Introspectable { ... };
357 interface org.freedesktop.DBus.Properties { ... };
358 interface org.freedesktop.DBus.ObjectManager { ... };
359 };
360 Methods
386 Activate(), Deactivate(), Unregister(), Realize(), Remove(), Fixate(),
387 Authenticate(), Update(), Resize(), ChangePassword(), Lock(), Unlock(),
388 Acquire(), Ref(), Release() operate like their matching counterparts on
389 the org.freedesktop.home1.Manager interface (see above). The main
390 difference is that they are methods of the home directory objects, and
391 hence carry no additional user name parameter. Which of the two flavors
392 of methods to call depends on the handles to the user known on the
393 client side: if only the user name is known, it's preferable to use the
394 methods on the manager object since they operate with user names only.
395 If however the home object path was already acquired some way it is
396 preferable to operate on the org.freedesktop.home1.Home objects
397 instead.
398 Properties
400 UserName contains the user name of the user account/home directory.
401 UID contains the numeric UNIX UID of the user account.
403 UnixRecord contains a structure encapsulating the six fields a struct
405 passwd typically contains (the password field is suppressed).
406 State exposes the current state home the home directory.
408 UserRecord contains the full JSON user record string of the user
410 account.
411
413 These D-Bus interfaces follow the usual interface versioning
414 guidelines[2].
415
417 systemd(1), systemd-homed.service(8), homectl(1)
418
420 1. JSON User Records
421 https://systemd.io/USER_RECORD
422 2. the usual interface versioning guidelines
424 http://0pointer.de/blog/projects/versioning-dbus.html
425systemd 246 ORG.FREEDESKTOP.HOME1(5)