]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/org.freedesktop.home1.xml
Merge pull request #30641 from YHNdnzj/hibernation-device
[thirdparty/systemd.git] / man / org.freedesktop.home1.xml
1 <?xml version='1.0'?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" >
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6 <refentry id="org.freedesktop.home1" conditional='ENABLE_HOMED'
7 xmlns:xi="http://www.w3.org/2001/XInclude">
8 <refentryinfo>
9 <title>org.freedesktop.home1</title>
10 <productname>systemd</productname>
11 </refentryinfo>
12
13 <refmeta>
14 <refentrytitle>org.freedesktop.home1</refentrytitle>
15 <manvolnum>5</manvolnum>
16 </refmeta>
17
18 <refnamediv>
19 <refname>org.freedesktop.home1</refname>
20 <refpurpose>The D-Bus interface of systemd-homed</refpurpose>
21 </refnamediv>
22
23 <refsect1>
24 <title>Introduction</title>
25
26 <para><citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
27 is a system service which may be used to create, remove, change or inspect home areas. This page
28 describes the D-Bus interface.
29 </para>
30 </refsect1>
31
32 <refsect1>
33 <title>The Manager Object</title>
34
35 <para>The service exposes the following interfaces on the Manager object on the bus:</para>
36
37 <programlisting executable="systemd-homed" node="/org/freedesktop/home1" interface="org.freedesktop.home1.Manager">
38 node /org/freedesktop/home1 {
39 interface org.freedesktop.home1.Manager {
40 methods:
41 GetHomeByName(in s user_name,
42 out u uid,
43 out s home_state,
44 out u gid,
45 out s real_name,
46 out s home_directory,
47 out s shell,
48 out o bus_path);
49 GetHomeByUID(in u uid,
50 out s user_name,
51 out s home_state,
52 out u gid,
53 out s real_name,
54 out s home_directory,
55 out s shell,
56 out o bus_path);
57 GetUserRecordByName(in s user_name,
58 out s user_record,
59 out b incomplete,
60 out o bus_path);
61 GetUserRecordByUID(in u uid,
62 out s user_record,
63 out b incomplete,
64 out o bus_path);
65 ListHomes(out a(susussso) home_areas);
66 @org.freedesktop.systemd1.Privileged("true")
67 ActivateHome(in s user_name,
68 in s secret);
69 @org.freedesktop.systemd1.Privileged("true")
70 DeactivateHome(in s user_name);
71 RegisterHome(in s user_record);
72 UnregisterHome(in s user_name);
73 CreateHome(in s user_record);
74 RealizeHome(in s user_name,
75 in s secret);
76 RemoveHome(in s user_name);
77 @org.freedesktop.systemd1.Privileged("true")
78 FixateHome(in s user_name,
79 in s secret);
80 AuthenticateHome(in s user_name,
81 in s secret);
82 UpdateHome(in s user_record);
83 ResizeHome(in s user_name,
84 in t size,
85 in s secret);
86 ChangePasswordHome(in s user_name,
87 in s new_secret,
88 in s old_secret);
89 @org.freedesktop.systemd1.Privileged("true")
90 LockHome(in s user_name);
91 @org.freedesktop.systemd1.Privileged("true")
92 UnlockHome(in s user_name,
93 in s secret);
94 AcquireHome(in s user_name,
95 in s secret,
96 in b please_suspend,
97 out h send_fd);
98 @org.freedesktop.systemd1.Privileged("true")
99 RefHome(in s user_name,
100 in b please_suspend,
101 out h send_fd);
102 @org.freedesktop.systemd1.Privileged("true")
103 ReleaseHome(in s user_name);
104 @org.freedesktop.systemd1.Privileged("true")
105 LockAllHomes();
106 @org.freedesktop.systemd1.Privileged("true")
107 DeactivateAllHomes();
108 @org.freedesktop.systemd1.Privileged("true")
109 Rebalance();
110 properties:
111 readonly a(sso) AutoLogin = [...];
112 };
113 interface org.freedesktop.DBus.Peer { ... };
114 interface org.freedesktop.DBus.Introspectable { ... };
115 interface org.freedesktop.DBus.Properties { ... };
116 };
117 </programlisting>
118
119 <!--Autogenerated cross-references for systemd.directives, do not edit-->
120
121 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Manager"/>
122
123 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Manager"/>
124
125 <variablelist class="dbus-method" generated="True" extra-ref="GetHomeByName()"/>
126
127 <variablelist class="dbus-method" generated="True" extra-ref="GetHomeByUID()"/>
128
129 <variablelist class="dbus-method" generated="True" extra-ref="GetUserRecordByName()"/>
130
131 <variablelist class="dbus-method" generated="True" extra-ref="GetUserRecordByUID()"/>
132
133 <variablelist class="dbus-method" generated="True" extra-ref="ListHomes()"/>
134
135 <variablelist class="dbus-method" generated="True" extra-ref="ActivateHome()"/>
136
137 <variablelist class="dbus-method" generated="True" extra-ref="DeactivateHome()"/>
138
139 <variablelist class="dbus-method" generated="True" extra-ref="RegisterHome()"/>
140
141 <variablelist class="dbus-method" generated="True" extra-ref="UnregisterHome()"/>
142
143 <variablelist class="dbus-method" generated="True" extra-ref="CreateHome()"/>
144
145 <variablelist class="dbus-method" generated="True" extra-ref="RealizeHome()"/>
146
147 <variablelist class="dbus-method" generated="True" extra-ref="RemoveHome()"/>
148
149 <variablelist class="dbus-method" generated="True" extra-ref="FixateHome()"/>
150
151 <variablelist class="dbus-method" generated="True" extra-ref="AuthenticateHome()"/>
152
153 <variablelist class="dbus-method" generated="True" extra-ref="UpdateHome()"/>
154
155 <variablelist class="dbus-method" generated="True" extra-ref="ResizeHome()"/>
156
157 <variablelist class="dbus-method" generated="True" extra-ref="ChangePasswordHome()"/>
158
159 <variablelist class="dbus-method" generated="True" extra-ref="LockHome()"/>
160
161 <variablelist class="dbus-method" generated="True" extra-ref="UnlockHome()"/>
162
163 <variablelist class="dbus-method" generated="True" extra-ref="AcquireHome()"/>
164
165 <variablelist class="dbus-method" generated="True" extra-ref="RefHome()"/>
166
167 <variablelist class="dbus-method" generated="True" extra-ref="ReleaseHome()"/>
168
169 <variablelist class="dbus-method" generated="True" extra-ref="LockAllHomes()"/>
170
171 <variablelist class="dbus-method" generated="True" extra-ref="DeactivateAllHomes()"/>
172
173 <variablelist class="dbus-method" generated="True" extra-ref="Rebalance()"/>
174
175 <variablelist class="dbus-property" generated="True" extra-ref="AutoLogin"/>
176
177 <!--End of Autogenerated section-->
178
179 <refsect2>
180 <title>Methods</title>
181
182 <para><function>GetHomeByName()</function> returns basic user information (a minimal subset of the full
183 user record), provided a user name. The information supplied more or less matches what
184 <citerefentry project="man-pages"><refentrytitle>getpwnam</refentrytitle><manvolnum>3</manvolnum></citerefentry> returns:
185 the numeric UID and GID, the real name, home directory and shell. In addition it returns a state
186 identifier describing the state the user's home directory is in, as well as a bus path referring to the
187 bus object encapsulating the user record and home directory. This object implements the
188 <classname>org.freedesktop.home1.Home</classname> interface documented below.</para>
189
190 <para><function>GetHomeByUID()</function> is similar to <function>GetHomeByName()</function> but
191 acquires the information based on the numeric UID of the user.</para>
192
193 <para><function>GetUserRecordByName()</function> is also similar to
194 <function>GetHomeByName()</function> but returns the full JSON user record data instead of the broken
195 down records. An additional returned boolean indicates whether the record is complete or not. A record
196 is considered complete when its <literal>privileged</literal> section is included, and incomplete if it
197 was removed (see <ulink url="https://systemd.io/USER_RECORD">JSON User Records</ulink> for details
198 about the various sections of a user record). Generally, only privileged clients and clients running
199 under the identity of the user itself get access to the <literal>privileged</literal> section and will
200 thus see complete records.</para>
201
202 <para><function>GetUserRecordByUID()</function> is similar to <function>GetUserRecordByName()</function>
203 but returns the user record matching the specified numeric UID.</para>
204
205 <para><function>ListHomes()</function> returns an array of all locally managed users. The array
206 contains the same fields <function>GetHomeByName()</function> returns: user name, numeric UID, state,
207 numeric GID, real name, home directory, shell and bus path of the matching bus object.</para>
208
209 <para><function>ActivateHome()</function> activates (i.e. mounts) the home directory of the specified
210 user. The second argument shall contain a user record consisting only of a <literal>secret</literal>
211 section (all other sections should be stripped, see <ulink url="https://systemd.io/USER_RECORD">JSON
212 User Records</ulink> for details), and should contain only the secret credentials necessary for
213 unlocking the home directory. Typically a client would invoke this function first with an entirely
214 empty record (which is possibly sufficient if single-factor authentication with a plugged-in security
215 token is configured), and would then retry with a record populated with more information, depending on
216 the returned error code, in case more credentials are necessary. This function is synchronous and
217 returns only after the home directory was fully activated (or the operation failed), which might take
218 some time. Clients must be prepared for that, and typically should extend the D-Bus method call
219 timeout accordingly. This method is equivalent to the <function>Activate()</function> method on the
220 <classname>org.freedesktop.home1.Home</classname> interface documented below, but may be called on the
221 manager object and takes a user name as additional argument, instead.</para>
222
223 <para><function>DeactivateHome()</function> deactivates (i.e. unmounts) the home directory of the
224 specified user. It is equivalent to the <function>Deactivate()</function> method on the
225 <classname>org.freedesktop.home1.Home</classname> interface documented below.</para>
226
227 <para><function>RegisterHome()</function> registers a new home directory locally. It receives the JSON
228 user record as only argument (which typically excludes the <literal>secret</literal>
229 section). Registering a home directory just makes the user record known to the system, it does not
230 create a home directory or such (which is expected to exist already, or created later). This operation
231 is useful to register home directories locally that are not located where
232 <filename>systemd-homed.service</filename> would find them automatically.</para>
233
234 <para><function>UnregisterHome()</function> unregisters an existing home directory. It takes a user
235 name as argument and undoes what <function>RegisterHome()</function> does. It does not attempt to
236 remove the home directory itself, it just unregisters it with the local system. Note that if the home
237 directory is placed where <filename>systemd-homed.service</filename> looks for home directories anyway
238 this call will only undo fixation (see below), but the record will remain known to
239 <filename>systemd-homed.service</filename> and be listed among known records. Since the user record is
240 embedded into the home directory this operation generally does not discard data belonging to the user
241 or their record. This method is equivalent to
242 <function>Unregister()</function> on the <classname>org.freedesktop.home1.Home</classname>
243 interface.</para>
244
245 <para><function>CreateHome()</function> registers and creates a new home directory. This takes a fully
246 specified JSON user record as argument (including the <literal>secret</literal> section). This registers
247 the user record locally and creates a home directory matching it, depending on the settings specified
248 in the record in combination with local configuration.</para>
249
250 <para><function>RealizeHome()</function> creates a home directory whose user record is already
251 registered locally. This takes a user name plus a user record consisting only of the
252 <literal>secret</literal> section. Invoking <function>RegisterHome()</function> followed by
253 <function>RealizeHome()</function> is mostly equivalent to calling <function>CreateHome()</function>,
254 except that the latter combines the two in atomic fashion. This method is equivalent to
255 <function>Realize()</function> on the <classname>org.freedesktop.home1.Home</classname>
256 interface.</para>
257
258 <para><function>RemoveHome()</function> unregisters a user record locally, and removes the home
259 directory belonging to it, if it is accessible. It takes a user name as argument. This method is equivalent to
260 <function>Remove()</function> on the <classname>org.freedesktop.home1.Home</classname>
261 interface.</para>
262
263 <para><function>FixateHome()</function> <literal>fixates</literal> an automatically discovered home
264 directory. <filename>systemd-homed.service</filename> automatically discovers home directories dropped
265 in our plugged in and adds them to the runtime list of user records it manages. A user record
266 discovered that way may be <literal>fixated</literal>, in which case it is copied out of the home
267 directory, onto persistent storage, to fixate the UID/GID assignment of the record, and extract
268 additional (typically previously encrypted) user record data from the home directory. A home directory
269 mus be fixated before it can be logged into. This method call takes a user name and a JSON user record
270 consisting only of the <literal>secret</literal> section as argument. This method is equivalent to
271 <function>Fixate()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para>
272
273 <para><function>AuthenticateHome()</function> checks passwords or other authentication credentials
274 associated with the home directory. It takes a user name and a JSON user record consisting only of the
275 <literal>secret</literal> section as argument. Note that many of the other method calls authenticate
276 the user first, in order to execute some other operation. This method call only authenticates and
277 executes no further operation. Like <function>ActivateHome()</function> it is usually first invoked
278 with an empty JSON user record, which is then populated for subsequent tries with additional
279 authentication data supplied. This method is equivalent to
280 <function>Authenticate()</function> on the <classname>org.freedesktop.home1.Home</classname>
281 interface.</para>
282
283 <para><function>UpdateHome()</function> updates a locally registered user record. Takes a fully
284 specified JSON user record as argument (including the <literal>secret</literal> section). A user with a
285 matching name and realm must be registered locally already, and the last change timestamp of the newly
286 supplied record must be newer than the previously existing user record. Note this operation updates the
287 user record only, it does not propagate passwords/authentication tokens from the user record to the
288 storage back-end, or resizes the storage back-end. Typically a home directory is first updated, and then
289 the password of the underlying storage updated using <function>ChangePasswordHome()</function> as well
290 as the storage resized using <function>ResizeHome()</function>. This method is equivalent to
291 <function>Update()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para>
292
293 <para><function>ResizeHome()</function> resizes the storage associated with a user record. Takes a user
294 name, a disk size in bytes and a user record consisting only of the <literal>secret</literal> section
295 as argument. If the size is specified as <constant>UINT64_MAX</constant> the storage is resized to the
296 size already specified in the user record. Typically, if the user record is updated using
297 <function>UpdateHome()</function> above this is used to propagate the size configured there-in down to
298 the underlying storage back-end. This method is equivalent to
299 <function>Resize()</function> on the <classname>org.freedesktop.home1.Home</classname>
300 interface.</para>
301
302 <para><function>ChangePasswordHome()</function> changes the passwords/authentication tokens of a home
303 directory. Takes a user name, and two JSON user record objects, each consisting only of the
304 <literal>secret</literal> section, for the old and for the new passwords/authentication tokens. If the
305 user record with the new passwords/authentication token data is specified as empty the existing user
306 record's settings are propagated down to the home directory storage. This is typically used after a
307 user record is updated using <function>UpdateHome()</function> in order to propagate the
308 secrets/authentication tokens down to the storage. Background: depending on the backend the user's
309 authentication credentials are stored at multiple places: the user record kept on the host, the user
310 record kept in the home directory and the encrypted LUKS volume slot. If the home directory is used on
311 a different machined temporarily, and the password is changed there, and then is moved back to the
312 original host, the passwords of the three might get out of sync. By issuing
313 <function>ChangePasswordHome()</function> the three locations are updated to match the newest
314 information. This method is equivalent to <function>ChangePassword()</function> on the
315 <classname>org.freedesktop.home1.Home</classname> interface.</para>
316
317 <para><function>LockHome()</function> temporarily suspends access to a home directory, flushing out any
318 cryptographic keys from memory. This is only supported on some back-ends, and usually done during system
319 suspend, in order to effectively secure home directories while the system is sleeping. Takes a user
320 name as single argument. If an application attempts to access a home directory while it is locked it
321 will typically freeze until the home directory is unlocked again. This method is equivalent to
322 <function>Lock()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para>
323
324 <para><function>UnlockHome()</function> undoes the effect of <function>LockHome()</function>. Takes a
325 user name and a user record consisting only of the <literal>secret</literal> section as arguments. This
326 method is equivalent to <function>Unlock()</function> on the
327 <classname>org.freedesktop.home1.Home</classname> interface.</para>
328
329 <para><function>AcquireHome()</function> activates or unlocks a home directory in a reference counted
330 mode of operation. Takes a user name and user record consisting only of <literal>secret</literal>
331 section as argument. If the home directory is not active yet, it is activated. If it is currently
332 locked it is unlocked. After completion a reference to the activation/unlocking of the home directory
333 is returned via a file descriptor. When the last client which acquired such a file descriptor closes it
334 the home directory is automatically deactivated again. This method is typically invoked when a user
335 logs in, and the file descriptor is held until the user logs out again, thus ensuring the user's home
336 directory can be unmounted automatically again in a robust fashion, when the user logs out. The third
337 argument is a boolean which indicates whether the client invoking the call is able to automatically
338 re-authenticate when the system comes back from suspending. It should be set by all clients that
339 implement a secure lock screen running outside of the user's context, that is brought up when the
340 system comes back from suspend and can be used to re-acquire the credentials to unlock the user's home
341 directory. If a home directory has at least one client with an open reference to the home directory
342 that does not support this it is not suspended automatically at system suspend, otherwise it is. This
343 method is equivalent to <function>Acquire()</function> on the
344 <classname>org.freedesktop.home1.Home</classname> interface.</para>
345
346 <para><function>RefHome()</function> is similar to <function>AcquireHome()</function> but takes no user
347 record with <literal>secret</literal> section, i.e. will take an additional reference to an already
348 activated/unlocked home directory without attempting to activate/unlock it itself. It will fail if the
349 home directory is not already activated. This method is equivalent to
350 <function>Ref()</function> on the <classname>org.freedesktop.home1.Home</classname>
351 interface.</para>
352
353 <para><function>ReleaseHome()</function> releases a home directory again, if all file descriptors
354 referencing it are already closed, that where acquired through <function>AcquireHome()</function> or
355 <function>RefHome()</function>. Note that this call does not actually cause the deactivation of the
356 home directory (which happens automatically when the last referencing file descriptor is closed), but
357 is simply a synchronization mechanism that allows delaying of the user session's termination until any
358 triggered deactivation is completed. This method is equivalent to <function>Release()</function> on the
359 <classname>org.freedesktop.home1.Home</classname> interface.</para>
360
361 <para><function>LockAllHomes()</function> locks all active home directories that only have references
362 that opted into automatic suspending during system suspend. This is usually invoked automatically
363 shortly before system suspend.</para>
364
365 <para><function>DeactivateAllHomes()</function> deactivates all home areas that are currently
366 active. This is usually invoked automatically shortly before system shutdown.</para>
367
368 <para><function>Rebalance()</function> synchronously rebalances free disk space between home
369 areas. This only executes an operation if at least one home area using the LUKS2 backend is active and
370 has rebalancing enabled, and is otherwise a NOP.</para>
371 </refsect2>
372
373 <refsect2>
374 <title>Properties</title>
375
376 <para><varname>AutoLogin</varname> exposes an array of structures consisting of user name, seat name
377 and object path of an home directory object. All locally managed users that have the
378 <literal>autoLogin</literal> field set are listed here, with the seat name they are associated with. A
379 display manager may watch this property and pre-fill the login screen with the users exposed this
380 way.</para>
381 </refsect2>
382 </refsect1>
383
384 <refsect1>
385 <title>The Home Object</title>
386
387 <programlisting executable="systemd-homed" node="/org/freedesktop/home1/home" interface="org.freedesktop.home1.Home">
388 node /org/freedesktop/home1/home {
389 interface org.freedesktop.home1.Home {
390 methods:
391 @org.freedesktop.systemd1.Privileged("true")
392 Activate(in s secret);
393 @org.freedesktop.systemd1.Privileged("true")
394 Deactivate();
395 Unregister();
396 Realize(in s secret);
397 Remove();
398 @org.freedesktop.systemd1.Privileged("true")
399 Fixate(in s secret);
400 Authenticate(in s secret);
401 Update(in s user_record);
402 Resize(in t size,
403 in s secret);
404 ChangePassword(in s new_secret,
405 in s old_secret);
406 @org.freedesktop.systemd1.Privileged("true")
407 Lock();
408 @org.freedesktop.systemd1.Privileged("true")
409 Unlock(in s secret);
410 @org.freedesktop.systemd1.Privileged("true")
411 Acquire(in s secret,
412 in b please_suspend,
413 out h send_fd);
414 @org.freedesktop.systemd1.Privileged("true")
415 Ref(in b please_suspend,
416 out h send_fd);
417 @org.freedesktop.systemd1.Privileged("true")
418 Release();
419 properties:
420 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
421 readonly s UserName = '...';
422 readonly u UID = ...;
423 readonly (suusss) UnixRecord = ...;
424 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
425 readonly s State = '...';
426 @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates")
427 readonly (sb) UserRecord = ...;
428 };
429 interface org.freedesktop.DBus.Peer { ... };
430 interface org.freedesktop.DBus.Introspectable { ... };
431 interface org.freedesktop.DBus.Properties { ... };
432 interface org.freedesktop.DBus.ObjectManager { ... };
433 };
434 </programlisting>
435
436 <!--Autogenerated cross-references for systemd.directives, do not edit-->
437
438 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.DBus.ObjectManager"/>
439
440 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Home"/>
441
442 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.DBus.ObjectManager"/>
443
444 <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Home"/>
445
446 <variablelist class="dbus-method" generated="True" extra-ref="Activate()"/>
447
448 <variablelist class="dbus-method" generated="True" extra-ref="Deactivate()"/>
449
450 <variablelist class="dbus-method" generated="True" extra-ref="Unregister()"/>
451
452 <variablelist class="dbus-method" generated="True" extra-ref="Realize()"/>
453
454 <variablelist class="dbus-method" generated="True" extra-ref="Remove()"/>
455
456 <variablelist class="dbus-method" generated="True" extra-ref="Fixate()"/>
457
458 <variablelist class="dbus-method" generated="True" extra-ref="Authenticate()"/>
459
460 <variablelist class="dbus-method" generated="True" extra-ref="Update()"/>
461
462 <variablelist class="dbus-method" generated="True" extra-ref="Resize()"/>
463
464 <variablelist class="dbus-method" generated="True" extra-ref="ChangePassword()"/>
465
466 <variablelist class="dbus-method" generated="True" extra-ref="Lock()"/>
467
468 <variablelist class="dbus-method" generated="True" extra-ref="Unlock()"/>
469
470 <variablelist class="dbus-method" generated="True" extra-ref="Acquire()"/>
471
472 <variablelist class="dbus-method" generated="True" extra-ref="Ref()"/>
473
474 <variablelist class="dbus-method" generated="True" extra-ref="Release()"/>
475
476 <variablelist class="dbus-property" generated="True" extra-ref="UserName"/>
477
478 <variablelist class="dbus-property" generated="True" extra-ref="UID"/>
479
480 <variablelist class="dbus-property" generated="True" extra-ref="UnixRecord"/>
481
482 <variablelist class="dbus-property" generated="True" extra-ref="State"/>
483
484 <variablelist class="dbus-property" generated="True" extra-ref="UserRecord"/>
485
486 <!--End of Autogenerated section-->
487
488 <refsect2>
489 <title>Methods</title>
490
491 <para><function>Activate()</function>, <function>Deactivate()</function>,
492 <function>Unregister()</function>, <function>Realize()</function>, <function>Remove()</function>,
493 <function>Fixate()</function>, <function>Authenticate()</function>, <function>Update()</function>,
494 <function>Resize()</function>, <function>ChangePassword()</function>, <function>Lock()</function>,
495 <function>Unlock()</function>, <function>Acquire()</function>, <function>Ref()</function>,
496 <function>Release()</function> operate like their matching counterparts on the
497 <classname>org.freedesktop.home1.Manager</classname> interface (see above). The main difference is that
498 they are methods of the home directory objects, and hence carry no additional user name
499 parameter. Which of the two flavors of methods to call depends on the handles to the user known on the
500 client side: if only the user name is known, it's preferable to use the methods on the manager object
501 since they operate with user names only. If however the home object path was already acquired some way
502 it is preferable to operate on the <classname>org.freedesktop.home1.Home</classname> objects
503 instead.</para>
504 </refsect2>
505
506 <refsect2>
507 <title>Properties</title>
508
509 <para><varname>UserName</varname> contains the user name of the user account/home directory.</para>
510
511 <para><varname>UID</varname> contains the numeric UNIX UID of the user account.</para>
512
513 <para><varname>UnixRecord</varname> contains a structure encapsulating the six fields a
514 <structname>struct passwd</structname> typically contains (the password field is suppressed).</para>
515
516 <para><varname>State</varname> exposes the current state home the home directory.</para>
517
518 <para><varname>UserRecord</varname> contains the full JSON user record string of the user account.</para>
519 </refsect2>
520 </refsect1>
521
522 <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
523
524 <refsect1>
525 <title>See Also</title>
526 <para><simplelist type="inline">
527 <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
528 <member><citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
529 <member><citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
530 </simplelist></para>
531 </refsect1>
532
533 </refentry>