zosbuilder/docs/NOTES.md

Zero-OS Branding Diagnostics and Notes

Context

• Goal: Branding flags should enable passwordless root in initramfs and update /etc/{issue,motd}.
• Source of truth for flags: config/build.conf
• Implementation hook: bash.initramfs_finalize_customization() called from bash.initramfs_create_cpio() just before CPIO creation.

Observed issue in latest build

• Branding flags were set: logs showed "Branding debug: ZEROOS_BRANDING=true ... _branding=true".
• Both /etc/passwd and /etc/shadow exist in initramfs; Alpine uses shadow for authentication.
• The script only edited /etc/passwd, leaving /etc/shadow unchanged; login still required a password.
• Evidence (from build logs):
  • Preview /etc/passwd (pre): root:(x):0:0:root:/root:/bin/sh
  • Preview /etc/shadow (pre): root:(***):...
  • Preview /etc/passwd (post): root:(x):0:0:root:/root:/bin/sh
  • Preview /etc/shadow (post): root:(***):...

Root cause

• Editing /etc/passwd is ineffective when /etc/shadow is present; the pw field is ignored in passwd and 'x' indicates to consult shadow.

Fix implemented

• Change in bash.initramfs_finalize_customization():
  • Prefer editing /etc/shadow for root’s password field; fallback to /etc/passwd if shadow is absent.
  • Command used:
    • sed -i 's/^root:[^:]*:/root::/' "${initramfs_dir}/etc/shadow"
• Diagnostics retained:
  • Logs branding vars, presence/perms of /etc/{shadow,passwd}, and sanitized previews pre/post.

Verification plan

• Minimal rebuild to re-run finalize:
  • rm -f .build-stages/initramfs_create.done .build-stages/initramfs_test.done
  • DEBUG=1 ./scripts/build.sh --skip-tests
• Confirm in logs:
  • "✓ Root password removed in /etc/shadow (passwordless root)"
  • Preview /etc/shadow (post): root:(***): with empty field notation "root::" internally.
• Optional deeper check by inspecting the archive:
  • cd dist && mkdir tmp && cd tmp
  • xz -dc ../initramfs.cpio.xz | cpio -idv
  • grep '^root:' ./etc/shadow | sed 's/^(root:)[^:]:/\1(**):/'
  • Expected: the second field is empty (root::...).

Behavior and safety notes

• Permissions: /etc/shadow typically 640 root:shadow; the fix does not alter permissions.
• Passwordless root in initramfs is intended only when config/build.conf sets ZEROOS_BRANDING="true" (or ZEROOS_REBRANDING="true").
• The change affects only the initramfs image; not the host system.

Code references

• Branding guard and customization: bash.initramfs_finalize_customization()
• Archive creation entry point: bash.initramfs_create_cpio()
• Build orchestrator: bash.main_build_process()

Notes usage

• This file (docs/NOTES.md) is the session-to-session log of debugging and decisions.
• For finalized policies, consider adding docs/DECISIONS.md.

Change log

• 2025-09-09: Added diagnostics and implemented shadow-first passwordless root; documented verification steps.