org.freedesktop.home1(5) — Linux manual page

NAME | INTRODUCTION | THE MANAGER OBJECT | THE HOME OBJECT | VERSIONING | HISTORY | SEE ALSO | NOTES | COLOPHON

ORG.FREEDESKTOP.HOME1(5)  org.freedesktop.home1 ORG.FREEDESKTOP.HOME1(5)

NAME         top

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

INTRODUCTION         top

       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         top

       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         top

           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         top

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

HISTORY         top

   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         top

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

NOTES         top

        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

COLOPHON         top

       This page is part of the systemd (systemd system and service
       manager) project.  Information about the project can be found at
       ⟨http://www.freedesktop.org/wiki/Software/systemd⟩.  If you have
       a bug report for this manual page, see
       ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://github.com/systemd/systemd.git⟩ on 2024-06-14.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2024-06-13.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

systemd 257~devel                               ORG.FREEDESKTOP.HOME1(5)

Pages that refer to this page: systemd.directives(7)systemd.index(7)systemd-homed.service(8)