Merging upstream version 256.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 119 insertions, 33 deletions

diff --git a/man/org.freedesktop.home1.xml b/man/org.freedesktop.home1.xml
index f217fb8..9334f1a 100644
--- a/man/org.freedesktop.home1.xml
+++ b/man/org.freedesktop.home1.xml
@@ -1,6 +1,6 @@
 <?xml version='1.0'?>
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" >
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
 
 <refentry id="org.freedesktop.home1" conditional='ENABLE_HOMED'
@@ -63,14 +63,18 @@ node /org/freedesktop/home1 {
                          out b incomplete,
                          out o bus_path);
       ListHomes(out a(susussso) home_areas);
-      @org.freedesktop.systemd1.Privileged("true")
       ActivateHome(in  s user_name,
                    in  s secret);
+      ActivateHomeIfReferenced(in  s user_name,
+                               in  s secret);
       @org.freedesktop.systemd1.Privileged("true")
       DeactivateHome(in  s user_name);
       RegisterHome(in  s user_record);
       UnregisterHome(in  s user_name);
       CreateHome(in  s user_record);
+      CreateHomeEx(in  s user_record,
+                   in  a{sh} blobs,
+                   in  t flags);
       RealizeHome(in  s user_name,
                   in  s secret);
       RemoveHome(in  s user_name);
