LinuxCommandLibrary

homectl

Manage user home directories

TLDR

List user accounts and their associated home directories

$ homectl list
copy

Create a user account and their associated home directory
$ sudo homectl create [username]
copy

Remove a specific user and the associated home directory
$ sudo homectl remove [username]
copy

Change the password for a specific user
$ sudo homectl passwd [username]
copy

Run a shell or a command with access to a specific home directory
$ sudo homectl with [username] -- [command] [command_arguments]
copy

Lock or unlock a specific home directory
$ sudo homectl [lock|unlock] [username]
copy

Change the disk space assigned to a specific home directory to 100 GiB
$ sudo homectl resize [username] [100G]
copy

Display help
$ homectl --help
copy

SYNOPSIS

homectl [OPTIONS] COMMAND [USER]

PARAMETERS

--json=MODE
    Output the results as JSON. MODE can be 'short' (defaults), 'pretty', 'json' or 'json-pretty'.
Note that this option is not part of the stable API of homectl. It is intended only for local consumption and its output should not be parsed by applications.

--portable=BOOL
    Take the home directory offline or put it online.

--realm=REALM
    Configure the home directory to be used in a particular realm.

--no-password
    Do not prompt for a password when creating a home directory.

--encryption=MODE
    Specify the encryption mode to use. Allowed modes are 'auto', 'fscrypt', 'fscrypt-direct', and 'off'. Defaults to 'auto'.

--storage=MODE
    Specify the storage mode to use. Allowed modes are 'auto', 'loop', and 'directory'. Defaults to 'auto'.

--size=SIZE
    Specify the size of the home directory image when it is created. Takes a SIZE argument as described in systemd.syntax(7).

create [USER]
    Create a new home directory.

activate [USER]
    Activate an existing home directory.

deactivate [USER]
    Deactivate a home directory.

delete [USER]
    Delete the home directory.

inspect [USER]
    Inspect the properties of a home directory.

update [USER]
    Update the home directory, which may involve changing encryption settings, or resizing the container image.

list
    List managed home directories.

-H, --host=HOST
    Operate on remote host.

-M, --machine=CONTAINER
    Operate on local container.

DESCRIPTION

The homectl command is used to manage portable user home directories on Linux systems. It allows you to create, activate, deactivate, and delete home directories that are stored as disk images. These images can be easily moved between machines, providing a convenient way to transport user profiles and data.

homectl leverages systemd and other system components to ensure a consistent and secure user experience. It simplifies the process of managing user data in containerized environments, on removable media, and across multiple systems. Home directories managed by homectl are typically encrypted for enhanced security.

The command provides a central interface for managing home directories, handling tasks such as creating the directory, setting up user accounts, generating encryption keys, and configuring systemd integration for automatic mounting and unmounting on login and logout.

CAVEATS

homectl requires root privileges for most operations. Ensure that systemd and related components are properly configured for home directory management. Password requirements and encryption methods might vary based on system configuration. Using external storage requires correct device and path configuration.

SECURITY CONSIDERATIONS

Encryption is a core feature of homectl to protect user data. Ensure that strong passwords or key pairs are used for encrypting home directories. Regularly back up encryption keys to avoid data loss. Be mindful of where the keys are stored, avoid storing them unencrypted.

STORAGE MODES

The homectl command supports different storage modes like loop devices or directory storage. Loop devices are suitable for storing the entire home directory in a single file, while directory storage involves a directory structure. Choose the most appropriate mode based on performance, storage capabilities and use-case scenarios.

HISTORY

The homectl command was introduced as part of the systemd project to provide a standardized and secure method for managing user home directories, especially in scenarios involving portability and encryption. It is developed and maintained as part of the systemd ecosystem.

SEE ALSO

systemd(1), systemd-homed(8), useradd(8), passwd(1)

Copied to clipboard