systemd-homed is a systemd service providing portable human-user (that is, accounts that are not from the system, like
bin, etc.) 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
/home encryption on login and locking the folder if the system is suspended.
systemd-homed is part of and packaged with.
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 service.
The simplest usage of homectl is:
# homectl create username
This command will create a user with the specified username, a free UID, 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.
Directory or Btrfs subvolume
A user home folder 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.
A user home folder 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.
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.
LUKS home directory
A user home folder is stored in a Linux filesystem, 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.
Enabling PAM modules
Since there are no records of systemd-homed users in traditional UNIX NSS databases (such as
pam_unix.so PAM module will not authorize these users. It is therefore necessary to use a
pam_systemd_home.so module provided. While the user is logged in systemd-homed will synthesize the NSS records for it.
Only one of the two modules will permit authorization, so PAM should be instructed to disregard the other one's failure. For this a sufficient control value can be used, but on module success this control value causes skipping the rest of the stack. One way to solve this is a substack:
#%PAM-1.0 auth sufficient pam_unix.so try_first_pass nullok auth sufficient pam_systemd_home.so auth required pam_deny.so account sufficient pam_unix.so account sufficient pam_systemd_home.so account required pam_deny.so password sufficient pam_unix.so try_first_pass nullok sha512 shadow password sufficient pam_systemd_home.so password required pam_deny.so
pam_unix.so in the existing
/etc/pam.d/system-auth file with the created configuration using a substack control value:
#%PAM-1.0 auth substack nss-auth auth optional pam_permit.so auth required pam_env.so account substack nss-auth account optional pam_permit.so account required pam_time.so password substack nss-auth password optional pam_permit.so session required pam_limits.so session optional pam_systemd_home.so session required pam_unix.so session optional pam_permit.so
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
You can modify or add several properties:
Seefor more options.
Create a user with LUKS encryption:
# homectl create username --storage=luks
Create a user with fscrypt encryption:
# homectl create username --storage=fscrypt
Create a user with a specific UID, shell and groups:
# homectl create username --shell=/bin/zsh --uid=1001 -G wheel,storage,games
Create a user using several of the more advanced options in homectl to personalize the encryption and other user settings.
# homectl --real-name='John Doe' --email@example.com' --location="United States" --member-of=users,wheel,video,audio --shell=/usr/bin/zsh --timezone=America/Los_Angeles --language=en_US.UTF8 --password-hint="None" --enforce-password-policy=yes --umask=077 --nice=-15 --luks-discard=true --luks-volume-key-size=64 --luks-pbkdf-type=argon2id --luks-pbkdf-hash-algorithm=SHA512 --luks-pbkdf-time-cost=45 --luks-pbkdf-memory-cost=40M --luks-pbkdf-parallel-threads=4 --fs-type=xfs create johndoe
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