man/org.freedesktop.home1.xml

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