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