How to Configure systemd-homed for Cryptographically Portable User Directories

Historically, Linux user management has relied on the standard /etc/passwd and /etc/shadow files, with home directories statically mounted in /home/username. This legacy architecture presents severe limitations in modern, highly mobile computing environments. If a developer needs to migrate from a desktop workstation to a laptop, they must manually sync their files, recreate their SSH keys, and ensure their UID/GID mathematically aligns across both systems to prevent permission errors. Furthermore, encrypting the home directory traditionally required complex LUKS setups tied to the full disk encryption. To solve these architectural flaws, the systemd project introduced systemd-homed, a revolutionary service that encapsulates a user’s entire identity, cryptographic keys, and data into a single, highly secure, portable cryptographic volume.

The Architecture of systemd-homed

Unlike legacy user management, systemd-homed completely decouples the user identity from the host operating system’s /etc/passwd file.

When you create a user utilizing systemd-homed, the system creates an isolated, encrypted loopback file (usually formatted with Btrfs or ext4 and encrypted via LUKS2) located in /home/username.home. This file contains the user’s actual data.

Crucially, the file also contains a cryptographic JSON payload embedded directly within the LUKS2 header. This JSON payload holds the user’s identity details (shell preference, SSH authorized keys, UID/GID requirements, and password hash). Because the identity metadata is mathematically bound to the encrypted volume, the user’s account is completely self-contained. You can literally copy the .home file to a USB drive, plug it into a completely different Linux machine running systemd-homed, authenticate, and instantly resume your session with all cryptographic keys and configurations intact.

Enabling the systemd-homed Daemon

While available on most modern distributions (like Arch Linux, Fedora, and Ubuntu 22.04+), it is often disabled by default to prevent conflicts with legacy user management.

To enable the daemon, you must start the service and configure the system’s PAM (Pluggable Authentication Modules) stack to recognize systemd-homed users alongside traditional /etc/passwd users.

# Enable and start the core service
sudo systemctl enable --now systemd-homed.service

On systems utilizing authselect (like Fedora), you integrate it into PAM via:

sudo authselect enable-feature with-systemd-homed
sudo authselect apply-changes

Provisioning a Cryptographic Home Directory

You do not use standard tools like useradd or usermod to interact with these new accounts. Instead, you utilize the homectl utility.

To create a new, highly secure, portable user account named jdoe, you instruct homectl to provision a LUKS-encrypted Btrfs volume:

sudo homectl create jdoe --storage=luks --fs-type=btrfs --disk-size=50G

The system will prompt you to set a password. Once complete, it generates the encrypted payload. To view the embedded cryptographic JSON metadata defining the user’s identity, execute:

homectl inspect jdoe

Managing the Portable Session

When the user is logged out, the home directory is completely inaccessible; it is a locked LUKS volume, mathematically impervious to offline attacks. When the user types their password at the GDM login screen or via SSH, the PAM module intercepts the credential, unlocks the LUKS volume, temporarily mounts it to /home/jdoe, and decrypts the JSON identity payload to initialize the shell.

If the user needs to change their SSH keys or update their shell, they use homectl, which dynamically injects the changes into the encrypted JSON header:

homectl update jdoe --shell=/usr/bin/zsh

If the user leaves the organization, wiping their data is cryptographically instantaneous. You do not need to securely shred gigabytes of data on the SSD; you simply delete the volume, instantly rendering the data mathematically unrecoverable:

sudo homectl remove jdoe

By deploying systemd-homed, Linux administrators eradicate the fragility of localized identity management, transitioning to a paradigm where users possess fully encrypted, hardware-agnostic identities that migrate seamlessly across the enterprise fleet.