omarabdul3ziz/zosbuilder
1
0
Fork 0
forked from tfgrid/zosbuilder
Code Pull Requests Activity
Files
310e11d2bfaa2e4b2a19240889f9b91be1c98a65
zosbuilder/docs/NOTES.md
Jan De Landtsheer 79ed723303 Notes.md, absolute path normalizing 
- edit NOTES.md for updating line numbers
- add check for using normalized path in initramfs normalization
2025-09-18 21:45:21 +02:00

10 KiB
Raw Blame History

Zero-OS Builder – Working Notes and Repository Map

Purpose

  • This document captures operational knowledge of this repository: build flow, key files, flags, and recent behavior decisions (e.g., passwordless root).
  • Links below point to exact functions and files for fast triage, using code navigation-friendly anchors.

Repository Overview

  • Build entrypoint: scripts/build.sh
    • Orchestrates incremental stages using stage markers.
    • Runs inside a container defined by Dockerfile for reproducibility.
  • Common utilities and config loading: bash.common.sh
    • Loads config/build.conf, normalizes directory paths, provides logging and safe execution wrappers.
  • Initramfs assembly and finalization: bash.initramfs_* functions
    • Copies components, sets up zinit configs, finalizes branding, creates CPIO archive, validates contents.
  • Kernel integration (optional embedded initramfs): bash.kernel_* functions
    • Downloads/configures/builds kernel and modules, embeds initramfs, runs depmod.
  • zinit configuration: config/zinit/
    • YAML service definitions and init scripts used by zinit inside the initramfs rootfs.
  • RFS tooling (modules/firmware flists): scripts/rfs/
    • Packs module/firmware flists and embeds them into initramfs at /etc/rfs.

Container Tooling (dev-container)

  • Base image: Alpine 3.22 in Dockerfile
  • Tools:
    • shadow (passwd/chpasswd): required for root password management in initramfs.
    • openssl, openssl-dev: kept for other build steps and potential hashing utilities.
    • build-base, rustup, kmod, upx, etc.: required by various build stages.
  • Removed: perl, not required for password handling after switching to passwd/chpasswd workflow.

Configuration – build.conf

  • File: config/build.conf
  • Key variables:
    • Versions: ALPINE_VERSION, KERNEL_VERSION
    • Directories (relative in config, normalized to absolute during runtime):
      • INSTALL_DIR="initramfs"
      • COMPONENTS_DIR="components"
      • KERNEL_DIR="kernel"
      • DIST_DIR="dist"
    • Flags:
      • ZEROOS_BRANDING="true"
      • ZEROOS_REBRANDING="true"
    • Branding behavior:
      • ZEROOS_PASSWORDLESS_ROOT="true" (default for branded builds in current policy)
      • ZEROOS_ROOT_PASSWORD_HASH / ROOT_PASSWORD_HASH (not used in current policy)
      • ZEROOS_ROOT_PASSWORD / ROOT_PASSWORD (not used in current policy)
    • FIRMWARE_TAG optional for reproducible firmware flist naming.

Absolute Path Normalization

  • Location: bash.common.sh
  • After sourcing build.conf, the following variables are normalized to absolute paths anchored at PROJECT_ROOT:
    • INSTALL_DIR, COMPONENTS_DIR, KERNEL_DIR, DIST_DIR
  • Rationale: Prevents path resolution errors when CWD changes (e.g., when kernel build operates in /workspace/kernel/current, validation now resolves to /workspace/initramfs instead of /workspace/kernel/current/initramfs).

Build Pipeline – High Level

  • Orchestrator: bash.main_build_process()
    • Stage list:
      • alpine_extract
      • alpine_configure
      • alpine_packages
      • alpine_firmware
      • components_build
      • components_verify
      • kernel_modules
      • init_script
      • components_copy
      • zinit_setup
      • modules_setup
      • modules_copy
      • cleanup
      • rfs_flists
      • validation
      • initramfs_create
      • initramfs_test
      • kernel_build
      • boot_tests
    • Each stage wrapped with bash.stage_run() and tracked under .build-stages/
  • Container use:
    • Always run in container for stable toolchain (podman/docker auto-detected).
    • Inside container, CWD normalized to PROJECT_ROOT.

Initramfs Assembly – Key Functions

Kernel Integration

RFS Flists (modules/firmware)

Branding Behavior (Passwordless Root, motd/issue)

  • Finalization hook: bash.initramfs_finalize_customization()
  • Behavior (current policy):
    • Passwordless root enforced using passwd for shadow-aware deletion:
    • Branding toggles: ZEROOS_BRANDING and ZEROOS_REBRANDING (branding guard printed in logs).
    • Branding also updates /etc/motd and /etc/issue to Zero-OS.

Console and getty

Validation Diagnostics and Triage

  • Common error previously observed:
    • “Initramfs directory not found: initramfs (resolved: /workspace/kernel/current/initramfs)”
  • Root cause:
    • INSTALL_DIR re-sourced in a different CWD and interpreted as relative.
  • Fix:
    • Absolute path normalization of INSTALL_DIR/COMPONENTS_DIR/KERNEL_DIR/DIST_DIR after sourcing build.conf in bash.common.sh.
    • Additional “Validation debug” prints added in bash.initramfs_validate().
  • Expected logs now:
    • “Validation debug: input='initramfs' PWD=/workspace PROJECT_ROOT=/workspace INSTALL_DIR=/workspace/initramfs”
    • Resolves correctly even if called from a different stage CWD.

How to Verify Passwordless Root

  • After build, check archive:
    • mkdir -p dist/_inspect && cd dist/_inspect
    • xz -dc ../initramfs.cpio.xz | cpio -idmv
    • grep '^root:' ./etc/shadow
    • Expect root:: (empty field) indicating passwordless root.
  • At runtime on console:
    • When prompted for root’s password, press Enter.

Stage System and Incremental Rebuilds

  • Stage markers stored in .build-stages/ (one file per stage).
  • To minimally rebuild:
    • Remove relevant .done files, e.g.:
      • initramfs_create.done initramfs_test.done validation.done
    • Rerun: DEBUG=1 ./scripts/build.sh --skip-tests
  • Show status:
    • ./scripts/build.sh --show-stages

Key Decisions (current)

  • Branding enforces passwordless root via passwd -d -R inside initramfs finalization, avoiding direct edits of passwd/shadow files.
  • Directory paths normalized to absolute after loading config to avoid CWD-sensitive behavior.
  • Container image contains shadow suite to ensure passwd/chpasswd availability; perl removed.

File Pointers (quick jump)

Change Log

  • 2025-09-09:
    • Enforce passwordless root using passwd -d -R in finalization.
    • Normalize INSTALL_DIR/COMPONENTS_DIR/KERNEL_DIR/DIST_DIR to absolute paths post-config load.
    • Add validation diagnostics prints (input/PWD/PROJECT_ROOT/INSTALL_DIR/resolved).
    • Ensure shadow package in container for passwd/chpasswd; keep openssl and openssl-dev; remove perl earlier.