From fc53809803cd2bc2434e312b19a18fa36776da12 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 12 Jun 2024 05:50:40 +0200 Subject: Adding upstream version 256. Signed-off-by: Daniel Baumann --- man/org.freedesktop.home1.xml | 152 +++++++++++++++++++++++++++++++++--------- 1 file changed, 119 insertions(+), 33 deletions(-) (limited to 'man/org.freedesktop.home1.xml') 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 @@ + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" > + + @@ -142,6 +155,8 @@ node /org/freedesktop/home1 { + + @@ -152,6 +167,8 @@ node /org/freedesktop/home1 { + + @@ -164,6 +181,8 @@ node /org/freedesktop/home1 { + + @@ -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 - org.freedesktop.home1.Home interface documented below. + org.freedesktop.home1.Home 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. GetHomeByUID() is similar to GetHomeByName() but acquires the information based on the numeric UID of the user. @@ -220,6 +241,11 @@ node /org/freedesktop/home1 { org.freedesktop.home1.Home interface documented below, but may be called on the manager object and takes a user name as additional argument, instead. + ActivateHomeIfReferenced() is identical to + ActivateHome(). However, the call only succeeds if the home directory is currently + referenced. Useful in conjunction with RefHomeUnrestricted(), which allows + creating a reference to a home directory even if the home directory is not active. + DeactivateHome() deactivates (i.e. unmounts) the home directory of the specified user. It is equivalent to the Deactivate() method on the org.freedesktop.home1.Home interface documented below. @@ -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. + CreateHomeEx() is like CreateHome(), but it allows the + home directory to be created with a pre-populated blob directory (see + User Record Blob Directories for more info). + This can be done via the dictionary passed as the blobs 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 O_PATH; 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 blobManifest + field it will be enforced; otherwise, a blobManifest field will be generated and inserted + into the record. The flags argument may be used for future expansion, but for now + pass 0. + RealizeHome() creates a home directory whose user record is already registered locally. This takes a user name plus a user record consisting only of the secret section. Invoking RegisterHome() followed by @@ -281,23 +320,38 @@ node /org/freedesktop/home1 { interface. UpdateHome() updates a locally registered user record. Takes a fully - specified JSON user record as argument (including the secret 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 secret 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 ChangePasswordHome() as well as the storage resized using ResizeHome(). This method is equivalent to Update() on the org.freedesktop.home1.Home interface. + UpdateHomeEx() is like UpdateHome(), but it allows for + changes to the blob directory (see User Record Blob + Directories for more info). The blobs argument works in the same way as + CreateHomeEx(), so check there for details. The new blob directory contents passed into + this method will completely replace the user's existing blob directory. The flags argument + can be used to further customize the behavior of this method via flags defined as follows: + +#define SD_HOMED_UPDATE_OFFLINE (UINT64_C(1) << 0) + + When SD_HOMED_UPDATE_OFFLINE (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 + UpdateEx() on the org.freedesktop.home1.Home interface. + ResizeHome() 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 secret section - as argument. If the size is specified as UINT64_MAX 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 secret + section as arguments. If the size is specified as UINT64_MAX the storage is resized to + the size already specified in the user record. Typically, if the user record is updated using UpdateHome() above this is used to propagate the size configured there-in down to - the underlying storage back-end. This method is equivalent to - Resize() on the org.freedesktop.home1.Home - interface. + the underlying storage back-end. This method is equivalent to Resize() on the + org.freedesktop.home1.Home interface. ChangePasswordHome() 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 { org.freedesktop.home1.Home interface. LockHome() 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 { Ref() on the org.freedesktop.home1.Home interface. + RefHomeUnrestricted() is identical to RefHome() but + succeeds even if the home area is not active currently. This is useful on conjunction with + ActivateHomeIfReferenced(). + ReleaseHome() releases a home directory again, if all file descriptors referencing it are already closed, that where acquired through AcquireHome() or RefHome(). 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 { + + @@ -459,6 +525,8 @@ node /org/freedesktop/home1/home { + + @@ -471,6 +539,8 @@ node /org/freedesktop/home1/home { + + @@ -488,19 +558,21 @@ node /org/freedesktop/home1/home { Methods - Activate(), Deactivate(), - Unregister(), Realize(), Remove(), - Fixate(), Authenticate(), Update(), - Resize(), ChangePassword(), Lock(), - Unlock(), Acquire(), Ref(), - Release() operate like their matching counterparts on the - org.freedesktop.home1.Manager 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 org.freedesktop.home1.Home objects - instead. + Activate(), ActivateIfReferenced(), + Deactivate(), Unregister(), Realize(), + Remove(), Fixate(), Authenticate(), + Update(), UpdateEx(), Resize(), + ChangePassword(), Lock(), Unlock(), + Acquire(), Ref(), RefUnrestricted(), + Release(), + operate like their matching counterparts on the org.freedesktop.home1.Manager + 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 org.freedesktop.home1.Home objects instead. @@ -521,13 +593,27 @@ node /org/freedesktop/home1/home { + + History + + The Manager Object + ActivateHomeIfReferenced(), RefHomeUnrestricted(), + CreateHomeEx(), and UpdateHomeEx() were added in version 256. + + + Home Objects + ActivateIfReferenced(), RefUnrestricted(), and + UpdateEx() were added in version 256. + + + See Also - - systemd1, - systemd-homed.service8, - homectl1 - + + systemd1 + systemd-homed.service8 + homectl1 + -- cgit v1.2.3