systemd-homed(8) is a systemd service providing portable human-user accounts that are not dependent on current system configuration.
It achieves portability by moving all user-related information into a storage medium, optionally encrypted, and creating an
~/.identity file that contains signed information about the user, password, what groups they belong to, UID/GID and other information that would typically be scattered over multiple files in
This approach allows not only for a home directory portability, but also provides security by automatically managing a home directory encryption on login and locking it if the system is suspended.
systemd-homed is part of and packaged with systemd. The pambase package since version 20200721.1-2 comes with the necessary PAM configuration to allow systemd-homed user sessions.
However, you must enable and start the
homectl is the main utility you will use for homed. With it, you can create, update, and inspect users; their home directories; and their
~/.identity files controlled by the systemd-homed(8) service.
The simplest usage of homectl is:
# homectl create username
This command will create a user with the specified username, a free UID in range 60001–60513, create a group with the same name and a GID equal to the chosen UID, set the specified user as its member, and set the user's default shell to
The home directory mount point is set to
/home/username. The storage mechanism is chosen in this order:
subvolumeif LUKS is not supported and subvolume is supported;
directoryif none of the above is supported and no other manual option is specified.
The image path for the LUKS mechanism is set to
/home/username.home. The directory path for the directory mechanism is set to
~/.identityfiles are signed and must not be edited directly with a text editor as it will break the signature and render them invalid. Use
homectl update --identity=/path/to/.identityto modify it.
A query tool used to inspect users, groups and group memberships provided by both classic UNIX mechanisms and systemd-homed.
LUKS home directory
A user home directory is stored in a Linux file system, inside an encrypted LUKS (Linux Unified Key Setup) volume inside a loopback file or any removable media. To use this mechanism provide
--storage=luks to homectl.
If you are using a removable media, make sure that these conditions are met:
- The image contains a GPT partition table. For now it should only contain a single partition, and that partition must have the type UUID
773f91ef-66d4-49b5-bd83-d683bf40ad16. Its partition label must be the user name.
- This partition must contain a LUKS2 volume, whose label must be the user name. The LUKS2 volume must contain a LUKS2 token field of type systemd-homed. The JSON data of this token must have a record field, containing a string with base64-encoded data. This data is the JSON user record, in the same serialization as in
~/.identity, though encrypted. The JSON data of this token must also have an iv field, which contains a base64-encoded binary initialization vector for the encryption. The encryption used is the same as the LUKS2 volume itself uses, unlocked by the same volume key, but based on its own IV.
- Inside of this LUKS2 volume must be a Linux file system, one of ext4, btrfs and XFS. The file system label must be the user name.
- This file system should contain a single directory named after the user. This directory will become the home directory of the user when activated. It contains a second copy of the user record in the
~/.identityfile, like in the other storage mechanisms.
A user home directory is stored the same way as when using the above method, but this time a native filesystem encryption is used. To use this mechanism provide
--storage=fscrypt to homectl.
Directory or Btrfs subvolume
A user home directory is stored in
/home/username.homedir and mounted to
/home/username using bind mount on unlocking. When this method is used no encryption is provided. To use this mechanism provide
--storage=subvolume to homectl.
Here, the home directory is mounted from a CIFS (Common Internet File System) server at login. Note that CIFS is implemented via the Samba protocol. Use
--storage=cifs on the homectl command line. The local password of the user is used to log into the CIFS service.
User record properties
You can view an entire user record with:
# homectl inspect username
You can modify or add to the user record with:
# homectl update username --property=VALUE
See homectl(1) for more options.
Create a user with LUKS encryption:
# homectl create username --storage=luks
Create a user with fscrypt encryption (make sure that fscrypt is enabled on the file system):
# homectl create username --storage=fscrypt
Create a user with a specific UID, shell and groups:
# homectl create username --shell=/usr/bin/zsh --uid=60100 --member-of=wheel,adm,uucp
Other options can be found in homectl(1) § USER RECORD PROPERTIES.
It is possible to delete several users at the same time, as root, you can run the command below to immediately delete 2 users:
# homectl remove username username2
Tips and tricks
Forget key on suspend
suspend option can be used with
pam_systemd_home.so entries in the files in
/etc/pam.d/ to enable forget key on suspend. No session manager at the moment supports this feature. Furthermore, TTY sessions do not support the reauthentication mechanism. So, when session managers start supporting this feature, the suspend option should only be enabled for them. Read pam_systemd_home(8) and the Linux-PAM System Administrators' Guide for more details.
SSH remote unlocking
systemd-homed encrypts your home directory using your password, so SSH configured for public key authentication cannot mount it or read
authorized_keys. A possible solution is to add authorized keys to your user record and require both public key and password for authentication. Add the following to
PasswordAuthentication yes PubkeyAuthentication yes AuthenticationMethods publickey,password AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u AuthorizedKeysCommandUser root
Update your user record with your authorized keys while the user is unlocked using:
# homectl update username --ssh-authorized-keys=@/path/to/mounted/home/.ssh/authorized_keys
From now on, SSH will ask you to enter your password after completing key-based authentication. systemd-homed will use it to unlock and mount your home directory.
Mounting encrypted home directory for rescue
If you need to mount a systemd-homed-encrypted directory from a rescue disk or another machine, you will need to decrypt the directory outside of the systemd-homed framework. You may wish to keep a text file or script of this solution from the forums on your rescue disk for emergencies:
# losetup -fP --show username.home # cryptsetup open /dev/loopXpY mappername # mount /dev/mapper/mappername /mnt/mountpoint
username.homeis the file in the
/homedirectory with your username and the .home extension as its name
loopXpYis the device in the
/devdirectory with the loop number of the loopback device created in the prior step and the partition number of the relevant partition, probably
mappernameis whatever alias you decide to adopt for the mapped device, e.g.
/mnt/mountpointis wherever you want to mount your decrypted home directory
Setup user with fido2 hmac-secret for authentication and encryption
This setup requires a fido2 security device and ask for a pin to login and decrypt the home directory:
# homectl create username --storage=fscrypt --fido2-device=auto --fido2-with-client-pin=yes --fido2-with-user-presence=no --recovery-key=yes
Setting up a recovery key is recommended in case the device is lost or broken. The recovery key will be used like a password to access the user and files. Instead of using a device pin, it is also possible to ask only for user presence, which requires touching the security device. Currently, homectl also requires the user to set a password as alternative login which also works as a backup secret.
Home directory remains active after logging out of Plasma
After logging out of Plasma, there may still be active user processes (e.g. dbus-daemon) that prevent the home directory's deactivation.
This can be solved by enabling Plasma's systemd startup.
User umask is ignored
If there is an umask set in
/etc/profile, the user's own umask set via homectl is currently ignored. See systemd issue 23007.
To solve this, set the umask in your login shell's startup files e.g.