The following commands are understood:
list
List all home directories (along with brief details)
currently managed by systemd-homed.service. This command is
also executed if none is specified on the command line. (Note
that the list of users shown by this command does not include
users managed by other subsystems, such as system users or
any traditional users listed in /etc/passwd.)
activate USER [USER...]
Activate one or more home directories. The home directories
of each listed user will be activated and made available
under their mount points (typically in /home/$USER). Note
that any home activated this way stays active indefinitely,
until it is explicitly deactivated again (with deactivate,
see below), or the user logs in and out again and it thus is
deactivated due to the automatic deactivation-on-logout
logic.
Activation of a home directory involves various operations
that depend on the selected storage mechanism. If the LUKS2
mechanism is used, this generally involves: inquiring the
user for a password, setting up a loopback device, validating
and activating the LUKS2 volume, checking the file system,
mounting the file system, and potentially changing the
ownership of all included files to the correct UID/GID.
deactivate USER [USER...]
Deactivate one or more home directories. This undoes the
effect of activate.
inspect USER [USER...]
Show various details about the specified home directories.
This shows various information about the home directory and
its user account, including runtime data such as current
state, disk use and similar. Combine with --json= to show the
detailed JSON user record instead, possibly combined with
--export-format= to suppress certain aspects of the output.
authenticate USER [USER...]
Validate authentication credentials of a home directory. This
queries the caller for a password (or similar) and checks
that it correctly unlocks the home directory. This leaves the
home directory in the state it is in, i.e. it leaves the home
directory in inactive state if it was inactive before, and in
active state if it was active before.
create USER, create --identity=PATH [USER]
Create a new home directory/user account of the specified
name. Use the various user record property options (as
documented above) to control various aspects of the home
directory and its user accounts.
The specified user name should follow the strict syntax
described on User/Group Name Syntax
remove USER
Remove a home directory/user account. This will remove both
the home directory's user record and the home directory
itself, and thus delete all files and directories owned by
the user.
update USER, update --identity=PATH [USER]
Update a home directory/user account. Use the various user
record property options (as documented above) to make changes
to the account, or alternatively provide a full, updated JSON
user record via the --identity= option.
Note that changes to user records not signed by a
cryptographic private key available locally are not
permitted, unless --identity= is used with a user record that
is already correctly signed by a recognized private key.
passwd USER
Change the password of the specified home directory/user
account.
resize USER BYTES
Change the disk space assigned to the specified home
directory. If the LUKS2 storage mechanism is used this will
automatically resize the loopback file and the file system
contained within. Note that if "ext4" is used inside of the
LUKS2 volume, it is necessary to deactivate the home
directory before shrinking it (i.e the user has to log out).
Growing can be done while the home directory is active. If
"xfs" is used inside of the LUKS2 volume the home directory
may not be shrunk whatsoever. On all three of "ext4", "xfs"
and "btrfs" the home directory may be grown while the user is
logged in, and on the latter also shrunk while the user is
logged in. If the "subvolume", "directory", "fscrypt" storage
mechanisms are used, resizing will change file system quota.
lock USER
Temporarily suspend access to the user's home directory and
remove any associated cryptographic keys from memory. Any
attempts to access the user's home directory will stall until
the home directory is unlocked again (i.e. re-authenticated).
This functionality is primarily intended to be used during
system suspend to make sure the user's data cannot be
accessed until the user re-authenticates on resume. This
operation is only defined for home directories that use the
LUKS2 storage mechanism.
unlock USER
Resume access to the user's home directory again, undoing the
effect of lock above. This requires authentication of the
user, as the cryptographic keys required for access to the
home directory need to be reacquired.
lock-all
Execute the lock command on all suitable home directories at
once. This operation is generally executed on system suspend
(i.e. by systemctl suspend and related commands), to ensure
all active user's cryptographic keys for accessing their home
directories are removed from memory.
deactivate-all
Execute the deactivate command on all active home directories
at once. This operation is generally executed on system shut
down (i.e. by systemctl poweroff and related commands), to
ensure all active user's home directories are fully
deactivated before /home/ and related file systems are
unmounted.
with USER COMMAND...
Activate the specified user's home directory, run the
specified command (under the caller's identity, not the
specified user's) and deactivate the home directory
afterwards again (unless the user is logged in otherwise).
This command is useful for running privileged backup scripts
and such, but requires authentication with the user's
credentials in order to be able to unlock the user's home
directory.
