out h send_fd);
@org.freedesktop.systemd1.Privileged("true")
ReleaseHome(in s user_name);
- InhibitSuspendHome(in s user_name,
- out h send_fd);
@org.freedesktop.systemd1.Privileged("true")
LockAllHomes();
@org.freedesktop.systemd1.Privileged("true")
<variablelist class="dbus-method" generated="True" extra-ref="ReleaseHome()"/>
- <variablelist class="dbus-method" generated="True" extra-ref="InhibitSuspendHome()"/>
-
<variablelist class="dbus-method" generated="True" extra-ref="LockAllHomes()"/>
<variablelist class="dbus-method" generated="True" extra-ref="DeactivateAllHomes()"/>
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>
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
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
- may be used for future expansion, but for now pass 0. This method is equivalent to <function>UpdateEx()</function>
- on the <classname>org.freedesktop.home1.Home</classname> interface.</para>
+ 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
re-authenticate when the system comes back from suspending. It should be set by all clients that
implement a secure lock screen running outside of the user's context, that is brought up when the
system comes back from suspend and can be used to re-acquire the credentials to unlock the user's home
- directory. A home directory is locked automatically at system suspend only if all clients with open
- references to the home directory specify that they support this functionality, and no client has
- temporarily inhibited it (see <function>InhibitSuspendHome()</function> below); otherwise the directory
- remains unlocked. This method is equivalent to <function>Acquire()</function> on the
+ directory. If a home directory has at least one client with an open reference to the home directory
+ that does not support this it is not suspended automatically at system suspend, otherwise it is. This
+ method is equivalent to <function>Acquire()</function> on the
<classname>org.freedesktop.home1.Home</classname> interface.</para>
<para><function>RefHome()</function> is similar to <function>AcquireHome()</function> but takes no user
triggered deactivation is completed. This method is equivalent to <function>Release()</function> on the
<classname>org.freedesktop.home1.Home</classname> interface.</para>
- <para><function>InhibitSuspendHome()</function> temporarily inhibits automatic locking during system
- suspend for a home directory. It returns a file descriptor that inhibits this functionality for as long
- as it is open. As mentioned above, locking a home directory requires a secure lock screen running
- outside of the user context, and is likely to freeze any process that attempts to access the directory.
- Thus, locking a home directory is a trade-off: it increases security, but prevents the client from
- displaying any user content on its secure lock screen, including notifications, media controls, contact
- information for incoming phone calls, and much more. A client may use this method to implement more
- complicated automatic locking behavior for home directories, in order to solve some of these UX issues.
- For instance, the client may choose to only lock the home directory and switch to the secure lock screen
- if the device has been suspended for over 24 hours. Note that this inhibitor does not prevent clients from
- calling <function>LockHome()</function>, and in fact clients will need to call <function>LockHome()</function>
- manually as part of their custom behavior to lock the home directory. Clients should take care to ensure that
- the file descriptor is closed in the event that their custom behavior fails or is disabled. This method is
- equivalent to <function>InhibitSuspend()</function> on the <classname>org.freedesktop.home1.Home</classname>
- interface.</para>
-
<para><function>LockAllHomes()</function> locks all active home directories that only have references
- that opted into automatic locking during system suspend and have no clients inhibiting this behavior.
- This is usually invoked automatically shortly before system suspend.</para>
+ that opted into automatic suspending during system suspend. This is usually invoked automatically
+ shortly before system suspend.</para>
<para><function>DeactivateAllHomes()</function> deactivates all home areas that are currently
active. This is usually invoked automatically shortly before system shutdown.</para>
out h send_fd);
@org.freedesktop.systemd1.Privileged("true")
Release();
- InhibitSuspend(out h send_fd);
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s UserName = '...';
<variablelist class="dbus-method" generated="True" extra-ref="Release()"/>
- <variablelist class="dbus-method" generated="True" extra-ref="InhibitSuspend()"/>
-
<variablelist class="dbus-property" generated="True" extra-ref="UserName"/>
<variablelist class="dbus-property" generated="True" extra-ref="UID"/>
<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>, <function>InhibitSuspend()</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>
+ <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>
<title>History</title>
<refsect2>
<title>The Manager Object</title>
- <para><function>InhibitSuspendHome()</function>, <function>ActivateHomeIfReferenced()</function>, <function>RefHomeUnrestricted()</function>,
+ <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>InhibitSuspend()</function>, <function>ActivateIfReferenced()</function>, <function>RefUnrestricted()</function>, and
+ <para><function>ActivateIfReferenced()</function>, <function>RefUnrestricted()</function>, and
<function>UpdateEx()</function> were added in version 256.</para>
</refsect2>
</refsect1>
projects / thirdparty / systemd.git / blobdiff