homectl

List user accounts and their associated home directories

$ homectl list

$ sudo homectl create [username]

$ sudo homectl remove [username]

$ sudo homectl passwd [username]

$ sudo homectl with [username] -- [command] [command_arguments]

$ sudo homectl [lock|unlock] [username]

$ sudo homectl resize [username] [100G]

$ homectl [[-h|--help]]

homectl [OPTIONS...] COMMAND [ARGS...]

--help, -h
    Show a help message and exit.

--version
    Show version information and exit.

--json=pretty|short|off
    Control JSON output format for machine-readable data.

--root=PATH
    Operate on a specified root directory instead of the system's default.

--no-pager
    Do not pipe output into a pager.

--dry-run
    Show what would be done without actually making changes.

--no-ask-password
    Do not ask for user password interactively when creating/updating. Requires password to be passed via properties or environment.

status
    Show the current status of the systemd-homed.service and managed users.

create USER
    Create a new user account managed by systemd-homed.

remove USER
    Remove a user account and their home directory.

activate USER
    Activate (mount) a user's home directory. This is usually done automatically on login.

deactivate USER
    Deactivate (unmount) a user's home directory. This is usually done automatically on logout.

update USER
    Update properties of an existing user account (e.g., password, full name, shell).

password USER
    Change the password for a user account.

inspect USER
    Display properties and details of a user account.

resize USER
    Resize the image file used for a user's home directory.

import PATH
    Import a user account from an exported file.

export USER PATH
    Export a user account and its data to a specified file.

homectl is a command-line utility used to create, manage, and inspect user accounts and their associated home directories when managed by the systemd-homed.service. It provides a modern approach to user and home directory management, supporting features like encrypted home directories (often using LUKS), stateless setups, and various authentication methods such as FIDO2, PKCS#11, and traditional passwords.

The tool allows administrators to perform operations like creating new users, activating/deactivating home directories, changing user passwords, resizing home directory images, importing/exporting user accounts, and inspecting user properties. It's designed to simplify the complexities of secure and flexible home directory management in contemporary Linux environments.

homectl relies on the systemd-homed.service to be running and enabled. It manages user accounts differently from traditional methods like useradd/usermod, focusing on encrypted and ephemeral home directories. Not all system users are managed by systemd-homed, only those specifically configured for it. Errors in managing encryption keys or image files can lead to data loss or inaccessibility.

By default, systemd-homed (and thus homectl) manages home directories as LUKS-encrypted disk images. This provides a high level of security by encrypting the entire home directory contents at rest. User passwords, FIDO2 devices, or PKCS#11 tokens are used to unlock these encrypted images during login.

Users managed by systemd-homed are exposed to the system via the Name Service Switch (NSS) through the nss-systemd module. This allows standard system tools and applications to recognize and interact with homed-managed users, ensuring compatibility with existing Linux infrastructure while leveraging homed's advanced features.

homectl was introduced as part of the systemd-homed project with systemd version 245, released in early 2020. Its development aimed to address modern challenges in user management, such as secure handling of sensitive user data, supporting stateless systems, and integrating with advanced authentication mechanisms like FIDO2/PKCS#11. It represents a significant evolution in how user accounts and their associated home directories can be managed within the systemd ecosystem.

systemd-homed(8), loginctl(1), useradd(8), usermod(8), userdel(8), passwd(1)