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