Provided by: systemd-homed_256.5-2ubuntu3_amd64 bug

NAME

       org.freedesktop.home1 - The D-Bus interface of systemd-homed

INTRODUCTION

       systemd-homed.service(8) is a system service which may be used to create, remove, change
       or inspect home areas. This page describes the D-Bus interface.

THE MANAGER OBJECT

       The service exposes the following interfaces on the Manager object on the bus:

           node /org/freedesktop/home1 {
             interface org.freedesktop.home1.Manager {
               methods:
                 GetHomeByName(in  s user_name,
                               out u uid,
                               out s home_state,
                               out u gid,
                               out s real_name,
                               out s home_directory,
                               out s shell,
                               out o bus_path);
                 GetHomeByUID(in  u uid,
                              out s user_name,
                              out s home_state,
                              out u gid,
                              out s real_name,
                              out s home_directory,
                              out s shell,
                              out o bus_path);
                 GetUserRecordByName(in  s user_name,
                                     out s user_record,
                                     out b incomplete,
                                     out o bus_path);
                 GetUserRecordByUID(in  u uid,
                                    out s user_record,
                                    out b incomplete,
                                    out o bus_path);
                 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 = [...];
             };
             interface org.freedesktop.DBus.Peer { ... };
             interface org.freedesktop.DBus.Introspectable { ... };
             interface org.freedesktop.DBus.Properties { ... };
           };

   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 getpwnam(3)
       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. 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.

       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[1] 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[1] 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 timeout 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.

       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.

       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.

       CreateHomeEx() is like CreateHome(), but it allows the home directory to be created with a
       pre-populated blob directory (see User Record Blob Directories[2] 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 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 (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[2] 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 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.

       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. 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 ChangePasswordHome() the three locations are updated to
       match the newest information. 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 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 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.

       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 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.

       DeactivateAllHomes() deactivates all home areas that are currently active. This is usually
       invoked automatically shortly before system shutdown.

       Rebalance() 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.

   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.

THE HOME OBJECT

           node /org/freedesktop/home1/home {
             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")
                 readonly s UserName = '...';
                 readonly u UID = ...;
                 readonly (suusss) UnixRecord = ...;
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
                 readonly s State = '...';
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("invalidates")
                 readonly (sb) UserRecord = ...;
             };
             interface org.freedesktop.DBus.Peer { ... };
             interface org.freedesktop.DBus.Introspectable { ... };
             interface org.freedesktop.DBus.Properties { ... };
             interface org.freedesktop.DBus.ObjectManager { ... };
           };

   Methods
       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.

   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

       These D-Bus interfaces follow the usual interface versioning guidelines[3].

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

       systemd(1), systemd-homed.service(8), homectl(1)

NOTES

        1. JSON User Records
           https://systemd.io/USER_RECORD

        2. User Record Blob Directories
           https://systemd.io/USER_RECORD_BLOB_DIRS

        3. the usual interface versioning guidelines
           https://0pointer.de/blog/projects/versioning-dbus.html