@@ -80,6 +84,9 @@ node /org/freedesktop/home1 {
       AuthenticateHome(in  s user_name,
                        in  s secret);
       UpdateHome(in  s user_record);
+      UpdateHomeEx(in  s user_record,
+                   in  a{sh} blobs,
+                   in  t flags);
       ResizeHome(in  s user_name,
                  in  t size,
                  in  s secret);
@@ -100,6 +107,10 @@ node /org/freedesktop/home1 {
               in  b please_suspend,
               out h send_fd);
       @org.freedesktop.systemd1.Privileged("true")
+      RefHomeUnrestricted(in  s user_name,
+                          in  b please_suspend,
+                          out h send_fd);
+      @org.freedesktop.systemd1.Privileged("true")
       ReleaseHome(in  s user_name);
       @org.freedesktop.systemd1.Privileged("true")
       LockAllHomes();
@@ -134,6 +145,8 @@ node /org/freedesktop/home1 {
 
     <variablelist class="dbus-method" generated="True" extra-ref="ActivateHome()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="ActivateHomeIfReferenced()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="DeactivateHome()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="RegisterHome()"/>
@@ -142,6 +155,8 @@ node /org/freedesktop/home1 {
 
     <variablelist class="dbus-method" generated="True" extra-ref="CreateHome()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="CreateHomeEx()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="RealizeHome()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="RemoveHome()"/>
@@ -152,6 +167,8 @@ node /org/freedesktop/home1 {
 
     <variablelist class="dbus-method" generated="True" extra-ref="UpdateHome()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="UpdateHomeEx()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="ResizeHome()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="ChangePasswordHome()"/>
@@ -164,6 +181,8 @@ node /org/freedesktop/home1 {
 
     <variablelist class="dbus-method" generated="True" extra-ref="RefHome()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="RefHomeUnrestricted()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="ReleaseHome()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="LockAllHomes()"/>
@@ -185,7 +204,9 @@ node /org/freedesktop/home1 {
       the numeric UID and GID, the real name, home directory and shell. In addition it returns a state
       identifier describing the state the user's home directory is in, as well as a bus path referring to the
       bus object encapsulating the user record and home directory. This object implements the
-      <classname>org.freedesktop.home1.Home</classname> interface documented below.</para>
+      <classname>org.freedesktop.home1.Home</classname> interface documented below. This method, and most others
+      in this interface that take user names, will try to use the caller's home area if the specified user name is
+      an empty string.</para>
 
       <para><function>GetHomeByUID()</function> is similar to <function>GetHomeByName()</function> but
       acquires the information based on the numeric UID of the user.</para>
@@ -220,6 +241,11 @@ node /org/freedesktop/home1 {
       <classname>org.freedesktop.home1.Home</classname> interface documented below, but may be called on the
       manager object and takes a user name as additional argument, instead.</para>
 
+      <para><function>ActivateHomeIfReferenced()</function> is identical to
+      <function>ActivateHome()</function>. However, the call only succeeds if the home directory is currently
+      referenced. Useful in conjunction with <function>RefHomeUnrestricted()</function>, which allows
+      creating a reference to a home directory even if the home directory is not active.</para>
+
       <para><function>DeactivateHome()</function> deactivates (i.e. unmounts) the home directory of the
       specified user. It is equivalent to the <function>Deactivate()</function> method on the
       <classname>org.freedesktop.home1.Home</classname> interface documented below.</para>
@@ -247,6 +273,19 @@ node /org/freedesktop/home1 {
       the user record locally and creates a home directory matching it, depending on the settings specified
       in the record in combination with local configuration.</para>
 
+      <para><function>CreateHomeEx()</function> is like <function>CreateHome()</function>, but it allows the
+      home directory to be created with a pre-populated blob directory (see
+      <ulink url="https://systemd.io/USER_RECORD_BLOB_DIRS">User Record Blob Directories</ulink> for more info).
+      This can be done via the dictionary passed as the <varname>blobs</varname> argument to this method: the values
+      are open file descriptors to regular files, and the keys are the filenames that should contain their respective
+      file's data in the blob directory. Note that for security reasons, the file descriptors passed into this method
+      must have enough privileges to read their target file and thus cannot be <literal>O_PATH</literal>; this
+      is done to ensure the caller is actually permitted to read the file they are asking to publish in the
+      blob directories. If the user record passed as the first argument contains a <literal>blobManifest</literal>
+      field it will be enforced; otherwise, a <literal>blobManifest</literal> field will be generated and inserted
+      into the record. The <varname>flags</varname> argument may be used for future expansion, but for now
+      pass 0.</para>
+
       <para><function>RealizeHome()</function> creates a home directory whose user record is already
       registered locally. This takes a user name plus a user record consisting only of the
       <literal>secret</literal> section. Invoking <function>RegisterHome()</function> followed by
@@ -281,23 +320,38 @@ node /org/freedesktop/home1 {
       interface.</para>
 
       <para><function>UpdateHome()</function> updates a locally registered user record. Takes a fully
-      specified JSON user record as argument (including the <literal>secret</literal> section). A user with a
-      matching name and realm must be registered locally already, and the last change timestamp of the newly
-      supplied record must be newer than the previously existing user record. Note this operation updates the
-      user record only, it does not propagate passwords/authentication tokens from the user record to the
+      specified JSON user record as argument (possibly including the <literal>secret</literal> section). A user
+      with a matching name and realm must be registered locally already, and the last change timestamp of the
+      newly supplied record must be newer than the previously existing user record. Note this operation updates
+      the user record only, it does not propagate passwords/authentication tokens from the user record to the
       storage back-end, or resizes the storage back-end. Typically a home directory is first updated, and then
       the password of the underlying storage updated using <function>ChangePasswordHome()</function> as well
       as the storage resized using <function>ResizeHome()</function>. This method is equivalent to
       <function>Update()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para>
 
+      <para><function>UpdateHomeEx()</function> is like <function>UpdateHome()</function>, but it allows for
+      changes to the blob directory (see <ulink url="https://systemd.io/USER_RECORD_BLOB_DIRS">User Record Blob
+      Directories</ulink> for more info). The <varname>blobs</varname> argument works in the same way as
+      <function>CreateHomeEx()</function>, so check there for details. The new blob directory contents passed into
+      this method will completely replace the user's existing blob directory. The <varname>flags</varname> argument
+      can be used to further customize the behavior of this method via flags defined as follows:</para>
+      <programlisting>
+#define SD_HOMED_UPDATE_OFFLINE (UINT64_C(1) &lt;&lt; 0)
+      </programlisting>
+      <para>When <constant>SD_HOMED_UPDATE_OFFLINE</constant> (0x01) is set, no attempt is made to update the copies
+      of the user record and blob directory that are embedded into the home directory. Changes will be stored, however,
+      and may be propagated into the home directory the next time it is reconciled (most likely when the user next logs in).
+      Note that any changes made with this flag set may be lost if the home area has a newer record, which can happen
+      if the home area is updated on another machine after this method call. This method is equivalent to
+      <function>UpdateEx()</function> on the <classname>org.freedesktop.home1.Home</classname> interface.</para>
+
       <para><function>ResizeHome()</function> resizes the storage associated with a user record. Takes a user
-      name, a disk size in bytes and a user record consisting only of the <literal>secret</literal> section
-      as argument. If the size is specified as <constant>UINT64_MAX</constant> the storage is resized to the
-      size already specified in the user record. Typically, if the user record is updated using
+      name, a disk size in bytes, and optionally a user record consisting only of the <literal>secret</literal>
+      section as arguments. If the size is specified as <constant>UINT64_MAX</constant> the storage is resized to
+      the size already specified in the user record. Typically, if the user record is updated using
       <function>UpdateHome()</function> above this is used to propagate the size configured there-in down to
-      the underlying storage back-end. This method is equivalent to
-      <function>Resize()</function> on the <classname>org.freedesktop.home1.Home</classname>
-      interface.</para>
+      the underlying storage back-end. This method is equivalent to <function>Resize()</function> on the
+      <classname>org.freedesktop.home1.Home</classname> interface.</para>
 
       <para><function>ChangePasswordHome()</function> changes the passwords/authentication tokens of a home
       directory. Takes a user name, and two JSON user record objects, each consisting only of the
@@ -315,7 +369,7 @@ node /org/freedesktop/home1 {
       <classname>org.freedesktop.home1.Home</classname> interface.</para>
 
       <para><function>LockHome()</function> temporarily suspends access to a home directory, flushing out any
-      cryptographic keys from memory. This is only supported on some back-ends, and usually done during system
+      cryptographic keys from memory. This is only supported on some back-ends, and is usually done during system
       suspend, in order to effectively secure home directories while the system is sleeping. Takes a user
       name as single argument. If an application attempts to access a home directory while it is locked it
       will typically freeze until the home directory is unlocked again. This method is equivalent to
@@ -350,6 +404,10 @@ node /org/freedesktop/home1 {
       <function>Ref()</function> on the <classname>org.freedesktop.home1.Home</classname>
       interface.</para>
 
+      <para><function>RefHomeUnrestricted()</function> is identical to <function>RefHome()</function> but
+      succeeds even if the home area is not active currently. This is useful on conjunction with
+      <function>ActivateHomeIfReferenced()</function>.</para>
+
       <para><function>ReleaseHome()</function> releases a home directory again, if all file descriptors
       referencing it are already closed, that where acquired through <function>AcquireHome()</function> or
       <function>RefHome()</function>. Note that this call does not actually cause the deactivation of the
@@ -388,8 +446,8 @@ node /org/freedesktop/home1 {
 node /org/freedesktop/home1/home {
   interface org.freedesktop.home1.Home {
     methods:
-      @org.freedesktop.systemd1.Privileged("true")
       Activate(in  s secret);
+      ActivateIfReferenced(in  s secret);
       @org.freedesktop.systemd1.Privileged("true")
       Deactivate();
       Unregister();
@@ -399,6 +457,9 @@ node /org/freedesktop/home1/home {
       Fixate(in  s secret);
       Authenticate(in  s secret);
       Update(in  s user_record);
+      UpdateEx(in  s user_record,
+               in  a{sh} blobs,
+               in  t flags);
       Resize(in  t size,
              in  s secret);
       ChangePassword(in  s new_secret,
@@ -415,6 +476,9 @@ node /org/freedesktop/home1/home {
       Ref(in  b please_suspend,
           out h send_fd);
       @org.freedesktop.systemd1.Privileged("true")
+      RefUnrestricted(in  b please_suspend,
+                      out h send_fd);
+      @org.freedesktop.systemd1.Privileged("true")
       Release();
     properties:
       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
@@ -445,6 +509,8 @@ node /org/freedesktop/home1/home {
 
     <variablelist class="dbus-method" generated="True" extra-ref="Activate()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="ActivateIfReferenced()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="Deactivate()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="Unregister()"/>
@@ -459,6 +525,8 @@ node /org/freedesktop/home1/home {
 
     <variablelist class="dbus-method" generated="True" extra-ref="Update()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="UpdateEx()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="Resize()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="ChangePassword()"/>
@@ -471,6 +539,8 @@ node /org/freedesktop/home1/home {
 
     <variablelist class="dbus-method" generated="True" extra-ref="Ref()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="RefUnrestricted()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="Release()"/>
 
     <variablelist class="dbus-property" generated="True" extra-ref="UserName"/>
@@ -488,19 +558,21 @@ node /org/freedesktop/home1/home {
     <refsect2>
       <title>Methods</title>
 
-      <para><function>Activate()</function>, <function>Deactivate()</function>,
-      <function>Unregister()</function>, <function>Realize()</function>, <function>Remove()</function>,
-      <function>Fixate()</function>, <function>Authenticate()</function>, <function>Update()</function>,
-      <function>Resize()</function>, <function>ChangePassword()</function>, <function>Lock()</function>,
-      <function>Unlock()</function>, <function>Acquire()</function>, <function>Ref()</function>,
-      <function>Release()</function> operate like their matching counterparts on the
-      <classname>org.freedesktop.home1.Manager</classname> interface (see above). The main difference is that
-      they are methods of the home directory objects, and hence carry no additional user name
-      parameter. Which of the two flavors of methods to call depends on the handles to the user known on the
-      client side: if only the user name is known, it's preferable to use the methods on the manager object
-      since they operate with user names only. If however the home object path was already acquired some way
-      it is preferable to operate on the <classname>org.freedesktop.home1.Home</classname> objects
-      instead.</para>
+      <para><function>Activate()</function>, <function>ActivateIfReferenced()</function>,
+      <function>Deactivate()</function>, <function>Unregister()</function>, <function>Realize()</function>,
+      <function>Remove()</function>, <function>Fixate()</function>, <function>Authenticate()</function>,
+      <function>Update()</function>, <function>UpdateEx()</function>, <function>Resize()</function>,
+      <function>ChangePassword()</function>, <function>Lock()</function>, <function>Unlock()</function>,
+      <function>Acquire()</function>, <function>Ref()</function>, <function>RefUnrestricted()</function>,
+      <function>Release()</function>,
+      operate like their matching counterparts on the <classname>org.freedesktop.home1.Manager</classname>
+      interface (see above). The main difference is that they are methods of the home directory objects, and
+      hence carry no additional user name parameter. Which of the two flavors of methods to call depends on
+      the handles to the user known on the client side: if only the user name is known, it's preferable to use
+      the methods on the manager object since they operate with user names only. Clients can also easily operate
+      on their own home area by using the methods on the manager object with an empty string as the user name.
+      If the client has the home's object path already acquired in some way, however, it is preferable to operate
+      on the <classname>org.freedesktop.home1.Home</classname> objects instead.</para>
     </refsect2>
 
     <refsect2>
@@ -522,12 +594,26 @@ node /org/freedesktop/home1/home {
   <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
 
   <refsect1>
+    <title>History</title>
+    <refsect2>
+      <title>The Manager Object</title>
+      <para><function>ActivateHomeIfReferenced()</function>, <function>RefHomeUnrestricted()</function>,
+      <function>CreateHomeEx()</function>, and <function>UpdateHomeEx()</function> were added in version 256.</para>
+    </refsect2>
+    <refsect2>
+      <title>Home Objects</title>
+      <para><function>ActivateIfReferenced()</function>, <function>RefUnrestricted()</function>, and
+      <function>UpdateEx()</function> were added in version 256.</para>
+    </refsect2>
+  </refsect1>
+
+  <refsect1>
     <title>See Also</title>
-    <para>
-      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    </para>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+    </simplelist></para>
   </refsect1>
 
 </refentry>