2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"org.freedesktop.home1" conditional='ENABLE_HOMED'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
9 <title>org.freedesktop.home1
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>org.freedesktop.home1
</refentrytitle>
15 <manvolnum>5</manvolnum>
19 <refname>org.freedesktop.home1
</refname>
20 <refpurpose>The D-Bus interface of systemd-homed
</refpurpose>
24 <title>Introduction
</title>
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.
33 <title>The Manager Object
</title>
35 <para>The service exposes the following interfaces on the Manager object on the bus:
</para>
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 {
41 GetHomeByName(in s user_name,
49 GetHomeByUID(in u uid,
57 GetUserRecordByName(in s user_name,
61 GetUserRecordByUID(in u uid,
65 ListHomes(out a(susussso) home_areas);
66 ActivateHome(in s user_name,
68 DeactivateHome(in s user_name);
69 RegisterHome(in s user_record);
70 UnregisterHome(in s user_name);
71 CreateHome(in s user_record);
72 RealizeHome(in s user_name,
74 RemoveHome(in s user_name);
75 FixateHome(in s user_name,
77 AuthenticateHome(in s user_name,
79 UpdateHome(in s user_record);
80 ResizeHome(in s user_name,
83 ChangePasswordHome(in s user_name,
86 LockHome(in s user_name);
87 UnlockHome(in s user_name,
89 AcquireHome(in s user_name,
93 RefHome(in s user_name,
96 ReleaseHome(in s user_name);
100 readonly a(sso) AutoLogin = [...];
102 interface org.freedesktop.DBus.Peer { ... };
103 interface org.freedesktop.DBus.Introspectable { ... };
104 interface org.freedesktop.DBus.Properties { ... };
108 <!--Autogenerated cross-references for systemd.directives, do not edit-->
110 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.home1.Manager"/>
112 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.home1.Manager"/>
114 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetHomeByName()"/>
116 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetHomeByUID()"/>
118 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetUserRecordByName()"/>
120 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetUserRecordByUID()"/>
122 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ListHomes()"/>
124 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ActivateHome()"/>
126 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"DeactivateHome()"/>
128 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"RegisterHome()"/>
130 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"UnregisterHome()"/>
132 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CreateHome()"/>
134 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"RealizeHome()"/>
136 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"RemoveHome()"/>
138 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"FixateHome()"/>
140 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"AuthenticateHome()"/>
142 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"UpdateHome()"/>
144 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ResizeHome()"/>
146 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ChangePasswordHome()"/>
148 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"LockHome()"/>
150 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"UnlockHome()"/>
152 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"AcquireHome()"/>
154 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"RefHome()"/>
156 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ReleaseHome()"/>
158 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"LockAllHomes()"/>
160 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"DeactivateAllHomes()"/>
162 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"AutoLogin"/>
164 <!--End of Autogenerated section-->
167 <title>Methods
</title>
169 <para><function>GetHomeByName()
</function> returns basic user information (a minimal subset of the full
170 user record), provided a user name. The information supplied more or less matches what
171 <citerefentry project=
"man-pages"><refentrytitle>getpwnam
</refentrytitle><manvolnum>3</manvolnum></citerefentry> returns:
172 the numeric UID and GID, the real name, home directory and shell. In addition it returns a state
173 identifier describing the state the user's home directory is in, as well as a bus path referring to the
174 bus object encapsulating the user record and home directory. This object implements the
175 <classname>org.freedesktop.home1.Home
</classname> interface documented below.
</para>
177 <para><function>GetHomeByUID()
</function> is similar to
<function>GetHomeByName()
</function> but
178 acquires the information based on the numeric UID of the user.
</para>
180 <para><function>GetUserRecordByName()
</function> is also similar to
181 <function>GetHomeByName()
</function> but returns the full JSON user record data instead of the broken
182 down records. An additional returned boolean indicates whether the record is complete or not. A record
183 is considered complete when its
<literal>privileged
</literal> section is included, and incomplete if it
184 was removed (see
<ulink url=
"https://systemd.io/USER_RECORD">JSON User Records
</ulink> for details
185 about the various sections of a user record). Generally, only privileged clients and clients running
186 under the identity of the user itself get access to the
<literal>privileged
</literal> section and will
187 thus see complete records.
</para>
189 <para><function>GetUserRecordByUID()
</function> is similar to
<function>GetUserRecordByName()
</function>
190 but returns the user record matching the specified numeric UID.
</para>
192 <para><function>ListHomes()
</function> returns an array of all locally managed users. The array
193 contains the same fields
<function>GetHomeByName()
</function> returns: user name, numeric UID, state,
194 numeric GID, real name, home directory, shell and bus path of the matching bus object.
</para>
196 <para><function>ActivateHome()
</function> activates (i.e. mounts) the home directory of the specified
197 user. The second argument shall contain a user record consisting only of a
<literal>secret
</literal>
198 section (all other sections should be stripped, see
<ulink url=
"https://systemd.io/USER_RECORD">JSON
199 User Records
</ulink> for details), and should contain only the secret credentials necessary for
200 unlocking the home directory. Typically a client would invoke this function first with an entirely
201 empty record (which is possibly sufficient if single-factor authentication with a plugged-in security
202 token is configured), and would then retry with a record populated with more information, depending on
203 the returned error code, in case more credentials are necessary. This function is synchronous and
204 returns only after the home directory was fully activated (or the operation failed), which might take
205 some time. Clients must be prepared for that, and typically should extend the D-Bus method call
206 timeout accordingly. This method is equivalent to the
<function>Activate()
</function> method on the
207 <classname>org.freedesktop.home1.Home
</classname> interface documented below, but may be called on the
208 manager object and takes a user name as additional argument, instead.
</para>
210 <para><function>DeactivateHome()
</function> deactivates (i.e. unmounts) the home directory of the
211 specified user. It is equivalent to the
<function>Deactivate()
</function> method on the
212 <classname>org.freedesktop.home1.Home
</classname> interface documented below.
</para>
214 <para><function>RegisterHome()
</function> registers a new home directory locally. It receives the JSON
215 user record as only argument (which typically excludes the
<literal>secret
</literal>
216 section). Registering a home directory just makes the user record known to the system, it does not
217 create a home directory or such (which is expected to exist already, or created later). This operation
218 is useful to register home directories locally that are not located where
219 <filename>systemd-homed.service
</filename> would find them automatically.
</para>
221 <para><function>UnregisterHome()
</function> unregisters an existing home directory. It takes a user
222 name as argument and undoes what
<function>RegisterHome()
</function> does. It does not attempt to
223 remove the home directory itself, it just unregisters it with the local system. Note that if the home
224 directory is placed where
<filename>systemd-homed.service
</filename> looks for home directories anyway
225 this call will only undo fixation (see below), but the record will remain known to
226 <filename>systemd-homed.service
</filename> and be listed among known records. Since the user record is
227 embedded into the home directory this operation generally does not discard data belonging to the user
228 or their record. This method is equivalent to
229 <function>Unregister()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
232 <para><function>CreateHome()
</function> registers and creates a new home directory. This takes a fully
233 specified JSON user record as argument (including the
<literal>secret
</literal> section). This registers
234 the user record locally and creates a home directory matching it, depending on the settings specified
235 in the record in combination with local configuration.
</para>
237 <para><function>RealizeHome()
</function> creates a home directory whose user record is already
238 registered locally. This takes a user name plus a user record consisting only of the
239 <literal>secret
</literal> section. Invoking
<function>RegisterHome()
</function> followed by
240 <function>RealizeHome()
</function> is mostly equivalent to calling
<function>CreateHome()
</function>,
241 except that the latter combines the two in atomic fashion. This method is equivalent to
242 <function>Realize()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
245 <para><function>RemoveHome()
</function> unregisters a user record locally, and removes the home
246 directory belonging to it, if it is accessible. It takes a user name as argument. This method is equivalent to
247 <function>Remove()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
250 <para><function>FixateHome()
</function> <literal>fixates
</literal> an automatically discovered home
251 directory.
<filename>systemd-homed.service
</filename> automatically discovers home directories dropped
252 in our plugged in and adds them to the runtime list of user records it manages. A user record
253 discovered that way may be
<literal>fixated
</literal>, in which case it is copied out of the home
254 directory, onto persistent storage, to fixate the UID/GID assignment of the record, and extract
255 additional (typically previously encrypted) user record data from the home directory. A home directory
256 mus be fixated before it can be logged into. This method call takes a user name and a JSON user record
257 consisting only of the
<literal>secret
</literal> section as argument. This method is equivalent to
258 <function>Fixate()
</function> on the
<classname>org.freedesktop.home1.Home
</classname> interface.
</para>
260 <para><function>AuthenticateHome()
</function> checks passwords or other authentication credentials
261 associated with the home directory. It takes a user name and a JSON user record consisting only of the
262 <literal>secret
</literal> section as argument. Note that many of the other method calls authenticate
263 the user first, in order to execute some other operation. This method call only authenticates and
264 executes no further operation. Like
<function>ActivateHome()
</function> it is usually first invoked
265 with an empty JSON user record, which is then populated for subsequent tries with additional
266 authentication data supplied. This method is equivalent to
267 <function>Authenticate()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
270 <para><function>UpdateHome()
</function> updates a locally registered user record. Takes a fully
271 specified JSON user record as argument (including the
<literal>secret
</literal> section). A user with a
272 matching name and realm must be registered locally already, and the last change timestamp of the newly
273 supplied record must be newer than the previously existing user record. Note this operation updates the
274 user record only, it does not propagate passwords/authentication tokens from the user record to the
275 storage back-end, or resizes the storage back-end. Typically a home directory is first updated, and then
276 the password of the underlying storage updated using
<function>ChangePasswordHome()
</function> as well
277 as the storage resized using
<function>ResizeHome()
</function>. This method is equivalent to
278 <function>Update()
</function> on the
<classname>org.freedesktop.home1.Home
</classname> interface.
</para>
280 <para><function>ResizeHome()
</function> resizes the storage associated with a user record. Takes a user
281 name, a disk size in bytes and a user record consisting only of the
<literal>secret
</literal> section
282 as argument. If the size is specified as
<constant>UINT64_MAX
</constant> the storage is resized to the
283 size already specified in the user record. Typically, if the user record is updated using
284 <function>UpdateHome()
</function> above this is used to propagate the size configured there-in down to
285 the underlying storage back-end. This method is equivalent to
286 <function>Resize()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
289 <para><function>ChangePasswordHome()
</function> changes the passwords/authentication tokens of a home
290 directory. Takes a user name, and two JSON user record objects, each consisting only of the
291 <literal>secret
</literal> section, for the old and for the new passwords/authentication tokens. If the
292 user record with the new passwords/authentication token data is specified as empty the existing user
293 record's settings are propagated down to the home directory storage. This is typically used after a
294 user record is updated using
<function>UpdateHome()
</function> in order to propagate the
295 secrets/authentication tokens down to the storage. This method is equivalent to
296 <function>ChangePassword()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
299 <para><function>LockHome()
</function> temporarily suspends access to a home directory, flushing out any
300 cryptographic keys from memory. This is only supported on some back-ends, and usually done during system
301 suspend, in order to effectively secure home directories while the system is sleeping. Takes a user
302 name as single argument. If an application attempts to access a home directory while it is locked it
303 will typically freeze until the home directory is unlocked again. This method is equivalent to
304 <function>Lock()
</function> on the
<classname>org.freedesktop.home1.Home
</classname> interface.
</para>
306 <para><function>UnlockHome()
</function> undoes the effect of
<function>LockHome()
</function>. Takes a
307 user name and a user record consisting only of the
<literal>secret
</literal> section as arguments. This
308 method is equivalent to
<function>Unlock()
</function> on the
309 <classname>org.freedesktop.home1.Home
</classname> interface.
</para>
311 <para><function>AcquireHome()
</function> activates or unlocks a home directory in a reference counted
312 mode of operation. Takes a user name and user record consisting only of
<literal>secret
</literal>
313 section as argument. If the home directory is not active yet, it is activated. If it is currently
314 locked it is unlocked. After completion a reference to the activation/unlocking of the home directory
315 is returned via a file descriptor. When the last client which acquired such a file descriptor closes it
316 the home directory is automatically deactivated again. This method is typically invoked when a user
317 logs in, and the file descriptor is held until the user logs out again, thus ensuring the user's home
318 directory can be unmounted automatically again in a robust fashion, when the user logs out. The third
319 argument is a boolean which indicates whether the client invoking the call is able to automatically
320 re-authenticate when the system comes back from suspending. It should be set by all clients that
321 implement a secure lock screen running outside of the user's context, that is brought up when the
322 system comes back from suspend and can be used to re-acquire the credentials to unlock the user's home
323 directory. If a home directory has at least one client with an open reference to the home directory
324 that does not support this it is not suspended automatically at system suspend, otherwise it is. This
325 method is equivalent to
<function>Acquire()
</function> on the
326 <classname>org.freedesktop.home1.Home
</classname> interface.
</para>
328 <para><function>RefHome()
</function> is similar to
<function>AcquireHome()
</function> but takes no user
329 record with
<literal>secret
</literal> section, i.e. will take an additional reference to an already
330 activated/unlocked home directory without attempting to activate/unlock it itself. It will fail if the
331 home directory is not already activated. This method is equivalent to
332 <function>Ref()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
335 <para><function>ReleaseHome()
</function> releases a home directory again, if all file descriptors
336 referencing it are already closed, that where acquired through
<function>AcquireHome()
</function> or
337 <function>RefHome()
</function>. Note that this call does not actually cause the deactivation of the
338 home directory (which happens automatically when the last referencing file descriptor is closed), but
339 is simply a synchronization mechanism that allows delaying of the user session's termination until any
340 triggered deactivation is completed. This method is equivalent to
<function>Release()
</function> on the
341 <classname>org.freedesktop.home1.Home
</classname> interface.
</para>
343 <para><function>LockAllHomes()
</function> locks all active home directories that only have references
344 that opted into automatic suspending during system suspend. This is usually invoked automatically
345 shortly before system suspend.
</para>
347 <para><function>DeactivateAllHomes()
</function> deactivates all home areas that are currently
348 active. This is usually invoked automatically shortly before system shutdown.
</para>
352 <title>Properties
</title>
354 <para><varname>AutoLogin
</varname> exposes an array of structures consisting of user name, seat name
355 and object path of an home directory object. All locally managed users that have the
356 <literal>autoLogin
</literal> field set are listed here, with the seat name they are associated with. A
357 display manager may watch this property and pre-fill the login screen with the users exposed this
363 <title>The Home Object
</title>
365 <programlisting executable=
"systemd-homed" node=
"/org/freedesktop/home1/home" interface=
"org.freedesktop.home1.Home">
366 node /org/freedesktop/home1/home {
367 interface org.freedesktop.home1.Home {
369 Activate(in s secret);
372 Realize(in s secret);
375 Authenticate(in s secret);
376 Update(in s user_record);
379 ChangePassword(in s new_secret,
386 Ref(in b please_suspend,
390 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
391 readonly s UserName = '...';
392 readonly u UID = ...;
393 readonly (suusss) UnixRecord = ...;
394 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
395 readonly s State = '...';
396 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"invalidates")
397 readonly (sb) UserRecord = ...;
399 interface org.freedesktop.DBus.Peer { ... };
400 interface org.freedesktop.DBus.Introspectable { ... };
401 interface org.freedesktop.DBus.Properties { ... };
402 interface org.freedesktop.DBus.ObjectManager { ... };
406 <!--Autogenerated cross-references for systemd.directives, do not edit-->
408 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.DBus.ObjectManager"/>
410 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.home1.Home"/>
412 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.DBus.ObjectManager"/>
414 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.home1.Home"/>
416 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Activate()"/>
418 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Deactivate()"/>
420 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Unregister()"/>
422 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Realize()"/>
424 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Remove()"/>
426 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Fixate()"/>
428 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Authenticate()"/>
430 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Update()"/>
432 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Resize()"/>
434 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ChangePassword()"/>
436 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Lock()"/>
438 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Unlock()"/>
440 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Acquire()"/>
442 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Ref()"/>
444 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Release()"/>
446 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"UserName"/>
448 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"UID"/>
450 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"UnixRecord"/>
452 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"State"/>
454 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"UserRecord"/>
456 <!--End of Autogenerated section-->
459 <title>Methods
</title>
461 <para><function>Activate()
</function>,
<function>Deactivate()
</function>,
462 <function>Unregister()
</function>,
<function>Realize()
</function>,
<function>Remove()
</function>,
463 <function>Fixate()
</function>,
<function>Authenticate()
</function>,
<function>Update()
</function>,
464 <function>Resize()
</function>,
<function>ChangePassword()
</function>,
<function>Lock()
</function>,
465 <function>Unlock()
</function>,
<function>Acquire()
</function>,
<function>Ref()
</function>,
466 <function>Release()
</function> operate like their matching counterparts on the
467 <classname>org.freedesktop.home1.Manager
</classname> interface (see above). The main difference is that
468 they are methods of the home directory objects, and hence carry no additional user name
469 parameter. Which of the two flavors of methods to call depends on the handles to the user known on the
470 client side: if only the user name is known, it's preferable to use the methods on the manager object
471 since they operate with user names only. If however the home object path was already acquired some way
472 it is preferable to operate on the
<classname>org.freedesktop.home1.Home
</classname> objects
477 <title>Properties
</title>
479 <para><varname>UserName
</varname> contains the user name of the user account/home directory.
</para>
481 <para><varname>UID
</varname> contains the numeric UNIX UID of the user account.
</para>
483 <para><varname>UnixRecord
</varname> contains a structure encapsulating the six fields a
484 <structname>struct passwd
</structname> typically contains (the password field is suppressed).
</para>
486 <para><varname>State
</varname> exposes the current state home the home directory.
</para>
488 <para><varname>UserRecord
</varname> contains the full JSON user record string of the user account.
</para>
493 <title>Versioning
</title>
495 <para>These D-Bus interfaces follow
<ulink url=
"http://0pointer.de/blog/projects/versioning-dbus.html">
496 the usual interface versioning guidelines
</ulink>.
</para>
500 <title>See Also
</title>
502 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
503 <citerefentry><refentrytitle>systemd-homed.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
504 <citerefentry><refentrytitle>homectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>