|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
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)
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);
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 { ... };
};
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
These D-Bus interfaces follow the usual interface versioning
guidelines[3].
The Manager Object
ActivateHomeIfReferenced(), RefHomeUnrestricted(), CreateHomeEx(),
and UpdateHomeEx() were added in version 256.
AdoptHome(), ListSigningKeys(), GetSigningKey(), AddSigningKey(),
and RemoveSigningKey() were added in version 258.
Home Objects
ActivateIfReferenced(), RefUnrestricted(), and UpdateEx() were
added in version 256.
systemd(1), systemd-homed.service(8), homectl(1)
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
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 2025-08-11. (At that
time, the date of the most recent commit that was found in the
repository was 2025-08-11.) 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 258~rc2 ORG.FREEDESKTOP.HOME1(5)
Pages that refer to this page: systemd.directives(7), systemd.index(7), systemd-homed.service(8)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|