<?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'
ListHomes(out a(susussso) home_areas);
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);
+ @org.freedesktop.systemd1.Privileged("true")
FixateHome(in s user_name,
in s secret);
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);
ChangePasswordHome(in s user_name,
in s new_secret,
in s old_secret);
+ @org.freedesktop.systemd1.Privileged("true")
LockHome(in s user_name);
+ @org.freedesktop.systemd1.Privileged("true")
UnlockHome(in s user_name,
in s secret);
AcquireHome(in s user_name,
in s secret,
in b please_suspend,
out h send_fd);
+ @org.freedesktop.systemd1.Privileged("true")
RefHome(in s user_name,
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();
+ @org.freedesktop.systemd1.Privileged("true")
DeactivateAllHomes();
+ @org.freedesktop.systemd1.Privileged("true")
+ Rebalance();
properties:
readonly a(sso) AutoLogin = [...];
};
<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()"/>
<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()"/>
<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()"/>
<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()"/>
<variablelist class="dbus-method" generated="True" extra-ref="DeactivateAllHomes()"/>
+ <variablelist class="dbus-method" generated="True" extra-ref="Rebalance()"/>
+
<variablelist class="dbus-property" generated="True" extra-ref="AutoLogin"/>
<!--End of Autogenerated section-->
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>
<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>
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
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
user record with the new passwords/authentication token data is specified as empty the existing user
record's settings are propagated down to the home directory storage. This is typically used after a
user record is updated using <function>UpdateHome()</function> in order to propagate the
- secrets/authentication tokens down to the storage. This method is equivalent to
- <function>ChangePassword()</function> on the <classname>org.freedesktop.home1.Home</classname>
- interface.</para>
+ secrets/authentication tokens down to the storage. Background: depending on the backend the user's
+ authentication credentials are stored at multiple places: the user record kept on the host, the user
+ record kept in the home directory and the encrypted LUKS volume slot. If the home directory is used on
+ a different machined temporarily, and the password is changed there, and then is moved back to the
+ original host, the passwords of the three might get out of sync. By issuing
+ <function>ChangePasswordHome()</function> the three locations are updated to match the newest
+ information. This method is equivalent to <function>ChangePassword()</function> on the
+ <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
<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
<para><function>DeactivateAllHomes()</function> deactivates all home areas that are currently
active. This is usually invoked automatically shortly before system shutdown.</para>
+
+ <para><function>Rebalance()</function> synchronously rebalances free disk space between home
+ areas. This only executes an operation if at least one home area using the LUKS2 backend is active and
+ has rebalancing enabled, and is otherwise a NOP.</para>
</refsect2>
<refsect2>
interface org.freedesktop.home1.Home {
methods:
Activate(in s secret);
+ ActivateIfReferenced(in s secret);
+ @org.freedesktop.systemd1.Privileged("true")
Deactivate();
Unregister();
Realize(in s secret);
Remove();
+ @org.freedesktop.systemd1.Privileged("true")
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,
in s old_secret);
+ @org.freedesktop.systemd1.Privileged("true")
Lock();
+ @org.freedesktop.systemd1.Privileged("true")
Unlock(in s secret);
+ @org.freedesktop.systemd1.Privileged("true")
Acquire(in s secret,
in b please_suspend,
out h send_fd);
+ @org.freedesktop.systemd1.Privileged("true")
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")
<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()"/>
<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()"/>
<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"/>
<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>
</refsect2>
</refsect1>
- <refsect1>
- <title>Versioning</title>
+ <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/>
- <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
- the usual interface versioning guidelines</ulink>.</para>
+ <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>
projects / thirdparty / systemd.git / blobdiff