SYSTEMD-HOMED.SERVICE(8)

📦
version 261.3 · 13 versions
, in ubuntu stonking

💖 NAME 💖

okay bestie, welcome to systemd-homed.service, systemd-homed — literally the Home Area/User Account Manager. it's giving "i handle your whole home directory situation" and honestly? iconic. 🏠✨

this is page SYSTEMD-HOMED.SERVICE(8) from the systemd manual, and i'm gonna walk you through it like we're texting at 2am. buckle up. 🎀

✨ SYNOPSIS ✨

systemd-homed.service

/usr/lib/systemd/systemd-homed

that's it. that's the whole vibe. two lines. she's lowkey mysterious. 💅

🦋 DESCRIPTION 🦋

okay so systemd-homed is a system service — and what does she do? she can create, remove, change or inspect home areas. and when i say home areas i don't just mean plain directories, i mean:

  • directories
  • network mounts
  • real or loopback block devices with a filesystem
  • ...optionally encrypted 👀

literally the full spectrum, no cap.

most of systemd-homed's functionality is accessible through the homectl(1) command. so like, that's your main character entry point, iykyk.

for the details about the format and design of home areas managed by systemd-homed.service, go read the Home Directories documentation (link's down in NOTES, don't worry babe 🫶).

each home directory managed by systemd-homed.service synthesizes a local user and group. yup, she just makes them. and these get made available to the system using the User/Group Record Lookup API via Varlink, which means you can browse them with userdbctl(1). cute, right? 🌸

also — systemd-homed.service manages blob directories for each home directory it manages. more on that in User Record Blob Directories (again, NOTES. i gotchu 💜).

🔑 KEY MANAGEMENT 🔑

okay this part is important so like, lock in bestie. 🔥

User records are cryptographically signed with a public/private key pair — and the signature is part of the JSON record itself. fancy.

here's the rules, and they're the whole game:

  • for a user to be permitted to log in locally, the public key matching the signature of their user record must be installed 🔓
  • for a user record to be modified locally, the private key matching the signature must be installed locally too 🔐

the keys live in the /var/lib/systemd/home/ directory:

  • /var/lib/systemd/home/local.private — the private key of the public/private key pair used for local records. Currently, only a single such key may be installed.

Added in version 246.

  • /var/lib/systemd/home/local.public — the public key of the public/private key pair used for local records. Currently, only a single such key may be installed.

Added in version 246.

  • /var/lib/systemd/home/*.public — additional public keys. Any users whose user records are signed with any of these keys are permitted to log in locally. An arbitrary number of keys may be installed this way. (slay, unlimited public keys 💅)

Added in version 246.

all key files listed above are in PEM format. don't ask me to convert them, just use PEM. 😌

🚚 the migration moment (still KEY MANAGEMENT, don't @ me)

say you wanna migrate a home directory from a host named "foobar" to another host named "quux". bestie, it's genuinely easy:

copy /var/lib/systemd/home/local.public from the host "foobar" to "quux" — and maybe call the file on the destination /var/lib/systemd/home/foobar.public, reflecting the origin of the key. 🎀

now if the user record should be modifiable on "quux", then the pair /var/lib/systemd/home/local.public and /var/lib/systemd/home/local.private need to be copied from "foobar" to "quux", and placed under the identical paths there — because currently only a single private key is supported per host. one private key per host, that's the rule. 🫡

⚠️ okay but note of course that the latter means that user records generated/signed before the key pair is copied in lose their validity. so like... do it in the right order, babe. 😭

📡 SIGNALS 📡

  • SIGUSR1 — upon reception of the SIGUSR1 process signal, systemd-homed will re-establish its file watches on /home/ and rescan the directory for home directories. like a little refresh. a vibe check for your home dirs. 🔄✨

Added in version 258.

👀 SEE ALSO 👀

go read these next, bestie, they're all part of the ecosystem:

🌈 NOTES 🌈

the receipts, the links, the sources — here they are:

  1. Home Directories https://systemd.io/HOME_DIRECTORY
  2. User/Group Record Lookup API via Varlink https://systemd.io/USER_GROUP_API
  3. User Record Blob Directories https://systemd.io/USER_RECORD_BLOB_DIRS

and that's the whole page, bestie!! 💜 this one's from systemd version 261.3 — so yeah, she's fresh, she's current, she's serving home area manager realness. mwah. 💋🎀🦋

periodt. 💅

📦 where this page comes from