HOMECTL(1) homectl HOMECTL(1) (NAME) homectl - (systemd-homed) (SYNOPSIS) homectl [OPTIONS...] {COMMAND} [NAME...] (DESCRIPTION) homectl . systemd-homed.service(8) . systemd-homed.service (self-contained) . systemd-homed.service . . : o (loopback) LUKS2 /home/*.home . LUKS2 (mount) . LUKS2 . . . o LUKS2 USB . USB . o "fscrypt" ( "ext4") /home/*.homedir. LUKS2 . . o (subvolume) "btrfs" /home/*.homedir. (quota) . o /home/*.homedir. (fallback) LUKS2 "fscrypt" "btrfs" . o (CIFS) . systemd-homed.service homectl <<>> useradd(8) . ( UID ) (<<>>) . systemd-homed.service /etc/passwd NSS glibc . getent(1) . systemd-homed.service . JSON userdbctl(1) . systemd-homed.service : "active" () (mount) "inactive" () . ( ) . . ( ) . . . (OPTIONS) ( systemd-homed.service ): --identity=FILE JSON . "-" . JSON JSON User Records[1] . create update ( ) JSON ( ). 245. --json=FORMAT, -j inspect ( ) JSON . "pretty" () "short" () "off" () . "pretty" JSON . "short" . "off" () JSON . -j "pretty" "short" . 245. --export-format=FORMAT, -E, -EE inspect JSON ( ) JSON . "stripped" binding runtime . "minimal" . "full" JSON ( ). . : homectl inspect -EE | ssh root@othersystem homectl create -i- (replication) . -E -j --export-format=stripped -EE -j --export-format=minimal . "stripped" . "minimal" . 245. --offline blob . (/) . 256. --key-name= add-signing-key . ".public" . . . 258. --seize= . create register JSON (local.public) . true ( ) false ( ). create true register false . 258. --prompt-new-user firstboot . 256. --prompt-shell= . firstboot --prompt-new-user (login shell) . true . 259. --prompt-groups= . firstboot --prompt-new-user . true . 259. --chrome= . firstboot --prompt-new-user ("chrome") false . 259. --mute-console= . true (log) firstboot --prompt-new-user . false . 259. --match=this|other|any|auto, -A, -N, -T --match= "this" "other" "any" "auto" . . . "this" ( ) "other" ( ) "any" ( ). "auto" : . . . . JSON User Records[1] . -A --match=any -T --match=this -N --match=other . storage "luks" "cifs" : # homectl update lennart -T --storage=luks -N --storage=cifs 258. -H, --host= . "@" . ssh ":" "/" . SSH . machinectl -H HOST . IPv6 . -M, --machine= . "@" . ".host" ( : "--user --machine=lennart@.host"). "@" root . "@" ( ) ".host" . --no-pager (pager) . --no-legend (legend) . --no-ask-password . -h, --help . --version . (GENERAL USER RECORD PROPERTIES) / systemd-homed.service . create update : --real-name=NAME, -c NAME . GECOS NSS . 245. --realm=REALM (realm) . . DNS . . . . 245. --alias=NAME[,NAME...] . . . . 258. --email-address=EMAIL . $EMAIL . 245. --location=TEXT . . : --location="Berlin, Germany" --location="Basement, Room 3a" 245. --birth-date=[DATE] ISO 8601 ("YYYY-MM-DD") . 1900 . . 261. --icon-name=ICON Icon Naming Specification[2] . 245. --home-dir=PATH, -dPATH . (mount) . --image-path= . /home/$USER . 245. --uid=UID (UID) . UID . UID systemd-homed UID . . UID 60001...60513 . UID . UID . ( binding ) UID . systemd-homed GID UID . GID . 245. --member-of=GROUP, -G GROUP . : --member-of=wheel . systemd-homed UID/GID . groupadd(8) . . . . 245. --capability-bounding-set=CAPABILITIES, --capability-ambient-set=CAPABILITIES (process capabilities) ( CAP_WAKE_ALARM CAP_BLOCK_SUSPEND ) (bounding) (ambient) . capabilities(7) . . "~" : () . 254. --access-mode=MODE () . . . : --access-mode=0700 245. --umask=MASK ( ) ("umask"). umask . 245. --skel=PATH . (skeleton) . . /etc/skel/ . 245. --shell=SHELL . . /bin/bash . 245. --setenv=VARIABLE[=VALUE] . . "=" VALUE . --email= --timezone= --language=. 245. --timezone=TIMEZONE . $TZ . : --timezone=Europe/Amsterdam "TZ=:Europe/Amsterdam" . (":" tzset(3) .) 245. --language=LANG . $LANG $LANGUAGE --language=de_DE.UTF-8. . 245. --default-area=AREA <<>> (area) . . $HOME ~/Areas/ . pam_systemd_home(8) . . . 258. (AUTHENTICATION USER RECORD PROPERTIES) --ssh-authorized-keys=KEYS SSH "@" . SSH SSH . SSH . 245. --pkcs11-token-uri=URI RFC 7512 PKCS#11 URI ( YubiKey PIV) . X.509 . X.509 . PKCS#11 . . PKCS#11 URI "list" "auto" . "list" PKCS#11 URI . "auto" PKCS#11 ( ). PKCS#11 . PKCS#11/PIV FIDO2 "hmac-secret" ( : YubiKey 5) --fido2-device= . FIDO2 . PKCS#11/PIV FIDO2 . PKCS#11/PIV ( / ) FIDO2 . 245. --fido2-credential-algorithm=STRING COSE . "es256" . "es256" "rs256" "eddsa". "es256" ECDSA NIST P-256 SHA-256 . "rs256" RSA - PKCS#1.5 SHA-256 . "eddsa" EDDSA Curve25519 SHA-512 . . 251. --fido2-device=PATH "hidraw" ( /dev/hidraw1) FIDO2 "hmac-secret" . FIDO2 HMAC . . FIDO2 . "hidraw" FIDO2 "list" "auto" . "list" FIDO2 . "auto" FIDO2 . FIDO2 . FIDO2 "hmac-secret" . ( YubiKey 5) . . FIDO2 ( homectl update $USER --fido2-device=""). FIDO2 PKCS#11/PIV ( --fido2-device= --pkcs11-token-uri= ) . 246. --fido2-with-client-pin=BOOL FIDO2 (PIN) ( "clientPin" FIDO2). "yes" . (: "clientPin" .) 249. --fido2-with-user-presence=BOOL FIDO2 ( "up" FIDO2) . "yes" . (: "up" .) 249. --fido2-with-user-verification=BOOL FIDO2 ( "uv" FIDO2) . "no" . (: "uv" .) 249. --recovery-key=BOOL . . . . . 247. BLOB (BLOB DIRECTORY USER RECORD PROPERTIES) --blob=PATH, -b PATH, --blob=FILENAME=PATH, -b FILENAME=PATH . blob . . blob . blob ( blob ). blob . . blob User Record Blob Directories[3] . 256. --avatar=PATH, --login-background=PATH . blob . blob . --blob=FILENAME=PATH User Record Blob Directories[3] . 256. (ACCOUNT MANAGEMENT USER RECORD PROPERTIES) --locked=BOOLEAN . . (true) (false - ) ( ). 245. --not-before=TIMESTAMP, --not-after=TIMESTAMP systemd.time(7) . 245. --rate-limit-interval=SECS, --rate-limit-burst=NUMBER . . . 245. --password-hint=TEXT . . : --password-hint="My first pet's name". 245. --enforce-password-policy=BOOL, -P . . (on) . -P --enforce-password-policy=no . 245. --password-change-now=BOOL . true . 245. --password-change-min=TIME, --password-change-max=TIME, --password-change-warn=TIME, --password-change-inactive=TIME ( systemd.time(7)) . --password-change-min= . . --password-change-max= . . --password-change-warn= --password-change-max= . --password-change-inactive= . ( PKCS#11) . 245. (RESOURCE MANAGEMENT USER RECORD PROPERTIES) --disk-size=BYTES ( K, M, G, ... ) "min" "max" . ( "%" ) . "min" "max" . LUKS2 loopback . ( ) . LUKS2 . 245. --nice=NICE (" nice") . - ( ) ( ) . 245. --rlimit=LIMIT=VALUE[:VALUE] getrlimit(2) . ( "LIMIT_NOFILE") . . . . 245. --tasks-max=TASKS . ( ) . su(1) . --rlimit=LIMIT_NPROC= UID . TasksMax= systemd user-$UID.slice . systemd.resource-control(5) . 245. --memory-high=BYTES, --memory-max=BYTES ( K, M, G, ... ). . MemoryHigh= MemoryMax= systemd user-$UID.slice . systemd.resource-control(5) . 245. --cpu-weight=WEIGHT, --io-weight=WEIGHT (CPU) / (IO) . ... . CPUWeight= IOWeight= systemd user-$UID.slice . systemd.resource-control(5) . 245. (STORAGE USER RECORD PROPERTIES) --tmp-limit=BYTES, --tmp-limit=PERCENT, --dev-shm-limit=BYTES, --dev-shm-limit=PERCENT /tmp/ /dev/shm/ . ( K, M, G, T ) . . "tmpfs" . ( ). 258. --storage=STORAGE . "luks" "fscrypt" "directory" "subvolume" "cifs" . . homed.conf(5) . 245. --image-path=PATH . . LUKS2 loopback ( /home/ ) . LUKS /home/$USER.home /home/$USER.homedir . "cifs" . LUKS2 ( USB) . LUKS2 . . 245. --drop-caches=BOOL . fscrypt ( ). . fscrypt . . 250. LUKS (LUKS STORAGE USER RECORD PROPERTIES) --fs-type=TYPE LUKS2 LUKS2 . "btrfs" "ext4" "xfs". homed.conf(5) . "xfs" . 245. --luks-discard=BOOL LUKS2 "discard" . LUKS2 LUKS2 loopback LUKS2 loopback ("sparse") . over-committing I/O . I/O . LUKS2 ( loopback) discard . 245. --luks-offline-discard=BOOL --luks-discard= (trimming) . --luks-discard= --luks-offline-discard= / . . 246. --luks-extra-mount-options=OPTIONS LUKS . . "compress=zstd:1,noacl,user_subvol_rm_allowed" . 250. --luks-cipher=CIPHER, --luks-cipher-mode=MODE, --luks-volume-key-size=BYTES, --luks-pbkdf-type=TYPE, --luks-pbkdf-hash-algorithm=ALGORITHM, --luks-pbkdf-force-iterations=ITERATIONS, --luks-pbkdf-time-cost=SECONDS, --luks-pbkdf-memory-cost=BYTES, --luks-pbkdf-parallel-threads=THREADS, --luks-sector-size=BYTES LUKS2 . cryptsetup(8) . homectl /proc/crypto cryptsetup(8) . 245. --auto-resize-mode= / . "off" "grow" "shrink-and-grow" . LUKS2 btrfs ( / ). LUKS2/btrfs "shrink-and-grow" off . "off" . "grow" --disk-size= . . "shrink-and-grow" . . . 250. --rebalance-weight= . LUKS2 ( LUKS2 loopback ). . ... "off" . . : . . "off" . ( homectl resize ) . --rebalance-weight= . 250. (MOUNTING USER RECORD PROPERTIES) --nosuid=BOOL, --nodev=BOOL, --noexec=BOOL "nosuid" "nodev" "noexec" . "nodev" "nosuid" "noexec" . mount(8) . 245. CIFS (CIFS USER RECORD PROPERTIES) --cifs-domain=DOMAIN, --cifs-user-name=USER, --cifs-service=SERVICE, --cifs-extra-mount-options=OPTIONS (CIFS) / ("service") . "cifs" . "//host/share/directory/..." . -- . --cifs-extra-mount-options= mount.cifs(8) . 245. (LOGIN BEHAVIOUR RECORD PROPERTIES) --stop-delay=SECS . logind.conf(5) ( LUKS2 ). . 245. --kill-processes=BOOL . logind.conf(5) . 245. --auto-login=BOOL . . . . 245. --session-launcher=LAUNCHER . desktop. ( "gnome" "plasma" /usr/share/xsessions/ /usr/share/wayland-sessions ). . 256. --session-type=TYPE . ( "x11" "wayland" $XDG_SESSION_TYPE). . 256. (COMMANDS) : list ( ) systemd-homed.service . . ( /etc/passwd .) 245. activate USER [USER...] . ( /home/$USER) . ( deactivate ) . . LUKS2 : loopback LUKS2 (mount) UID/GID . 245. deactivate USER [USER...] . activate . 245. inspect USER [USER...] . . --json= JSON --export-format= . 245. authenticate USER [USER...] . ( ) . . 245. create USER, create --identity=PATH [USER] / . ( ) . User/Group Name Syntax[4] . 245. adopt PATH [PATH...] . *.home LUKS *.homedir/ systemd-homed . . /home/ ( ). 258. register FILE [FILE...] . JSON . "-" JSON . . . SMB/CIFS . Samba "root" : # smbpasswd -a lennart "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 "lennart" Samba . SSH CIFS . . . . SMB/CIFS . 258. unregister USER... . . register adopt . /home/ . <<>> . UID/GID . 258. remove USER / . . 245. update USER, update --identity=PATH [USER] / . ( ) JSON --identity= . --identity= . 245. passwd USER / . 245. resize USER BYTES . LUKS2 loopback . "ext4" LUKS2 ( ). . "xfs" LUKS2 . "ext4" "xfs" "btrfs" . "subvolume" "directory" "fscrypt" (quota) . B K M G T ( ) . "min" "max" . 245. lock USER . ( ). (system suspend) (resume) . LUKS2 . 245. unlock USER lock . . 245. lock-all lock . ( systemctl suspend ) . 245. deactivate-all deactivate . ( systemctl poweroff ) (unmount) /home/ . 247. with USER COMMAND... ( ) ( ). . 245. rebalance . --rebalance-weight= . LUKS2 . (synchronous) : . . . 250. firstboot . ( --prompt-new-user ). "home.create." ( JSON) . systemd-homed-firstboot.service . 256. list-signing-keys . (local.public) ( add-signing-key ). 258. get-signing-key [NAME...] ( PEM). local.public . 258. add-signing-key [FILE...] () () PEM . "-" . () .public () () . --key-name= . . : homectl get-signing-key | ssh myotherhost homectl add-signing-key --key-name="$HOSTNAME".public 258. remove-signing-key NAME... . 258. (CREDENTIALS) firstboot homectl ImportCredential=/LoadCredential=/SetCredential= ( systemd.exec(5) ). : home.create.* "home.create." . 256. (KERNEL COMMAND LINE) systemd.firstboot= homectl firstboot . systemd-firstboot(1) . 256. (EXIT STATUS) 0 . with . homectl . (ENVIRONMENT) $SYSTEMD_LOG_LEVEL ( ). . ( ): emerg alert crit err warning notice info debug 0...7. syslog(3) . console syslog kmsg journal ( SYSTEMD_LOG_LEVEL=debug,console:info debug info ). . $SYSTEMD_LOG_COLOR . tty . journalctl(1) . $SYSTEMD_LOG_TIME . . journalctl(1) . $SYSTEMD_LOG_LOCATION . . . . $SYSTEMD_LOG_TID . (TID) . . . $SYSTEMD_LOG_TARGET . : console ( tty ) console-prefixed ( tty <> syslog(3) ) kmsg ( ) journal ( ) journal-or-kmsg ( kmsg) auto ( ) null ( ). $SYSTEMD_LOG_RATELIMIT_KMSG kmsg (ratelimit) . . "true" . systemd kmsg . $SYSTEMD_PAGER, $PAGER --no-pager . $SYSTEMD_PAGER $PAGER . $SYSTEMD_PAGER $PAGER less(1) more(1) . . "cat" --no-pager . : $SYSTEMD_PAGERSECURE $SYSTEMD_PAGER $PAGER ( "cat" "") . $SYSTEMD_LESS less ( "FRSXMK"). : K Ctrl+C . less Ctrl+C . $SYSTEMD_LESS "K" less Ctrl+C . X termcap . . . $LESS less systemd . less(1) . $SYSTEMD_LESSCHARSET (charset) less ( "utf-8" UTF-8 ). $LESSCHARSET less systemd . $SYSTEMD_PAGERSECURE less(1) <<>> . sudo(8) pkexec(1) . . << >> ( ). << >> --no-pager PAGER=cat . . true << >> . << >> LESSSECURE=1 . less(1) << >> . false . SYSTEMD_PAGERSECURE=0 . $SYSTEMD_PAGERSECURE systemd << >> . UID geteuid(2) sd_pid_get_owner_uid(3) sudo(8) ( $SUDO_UID [5]) << >> . SYSTEMD_PAGERSECURE=1 << >> . . $SYSTEMD_PAGERSECURE . $SYSTEMD_PAGER $PAGER $SYSTEMD_PAGERSECURE . $SYSTEMD_COLORS . () systemd . $COLORTERM "truecolor" "24bit" $NO_COLOR $TERM . true $NO_COLOR . false ( ) . "16", "256", "24bit" ANSI . "auto-16", "auto-256", "auto-24bit" $TERM . $SYSTEMD_URLIFY . . systemd $TERM . (EXAMPLES) 1. "waldo" "wheel" 500 MiB . homectl create waldo --real-name="Waldo McWaldo" -G wheel --disk-size=500M 2. "wally" USB 500 . homectl create wally --real-name="Wally McWally" --image-path=/dev/disk/by-id/usb-SanDisk_Ultra_Fit_476fff954b2b5c44-0:0 --tasks-max=500 3. nice "odlaw" +5 $SOME "THING" . homectl update odlaw --nice=5 --setenv=SOME=THING 4. YubiKey PKCS#11/PIV: # 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 5. FIDO2: # Allow a FIDO2 security token to unlock the account of user 'nihilbaxter'. homectl update nihilbaxter --fido2-device=auto 6. : # Generate and add a recovery key for user 'emily'. homectl update emily --recovery-key=yes (SEE ALSO) systemd(1), systemd-homed.service(8), homed.conf(5), userdbctl(1), useradd(8), cryptsetup(8) (NOTES) 1. JSON https://systemd.io/USER_RECORD 2. https://standards.freedesktop.org/icon-naming-spec/icon-naming- spec-latest.html 3. (Blob) https://systemd.io/USER_RECORD_BLOB_DIRS 4. / https://systemd.io/USER_NAMES 5. $SUDO_UID . systemd 261.2 HOMECTL(1)