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);
99 readonly a(sso) AutoLogin = [...];
101 interface org.freedesktop.DBus.Peer { ... };
102 interface org.freedesktop.DBus.Introspectable { ... };
103 interface org.freedesktop.DBus.Properties { ... };
107 <!--Autogenerated cross-references for systemd.directives, do not edit-->
109 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.home1.Manager"/>
111 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.home1.Manager"/>
113 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetHomeByName()"/>
115 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetHomeByUID()"/>
117 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetUserRecordByName()"/>
119 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"GetUserRecordByUID()"/>
121 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ListHomes()"/>
123 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ActivateHome()"/>
125 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"DeactivateHome()"/>
127 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"RegisterHome()"/>
129 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"UnregisterHome()"/>
131 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"CreateHome()"/>
133 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"RealizeHome()"/>
135 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"RemoveHome()"/>
137 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"FixateHome()"/>
139 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"AuthenticateHome()"/>
141 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"UpdateHome()"/>
143 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ResizeHome()"/>
145 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ChangePasswordHome()"/>
147 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"LockHome()"/>
149 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"UnlockHome()"/>
151 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"AcquireHome()"/>
153 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"RefHome()"/>
155 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ReleaseHome()"/>
157 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"LockAllHomes()"/>
159 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"AutoLogin"/>
161 <!--End of Autogenerated section-->
164 <title>Methods
</title>
166 <para><function>GetHomeByName()
</function> returns basic user information (a minimal subset of the full
167 user record), provided a user name. The information supplied more or less matches what
168 <citerefentry project='man-pages'
><refentrytitle>getpwnam
</refentrytitle><manvolnum>3</manvolnum></citerefentry> returns:
169 the numeric UID and GID, the real name, home directory and shell. In addition it returns a state
170 identifier describing the state the user's home directory is in, as well as a bus path referring to the
171 bus object encapsulating the user record and home directory. This object implements the
172 <classname>org.freedesktop.home1.Home
</classname> interface documented below.
</para>
174 <para><function>GetHomeByUID()
</function> is similar to
<function>GetHomeByName()
</function> but
175 acquires the information based on the numeric UID of the user.
</para>
177 <para><function>GetUserRecordByName()
</function> is also similar to
178 <function>GetHomeByName()
</function> but returns the full JSON user record data instead of the broken
179 down records. An additional returned boolean indicates whether the record is complete or not. A record
180 is considered complete when its
<literal>privileged
</literal> section is included, and incomplete if it
181 was removed (see
<ulink url=
"https://systemd.io/USER_RECORD">JSON User Records
</ulink> for details
182 about the various sections of a user record). Generally, only privileged clients and clients running
183 under the identity of the user itself get access to the
<literal>privileged
</literal> section and will
184 thus see complete records.
</para>
186 <para><function>GetUserRecordByUID()
</function> is similar to
<function>GetUserRecordByName()
</function>
187 but returns the user record matching the specified numeric UID.
</para>
189 <para><function>ListHomes()
</function> returns an array of all locally managed users. The array
190 contains the same fields
<function>GetHomeByName()
</function> returns: user name, numeric UID, state,
191 numeric GID, real name, home directory, shell and bus path of the matching bus object.
</para>
193 <para><function>ActivateHome()
</function> activates (i.e. mounts) the home directory of the specified
194 user. The second argument shall contain a user record consisting only of a
<literal>secret
</literal>
195 section (all other sections should be stripped, see
<ulink url=
"https://systemd.io/USER_RECORD">JSON
196 User Records
</ulink> for details), and should contain only the secret credentials necessary for
197 unlocking the home directory. Typically a client would invoke this function first with an entirely
198 empty record (which is possibly sufficient if single-factor authentication with a plugged-in security
199 token is configured), and would then retry with a record populated with more information, depending on
200 the returned error code, in case more credentials are necessary. This function is synchronous and
201 returns only after the home directory was fully activated (or the operation failed), which might take
202 some time. Clients must be prepared for that, and typically should extend the D-Bus method call
203 timeout accordingly. This method is equivalent to the
<function>Activate()
</function> method on the
204 <classname>org.freedesktop.home1.Home
</classname> interface documented below, but may be called on the
205 manager object and takes a user name as additional argument, instead.
</para>
207 <para><function>DeactivateHome()
</function> deactivates (i.e. unmounts) the home directory of the
208 specified user. It is equivalent to the
<function>Deactivate()
</function> method on the
209 <classname>org.freedesktop.home1.Home
</classname> interface documented below.
</para>
211 <para><function>RegisterHome()
</function> registers a new home directory locally. It receives the JSON
212 user record as only argument (which typically excludes the
<literal>secret
</literal>
213 section). Registering a home directory just makes the user record known to the system, it does not
214 create a home directory or such (which is expected to exist already, or created later). This operation
215 is useful to register home directories locally that are not located where
216 <filename>systemd-homed.service
</filename> would find them automatically.
</para>
218 <para><function>UnregisterHome()
</function> unregisters an existing home directory. It takes a user
219 name as argument and undoes what
<function>RegisterHome()
</function> does. It does not attempt to
220 remove the home directory itself, it just unregisters it with the local system. Note that if the home
221 directory is placed where
<filename>systemd-homed.service
</filename> looks for home directories anyway
222 this call will only undo fixation (see below), but the record will remain known to
223 <filename>systemd-homed.service
</filename> and be listed among known records. Since the user record is
224 embedded into the home directory this operation generally does not discard data belonging to the user
225 or their record. This method is equivalent to
226 <function>Unregister()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
229 <para><function>CreateHome()
</function> registers and creates a new home directory. This takes a fully
230 specified JSON user record as argument (including the
<literal>secret
</literal> section). This registers
231 the user record locally and creates a home directory matching it, depending on the settings specified
232 in the record in combination with local configuration.
</para>
234 <para><function>RealizeHome()
</function> creates a home directory whose user record is already
235 registered locally. This takes a user name plus a user record consisting only of the
236 <literal>secret
</literal> section. Invoking
<function>RegisterHome()
</function> followed by
237 <function>RealizeHome()
</function> is mostly equivalent to calling
<function>CreateHome()
</function>,
238 except that the latter combines the two in atomic fashion. This method is equivalent to
239 <function>Realize()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
242 <para><function>RemoveHome()
</function> unregisters a user record locally, and removes the home
243 directory belonging to it, if it is accessible. It takes a user name as argument. This method is equivalent to
244 <function>Remove()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
247 <para><function>FixateHome()
</function> <literal>fixates
</literal> an automatically discovered home
248 directory.
<filename>systemd-homed.service
</filename> automatically discovers home directories dropped
249 in our plugged in and adds them to the runtime list of user records it manages. A user record
250 discovered that way may be
<literal>fixated
</literal>, in which case it is copied out of the home
251 directory, onto persistent storage, to fixate the UID/GID assignment of the record, and extract
252 additional (typically previously encrypted) user record data from the home directory. A home directory
253 mus be fixated before it can be logged into. This method call takes a user name and a JSON user record
254 consisting only of the
<literal>secret
</literal> section as argument. This method is equivalent to
255 <function>Fixate()
</function> on the
<classname>org.freedesktop.home1.Home
</classname> interface.
</para>
257 <para><function>AuthenticateHome()
</function> checks passwords or other authentication credentials
258 associated with the home directory. It takes a user name and a JSON user record consisting only of the
259 <literal>secret
</literal> section as argument. Note that many of the other method calls authenticate
260 the user first, in order to execute some other operation. This method call only authenticates and
261 executes no further operation. Like
<function>ActivateHome()
</function> it is usually first invoked
262 with an empty JSON user record, which is then populated for subsequent tries with additional
263 authentication data supplied. This method is equivalent to
264 <function>Authenticate()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
267 <para><function>UpdateHome()
</function> updates a locally registered user record. Takes a fully
268 specified JSON user record as argument (including the
<literal>secret
</literal> section). A user with a
269 matching name and realm must be registered locally already, and the last change timestamp of the newly
270 supplied record must be newer than the previously existing user record. Note this operation updates the
271 user record only, it does not propagate passwords/authentication tokens from the user record to the
272 storage back-end, or resizes the storage back-end. Typically a home directory is first updated, and then
273 the password of the underlying storage updated using
<function>ChangePasswordHome()
</function> as well
274 as the storage resized using
<function>ResizeHome()
</function>. This method is equivalent to
275 <function>Update()
</function> on the
<classname>org.freedesktop.home1.Home
</classname> interface.
</para>
277 <para><function>ResizeHome()
</function> resizes the storage associated with a user record. Takes a user
278 name, a disk size in bytes and a user record consisting only of the
<literal>secret
</literal> section
279 as argument. If the size is specified as
<constant>UINT64_MAX
</constant> the storage is resized to the
280 size already specified in the user record. Typically, if the user record is updated using
281 <function>UpdateHome()
</function> above this is used to propagate the size configured there-in down to
282 the underlying storage back-end. This method is equivalent to
283 <function>Resize()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
286 <para><function>ChangePasswordHome()
</function> changes the passwords/authentication tokens of a home
287 directory. Takes a user name, and two JSON user record objects, each consisting only of the
288 <literal>secret
</literal> section, for the old and for the new passwords/authentication tokens. If the
289 user record with the new passwords/authentication token data is specified as empty the existing user
290 record's settings are propagated down to the home directory storage. This is typically used after a
291 user record is updated using
<function>UpdateHome()
</function> in order to propagate the
292 secrets/authentication tokens down to the storage. This method is equivalent to
293 <function>ChangePassword()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
296 <para><function>LockHome()
</function> temporarily suspends access to a home directory, flushing out any
297 cryptographic keys from memory. This is only supported on some back-ends, and usually done during system
298 suspend, in order to effectively secure home directories while the system is sleeping. Takes a user
299 name as single argument. If an application attempts to access a home directory while it is locked it
300 will typically freeze until the home directory is unlocked again. This method is equivalent to
301 <function>Lock()
</function> on the
<classname>org.freedesktop.home1.Home
</classname> interface.
</para>
303 <para><function>UnlockHome()
</function> undoes the effect of
<function>LockHome()
</function>. Takes a
304 user name and a user record consisting only of the
<literal>secret
</literal> section as arguments. This
305 method is equivalent to
<function>Unlock()
</function> on the
306 <classname>org.freedesktop.home1.Home
</classname> interface.
</para>
308 <para><function>AcquireHome()
</function> activates or unlocks a home directory in a reference counted
309 mode of operation. Takes a user name and user record consisting only of
<literal>secret
</literal>
310 section as argument. If the home directory is not active yet, it is activated. If it is currently
311 locked it is unlocked. After completion a reference to the activation/unlocking of the home directory
312 is returned via a file descriptor. When the last client which acquired such a file descriptor closes it
313 the home directory is automatically deactivated again. This method is typically invoked when a user
314 logs in, and the file descriptor is held until the user logs out again, thus ensuring the user's home
315 directory can be unmounted automatically again in a robust fashion, when the user logs out. The third
316 argument is a boolean which indicates whether the client invoking the call is able to automatically
317 re-authenticate when the system comes back from suspending. It should be set by all clients that
318 implement a secure lock screen running outside of the user's context, that is brought up when the
319 system comes back from suspend and can be used to re-acquire the credentials to unlock the user's home
320 directory. If a home directory has at least one client with an open reference to the home directory
321 that does not support this it is not suspended automatically at system suspend, otherwise it is. This
322 method is equivalent to
<function>Acquire()
</function> on the
323 <classname>org.freedesktop.home1.Home
</classname> interface.
</para>
325 <para><function>RefHome()
</function> is similar to
<function>AcquireHome()
</function> but takes no user
326 record with
<literal>secret
</literal> section, i.e. will take an additional reference to an already
327 activated/unlocked home directory without attempting to activate/unlock it itself. It will fail if the
328 home directory is not already activated. This method is equivalent to
329 <function>Ref()
</function> on the
<classname>org.freedesktop.home1.Home
</classname>
332 <para><function>ReleaseHome()
</function> releases a home directory again, if all file descriptors
333 referencing it are already closed, that where acquired through
<function>AcquireHome()
</function> or
334 <function>RefHome()
</function>. Note that this call does not actually cause the deactivation of the
335 home directory (which happens automatically when the last referencing file descriptor is closed), but
336 is simply a synchronization mechanism that allows delaying of the user session's termination until any
337 triggered deactivation is completed. This method is equivalent to
<function>Release()
</function> on the
338 <classname>org.freedesktop.home1.Home
</classname> interface.
</para>
340 <para><function>LockAllHomes()
</function> locks all active home directories that only have references
341 that opted into automatic suspending during system suspend. This is usually invoked automatically
342 shortly before system suspend.
</para>
346 <title>Properties
</title>
348 <para><varname>AutoLogin
</varname> exposes an array of structures consisting of user name, seat name
349 and object path of an home directory object. All locally managed users that have the
350 <literal>autoLogin
</literal> field set are listed here, with the seat name they are associated with. A
351 display manager may watch this property and pre-fill the login screen with the users exposed this
357 <title>The Home Object
</title>
359 <programlisting executable=
"systemd-homed" node=
"/org/freedesktop/home1/home" interface=
"org.freedesktop.home1.Home">
360 node /org/freedesktop/home1/home {
361 interface org.freedesktop.home1.Home {
363 Activate(in s secret);
366 Realize(in s secret);
369 Authenticate(in s secret);
370 Update(in s user_record);
373 ChangePassword(in s new_secret,
380 Ref(in b please_suspend,
384 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
385 readonly s UserName = '...';
386 readonly u UID = ...;
387 readonly (suusss) UnixRecord = ...;
388 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
389 readonly s State = '...';
390 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"invalidates")
391 readonly (sb) UserRecord = ...;
393 interface org.freedesktop.DBus.Peer { ... };
394 interface org.freedesktop.DBus.Introspectable { ... };
395 interface org.freedesktop.DBus.Properties { ... };
396 interface org.freedesktop.DBus.ObjectManager { ... };
400 <!--Autogenerated cross-references for systemd.directives, do not edit-->
402 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.DBus.ObjectManager"/>
404 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.home1.Home"/>
406 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.DBus.ObjectManager"/>
408 <variablelist class=
"dbus-interface" generated=
"True" extra-ref=
"org.freedesktop.home1.Home"/>
410 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Activate()"/>
412 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Deactivate()"/>
414 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Unregister()"/>
416 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Realize()"/>
418 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Remove()"/>
420 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Fixate()"/>
422 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Authenticate()"/>
424 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Update()"/>
426 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Resize()"/>
428 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"ChangePassword()"/>
430 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Lock()"/>
432 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Unlock()"/>
434 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Acquire()"/>
436 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Ref()"/>
438 <variablelist class=
"dbus-method" generated=
"True" extra-ref=
"Release()"/>
440 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"UserName"/>
442 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"UID"/>
444 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"UnixRecord"/>
446 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"State"/>
448 <variablelist class=
"dbus-property" generated=
"True" extra-ref=
"UserRecord"/>
450 <!--End of Autogenerated section-->
453 <title>Methods
</title>
455 <para><function>Activate()
</function>,
<function>Deactivate()
</function>,
456 <function>Unregister()
</function>,
<function>Realize()
</function>,
<function>Remove()
</function>,
457 <function>Fixate()
</function>,
<function>Authenticate()
</function>,
<function>Update()
</function>,
458 <function>Resize()
</function>,
<function>ChangePassword()
</function>,
<function>Lock()
</function>,
459 <function>Unlock()
</function>,
<function>Acquire()
</function>,
<function>Ref()
</function>,
460 <function>Release()
</function> operate like their matching counterparts on the
461 <classname>org.freedesktop.home1.Manager
</classname> interface (see above). The main difference is that
462 they are methods of the home directory objects, and hence carry no additional user name
463 parameter. Which of the two flavors of methods to call depends on the handles to the user known on the
464 client side: if only the user name is known, it's preferable to use the methods on the manager object
465 since they operate with user names only. If however the home object path was already acquired some way
466 it is preferable to operate on the
<classname>org.freedesktop.home1.Home
</classname> objects
471 <title>Properties
</title>
473 <para><varname>UserName
</varname> contains the user name of the user account/home directory.
</para>
475 <para><varname>UID
</varname> contains the numeric UNIX UID of the user account.
</para>
477 <para><varname>UnixRecord
</varname> contains a structure encapsulating the six fields a
478 <structname>struct passwd
</structname> typically contains (the password field is suppressed).
</para>
480 <para><varname>State
</varname> exposes the current state home the home directory.
</para>
482 <para><varname>UserRecord
</varname> contains the full JSON user record string of the user account.
</para>
487 <title>Versioning
</title>
489 <para>These D-Bus interfaces follow
<ulink url=
"http://0pointer.de/blog/projects/versioning-dbus.html">
490 the usual interface versioning guidelines
</ulink>.
</para>
494 <title>See Also
</title>
496 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
497 <citerefentry><refentrytitle>systemd-homed.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
498 <citerefentry><refentrytitle>homectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>