| ORG.FREEDESKTOP.HOME1(5) | org.freedesktop.home1 | ORG.FREEDESKTOP.HOME1(5) |
.SH "NAME" org.freedesktop.home1 - The D-Bus interface of
systemd-homed
.SH "INTRODUCTION"
.PP 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.
.SH "THE MANAGER OBJECT"
.PP 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);
AdoptHome(in s image_path,
in t flags);
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);
ListSigningKeys(out a(sst) keys);
GetSigningKey(in s name,
out s der,
out t flags);
AddSigningKey(in s name,
in s pem,
in t flags);
RemoveSigningKey(in s name,
in t flags);
@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 { ... };
};
.SS "Methods"
.PP 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.
.PP GetHomeByUID() is similar to GetHomeByName() but acquires
the information based on the numeric UID of the user.
.PP 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.
.PP GetUserRecordByUID() is similar to GetUserRecordByName()
but returns the user record matching the specified numeric UID.
.PP 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.
.PP 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.
.PP 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.
.PP 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.
.PP 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.
.PP AdoptHome() also registers a new home directory locally. It takes
a path to a home directory itself, and will register it locally. This only
works for *.home and *.homedir/ home directories. This operation is done
automatically for all such home areas showing up in /home/, but may be
requested explicitly with this call for directories elsewhere. The
flags must be set to zero, currently.
.PP 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.
.PP 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.
.PP 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.
.PP 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.
.PP 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.
.PP 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.
.PP 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.
.PP 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.
.PP 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)
.PP 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.
.PP 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.
.PP 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.
.PP 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.
.PP 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.
.PP 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.
.PP 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.
.PP RefHomeUnrestricted() is identical to RefHome() but
succeeds even if the home area is not active currently. This is useful on
conjunction with ActivateHomeIfReferenced().
.PP 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.
.PP 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.
.PP DeactivateAllHomes() deactivates all home areas that are currently
active. This is usually invoked automatically shortly before system
shutdown.
.PP 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.
.PP ListSigningKeys() acquires a list of installed home area signing
keys. Returns an array of key names with their PEM encoded public key data.
Each entry also comes with a flags value which is currently unused and
should be ignored by clients.
.PP GetSigningKey() acquires the PEM encoded public part of the
specified home area signing key of the specified name. Also returns a
currently unused flags value that should be ignored. The flags
parameter must be set to zero, currently.
.PP AddSigningKey() adds a new key to the list of home area signing
keys. Takes a name string (free-form, suitable as filename, with suffix
.public), the PEM encoded public key data and a currently unused flags value
that must be zero. The flags parameter must be set to zero,
currently.
.PP RemoveSigningKey() removes a key from the list of home area
signing keys. Takes the name of the key to remove and a currently unused
flags value that must be zero. The flags parameter must be set to
zero, currently.
.SS "Properties"
.PP 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.
.SH "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 { ... };
};
.SS "Methods"
.PP 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 is 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.
.SS "Properties"
.PP UserName contains the user name of the user account/home
directory.
.PP UID contains the numeric UNIX UID of the user account.
.PP UnixRecord contains a structure encapsulating the six fields a
struct passwd typically contains (the password field is suppressed).
.PP State exposes the current state home the home directory.
.PP UserRecord contains the full JSON user record string of the user
account.
.SH "VERSIONING"
.PP These D-Bus interfaces follow the usual interface versioning
guidelines[3].
.SH "HISTORY"
.SS "The Manager Object"
.PP ActivateHomeIfReferenced(), RefHomeUnrestricted(),
CreateHomeEx(), and UpdateHomeEx() were added in version
256.
.PP AdoptHome(), ListSigningKeys(), GetSigningKey(),
AddSigningKey(), and RemoveSigningKey() were added in version
258.
.SS "Home Objects"
.PP ActivateIfReferenced(), RefUnrestricted(), and
UpdateEx() were added in version 256.
.SH "SEE ALSO"
.PP systemd(1), systemd-homed.service(8), homectl(1)
NOTES
- 1.
- JSON User Records
- 2.
- User Record Blob Directories
- 3.
- the usual interface versioning guidelines
| systemd 262.2 |