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);
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);
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);
LockHome(in s user_name);
UnlockHome(in s user_name,
in s secret);
AcquireHome(in s user_name,
in s secret,
in b please_suspend,
out h send_fd);
RefHome(in s user_name,
in b please_suspend,
out h send_fd);
ReleaseHome(in s user_name);
LockAllHomes();
DeactivateAllHomes();
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.
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
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 RecordsActivate() method on the org.freedesktop.home1.Home interface
documented below, but may be called on the manager object and
takes a user name as additional argument, instead.
DeactivateHome() deactivates (i.e. unmounts) the home directory
of the specified user. It is equivalent to the Deactivate()
method on the org.freedesktop.home1.Home interface documented
below.
RegisterHome() registers a new home directory locally. It
receives the JSON user record as only argument (which typically
excludes the "secret" section). Registering a home directory just
makes the user record known to the system, it does not create a
home directory or such (which is expected to exist already, or
created later). This operation is useful to register home
directories locally that are not located where
systemd-homed.service would find them automatically.
UnregisterHome() unregisters an existing home directory. It takes
a user name as argument and undoes what RegisterHome() does. It
does not attempt to remove the home directory itself, it just
unregisters it with the local system. Note that if the home
directory is placed where systemd-homed.service looks for home
directories anyway this call will only undo fixation (see below),
but the record will remain known to systemd-homed.service and be
listed among known records. Since the user record is embedded
into the home directory this operation generally does not discard
data belonging to the user or their record. This method is
equivalent to Unregister() on the org.freedesktop.home1.Home
interface.
CreateHome() registers and creates a new home directory. This
takes a fully specified JSON user record as argument (including
the "secret" section). This registers the user record locally and
creates a home directory matching it, depending on the settings
specified in the record in combination with local configuration.
RealizeHome() creates a home directory whose user record is
already registered locally. This takes a user name plus a user
record consisting only of the "secret" section. Invoking
RegisterHome() followed by RealizeHome() is mostly equivalent to
calling CreateHome(), except that the latter combines the two in
atomic fashion. This method is equivalent to Realize() on the
org.freedesktop.home1.Home interface.
RemoveHome() unregisters a user record locally, and removes the
home directory belonging to it, if it is accessible. It takes a
user name as argument. This method is equivalent to Remove() on
the org.freedesktop.home1.Home interface.
FixateHome() "fixates" an automatically discovered home
directory. systemd-homed.service automatically discovers home
directories dropped in our plugged in and adds them to the
runtime list of user records it manages. A user record discovered
that way may be "fixated", in which case it is copied out of the
home directory, onto persistent storage, to fixate the UID/GID
assignment of the record, and extract additional (typically
previously encrypted) user record data from the home directory. A
home directory mus be fixated before it can be logged into. This
method call takes a user name and a JSON user record consisting
only of the "secret" section as argument. This method is
equivalent to Fixate() on the org.freedesktop.home1.Home
interface.
AuthenticateHome() checks passwords or other authentication
credentials associated with the home directory. It takes a user
name and a JSON user record consisting only of the "secret"
section as argument. Note that many of the other method calls
authenticate the user first, in order to execute some other
operation. This method call only authenticates and executes no
further operation. Like ActivateHome() it is usually first
invoked with an empty JSON user record, which is then populated
for subsequent tries with additional authentication data
supplied. This method is equivalent to Authenticate() on the
org.freedesktop.home1.Home interface.
UpdateHome() updates a locally registered user record. Takes a
fully specified JSON user record as argument (including the
"secret" section). A user with a matching name and realm must be
registered locally already, and the last change timestamp of the
newly supplied record must be newer than the previously existing
user record. Note this operation updates the user record only, it
does not propagate passwords/authentication tokens from the user
record to the storage back-end, or resizes the storage back-end.
Typically a home directory is first updated, and then the
password of the underlying storage updated using
ChangePasswordHome() as well as the storage resized using
ResizeHome(). This method is equivalent to Update() on the
org.freedesktop.home1.Home interface.
ResizeHome() resizes the storage associated with a user record.
Takes a user name, a disk size in bytes and a user record
consisting only of the "secret" section as argument. If the size
is specified as UINT64_MAX the storage is resized to the size
already specified in the user record. Typically, if the user
record is updated using UpdateHome() above this is used to
propagate the size configured there-in down to the underlying
storage back-end. This method is equivalent to Resize() on the
org.freedesktop.home1.Home interface.
ChangePasswordHome() changes the passwords/authentication tokens
of a home directory. Takes a user name, and two JSON user record
objects, each consisting only of the "secret" section, for the
old and for the new passwords/authentication tokens. If the user
record with the new passwords/authentication token data is
specified as empty the existing user record's settings are
propagated down to the home directory storage. This is typically
used after a user record is updated using UpdateHome() in order
to propagate the secrets/authentication tokens down to the
storage. This method is equivalent to ChangePassword() on the
org.freedesktop.home1.Home interface.
LockHome() temporarily suspends access to a home directory,
flushing out any cryptographic keys from memory. This is only
supported on some back-ends, and usually done during system
suspend, in order to effectively secure home directories while
the system is sleeping. Takes a user name as single argument. If
an application attempts to access a home directory while it is
locked it will typically freeze until the home directory is
unlocked again. This method is equivalent to Lock() on the
org.freedesktop.home1.Home interface.
UnlockHome() undoes the effect of LockHome(). Takes a user name
and a user record consisting only of the "secret" section as
arguments. This method is equivalent to Unlock() on the
org.freedesktop.home1.Home interface.
AcquireHome() activates or unlocks a home directory in a
reference counted mode of operation. Takes a user name and user
record consisting only of "secret" section as argument. If the
home directory is not active yet, it is activated. If it is
currently locked it is unlocked. After completion a reference to
the activation/unlocking of the home directory is returned via a
file descriptor. When the last client which acquired such a file
descriptor closes it the home directory is automatically
deactivated again. This method is typically invoked when a user
logs in, and the file descriptor is held until the user logs out
again, thus ensuring the user's home directory can be unmounted
automatically again in a robust fashion, when the user logs out.
The third argument is a boolean which indicates whether the
client invoking the call is able to automatically re-authenticate
when the system comes back from suspending. It should be set by
all clients that implement a secure lock screen running outside
of the user's context, that is brought up when the system comes
back from suspend and can be used to re-acquire the credentials
to unlock the user's home directory. If a home directory has at
least one client with an open reference to the home directory
that does not support this it is not suspended automatically at
system suspend, otherwise it is. This method is equivalent to
Acquire() on the org.freedesktop.home1.Home interface.
RefHome() is similar to AcquireHome() but takes no user record
with "secret" section, i.e. will take an additional reference to
an already activated/unlocked home directory without attempting
to activate/unlock it itself. It will fail if the home directory
is not already activated. This method is equivalent to Ref() on
the org.freedesktop.home1.Home interface.
ReleaseHome() releases a home directory again, if all file
descriptors referencing it are already closed, that where
acquired through AcquireHome() or RefHome(). Note that this call
does not actually cause the deactivation of the home directory
(which happens automatically when the last referencing file
descriptor is closed), but is simply a synchronization mechanism
that allows delaying of the user session's termination until any
triggered deactivation is completed. This method is equivalent to
Release() on the org.freedesktop.home1.Home interface.
LockAllHomes() locks all active home directories that only have
references that opted into automatic suspending during system
suspend. This is usually invoked automatically shortly before
system suspend.
DeactivateAllHomes() deactivates all home areas that are
currently active. This is usually invoked automatically shortly
before system shutdown.
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.
