man/org.freedesktop.home1.xml

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