Debian Codegraph @

upstream/debian-unstable/man5/org.freedesktop.home1.5

raw
1 '\" t
2 .TH "ORG\&.FREEDESKTOP\&.HOME1" "5" "" "systemd 261~rc3" "org.freedesktop.home1"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 org.freedesktop.home1 \- The D\-Bus interface of systemd\-homed
24 .SH "INTRODUCTION"
25 .PP
26 \fBsystemd-homed.service\fR(8)
27 is a system service which may be used to create, remove, change or inspect home areas\&. This page describes the D\-Bus interface\&.
28 .SH "THE MANAGER OBJECT"
29 .PP
30 The service exposes the following interfaces on the Manager object on the bus:
31 .sp
32 .if n \{\
33 .RS 4
34 .\}
35 .nf
36 node /org/freedesktop/home1 {
37 interface org\&.freedesktop\&.home1\&.Manager {
38 methods:
39 GetHomeByName(in s user_name,
40 out u uid,
41 out s home_state,
42 out u gid,
43 out s real_name,
44 out s home_directory,
45 out s shell,
46 out o bus_path);
47 GetHomeByUID(in u uid,
48 out s user_name,
49 out s home_state,
50 out u gid,
51 out s real_name,
52 out s home_directory,
53 out s shell,
54 out o bus_path);
55 GetUserRecordByName(in s user_name,
56 out s user_record,
57 out b incomplete,
58 out o bus_path);
59 GetUserRecordByUID(in u uid,
60 out s user_record,
61 out b incomplete,
62 out o bus_path);
63 ListHomes(out a(susussso) home_areas);
64 ActivateHome(in s user_name,
65 in s secret);
66 ActivateHomeIfReferenced(in s user_name,
67 in s secret);
68 @org\&.freedesktop\&.systemd1\&.Privileged("true")
69 DeactivateHome(in s user_name);
70 RegisterHome(in s user_record);
71 AdoptHome(in s image_path,
72 in t flags);
73 UnregisterHome(in s user_name);
74 CreateHome(in s user_record);
75 CreateHomeEx(in s user_record,
76 in a{sh} blobs,
77 in t flags);
78 RealizeHome(in s user_name,
79 in s secret);
80 RemoveHome(in s user_name);
81 @org\&.freedesktop\&.systemd1\&.Privileged("true")
82 FixateHome(in s user_name,
83 in s secret);
84 AuthenticateHome(in s user_name,
85 in s secret);
86 UpdateHome(in s user_record);
87 UpdateHomeEx(in s user_record,
88 in a{sh} blobs,
89 in t flags);
90 ResizeHome(in s user_name,
91 in t size,
92 in s secret);
93 ChangePasswordHome(in s user_name,
94 in s new_secret,
95 in s old_secret);
96 @org\&.freedesktop\&.systemd1\&.Privileged("true")
97 LockHome(in s user_name);
98 @org\&.freedesktop\&.systemd1\&.Privileged("true")
99 UnlockHome(in s user_name,
100 in s secret);
101 AcquireHome(in s user_name,
102 in s secret,
103 in b please_suspend,
104 out h send_fd);
105 @org\&.freedesktop\&.systemd1\&.Privileged("true")
106 RefHome(in s user_name,
107 in b please_suspend,
108 out h send_fd);
109 @org\&.freedesktop\&.systemd1\&.Privileged("true")
110 RefHomeUnrestricted(in s user_name,
111 in b please_suspend,
112 out h send_fd);
113 @org\&.freedesktop\&.systemd1\&.Privileged("true")
114 ReleaseHome(in s user_name);
115 ListSigningKeys(out a(sst) keys);
116 GetSigningKey(in s name,
117 out s der,
118 out t flags);
119 AddSigningKey(in s name,
120 in s pem,
121 in t flags);
122 RemoveSigningKey(in s name,
123 in t flags);
124 @org\&.freedesktop\&.systemd1\&.Privileged("true")
125 LockAllHomes();
126 @org\&.freedesktop\&.systemd1\&.Privileged("true")
127 DeactivateAllHomes();
128 @org\&.freedesktop\&.systemd1\&.Privileged("true")
129 Rebalance();
130 properties:
131 readonly a(sso) AutoLogin = [\&.\&.\&.];
132 };
133 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
134 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
135 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
136 };
137 .fi
138 .if n \{\
139 .RE
140 .\}
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177 .SS "Methods"
178 .PP
179 \fBGetHomeByName()\fR
180 returns basic user information (a minimal subset of the full user record), provided a user name\&. The information supplied more or less matches what
181 \fBgetpwnam\fR(3)
182 returns: the numeric UID and GID, the real name, home directory and shell\&. In addition it returns a state identifier describing the state the user\*(Aqs home directory is in, as well as a bus path referring to the bus object encapsulating the user record and home directory\&. This object implements the
183 org\&.freedesktop\&.home1\&.Home
184 interface documented below\&. This method, and most others in this interface that take user names, will try to use the caller\*(Aqs home area if the specified user name is an empty string\&.
185 .PP
186 \fBGetHomeByUID()\fR
187 is similar to
188 \fBGetHomeByName()\fR
189 but acquires the information based on the numeric UID of the user\&.
190 .PP
191 \fBGetUserRecordByName()\fR
192 is also similar to
193 \fBGetHomeByName()\fR
194 but returns the full JSON user record data instead of the broken down records\&. An additional returned boolean indicates whether the record is complete or not\&. A record is considered complete when its
195 "privileged"
196 section is included, and incomplete if it was removed (see
197 \m[blue]\fBJSON User Records\fR\m[]\&\s-2\u[1]\d\s+2
198 for details about the various sections of a user record)\&. Generally, only privileged clients and clients running under the identity of the user itself get access to the
199 "privileged"
200 section and will thus see complete records\&.
201 .PP
202 \fBGetUserRecordByUID()\fR
203 is similar to
204 \fBGetUserRecordByName()\fR
205 but returns the user record matching the specified numeric UID\&.
206 .PP
207 \fBListHomes()\fR
208 returns an array of all locally managed users\&. The array contains the same fields
209 \fBGetHomeByName()\fR
210 returns: user name, numeric UID, state, numeric GID, real name, home directory, shell and bus path of the matching bus object\&.
211 .PP
212 \fBActivateHome()\fR
213 activates (i\&.e\&. mounts) the home directory of the specified user\&. The second argument shall contain a user record consisting only of a
214 "secret"
215 section (all other sections should be stripped, see
216 \m[blue]\fBJSON User Records\fR\m[]\&\s-2\u[1]\d\s+2
217 for details), and should contain only the secret credentials necessary for unlocking the home directory\&. Typically a client would invoke this function first with an entirely empty record (which is possibly sufficient if single\-factor authentication with a plugged\-in security token is configured), and would then retry with a record populated with more information, depending on the returned error code, in case more credentials are necessary\&. This function is synchronous and returns only after the home directory was fully activated (or the operation failed), which might take some time\&. Clients must be prepared for that, and typically should extend the D\-Bus method call timeout accordingly\&. This method is equivalent to the
218 \fBActivate()\fR
219 method on the
220 org\&.freedesktop\&.home1\&.Home
221 interface documented below, but may be called on the manager object and takes a user name as additional argument, instead\&.
222 .PP
223 \fBActivateHomeIfReferenced()\fR
224 is identical to
225 \fBActivateHome()\fR\&. However, the call only succeeds if the home directory is currently referenced\&. Useful in conjunction with
226 \fBRefHomeUnrestricted()\fR, which allows creating a reference to a home directory even if the home directory is not active\&.
227 .PP
228 \fBDeactivateHome()\fR
229 deactivates (i\&.e\&. unmounts) the home directory of the specified user\&. It is equivalent to the
230 \fBDeactivate()\fR
231 method on the
232 org\&.freedesktop\&.home1\&.Home
233 interface documented below\&.
234 .PP
235 \fBRegisterHome()\fR
236 registers a new home directory locally\&. It receives the JSON user record as only argument (which typically excludes the
237 "secret"
238 section)\&. Registering a home directory just makes the user record known to the system, it does not create a home directory or such (which is expected to exist already, or created later)\&. This operation is useful to register home directories locally that are not located where
239 systemd\-homed\&.service
240 would find them automatically\&.
241 .PP
242 \fBAdoptHome()\fR
243 also registers a new home directory locally\&. It takes a path to a home directory itself, and will register it locally\&. This only works for
244 *\&.home
245 and
246 *\&.homedir/
247 home directories\&. This operation is done automatically for all such home areas showing up in
248 /home/, but may be requested explicitly with this call for directories elsewhere\&. The
249 \fIflags\fR
250 must be set to zero, currently\&.
251 .PP
252 \fBUnregisterHome()\fR
253 unregisters an existing home directory\&. It takes a user name as argument and undoes what
254 \fBRegisterHome()\fR
255 does\&. It does not attempt to remove the home directory itself, it just unregisters it with the local system\&. Note that if the home directory is placed where
256 systemd\-homed\&.service
257 looks for home directories anyway this call will only undo fixation (see below), but the record will remain known to
258 systemd\-homed\&.service
259 and be listed among known records\&. Since the user record is embedded into the home directory this operation generally does not discard data belonging to the user or their record\&. This method is equivalent to
260 \fBUnregister()\fR
261 on the
262 org\&.freedesktop\&.home1\&.Home
263 interface\&.
264 .PP
265 \fBCreateHome()\fR
266 registers and creates a new home directory\&. This takes a fully specified JSON user record as argument (including the
267 "secret"
268 section)\&. This registers the user record locally and creates a home directory matching it, depending on the settings specified in the record in combination with local configuration\&.
269 .PP
270 \fBCreateHomeEx()\fR
271 is like
272 \fBCreateHome()\fR, but it allows the home directory to be created with a pre\-populated blob directory (see
273 \m[blue]\fBUser Record Blob Directories\fR\m[]\&\s-2\u[2]\d\s+2
274 for more info)\&. This can be done via the dictionary passed as the
275 \fIblobs\fR
276 argument to this method: the values are open file descriptors to regular files, and the keys are the filenames that should contain their respective file\*(Aqs data in the blob directory\&. Note that for security reasons, the file descriptors passed into this method must have enough privileges to read their target file and thus cannot be
277 "O_PATH"; this is done to ensure the caller is actually permitted to read the file they are asking to publish in the blob directories\&. If the user record passed as the first argument contains a
278 "blobManifest"
279 field it will be enforced; otherwise, a
280 "blobManifest"
281 field will be generated and inserted into the record\&. The
282 \fIflags\fR
283 argument may be used for future expansion, but for now pass 0\&.
284 .PP
285 \fBRealizeHome()\fR
286 creates a home directory whose user record is already registered locally\&. This takes a user name plus a user record consisting only of the
287 "secret"
288 section\&. Invoking
289 \fBRegisterHome()\fR
290 followed by
291 \fBRealizeHome()\fR
292 is mostly equivalent to calling
293 \fBCreateHome()\fR, except that the latter combines the two in atomic fashion\&. This method is equivalent to
294 \fBRealize()\fR
295 on the
296 org\&.freedesktop\&.home1\&.Home
297 interface\&.
298 .PP
299 \fBRemoveHome()\fR
300 unregisters a user record locally, and removes the home directory belonging to it, if it is accessible\&. It takes a user name as argument\&. This method is equivalent to
301 \fBRemove()\fR
302 on the
303 org\&.freedesktop\&.home1\&.Home
304 interface\&.
305 .PP
306 \fBFixateHome()\fR
307 "fixates"
308 an automatically discovered home directory\&.
309 systemd\-homed\&.service
310 automatically discovers home directories dropped in our plugged in and adds them to the runtime list of user records it manages\&. A user record discovered that way may be
311 "fixated", in which case it is copied out of the home directory, onto persistent storage, to fixate the UID/GID assignment of the record, and extract additional (typically previously encrypted) user record data from the home directory\&. A home directory mus be fixated before it can be logged into\&. This method call takes a user name and a JSON user record consisting only of the
312 "secret"
313 section as argument\&. This method is equivalent to
314 \fBFixate()\fR
315 on the
316 org\&.freedesktop\&.home1\&.Home
317 interface\&.
318 .PP
319 \fBAuthenticateHome()\fR
320 checks passwords or other authentication credentials associated with the home directory\&. It takes a user name and a JSON user record consisting only of the
321 "secret"
322 section as argument\&. Note that many of the other method calls authenticate the user first, in order to execute some other operation\&. This method call only authenticates and executes no further operation\&. Like
323 \fBActivateHome()\fR
324 it is usually first invoked with an empty JSON user record, which is then populated for subsequent tries with additional authentication data supplied\&. This method is equivalent to
325 \fBAuthenticate()\fR
326 on the
327 org\&.freedesktop\&.home1\&.Home
328 interface\&.
329 .PP
330 \fBUpdateHome()\fR
331 updates a locally registered user record\&. Takes a fully specified JSON user record as argument (possibly including the
332 "secret"
333 section)\&. A user with a matching name and realm must be registered locally already, and the last change timestamp of the newly supplied record must be newer than the previously existing user record\&. Note this operation updates the user record only, it does not propagate passwords/authentication tokens from the user record to the storage back\-end, or resizes the storage back\-end\&. Typically a home directory is first updated, and then the password of the underlying storage updated using
334 \fBChangePasswordHome()\fR
335 as well as the storage resized using
336 \fBResizeHome()\fR\&. This method is equivalent to
337 \fBUpdate()\fR
338 on the
339 org\&.freedesktop\&.home1\&.Home
340 interface\&.
341 .PP
342 \fBUpdateHomeEx()\fR
343 is like
344 \fBUpdateHome()\fR, but it allows for changes to the blob directory (see
345 \m[blue]\fBUser Record Blob Directories\fR\m[]\&\s-2\u[2]\d\s+2
346 for more info)\&. The
347 \fIblobs\fR
348 argument works in the same way as
349 \fBCreateHomeEx()\fR, so check there for details\&. The new blob directory contents passed into this method will completely replace the user\*(Aqs existing blob directory\&. The
350 \fIflags\fR
351 argument can be used to further customize the behavior of this method via flags defined as follows:
352 .sp
353 .if n \{\
354 .RS 4
355 .\}
356 .nf
357 #define SD_HOMED_UPDATE_OFFLINE (UINT64_C(1) << 0)
358 .fi
359 .if n \{\
360 .RE
361 .\}
362 .PP
363 When
364 \fBSD_HOMED_UPDATE_OFFLINE\fR
365 (0x01) is set, no attempt is made to update the copies of the user record and blob directory that are embedded into the home directory\&. Changes will be stored, however, and may be propagated into the home directory the next time it is reconciled (most likely when the user next logs in)\&. Note that any changes made with this flag set may be lost if the home area has a newer record, which can happen if the home area is updated on another machine after this method call\&. This method is equivalent to
366 \fBUpdateEx()\fR
367 on the
368 org\&.freedesktop\&.home1\&.Home
369 interface\&.
370 .PP
371 \fBResizeHome()\fR
372 resizes the storage associated with a user record\&. Takes a user name, a disk size in bytes, and optionally a user record consisting only of the
373 "secret"
374 section as arguments\&. If the size is specified as
375 \fBUINT64_MAX\fR
376 the storage is resized to the size already specified in the user record\&. Typically, if the user record is updated using
377 \fBUpdateHome()\fR
378 above this is used to propagate the size configured there\-in down to the underlying storage back\-end\&. This method is equivalent to
379 \fBResize()\fR
380 on the
381 org\&.freedesktop\&.home1\&.Home
382 interface\&.
383 .PP
384 \fBChangePasswordHome()\fR
385 changes the passwords/authentication tokens of a home directory\&. Takes a user name, and two JSON user record objects, each consisting only of the
386 "secret"
387 section, for the old and for the new passwords/authentication tokens\&. If the user record with the new passwords/authentication token data is specified as empty the existing user record\*(Aqs settings are propagated down to the home directory storage\&. This is typically used after a user record is updated using
388 \fBUpdateHome()\fR
389 in order to propagate the secrets/authentication tokens down to the storage\&. Background: depending on the backend the user\*(Aqs authentication credentials are stored at multiple places: the user record kept on the host, the user record kept in the home directory and the encrypted LUKS volume slot\&. If the home directory is used on a different machined temporarily, and the password is changed there, and then is moved back to the original host, the passwords of the three might get out of sync\&. By issuing
390 \fBChangePasswordHome()\fR
391 the three locations are updated to match the newest information\&. This method is equivalent to
392 \fBChangePassword()\fR
393 on the
394 org\&.freedesktop\&.home1\&.Home
395 interface\&.
396 .PP
397 \fBLockHome()\fR
398 temporarily suspends access to a home directory, flushing out any cryptographic keys from memory\&. This is only supported on some back\-ends, and is usually done during system suspend, in order to effectively secure home directories while the system is sleeping\&. Takes a user name as single argument\&. If an application attempts to access a home directory while it is locked it will typically freeze until the home directory is unlocked again\&. This method is equivalent to
399 \fBLock()\fR
400 on the
401 org\&.freedesktop\&.home1\&.Home
402 interface\&.
403 .PP
404 \fBUnlockHome()\fR
405 undoes the effect of
406 \fBLockHome()\fR\&. Takes a user name and a user record consisting only of the
407 "secret"
408 section as arguments\&. This method is equivalent to
409 \fBUnlock()\fR
410 on the
411 org\&.freedesktop\&.home1\&.Home
412 interface\&.
413 .PP
414 \fBAcquireHome()\fR
415 activates or unlocks a home directory in a reference counted mode of operation\&. Takes a user name and user record consisting only of
416 "secret"
417 section as argument\&. If the home directory is not active yet, it is activated\&. If it is currently locked it is unlocked\&. After completion a reference to the activation/unlocking of the home directory is returned via a file descriptor\&. When the last client which acquired such a file descriptor closes it the home directory is automatically deactivated again\&. This method is typically invoked when a user logs in, and the file descriptor is held until the user logs out again, thus ensuring the user\*(Aqs home directory can be unmounted automatically again in a robust fashion, when the user logs out\&. The third argument is a boolean which indicates whether the client invoking the call is able to automatically re\-authenticate when the system comes back from suspending\&. It should be set by all clients that implement a secure lock screen running outside of the user\*(Aqs context, that is brought up when the system comes back from suspend and can be used to re\-acquire the credentials to unlock the user\*(Aqs home directory\&. If a home directory has at least one client with an open reference to the home directory that does not support this it is not suspended automatically at system suspend, otherwise it is\&. This method is equivalent to
418 \fBAcquire()\fR
419 on the
420 org\&.freedesktop\&.home1\&.Home
421 interface\&.
422 .PP
423 \fBRefHome()\fR
424 is similar to
425 \fBAcquireHome()\fR
426 but takes no user record with
427 "secret"
428 section, i\&.e\&. will take an additional reference to an already activated/unlocked home directory without attempting to activate/unlock it itself\&. It will fail if the home directory is not already activated\&. This method is equivalent to
429 \fBRef()\fR
430 on the
431 org\&.freedesktop\&.home1\&.Home
432 interface\&.
433 .PP
434 \fBRefHomeUnrestricted()\fR
435 is identical to
436 \fBRefHome()\fR
437 but succeeds even if the home area is not active currently\&. This is useful on conjunction with
438 \fBActivateHomeIfReferenced()\fR\&.
439 .PP
440 \fBReleaseHome()\fR
441 releases a home directory again, if all file descriptors referencing it are already closed, that where acquired through
442 \fBAcquireHome()\fR
443 or
444 \fBRefHome()\fR\&. Note that this call does not actually cause the deactivation of the home directory (which happens automatically when the last referencing file descriptor is closed), but is simply a synchronization mechanism that allows delaying of the user session\*(Aqs termination until any triggered deactivation is completed\&. This method is equivalent to
445 \fBRelease()\fR
446 on the
447 org\&.freedesktop\&.home1\&.Home
448 interface\&.
449 .PP
450 \fBLockAllHomes()\fR
451 locks all active home directories that only have references that opted into automatic suspending during system suspend\&. This is usually invoked automatically shortly before system suspend\&.
452 .PP
453 \fBDeactivateAllHomes()\fR
454 deactivates all home areas that are currently active\&. This is usually invoked automatically shortly before system shutdown\&.
455 .PP
456 \fBRebalance()\fR
457 synchronously rebalances free disk space between home areas\&. This only executes an operation if at least one home area using the LUKS2 backend is active and has rebalancing enabled, and is otherwise a NOP\&.
458 .PP
459 \fBListSigningKeys()\fR
460 acquires a list of installed home area signing keys\&. Returns an array of key names with their PEM encoded public key data\&. Each entry also comes with a flags value which is currently unused and should be ignored by clients\&.
461 .PP
462 \fBGetSigningKey()\fR
463 acquires the PEM encoded public part of the specified home area signing key of the specified name\&. Also returns a currently unused flags value that should be ignored\&. The
464 \fIflags\fR
465 parameter must be set to zero, currently\&.
466 .PP
467 \fBAddSigningKey()\fR
468 adds a new key to the list of home area signing keys\&. Takes a name string (free\-form, suitable as filename, with suffix
469 "\&.public"), the PEM encoded public key data and a currently unused flags value that must be zero\&. The
470 \fIflags\fR
471 parameter must be set to zero, currently\&.
472 .PP
473 \fBRemoveSigningKey()\fR
474 removes a key from the list of home area signing keys\&. Takes the name of the key to remove and a currently unused flags value that must be zero\&. The
475 \fIflags\fR
476 parameter must be set to zero, currently\&.
477 .SS "Properties"
478 .PP
479 \fIAutoLogin\fR
480 exposes an array of structures consisting of user name, seat name and object path of an home directory object\&. All locally managed users that have the
481 "autoLogin"
482 field set are listed here, with the seat name they are associated with\&. A display manager may watch this property and pre\-fill the login screen with the users exposed this way\&.
483 .SH "THE HOME OBJECT"
484 .sp
485 .if n \{\
486 .RS 4
487 .\}
488 .nf
489 node /org/freedesktop/home1/home {
490 interface org\&.freedesktop\&.home1\&.Home {
491 methods:
492 Activate(in s secret);
493 ActivateIfReferenced(in s secret);
494 @org\&.freedesktop\&.systemd1\&.Privileged("true")
495 Deactivate();
496 Unregister();
497 Realize(in s secret);
498 Remove();
499 @org\&.freedesktop\&.systemd1\&.Privileged("true")
500 Fixate(in s secret);
501 Authenticate(in s secret);
502 Update(in s user_record);
503 UpdateEx(in s user_record,
504 in a{sh} blobs,
505 in t flags);
506 Resize(in t size,
507 in s secret);
508 ChangePassword(in s new_secret,
509 in s old_secret);
510 @org\&.freedesktop\&.systemd1\&.Privileged("true")
511 Lock();
512 @org\&.freedesktop\&.systemd1\&.Privileged("true")
513 Unlock(in s secret);
514 @org\&.freedesktop\&.systemd1\&.Privileged("true")
515 Acquire(in s secret,
516 in b please_suspend,
517 out h send_fd);
518 @org\&.freedesktop\&.systemd1\&.Privileged("true")
519 Ref(in b please_suspend,
520 out h send_fd);
521 @org\&.freedesktop\&.systemd1\&.Privileged("true")
522 RefUnrestricted(in b please_suspend,
523 out h send_fd);
524 @org\&.freedesktop\&.systemd1\&.Privileged("true")
525 Release();
526 properties:
527 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
528 readonly s UserName = \*(Aq\&.\&.\&.\*(Aq;
529 readonly u UID = \&.\&.\&.;
530 readonly (suusss) UnixRecord = \&.\&.\&.;
531 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
532 readonly s State = \*(Aq\&.\&.\&.\*(Aq;
533 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("invalidates")
534 readonly (sb) UserRecord = \&.\&.\&.;
535 };
536 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
537 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
538 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
539 interface org\&.freedesktop\&.DBus\&.ObjectManager { \&.\&.\&. };
540 };
541 .fi
542 .if n \{\
543 .RE
544 .\}
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571 .SS "Methods"
572 .PP
573 \fBActivate()\fR,
574 \fBActivateIfReferenced()\fR,
575 \fBDeactivate()\fR,
576 \fBUnregister()\fR,
577 \fBRealize()\fR,
578 \fBRemove()\fR,
579 \fBFixate()\fR,
580 \fBAuthenticate()\fR,
581 \fBUpdate()\fR,
582 \fBUpdateEx()\fR,
583 \fBResize()\fR,
584 \fBChangePassword()\fR,
585 \fBLock()\fR,
586 \fBUnlock()\fR,
587 \fBAcquire()\fR,
588 \fBRef()\fR,
589 \fBRefUnrestricted()\fR,
590 \fBRelease()\fR, operate like their matching counterparts on the
591 org\&.freedesktop\&.home1\&.Manager
592 interface (see above)\&. The main difference is that they are methods of the home directory objects, and hence carry no additional user name parameter\&. Which of the two flavors of methods to call depends on the handles to the user known on the client side: if only the user name is known, it is preferable to use the methods on the manager object since they operate with user names only\&. Clients can also easily operate on their own home area by using the methods on the manager object with an empty string as the user name\&. If the client has the home\*(Aqs object path already acquired in some way, however, it is preferable to operate on the
593 org\&.freedesktop\&.home1\&.Home
594 objects instead\&.
595 .SS "Properties"
596 .PP
597 \fIUserName\fR
598 contains the user name of the user account/home directory\&.
599 .PP
600 \fIUID\fR
601 contains the numeric UNIX UID of the user account\&.
602 .PP
603 \fIUnixRecord\fR
604 contains a structure encapsulating the six fields a
605 struct passwd
606 typically contains (the password field is suppressed)\&.
607 .PP
608 \fIState\fR
609 exposes the current state home the home directory\&.
610 .PP
611 \fIUserRecord\fR
612 contains the full JSON user record string of the user account\&.
613 .SH "VERSIONING"
614 .PP
615 These D\-Bus interfaces follow
616 \m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[3]\d\s+2\&.
617 .SH "HISTORY"
618 .SS "The Manager Object"
619 .PP
620 \fBActivateHomeIfReferenced()\fR,
621 \fBRefHomeUnrestricted()\fR,
622 \fBCreateHomeEx()\fR, and
623 \fBUpdateHomeEx()\fR
624 were added in version 256\&.
625 .PP
626 \fBAdoptHome()\fR,
627 \fBListSigningKeys()\fR,
628 \fBGetSigningKey()\fR,
629 \fBAddSigningKey()\fR, and
630 \fBRemoveSigningKey()\fR
631 were added in version 258\&.
632 .SS "Home Objects"
633 .PP
634 \fBActivateIfReferenced()\fR,
635 \fBRefUnrestricted()\fR, and
636 \fBUpdateEx()\fR
637 were added in version 256\&.
638 .SH "SEE ALSO"
639 .PP
640 \fBsystemd\fR(1), \fBsystemd-homed.service\fR(8), \fBhomectl\fR(1)
641 .SH "NOTES"
642 .IP " 1." 4
643 JSON User Records
644 .RS 4
645 \%https://systemd.io/USER_RECORD
646 .RE
647 .IP " 2." 4
648 User Record Blob Directories
649 .RS 4
650 \%https://systemd.io/USER_RECORD_BLOB_DIRS
651 .RE
652 .IP " 3." 4
653 the usual interface versioning guidelines
654 .RS 4
655 \%https://0pointer.de/blog/projects/versioning-dbus.html
656 .RE