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       ActivateHome(in  s user_name,
  67                    in  s secret);
  68       ActivateHomeIfReferenced(in  s user_name,
  69                                in  s secret);
  70       @org.freedesktop.systemd1.Privileged("true")
  71       DeactivateHome(in  s user_name);
  72       RegisterHome(in  s user_record);
  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       InhibitSuspendHome(in  s user_name,
 116                          out h send_fd);
 117       @org.freedesktop.systemd1.Privileged("true")
 118       LockAllHomes();
 119       @org.freedesktop.systemd1.Privileged("true")
 120       DeactivateAllHomes();
 121       @org.freedesktop.systemd1.Privileged("true")
 122       Rebalance();
 123     properties:
 124       readonly a(sso) AutoLogin = [...];
 125   };
 126   interface org.freedesktop.DBus.Peer { ... };
 127   interface org.freedesktop.DBus.Introspectable { ... };
 128   interface org.freedesktop.DBus.Properties { ... };
 129 };
 130     </programlisting>
 131
 132     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 133
 134     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Manager"/>
 135
 136     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Manager"/>
 137
 138     <variablelist class="dbus-method" generated="True" extra-ref="GetHomeByName()"/>
 139
 140     <variablelist class="dbus-method" generated="True" extra-ref="GetHomeByUID()"/>
 141
 142     <variablelist class="dbus-method" generated="True" extra-ref="GetUserRecordByName()"/>
 143
 144     <variablelist class="dbus-method" generated="True" extra-ref="GetUserRecordByUID()"/>
 145
 146     <variablelist class="dbus-method" generated="True" extra-ref="ListHomes()"/>
 147
 148     <variablelist class="dbus-method" generated="True" extra-ref="ActivateHome()"/>
 149
 150     <variablelist class="dbus-method" generated="True" extra-ref="ActivateHomeIfReferenced()"/>
 151
 152     <variablelist class="dbus-method" generated="True" extra-ref="DeactivateHome()"/>
 153
 154     <variablelist class="dbus-method" generated="True" extra-ref="RegisterHome()"/>
 155
 156     <variablelist class="dbus-method" generated="True" extra-ref="UnregisterHome()"/>
 157
 158     <variablelist class="dbus-method" generated="True" extra-ref="CreateHome()"/>
 159
 160     <variablelist class="dbus-method" generated="True" extra-ref="CreateHomeEx()"/>
 161
 162     <variablelist class="dbus-method" generated="True" extra-ref="RealizeHome()"/>
 163
 164     <variablelist class="dbus-method" generated="True" extra-ref="RemoveHome()"/>
 165
 166     <variablelist class="dbus-method" generated="True" extra-ref="FixateHome()"/>
 167
 168     <variablelist class="dbus-method" generated="True" extra-ref="AuthenticateHome()"/>
 169
 170     <variablelist class="dbus-method" generated="True" extra-ref="UpdateHome()"/>
 171
 172     <variablelist class="dbus-method" generated="True" extra-ref="UpdateHomeEx()"/>
 173
 174     <variablelist class="dbus-method" generated="True" extra-ref="ResizeHome()"/>
 175
 176     <variablelist class="dbus-method" generated="True" extra-ref="ChangePasswordHome()"/>
 177
 178     <variablelist class="dbus-method" generated="True" extra-ref="LockHome()"/>
 179
 180     <variablelist class="dbus-method" generated="True" extra-ref="UnlockHome()"/>
 181
 182     <variablelist class="dbus-method" generated="True" extra-ref="AcquireHome()"/>
 183
 184     <variablelist class="dbus-method" generated="True" extra-ref="RefHome()"/>
 185
 186     <variablelist class="dbus-method" generated="True" extra-ref="RefHomeUnrestricted()"/>
 187
 188     <variablelist class="dbus-method" generated="True" extra-ref="ReleaseHome()"/>
 189
 190     <variablelist class="dbus-method" generated="True" extra-ref="InhibitSuspendHome()"/>
 191
 192     <variablelist class="dbus-method" generated="True" extra-ref="LockAllHomes()"/>
 193
 194     <variablelist class="dbus-method" generated="True" extra-ref="DeactivateAllHomes()"/>
 195
 196     <variablelist class="dbus-method" generated="True" extra-ref="Rebalance()"/>
 197
 198     <variablelist class="dbus-property" generated="True" extra-ref="AutoLogin"/>
 199
 200     <!--End of Autogenerated section-->
 201
 202     <refsect2>
 203       <title>Methods</title>
 204
 205       <para><function>GetHomeByName()</function> returns basic user information (a minimal subset of the full
 206       user record), provided a user name. The information supplied more or less matches what
 207       <citerefentry project="man-pages"><refentrytitle>getpwnam</refentrytitle><manvolnum>3</manvolnum></citerefentry> returns:
 208       the numeric UID and GID, the real name, home directory and shell. In addition it returns a state
 209       identifier describing the state the user's home directory is in, as well as a bus path referring to the
 210       bus object encapsulating the user record and home directory. This object implements the
 211       <classname>org.freedesktop.home1.Home</classname> interface documented below.</para>
 212
 213       <para><function>GetHomeByUID()</function> is similar to <function>GetHomeByName()</function> but
 214       acquires the information based on the numeric UID of the user.</para>
 215
 216       <para><function>GetUserRecordByName()</function> is also similar to
 217       <function>GetHomeByName()</function> but returns the full JSON user record data instead of the broken
 218       down records. An additional returned boolean indicates whether the record is complete or not. A record
 219       is considered complete when its <literal>privileged</literal> section is included, and incomplete if it
 220       was removed (see <ulink url="https://systemd.io/USER_RECORD">JSON User Records</ulink> for details
 221       about the various sections of a user record). Generally, only privileged clients and clients running
 222       under the identity of the user itself get access to the <literal>privileged</literal> section and will
 223       thus see complete records.</para>
 224
 225       <para><function>GetUserRecordByUID()</function> is similar to <function>GetUserRecordByName()</function>
 226       but returns the user record matching the specified numeric UID.</para>
 227
 228       <para><function>ListHomes()</function> returns an array of all locally managed users. The array
 229       contains the same fields <function>GetHomeByName()</function> returns: user name, numeric UID, state,
 230       numeric GID, real name, home directory, shell and bus path of the matching bus object.</para>
 231
 232       <para><function>ActivateHome()</function> activates (i.e. mounts) the home directory of the specified
 233       user. The second argument shall contain a user record consisting only of a <literal>secret</literal>
 234       section (all other sections should be stripped, see <ulink url="https://systemd.io/USER_RECORD">JSON
 235       User Records</ulink> for details), and should contain only the secret credentials necessary for
 236       unlocking the home directory. Typically a client would invoke this function first with an entirely
 237       empty record (which is possibly sufficient if single-factor authentication with a plugged-in security
 238       token is configured), and would then retry with a record populated with more information, depending on
 239       the returned error code, in case more credentials are necessary. This function is synchronous and
 240       returns only after the home directory was fully activated (or the operation failed), which might take
 241       some time. Clients must be prepared for that, and typically should extend the D-Bus method call
 242       timeout accordingly. This method is equivalent to the <function>Activate()</function> method on the
 243       <classname>org.freedesktop.home1.Home</classname> interface documented below, but may be called on the
 244       manager object and takes a user name as additional argument, instead.</para>
 245
 246       <para><function>ActivateHomeIfReferenced()</function> is identical to
 247       <function>ActivateHome()</function>. However, the call only succeeds if the home directory is currently
 248       referenced. Useful in conjunction with <function>RefHomeUnrestricted()</function>, which allows
 249       creating a reference to a home directory even if the home directory is not active.</para>
 250
 251       <para><function>DeactivateHome()</function> deactivates (i.e. unmounts) the home directory of the
 252       specified user. It is equivalent to the <function>Deactivate()</function> method on the
 253       <classname>org.freedesktop.home1.Home</classname> interface documented below.</para>
 254
 255       <para><function>RegisterHome()</function> registers a new home directory locally. It receives the JSON
 256       user record as only argument (which typically excludes the <literal>secret</literal>
 257       section). Registering a home directory just makes the user record known to the system, it does not
 258       create a home directory or such (which is expected to exist already, or created later). This operation
 259       is useful to register home directories locally that are not located where
 260       <filename>systemd-homed.service</filename> would find them automatically.</para>
 261
 262       <para><function>UnregisterHome()</function> unregisters an existing home directory. It takes a user
 263       name as argument and undoes what <function>RegisterHome()</function> does. It does not attempt to
 264       remove the home directory itself, it just unregisters it with the local system. Note that if the home
 265       directory is placed where <filename>systemd-homed.service</filename> looks for home directories anyway
 266       this call will only undo fixation (see below), but the record will remain known to
 267       <filename>systemd-homed.service</filename> and be listed among known records. Since the user record is
 268       embedded into the home directory this operation generally does not discard data belonging to the user
 269       or their record. This method is equivalent to
 270       <function>Unregister()</function> on the <classname>org.freedesktop.home1.Home</classname>
 271       interface.</para>
 272
 273       <para><function>CreateHome()</function> registers and creates a new home directory. This takes a fully
 274       specified JSON user record as argument (including the <literal>secret</literal> section). This registers
 275       the user record locally and creates a home directory matching it, depending on the settings specified
 276       in the record in combination with local configuration.</para>
 277
 278       <para><function>CreateHomeEx()</function> is like <function>CreateHome()</function>, but it allows the
 279       home directory to be created with a pre-populated blob directory (see
 280       <ulink url="https://systemd.io/USER_RECORD_BLOB_DIRS">User Record Blob Directories</ulink> for more info).
 281       This can be done via the dictionary passed as the <varname>blobs</varname> argument to this method: the values
 282       are open file descriptors to regular files, and the keys are the filenames that should contain their respective
 283       file's data in the blob directory. Note that for security reasons, the file descriptors passed into this method
 284       must have enough privileges to read their target file and thus cannot be <literal>O_PATH</literal>; this
 285       is done to ensure the caller is actually permitted to read the file they are asking to publish in the
 286       blob directories. If the user record passed as the first argument contains a <literal>blobManifest</literal>
 287       field it will be enforced; otherwise, a <literal>blobManifest</literal> field will be generated and inserted
 288       into the record. The <varname>flags</varname> argument may be used for future expansion, but for now
 289       pass 0.</para>
 290
 291       <para><function>RealizeHome()</function> creates a home directory whose user record is already
 292       registered locally. This takes a user name plus a user record consisting only of the
 293       <literal>secret</literal> section. Invoking <function>RegisterHome()</function> followed by
 294       <function>RealizeHome()</function> is mostly equivalent to calling <function>CreateHome()</function>,
 295       except that the latter combines the two in atomic fashion. This method is equivalent to
 296       <function>Realize()</function> on the <classname>org.freedesktop.home1.Home</classname>
 297       interface.</para>
 298
 299       <para><function>RemoveHome()</function> unregisters a user record locally, and removes the home
 300       directory belonging to it, if it is accessible. It takes a user name as argument. This method is equivalent to
 301       <function>Remove()</function> on the <classname>org.freedesktop.home1.Home</classname>
 302       interface.</para>
 303
 304       <para><function>FixateHome()</function> <literal>fixates</literal> an automatically discovered home
 305       directory. <filename>systemd-homed.service</filename> automatically discovers home directories dropped
 306       in our plugged in and adds them to the runtime list of user records it manages. A user record
 307       discovered that way may be <literal>fixated</literal>, in which case it is copied out of the home
 308       directory, onto persistent storage, to fixate the UID/GID assignment of the record, and extract
 309       additional (typically previously encrypted) user record data from the home directory. A home directory
 310       mus be fixated before it can be logged into. This method call takes a user name and a JSON user record
 311       consisting only of the <literal>secret</literal> section as argument. This method is equivalent to
 312       <function>Fixate()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para>
 313
 314       <para><function>AuthenticateHome()</function> checks passwords or other authentication credentials
 315       associated with the home directory. It takes a user name and a JSON user record consisting only of the
 316       <literal>secret</literal> section as argument. Note that many of the other method calls authenticate
 317       the user first, in order to execute some other operation. This method call only authenticates and
 318       executes no further operation. Like <function>ActivateHome()</function> it is usually first invoked
 319       with an empty JSON user record, which is then populated for subsequent tries with additional
 320       authentication data supplied. This method is equivalent to
 321       <function>Authenticate()</function> on the <classname>org.freedesktop.home1.Home</classname>
 322       interface.</para>
 323
 324       <para><function>UpdateHome()</function> updates a locally registered user record. Takes a fully
 325       specified JSON user record as argument (including the <literal>secret</literal> section). A user with a
 326       matching name and realm must be registered locally already, and the last change timestamp of the newly
 327       supplied record must be newer than the previously existing user record. Note this operation updates the
 328       user record only, it does not propagate passwords/authentication tokens from the user record to the
 329       storage back-end, or resizes the storage back-end. Typically a home directory is first updated, and then
 330       the password of the underlying storage updated using <function>ChangePasswordHome()</function> as well
 331       as the storage resized using <function>ResizeHome()</function>. This method is equivalent to
 332       <function>Update()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para>
 333
 334       <para><function>UpdateHomeEx()</function> is like <function>UpdateHome()</function>, but it allows for
 335       changes to the blob directory (see <ulink url="https://systemd.io/USER_RECORD_BLOB_DIRS">User Record Blob
 336       Directories</ulink> for more info). The <varname>blobs</varname> argument works in the same way as
 337       <function>CreateHomeEx()</function>, so check there for details. The new blob directory contents passed into
 338       this method will completely replace the user's existing blob directory. The <varname>flags</varname> argument
 339       may be used for future expansion, but for now pass 0. This method is equivalent to <function>UpdateEx()</function>
 340       on the <classname>org.freedesktop.home1.Home</classname> interface.</para>
 341
 342       <para><function>ResizeHome()</function> resizes the storage associated with a user record. Takes a user
 343       name, a disk size in bytes and a user record consisting only of the <literal>secret</literal> section
 344       as argument. If the size is specified as <constant>UINT64_MAX</constant> the storage is resized to the
 345       size already specified in the user record. Typically, if the user record is updated using
 346       <function>UpdateHome()</function> above this is used to propagate the size configured there-in down to
 347       the underlying storage back-end. This method is equivalent to
 348       <function>Resize()</function> on the <classname>org.freedesktop.home1.Home</classname>
 349       interface.</para>
 350
 351       <para><function>ChangePasswordHome()</function> changes the passwords/authentication tokens of a home
 352       directory. Takes a user name, and two JSON user record objects, each consisting only of the
 353       <literal>secret</literal> section, for the old and for the new passwords/authentication tokens. If the
 354       user record with the new passwords/authentication token data is specified as empty the existing user
 355       record's settings are propagated down to the home directory storage. This is typically used after a
 356       user record is updated using <function>UpdateHome()</function> in order to propagate the
 357       secrets/authentication tokens down to the storage. Background: depending on the backend the user's
 358       authentication credentials are stored at multiple places: the user record kept on the host, the user
 359       record kept in the home directory and the encrypted LUKS volume slot. If the home directory is used on
 360       a different machined temporarily, and the password is changed there, and then is moved back to the
 361       original host, the passwords of the three might get out of sync. By issuing
 362       <function>ChangePasswordHome()</function> the three locations are updated to match the newest
 363       information. This method is equivalent to <function>ChangePassword()</function> on the
 364       <classname>org.freedesktop.home1.Home</classname> interface.</para>
 365
 366       <para><function>LockHome()</function> temporarily suspends access to a home directory, flushing out any
 367       cryptographic keys from memory. This is only supported on some back-ends, and is usually done during system
 368       suspend, in order to effectively secure home directories while the system is sleeping. Takes a user
 369       name as single argument. If an application attempts to access a home directory while it is locked it
 370       will typically freeze until the home directory is unlocked again. This method is equivalent to
 371       <function>Lock()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para>
 372
 373       <para><function>UnlockHome()</function> undoes the effect of <function>LockHome()</function>. Takes a
 374       user name and a user record consisting only of the <literal>secret</literal> section as arguments. This
 375       method is equivalent to <function>Unlock()</function> on the
 376       <classname>org.freedesktop.home1.Home</classname> interface.</para>
 377
 378       <para><function>AcquireHome()</function> activates or unlocks a home directory in a reference counted
 379       mode of operation. Takes a user name and user record consisting only of <literal>secret</literal>
 380       section as argument. If the home directory is not active yet, it is activated. If it is currently
 381       locked it is unlocked. After completion a reference to the activation/unlocking of the home directory
 382       is returned via a file descriptor. When the last client which acquired such a file descriptor closes it
 383       the home directory is automatically deactivated again. This method is typically invoked when a user
 384       logs in, and the file descriptor is held until the user logs out again, thus ensuring the user's home
 385       directory can be unmounted automatically again in a robust fashion, when the user logs out. The third
 386       argument is a boolean which indicates whether the client invoking the call is able to automatically
 387       re-authenticate when the system comes back from suspending. It should be set by all clients that
 388       implement a secure lock screen running outside of the user's context, that is brought up when the
 389       system comes back from suspend and can be used to re-acquire the credentials to unlock the user's home
 390       directory. A home directory is locked automatically at system suspend only if all clients with open
 391       references to the home directory specify that they support this functionality, and no client has
 392       temporarily inhibited it (see <function>InhibitSuspendHome()</function> below); otherwise the directory
 393       remains unlocked. This method is equivalent to <function>Acquire()</function> on the
 394       <classname>org.freedesktop.home1.Home</classname> interface.</para>
 395
 396       <para><function>RefHome()</function> is similar to <function>AcquireHome()</function> but takes no user
 397       record with <literal>secret</literal> section, i.e. will take an additional reference to an already
 398       activated/unlocked home directory without attempting to activate/unlock it itself. It will fail if the
 399       home directory is not already activated. This method is equivalent to
 400       <function>Ref()</function> on the <classname>org.freedesktop.home1.Home</classname>
 401       interface.</para>
 402
 403       <para><function>RefHomeUnrestricted()</function> is identical to <function>RefHome()</function> but
 404       succeeds even if the home area is not active currently. This is useful on conjunction with
 405       <function>ActivateHomeIfReferenced()</function>.</para>
 406
 407       <para><function>ReleaseHome()</function> releases a home directory again, if all file descriptors
 408       referencing it are already closed, that where acquired through <function>AcquireHome()</function> or
 409       <function>RefHome()</function>. Note that this call does not actually cause the deactivation of the
 410       home directory (which happens automatically when the last referencing file descriptor is closed), but
 411       is simply a synchronization mechanism that allows delaying of the user session's termination until any
 412       triggered deactivation is completed. This method is equivalent to <function>Release()</function> on the
 413       <classname>org.freedesktop.home1.Home</classname> interface.</para>
 414
 415       <para><function>InhibitSuspendHome()</function> temporarily inhibits automatic locking during system
 416       suspend for a home directory. It returns a file descriptor that inhibits this functionality for as long
 417       as it is open. As mentioned above, locking a home directory requires a secure lock screen running
 418       outside of the user context, and is likely to freeze any process that attempts to access the directory.
 419       Thus, locking a home directory is a trade-off: it increases security, but prevents the client from
 420       displaying any user content on its secure lock screen, including notifications, media controls, contact
 421       information for incoming phone calls, and much more. A client may use this method to implement more
 422       complicated automatic locking behavior for home directories, in order to solve some of these UX issues.
 423       For instance, the client may choose to only lock the home directory and switch to the secure lock screen
 424       if the device has been suspended for over 24 hours. Note that this inhibitor does not prevent clients from
 425       calling <function>LockHome()</function>, and in fact clients will need to call <function>LockHome()</function>
 426       manually as part of their custom behavior to lock the home directory. Clients should take care to ensure that
 427       the file descriptor is closed in the event that their custom behavior fails or is disabled. This method is
 428       equivalent to <function>InhibitSuspend()</function> on the <classname>org.freedesktop.home1.Home</classname>
 429       interface.</para>
 430
 431       <para><function>LockAllHomes()</function> locks all active home directories that only have references
 432       that opted into automatic locking during system suspend and have no clients inhibiting this behavior.
 433       This is usually invoked automatically shortly before system suspend.</para>
 434
 435       <para><function>DeactivateAllHomes()</function> deactivates all home areas that are currently
 436       active. This is usually invoked automatically shortly before system shutdown.</para>
 437
 438       <para><function>Rebalance()</function> synchronously rebalances free disk space between home
 439       areas. This only executes an operation if at least one home area using the LUKS2 backend is active and
 440       has rebalancing enabled, and is otherwise a NOP.</para>
 441     </refsect2>
 442
 443     <refsect2>
 444       <title>Properties</title>
 445
 446       <para><varname>AutoLogin</varname> exposes an array of structures consisting of user name, seat name
 447       and object path of an home directory object. All locally managed users that have the
 448       <literal>autoLogin</literal> field set are listed here, with the seat name they are associated with. A
 449       display manager may watch this property and pre-fill the login screen with the users exposed this
 450       way.</para>
 451     </refsect2>
 452   </refsect1>
 453
 454   <refsect1>
 455     <title>The Home Object</title>
 456
 457     <programlisting executable="systemd-homed" node="/org/freedesktop/home1/home" interface="org.freedesktop.home1.Home">
 458 node /org/freedesktop/home1/home {
 459   interface org.freedesktop.home1.Home {
 460     methods:
 461       Activate(in  s secret);
 462       ActivateIfReferenced(in  s secret);
 463       @org.freedesktop.systemd1.Privileged("true")
 464       Deactivate();
 465       Unregister();
 466       Realize(in  s secret);
 467       Remove();
 468       @org.freedesktop.systemd1.Privileged("true")
 469       Fixate(in  s secret);
 470       Authenticate(in  s secret);
 471       Update(in  s user_record);
 472       UpdateEx(in  s user_record,
 473                in  a{sh} blobs,
 474                in  t flags);
 475       Resize(in  t size,
 476              in  s secret);
 477       ChangePassword(in  s new_secret,
 478                      in  s old_secret);
 479       @org.freedesktop.systemd1.Privileged("true")
 480       Lock();
 481       @org.freedesktop.systemd1.Privileged("true")
 482       Unlock(in  s secret);
 483       @org.freedesktop.systemd1.Privileged("true")
 484       Acquire(in  s secret,
 485               in  b please_suspend,
 486               out h send_fd);
 487       @org.freedesktop.systemd1.Privileged("true")
 488       Ref(in  b please_suspend,
 489           out h send_fd);
 490       @org.freedesktop.systemd1.Privileged("true")
 491       RefUnrestricted(in  b please_suspend,
 492                       out h send_fd);
 493       @org.freedesktop.systemd1.Privileged("true")
 494       Release();
 495       InhibitSuspend(out h send_fd);
 496     properties:
 497       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
 498       readonly s UserName = '...';
 499       readonly u UID = ...;
 500       readonly (suusss) UnixRecord = ...;
 501       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
 502       readonly s State = '...';
 503       @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates")
 504       readonly (sb) UserRecord = ...;
 505   };
 506   interface org.freedesktop.DBus.Peer { ... };
 507   interface org.freedesktop.DBus.Introspectable { ... };
 508   interface org.freedesktop.DBus.Properties { ... };
 509   interface org.freedesktop.DBus.ObjectManager { ... };
 510 };
 511     </programlisting>
 512
 513     <!--Autogenerated cross-references for systemd.directives, do not edit-->
 514
 515     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.DBus.ObjectManager"/>
 516
 517     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Home"/>
 518
 519     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.DBus.ObjectManager"/>
 520
 521     <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.home1.Home"/>
 522
 523     <variablelist class="dbus-method" generated="True" extra-ref="Activate()"/>
 524
 525     <variablelist class="dbus-method" generated="True" extra-ref="ActivateIfReferenced()"/>
 526
 527     <variablelist class="dbus-method" generated="True" extra-ref="Deactivate()"/>
 528
 529     <variablelist class="dbus-method" generated="True" extra-ref="Unregister()"/>
 530
 531     <variablelist class="dbus-method" generated="True" extra-ref="Realize()"/>
 532
 533     <variablelist class="dbus-method" generated="True" extra-ref="Remove()"/>
 534
 535     <variablelist class="dbus-method" generated="True" extra-ref="Fixate()"/>
 536
 537     <variablelist class="dbus-method" generated="True" extra-ref="Authenticate()"/>
 538
 539     <variablelist class="dbus-method" generated="True" extra-ref="Update()"/>
 540
 541     <variablelist class="dbus-method" generated="True" extra-ref="UpdateEx()"/>
 542
 543     <variablelist class="dbus-method" generated="True" extra-ref="Resize()"/>
 544
 545     <variablelist class="dbus-method" generated="True" extra-ref="ChangePassword()"/>
 546
 547     <variablelist class="dbus-method" generated="True" extra-ref="Lock()"/>
 548
 549     <variablelist class="dbus-method" generated="True" extra-ref="Unlock()"/>
 550
 551     <variablelist class="dbus-method" generated="True" extra-ref="Acquire()"/>
 552
 553     <variablelist class="dbus-method" generated="True" extra-ref="Ref()"/>
 554
 555     <variablelist class="dbus-method" generated="True" extra-ref="RefUnrestricted()"/>
 556
 557     <variablelist class="dbus-method" generated="True" extra-ref="Release()"/>
 558
 559     <variablelist class="dbus-method" generated="True" extra-ref="InhibitSuspend()"/>
 560
 561     <variablelist class="dbus-property" generated="True" extra-ref="UserName"/>
 562
 563     <variablelist class="dbus-property" generated="True" extra-ref="UID"/>
 564
 565     <variablelist class="dbus-property" generated="True" extra-ref="UnixRecord"/>
 566
 567     <variablelist class="dbus-property" generated="True" extra-ref="State"/>
 568
 569     <variablelist class="dbus-property" generated="True" extra-ref="UserRecord"/>
 570
 571     <!--End of Autogenerated section-->
 572
 573     <refsect2>
 574       <title>Methods</title>
 575
 576       <para><function>Activate()</function>, <function>ActivateIfReferenced()</function>,
 577       <function>Deactivate()</function>, <function>Unregister()</function>, <function>Realize()</function>,
 578       <function>Remove()</function>, <function>Fixate()</function>, <function>Authenticate()</function>,
 579       <function>Update()</function>, <function>UpdateEx()</function>, <function>Resize()</function>,
 580       <function>ChangePassword()</function>, <function>Lock()</function>, <function>Unlock()</function>,
 581       <function>Acquire()</function>, <function>Ref()</function>, <function>RefUnrestricted()</function>,
 582       <function>Release()</function>, <function>InhibitSuspend()</function> operate like their matching counterparts
 583       on the <classname>org.freedesktop.home1.Manager</classname> interface (see above). The main difference is that
 584       they are methods of the home directory objects, and hence carry no additional user name
 585       parameter. Which of the two flavors of methods to call depends on the handles to the user known on the
 586       client side: if only the user name is known, it's preferable to use the methods on the manager object
 587       since they operate with user names only. If however the home object path was already acquired some way
 588       it is preferable to operate on the <classname>org.freedesktop.home1.Home</classname> objects
 589       instead.</para>
 590     </refsect2>
 591
 592     <refsect2>
 593       <title>Properties</title>
 594
 595       <para><varname>UserName</varname> contains the user name of the user account/home directory.</para>
 596
 597       <para><varname>UID</varname> contains the numeric UNIX UID of the user account.</para>
 598
 599       <para><varname>UnixRecord</varname> contains a structure encapsulating the six fields a
 600       <structname>struct passwd</structname> typically contains (the password field is suppressed).</para>
 601
 602       <para><varname>State</varname> exposes the current state home the home directory.</para>
 603
 604       <para><varname>UserRecord</varname> contains the full JSON user record string of the user account.</para>
 605     </refsect2>
 606   </refsect1>
 607
 608   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
 609
 610   <refsect1>
 611     <title>History</title>
 612     <refsect2>
 613       <title>The Manager Object</title>
 614       <para><function>InhibitSuspendHome()</function>, <function>ActivateHomeIfReferenced()</function>, <function>RefHomeUnrestricted()</function>,
 615       <function>CreateHomeEx()</function>, and <function>UpdateHomeEx()</function> were added in version 256.</para>
 616     </refsect2>
 617     <refsect2>
 618       <title>Home Objects</title>
 619       <para><function>InhibitSuspend()</function>, <function>ActivateIfReferenced()</function>, <function>RefUnrestricted()</function>, and
 620       <function>UpdateEx()</function> were added in version 256.</para>
 621     </refsect2>
 622   </refsect1>
 623
 624   <refsect1>
 625     <title>See Also</title>
 626     <para><simplelist type="inline">
 627       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 628       <member><citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 629       <member><citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 630     </simplelist></para>
 631   </refsect1>
 632
 633 </refentry>