org.freedesktop.home1 - The D-Bus interface of systemd-homed
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 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);
@org.freedesktop.systemd1.Privileged("true")
ActivateHome(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);
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);
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")
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 { ... };
};
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.
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.
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.
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 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.
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.
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.
node /org/freedesktop/home1/home {
interface org.freedesktop.home1.Home {
methods:
@org.freedesktop.systemd1.Privileged("true")
Activate(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);
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")
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 { ... };
};
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.
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.
These D-Bus interfaces follow
the usual interface versioning
guidelines[2].
systemd(1),
systemd-homed.service(8),
homectl(1)
- 1.
- JSON User Records
- 2.
- the usual interface versioning guidelines