diff --git a/man/org.freedesktop.home1.xml b/man/org.freedesktop.home1.xml
index 3f1094595a..e7d12a031e 100644
--- a/man/org.freedesktop.home1.xml
+++ b/man/org.freedesktop.home1.xml
@@ -23,8 +23,7 @@
Introduction
-
- systemd-homed.service8
+ systemd-homed.service8
is a system service which may be used to to create, remove, change or inspect home areas. This page
describes the D-Bus interface.
@@ -105,54 +104,6 @@ node /org/freedesktop/home1 {
};
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
@@ -212,13 +163,193 @@ node /org/freedesktop/home1 {
Methods
- ...
+ GetHomeByName() returns basic user information (a minimal subset of the full
+ user record), provided a user name. The information supplied more or less matches what
+ getpwnam3 returns:
+ 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.
+
+ GetHomeByUID() is similar to GetHomeByName() but
+ acquires the information based on the numeric UID of the user.
+
+ GetUserRecordByName() is also similar to
+ GetHomeByName() but returns the full JSON user record data instead of the broken
+ down records. An additional returned boolean indicates whether the record is complete or not. A record
+ is considered complete when its privileged section is included, and incomplete if it
+ was removed (see JSON User Records for details
+ about the various sections of a user record). Generally, only privileged clients and clients running
+ under the identity of the user itself get access to the privileged section and will
+ thus see complete records.
+
+ GetUserRecordByUID() is similar to GetUserRecordByName()
+ but returns the user record matching the specified numeric UID.
+
+ ListHomes() returns an array of all locally managed users. The array
+ contains the same fields GetHomeByName() returns: user name, numeric UID, state,
+ numeric GID, real name, home directory, shell and bus path of the matching bus object.
+
+ ActivateHome() activates (i.e. mounts) the home directory of the specified
+ user. The second argument shall contain a user record consisting only of a secret
+ section (all other sections should be stripped, see JSON
+ User Records for details), and should contain only the secret credentials necessary for
+ unlocking the home directory. Typically a client would invoke this function first with an entirely
+ empty record (which is possibly sufficient if single-factor authentication with a plugged-in security
+ token is configured), and would then retry with a record populated with more information, depending on
+ the returned error code, in case more credentials are necessary. This function is synchronous and
+ returns only after the home directory was fully activated (or the operation failed), which might take
+ some time. Clients must be prepared for that, and typically should extend the D-Bus method call
+ time-out accordingly. This method is equivalent to the Activate() method on the
+ org.freedesktop.home1.Home interface documented below, but may be called on the
+ manager object and takes a user name as additional argument, instead.
+
+ 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.
+
+ RegisterHome() registers a new home directory locally. It receives the JSON
+ user record as only argument (which typically excludes the secret
+ section). Registering a home directory just makes the user record known to the system, it does not
+ create a home directory or such (which is expected to exist already, or created later). This operation
+ is useful to register home directories locally that are not located where
+ systemd-homed.service would find them automatically.
+
+ UnregisterHome() unregisters an existing home directory. It takes a user
+ name as argument and undoes what RegisterHome() does. It does not attempt to
+ remove the home directory itself, it just unregisters it with the local system. Note that if the home
+ directory is placed where systemd-homed.service looks for home directories anyway
+ this call will only undo fixation (see below), but the record will remain known to
+ systemd-homed.service and be listed among known records. Since the user record is
+ embedded into the home directory this operation generally does not discard data belonging to the user
+ or their record. This method is equivalent to
+ Unregister() on the org.freedesktop.home1.Home
+ interface.
+
+ CreateHome() registers and creates a new home directory. This takes a fully
+ specified JSON user record as argument (including the secret section. This registers
+ the user record locally and creates a home directory matching it, depending on the settings specified
+ in the record in combination with local configuration.
+
+ 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
+ RealizeHome() is mostly equivalent to calling CreateHome(),
+ except that the latter combines the two in atomic fashion. This method is equivalent to
+ Realize() on the org.freedesktop.home1.Home
+ interface.
+
+ RemoveHome() unregisters a user record locally, and removes the home
+ directory belonging to it, if it is accessible. It takes a user name as argument. This method is equivalent to
+ Remove() on the org.freedesktop.home1.Home
+ interface.
+
+ FixateHome() fixates an automatically discovered home
+ directory. systemd-homed.service automatically discovers home directories dropped
+ in our plugged in and adds them to the runtime list of user records it manages. A user record
+ discovered that way may be fixated, in which case it is copied out of the home
+ directory, onto persistent storage, to fixate the UID/GID assignment of the record, and extract
+ additional (typically previously encrypted) user record data from the home directory. A home directory
+ mus be fixated before it can be logged into. This method call takes a user name and a JSON user record
+ consisting only of the secret section as argument. This method is equivalent to
+ Fixate() on the org.freedesktop.home1.Home interface.
+
+ AuthenticateHome() checks passwords or other authentication credentials
+ associated with the home directory. It takes a user name and a JSON user record consisting only of the
+ secret section as argument. Note that many of the other method calls authenticate
+ the user first, in order to execute some other operation. This method call only authenticates and
+ executes no further operation. Like ActivateHome() it is usually first invoked
+ with an empty JSON user record, which is then populated for subsequent tries with additional
+ authentication data supplied. This method is equivalent to
+ Authenticate() on the org.freedesktop.home1.Home
+ 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
+ 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.
+
+ 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
+ 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.
+
+ 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
+ secret section, for the old and for the new passwords/authentication tokens. If 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 UpdateHome() in order to propagate the
+ secrets/authentication tokens down to the storage. This method is equivalent to
+ ChangePassword() on the 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
+ 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
+ Lock() on the org.freedesktop.home1.Home interface.
+
+ UnlockHome() undoes the effect of LockHome(). Takes a
+ user name and a user record consisting only of the secret section as arguments. This
+ method is equivalent to Unlock() on the
+ org.freedesktop.home1.Home interface.
+
+ AcquireHome() activates or unlocks a home directory in a reference counted
+ mode of operation. Takes a user name and user record consisting only of secret
+ section as argument. If the home directory is not active yet, it is activated. If it is currently
+ locked it is unlocked. After completion a reference to the activation/unlocking of the home directory
+ is returned via a file descriptor. When the last client which acquired such a file descriptor closes it
+ the home directory is automatically deactivated again. This method is typically invoked when a user
+ logs in, and the file descriptor is held until the user logs out again, thus ensuring the user's home
+ directory can be unmounted automatically again in a robust fashion, when the user logs out. The third
+ argument is a boolean which indicates whether the client invoking the call is able to automatically
+ 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. 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 Acquire() on the
+ org.freedesktop.home1.Home interface.
+
+ RefHome() is similar to AcquireHome() but takes no user
+ record with secret section, i.e. will take an additional reference to an already
+ activated/unlocked home directory without attempting to activate/unlock it itself. It will fail if the
+ home directory is not already activated. This method is equivalent to
+ Ref() on the org.freedesktop.home1.Home
+ interface.
+
+ 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
+ home directory (which happens automatically when the last referencing file descriptor is closed), but
+ is simply a synchronization mechanism that allows delaying of the user session's termination until any
+ triggered deactivation is completed. This method is equivalent to Release() on the
+ org.freedesktop.home1.Home interface.
+
+ LockAllHomes() locks all active home directories that only have references
+ that opted into automatic suspending during system suspend. This is usually invoked automatically
+ shortly before system suspend.
- Signals
+ Properties
- ...
+ AutoLogin exposes an array of structures consisting of user name, seat name
+ and object path of an home directory object. All locally managed users that have the
+ autoLogin field set are listed here, with the seat name they are associated with. A
+ display manager may watch this property and pre-fill the login screen with the users exposed this
+ way.
@@ -266,46 +397,6 @@ node /org/freedesktop/home1/home {
};
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
@@ -358,7 +449,39 @@ 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.
+
+
+
+ Properties
+
+ UserName contains the user name of the user account/home directory.
+
+ UID contains the numeric UNIX UID of the user account.
+
+ UnixRecord contains a structure encapsulating the six fields a
+ struct passwd typically contains (the password field is suppressed).
+
+ State exposes the current state home the home directory.
+
+ UserRecord contains the full JSON user record string of the user account.
+
+
Versioning
@@ -366,4 +489,14 @@ node /org/freedesktop/home1/home {
These D-Bus interfaces follow
the usual interface versioning guidelines.
+
+
+ See Also
+
+ systemd1,
+ systemd-homed.service8,
+ homectl1
+
+
+
diff --git a/man/systemd-homed.service.xml b/man/systemd-homed.service.xml
index 049b7e9097..ab8bcab8cb 100644
--- a/man/systemd-homed.service.xml
+++ b/man/systemd-homed.service.xml
@@ -103,7 +103,8 @@
homed.conf5,
homectl1,
pam_systemd_home8,
- userdbctl1
+ userdbctl1,
+ org.freedesktop.home15