The mental model

Traditional Linux: /etc/passwd has the user record, /home/$USER is a regular directory, encryption (if any) is whole-disk via LUKS. Moving a user between machines means manually copying /etc/passwd entry + the directory + the shadow record.

systemd-homed: the user's record is a JSON blob signed and stored inside the encrypted home image. Login decrypts the image; nss/pam read the embedded record. Move the image, the user moves with it.

Install

systemd-homed is part of systemd. Distros vary on whether it's enabled out of the box:

# Debian / Ubuntu: install the systemd-homed package
sudo apt install systemd-homed

# Fedora has it enabled by default in recent releases

# Enable + start
sudo systemctl enable --now systemd-homed

# Verify
systemctl status systemd-homed
homectl list           # may be empty initially

Create a homed user

# LUKS-backed home (default; encrypted file)
sudo homectl create amir --real-name="Amir Eslampanah"
# Prompts for password

# Or with options
sudo homectl create amir \
    --storage=luks \
    --disk-size=50G \
    --shell=/bin/bash \
    --member-of=wheel,docker \
    --real-name="Amir Eslampanah" \
    --email-address="amir@example.com"

Creates /home/amir.home (the LUKS image; size = 50 GB grown automatically as content fills it). The user record is inside; getent passwd amir shows it.

Storage backends

# LUKS image file (default; portable, fully encrypted)
homectl create user1 --storage=luks --disk-size=50G

# btrfs subvolume (CoW snapshots; less portable)
homectl create user2 --storage=subvolume

# fscrypt (per-file encryption on ext4)
homectl create user3 --storage=fscrypt

# Plain directory (no encryption; for compatibility)
homectl create user4 --storage=directory

# Encrypted CIFS / NFS (for network-attached homes)
homectl create user5 --storage=cifs --cifs-domain=lab --cifs-user-name=amir \
    --cifs-service="//nas.lab/homes/amir"

LUKS is the most-portable option (the encrypted image is a single file you can copy); btrfs subvolumes give you snapshot semantics; fscrypt is lighter-weight.

The portability story

# On machine A: lock the home and copy it
sudo homectl lock amir
sudo cp /home/amir.home /mnt/usb/

# On machine B (different Linux box with systemd-homed)
# Just put the image somewhere homed scans
sudo cp /mnt/usb/amir.home /home/

# Refresh
sudo homectl inspect amir
# Shows the user; login works with the same password

The encrypted file is self-contained: UID assignment is via the user record (renegotiated if there's a conflict), the password is checked against the LUKS key, the home content is decrypted.

Per-user resource limits

sudo homectl create alice \
    --rate-limit-interval=5min \
    --rate-limit-burst=10 \
    --tasks-max=2000 \
    --memory-max=4G \
    --member-of=users

# Update later
sudo homectl update alice --memory-max=8G

cgroup-backed limits applied at login. Much cleaner than ulimit / PAM-limits gymnastics.

Multi-factor auth

# FIDO2 (Yubikey, etc.)
sudo homectl update amir --fido2-device=auto
# Prompts to plug in and tap a FIDO2 key

# PKCS#11 (smart cards)
sudo homectl update amir --pkcs11-token-uri=auto

# Recovery key (one-time-use printed)
sudo homectl update amir --recovery-key=yes
# Prints a long key; store offline; use to recover access if password lost

Unlock requires the configured factor(s); without FIDO2 tap, the home stays encrypted even with the password.

Inspect + edit user records

# Show full info
homectl inspect amir

# Edit (opens an editor with the JSON record)
sudo homectl update amir --shell=/usr/bin/fish

# Or edit the JSON record interactively
sudo homectl update amir
# Opens $EDITOR on the JSON; changes apply on save

# List all homed users
homectl list

Locking, password change

# Lock (encrypted; can't be accessed)
sudo homectl lock amir

# Unlock without logging in (for backup, etc.)
sudo homectl unlock amir

# Change password
sudo passwd amir
# Standard passwd works against the homed record

Backups

The .home file is what you back up; restic / rsync on the file is straightforward. Critical: lock the home before backup (otherwise the image is in-use and might be inconsistent):

# Backup script
sudo homectl lock amir
sudo restic backup /home/amir.home
sudo homectl unlock amir       # without password (admin privilege)

What systemd-homed doesn't do

  • System-wide encryption. Only homes are encrypted; other paths (logs, /var, /tmp) are in the clear. For that, pair with full-disk LUKS at the root.
  • Multi-user homes. Each user has their own home; no shared /home semantics.
  • Replace LDAP / SSO directories. homed is per-machine; for centralized accounts, FreeIPA / Active Directory still rule. homed can coexist with PAM-LDAP for hybrid setups.

When systemd-homed is the right pick

  • Laptop / mobile workstation where the home dir contains sensitive data.
  • Multi-host devs who want to carry their home dir on a USB-encrypted-stick.
  • Shared family / lab machines where each user gets a separate encrypted home.

When it isn't

  • Servers with one or two service accounts — the abstraction overhead doesn't pay off.
  • Distros without systemd-homed support (rare in 2026 but check before committing).
  • Compatibility-critical scripts that assume /etc/passwd is the source of truth — homed users may not appear there in the traditional sense (use getent, not cat /etc/passwd).

Worth knowing

  • Resize automatically. The LUKS image grows on demand up to the configured cap; no manual resize.
  • Mounted only while you're logged in. Logout, the home image re-encrypts and locks. Compare to whole-disk LUKS where the disk stays unlocked while powered on.
  • nss-systemd is the glue that makes other tools see homed users; configured automatically when homed is enabled.