DEV Community

Cover image for Practical Encrypted Home Directories with systemd-homed on Linux
Lyra
Lyra

Posted on

Practical Encrypted Home Directories with systemd-homed on Linux

#linux #systemd #security #devops

Practical Encrypted Home Directories with systemd-homed on Linux

Traditional Linux user homes live in /home/username with passwords in /etc/shadow. This works, but has limitations: accounts are tied to the machine, encryption (if any) is often manual or uses older tools like ecryptfs, and moving a user's entire environment between machines is painful.

systemd-homed solves this by managing self-contained user accounts. Everything the user needs — home directory, UID/GID, groups, shell, even resource limits — lives in a portable record. Homes can be encrypted with LUKS (recommended) or fscrypt, and they automatically activate on login through PAM.

The result: portable .home image files you can copy to another machine, per-user encryption that locks on logout or suspend, and a cleaner separation from the host system.

Why Use systemd-homed?

  • Encryption by default (LUKS or fscrypt) for each user.
  • Portability: A single .home file (or directory) contains the home + identity. Copy it, activate it elsewhere.
  • Automatic lifecycle: Homes mount on login and unmount on logout (or stay active until explicitly deactivated).
  • Resource controls and per-user settings without touching /etc/passwd or systemd user units manually.
  • Works alongside traditional users.

It is not a full replacement for all use cases (NFS homes, some containers, and very old systems can be awkward), but for laptops, workstations, and many servers it is excellent.

Installation on Debian and Ubuntu 

sudo apt update
sudo apt install systemd-homed
Enter fullscreen mode Exit fullscreen mode

Enable and start the service:

sudo systemctl enable --now systemd-homed
sudo systemctl status systemd-homed
Enter fullscreen mode Exit fullscreen mode

PAM integration is usually automatic. Verify with:

grep pam_systemd_home /etc/pam.d/common-session
Enter fullscreen mode Exit fullscreen mode

If you use SSH, ensure pam_systemd_home.so is present in the session stack of /etc/pam.d/sshd.

Creating an Encrypted User

The main tool is homectl. Create a user with a LUKS-encrypted home (recommended):

sudo homectl create alice \
  --storage=luks \
  --disk-size=20G \
  --shell=/bin/bash \
  --member-of=sudo \
  --real-name="Alice Example"
Enter fullscreen mode Exit fullscreen mode

The command will prompt for a password. This becomes the unlock key for the home.

Other useful creation options:

  • --storage=fscrypt (lighter native filesystem encryption on ext4/F2FS).
  • --storage=directory (plain, no encryption — useful for testing).
  • --uid=60123 (pick a high UID in the systemd-homed range).
  • --recovery-key=yes (generate a one-time recovery key — highly recommended).

After creation you will see a file like /var/lib/systemd/home/alice.home (for LUKS) and the home appears at /home/alice when activated.

Everyday Management 

# List all homed users
homectl list

# Detailed view of a user (including current state)
homectl inspect alice

# Change password (works as root or as the user when home is active)
sudo homectl passwd alice

# Resize the home (LUKS)
sudo homectl update alice --disk-size=50G

# Add groups or other properties
sudo homectl update alice --member-of=sudo,adm

# Manually activate (mount) or deactivate (unmount + lock)
sudo homectl activate alice
sudo homectl deactivate alice
Enter fullscreen mode Exit fullscreen mode

When the user logs in (console, SSH, graphical session), PAM activates the home automatically using the login password.

Backup and Portability

The beauty of systemd-homed is how simple backups become.

  1. Deactivate the home: 
   sudo homectl deactivate alice
Enter fullscreen mode Exit fullscreen mode
  1. Copy the image: 
   sudo cp /var/lib/systemd/home/alice.home /backup/alice-2026-07-01.home
Enter fullscreen mode Exit fullscreen mode

To restore on the same or another machine (with systemd-homed installed):

sudo cp /backup/alice-2026-07-01.home /var/lib/systemd/home/
sudo systemctl restart systemd-homed
sudo homectl activate alice
Enter fullscreen mode Exit fullscreen mode

The user can then log in with their password.

You can also export the identity record for extra safety:

homectl inspect alice --json=pretty > alice.identity
Enter fullscreen mode Exit fullscreen mode

Migration from a Traditional Home

If you have an existing user you want to convert:

  1. Back up the current home.
  2. Create a new homed user (or use homectl create with a different name first).
  3. Copy data into the active homed home.
  4. Update the user record as needed.
  5. Change the user's shell/login to the homed account.

There is no one-command "convert" for security reasons — the old home must be handled carefully.

See the upstream guide for more details on converting existing systems.

Troubleshooting

Home stays active after logout

Some desktop environments or services (dbus, etc.) keep processes alive. Try:

loginctl terminate-user alice
Enter fullscreen mode Exit fullscreen mode

or enable the desktop's systemd user session features.

Dirty LUKS state after crash

sudo homectl inspect alice   # note the image path
sudo losetup -fP --show /var/lib/systemd/home/alice.home
sudo cryptsetup open /dev/loopXpY alice_recover
sudo fsck /dev/mapper/alice_recover
sudo cryptsetup close alice_recover
sudo losetup -d /dev/loopXpY
Enter fullscreen mode Exit fullscreen mode

Then try activating normally.

SSH public-key auth doesn't unlock the home

Add the keys to the user record while the home is active:

homectl update alice --ssh-authorized-keys=@/home/alice/.ssh/authorized_keys
Enter fullscreen mode Exit fullscreen mode

Then configure sshd to require password as a second factor, or use the recovery key.

Check logs:

journalctl -u systemd-homed -e
journalctl -u systemd-homed --since today
Enter fullscreen mode Exit fullscreen mode

Limitations and Considerations

  • Recovery always requires the password or a recovery key you saved earlier.
  • Some traditional tools that read /etc/passwd directly may need updates.
  • Not ideal for homes that must be available before login (certain server setups).
  • fscrypt is weaker than full LUKS (metadata not encrypted).

For most personal machines and many homelab users, the portability and automatic encryption are worth it.

References

Start simple with one test user (--storage=luks --disk-size=5G) before migrating anything important.

This gives you modern, encrypted, portable homes with very little ongoing maintenance.

Top comments (0)