org.freedesktop.home1
systemd
org.freedesktop.home1
5
org.freedesktop.home1
The D-Bus interface of systemd-homed
Introduction
systemd-homed.service8
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
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. 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 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
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 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 (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
may be used for future expansion, but for now pass 0. 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
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.
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