From 33668eb84f0fddac58d31f6ea9f3684ff84e2899 Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Sun, 20 Sep 2026 03:11:10 -0400 Subject: [PATCH] docs: add appliance identity, mDNS, and Bash prompt design Split out of #80 so this architectural commitment gets its own review. The spec covers hostname persistence across OS DDI updates, the `blueserver-0` default, mDNS resolution on the appliance network, and the interactive Bash prompt style. None of that is part of the CoreOS login hardening and core key provisioning work that #80 delivers. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../2026-09-09-appliance-identity-design.md | 147 ++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-09-appliance-identity-design.md diff --git a/docs/superpowers/specs/2026-09-09-appliance-identity-design.md b/docs/superpowers/specs/2026-09-09-appliance-identity-design.md new file mode 100644 index 00000000..ca5cef28 --- /dev/null +++ b/docs/superpowers/specs/2026-09-09-appliance-identity-design.md @@ -0,0 +1,147 @@ +# Appliance Identity, mDNS, and Bash Prompt Design + +**Status:** Approved design + +## Goal + +Give each Bluefin Server appliance a stable, human-readable network identity +and a clear interactive prompt. A newly provisioned appliance without an +operator-selected hostname is `blueserver-0`, reachable as +`blueserver-0.local`. + +## Scope + +- Persist a selected hostname across OS DDI updates. +- Default an unselected appliance to `blueserver-0`. +- Resolve and announce appliance names through mDNS on the wired appliance + network. +- Display `username@hostname` with a blue `@` in interactive Bash sessions. +- Direct console users to the hostname-based KubeStellar URL. + +This design does not add an authoritative DNS server, DHCP server, Avahi, or +automatic hostname allocation. + +## Naming Policy + +The recommended fleet sequence is `blueserver-0`, `blueserver-1`, +`blueserver-2`, and so on. The default is always `blueserver-0`; later +appliances receive an explicitly selected hostname through provisioning. + +An operator may select another valid lower-case static hostname, but +documentation recommends the numbered pattern and requires checking +`.local` before selecting a name. The system does not probe mDNS and +choose a number automatically: two simultaneous installations can otherwise +choose the same name. A collision is an operator-visible configuration error, +not a reason to silently rename an appliance. + +`blueserver.local` is intentionally not an alias. The canonical address is +always the selected hostname followed by `.local`, so each device has exactly +one predictable appliance name. + +## Persistent Hostname State + +`/var/lib/bluefin-server/hostname` is the canonical hostname source. It lives +on the persistent `/var` partition, outside the replaceable OS DDI. + +The image creates `/etc/hostname` as a symlink to that file. A static tmpfiles +rule creates the persistent source with `blueserver-0` only if it does not +exist. An operator-provided `tmpfiles.extra` credential can replace it before +first boot with a selected hostname: + +```text +f+~ /var/lib/bluefin-server/hostname 0644 root root - Ymx1ZXNlcnZlci0xCg== +``` + +The base64 payload in this example is `blueserver-1\n`. The hostname +application service validates the stored value as a lower-case hostname before +calling `hostnamectl set-hostname --static`. It runs after `/var` and tmpfiles +setup, and before the network and resolver services. If validation fails, the +service fails visibly and leaves networking available for local diagnosis; it +does not substitute or silently generate a different hostname. + +Because `/etc/hostname` points at the persistent source, an authenticated +operator may use `sudo hostnamectl set-hostname --static blueserver-1` to +rename an appliance. The change survives reboot and OS DDI replacement. + +## DNS and Discovery Plan + +Bluefin uses `systemd-resolved` and standards-based multicast DNS, not a local +DNS authority: + +1. Enable `systemd-resolved.service` in the installed OS and make + `/etc/resolv.conf` point at its local stub resolver. +2. Set `MulticastDNS=yes` and `LLMNR=no` on the existing wired + `systemd-networkd` profile. mDNS is required for `.local`; LLMNR is neither + needed nor desirable on an appliance network. +3. Set `MulticastDNS=yes` in resolved configuration as the explicit global + policy. +4. Announce and resolve the static hostname as `.local`; no search + domain or unicast DNS zone is configured. + +This works without router configuration on clients whose system resolver +supports mDNS. The appliance documentation will identify +`https://blueserver-0.local:8080/` as the first-appliance URL. The existing +local TLS wildcard certificate coverage remains compatible with named +`.local` access. + +## Bash Prompt + +Add FSDK's `bash-config` component so `/etc/bashrc` loads +`/etc/profile.d/*.sh` for interactive Bash sessions. A small profile hook sets +the following prompt only when `PS1` is present: + +```bash +PS1='\u\[\e[1;34m\]@\[\e[0m\]\h:\w\$ ' +``` + +It renders, for example: + +```text +core@blueserver-0:~$ +``` + +Only the `@` is bright blue. `\h` tracks the live system hostname, `\w` +retains working-directory context, and `\$` renders `$` for `core` and `#` +after `sudo -i`. + +## Console Experience + +The installed OS console issue banner uses systemd's hostname escape rather +than the address-derived IP escape. It directs an operator to: + +```text +KubeStellar Console: https://.local:8080/ +``` + +At runtime, a device named `blueserver-0` therefore displays +`https://blueserver-0.local:8080/`. + +## Failure Handling + +- An invalid supplied hostname fails the hostname service visibly; networking + is not blocked. +- A duplicate hostname is not renamed automatically. mDNS collision symptoms + require the operator to select a different persistent hostname. +- If `systemd-resolved` is unavailable, normal DNS resolution must fail + visibly through the service dependency rather than falling back to a + hand-written resolver file. +- The hostname and mDNS controls apply only to the installed OS, not the + Installer environment. + +## Verification + +Focused tests will assert the default and credential hostname rules, hostname +validation and service ordering, resolver enablement and mDNS/LLMNR policy, +the `/etc/resolv.conf` and `/etc/hostname` links, the console `.local` URL, +and the exact color-safe prompt definition. A QEMU smoke test will confirm +that a default installation announces and resolves `blueserver-0.local` after +DHCP is ready. + +## References + +- `systemd.network(5)`: + +- `systemd-resolved.service(8)`: + +- `tmpfiles.d(5)`: +