homectl(1)

.SH "NAME" homectl, systemd-homed-firstboot.service - Create, remove, change or inspect home directories

.SH "SYNOPSIS"

.HP 192u

homectl
[OPTIONS...]
{COMMAND}
[NAME...]

.SH "DESCRIPTION"

.PP homectl may be used to create, remove, change or inspect a user's home directory. It's primarily a command interfacing with systemd-homed.service(8) which manages home directories of users.

.PP Home directories managed by systemd-homed.service are self-contained, and thus include the user's full metadata record in the home's data storage itself, making them easy to migrate between machines. In particular, a home directory describes a matching user record, and every user record managed by systemd-homed.service also implies existence and encapsulation of a home directory. The user account and home directory become the same concept.

.PP The following backing storage mechanisms are supported:

.PP Note that systemd-homed.service and homectl will not manage "classic" UNIX user accounts as created with useradd(8) or similar tools. In particular, this functionality is not suitable for managing system users (i.e. users with a UID below 1000) but is exclusive to regular ("human") users.

.PP Note that users/home directories managed via systemd-homed.service do not show up in /etc/passwd and similar files, they are synthesized via glibc NSS during runtime. They are thus resolvable and may be enumerated via the getent(1) tool.

.PP This tool interfaces directly with systemd-homed.service, and may execute specific commands on the home directories it manages. Since every home directory managed that way also defines a JSON user and group record these home directories may also be inspected and enumerated via userdbctl(1).

.PP Home directories managed by systemd-homed.service are usually in one of two states, or in a transition state between them: when active they are unlocked and mounted, and thus accessible to the system and its programs; when inactive they are not mounted and thus not accessible. Activation happens automatically at login of the user and usually can only complete after a password (or other authentication token) has been supplied. Deactivation happens after the user fully logged out. A home directory remains active as long as the user is logged in at least once, i.e. has at least one login session. When the user logs in a second time simultaneously the home directory remains active. It is deactivated only after the last of the user's sessions ends.

.SH "OPTIONS"

.PP The following general options are understood (further options that control the various properties of user records managed by systemd-homed.service are documented further down):

.PP --identity=FILE

# homectl update lennart -T --storage=luks -N --storage=cifs

# smbpasswd -a lennart

$ homectl update lennart --ssh-authorized-keys=... -N --storage=cifs --cifs-service="//$HOSTNAME/lennart"
$ homectl get-signing-key | ssh targetsystem homectl add-signing-key --key-name="$HOSTNAME".public
$ homectl inspect -E lennart | ssh targetsystem homectl register -
$ ssh lennart@targetsystem

homectl get-signing-key | ssh myotherhost homectl add-signing-key --key-name="$HOSTNAME".public

homectl create waldo --real-name="Waldo McWaldo" -G wheel --disk-size=500M

homectl create wally --real-name="Wally McWally" --image-path=/dev/disk/by-id/usb-SanDisk_Ultra_Fit_476fff954b2b5c44-0:0 --tasks-max=500

homectl update odlaw --nice=5 --setenv=SOME=THING

# Clear the Yubikey from any old keys (careful!)
ykman piv reset
# Generate a new private/public key pair on the device, store the public key in 'pubkey.pem'.
ykman piv generate-key -a RSA2048 9d pubkey.pem
# Create a self-signed certificate from this public key, and store it on the device.
ykman piv generate-certificate --subject "Knobelei" 9d pubkey.pem
# We do not need the public key on disk anymore
rm pubkey.pem
# Allow the security token to unlock the account of user 'lafcadio'.
homectl update lafcadio --pkcs11-token-uri=auto

# Allow a FIDO2 security token to unlock the account of user 'nihilbaxter'.
homectl update nihilbaxter --fido2-device=auto

# Generate and add a recovery key for user 'emily'.
homectl update emily --recovery-key=yes