diff options
Diffstat (limited to 'man/org.freedesktop.home1.xml')
| -rw-r--r-- | man/org.freedesktop.home1.xml | 152 |
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) << 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> |