Difference between revisions of "Systemd-homed"

From ArchWiki
Jump to navigation Jump to search
m (Improve style)
m (Add missing apostrophe and remove unnecessary bolding)
Line 34: Line 34:
 
  # homectl create username
 
  # homectl create username
  
This command will create a user with the specified username, using the first 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 users default shell to {{ic|/bin/bash}}.
+
This command will create a user with the specified username, using the first 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 {{ic|/bin/bash}}.
  
The home directory mount point is set to {{ic|/home/username}}. The storage mechanism is chosen in this order: '''LUKS''' if supported; if not, then '''subvolume''' if supported; if not, then '''directory'''. The image path for the '''LUKS''' mechanism is set to {{ic|/home/username.home}}. The directory path for the '''directory''' mechanism is set to {{ic|/home/username.homedir}}.
+
The home directory mount point is set to {{ic|/home/username}}. The storage mechanism is chosen in this order: LUKS if supported; if not, then subvolume if supported; if not, then directory. The image path for the LUKS mechanism is set to {{ic|/home/username.home}}. The directory path for the directory mechanism is set to {{ic|/home/username.homedir}}.
  
{{Note| '''homectl''' does not manage group creation or deletion other than those matching the name and ID of users managed by homed}}
+
{{Note| homectl does not manage group creation or deletion other than those matching the name and ID of users managed by homed}}
  
 
{{Warning|The {{ic|~/.identity}} files are signed and must not be edited directly with a text editor as it will break the signature and render them invalid. Use {{ic|1=homectl update --identity=/path/to/.identity}} to modify it.}}
 
{{Warning|The {{ic|~/.identity}} files are signed and must not be edited directly with a text editor as it will break the signature and render them invalid. Use {{ic|1=homectl update --identity=/path/to/.identity}} to modify it.}}

Revision as of 21:28, 5 April 2020

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements. See Help:Style for reference.Tango-edit-clear.png

Reason: See Help:Style. Why is it in Category:Security? (Discuss in Talk:Systemd-homed#)

systemd-homed is a systemd service providing portable human-user accounts that aren't dependent on current system configuration.

It achieves portability by moving all user-related information into a storage medium, preferably 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.

Installation

systemd-homed is part of and packaged with systemd.

However, you must enable the service:

# systemctl enable --now systemd-homed.service

Utilities

homectl

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 service.

The simplest usage of homectl is:

# homectl create username

This command will create a user with the specified username, using the first 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 /bin/bash.

The home directory mount point is set to /home/username. The storage mechanism is chosen in this order: LUKS if supported; if not, then subvolume if supported; if not, then directory. The image path for the LUKS mechanism is set to /home/username.home. The directory path for the directory mechanism is set to /home/username.homedir.

Note: homectl does not manage group creation or deletion other than those matching the name and ID of users managed by homed
Warning: The ~/.identity files 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/.identity to modify it.

userdbctl

A query tool used to inspect users, groups and group memberships provided by both classic unix mechanisms and systemd-homed.

Storage mechanism

Directory or btrfs subvolume

A user home folder is stored in /home/user.homedir and mounted to /home/user using bind mount on unlocking. When this method is used no encryption is provided. To use this mechanism provide --storage=directory or --storage=subvolume to homectl.

fscrypt directory

Tip: Filesystems with fscrypt support include ext4 and F2FS

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.

LUKS home directory

A user home folder is stored in a linux filesystem, inside a LUKS volume inside a loopback file or any removable media. To use this mechanism provide --storage=luks to homectl.

If you are using 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. It’s 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 ~/.identity file, 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 /etc/passwd, /etc/shadow and /etc/group), 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.

Warning: Mistakes in PAM configuration can break the system authorization up to not being able to login even as root. Backing up existing configuration files is recommended before making any changes.

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:

/etc/pam.d/nss-auth
#%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

Replace pam_unix.so in the existing /etc/pam.d/system-auth file with the created configuration using a substack control value:

/etc/pam.d/system-auth
#%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
Tip: Refer to pam_systemd_home(8) and pam.d(5) for more info on options.

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:

  • --timezone=TIMEZONE
  • --language=LANG
  • --member-of=GROUP
  • --real-name=NAME
  • --email-address=EMAIL

See homectl(1) for more options.

Example user creation

Create a user with LUKS encryption, using the argon2id key derivation function:

# homectl create username --storage=luks --luks-pbkdf-type=argon2id

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

Delete a user

Warning: The user deletion is instant, be careful!
# homectl remove archie

See also