How netbsdfr/smolbsd works
Project Type and Purpose
• This project is a specialized, minimalistic operating system image builder that creates a microVM based on NetBSD. Its primary goal is to generate a bootable NetBSD virtual machine that starts a designated service (such as a rescue shell, bozohttpd, nginx, etc.) in under a second. It supports building images on both NetBSD and GNU/Linux hosts and targets different architectures (amd64, i386, aarch64, etc.).
• There is also a simple Python/Flask-based frontend in the app/ directory that provides basic virtual machine management, and some Kubernetes (k8s) resources for containerized use cases.
File Structure and Key Components
• Top-level directories like .github indicate CI/CD integration, while the k8s folder shows that there is support for containerized deployment.
• The “app” directory contains a Flask application for a basic virtual machine manager, which exposes a web GUI.
• The “bios” folder holds binary firmware images used to boot the microVM.
• The “etc” folder provides various preconfigured configuration files (live.conf, rescue.conf, etc) needed by the VM.
• The “service” directory is the heart of the service configuration. Here, each service (e.g., rescue, bozohttpd, nbakery, runbsd, systembsd, etc.) has its own folder structure:
• Each service provides its own /etc/rc scripts to specify what to start on boot (executed inside the microVM).
• Some services also include “postinst” scripts, executed on the build host to perform final image customization.
• There’s also a “common” subdirectory that contains scripts (like basicrc) meant to be bundled into the final image.
• Scripts like "mkimg.sh" and "startnb.sh" are the build and boot scripts respectively:
• mkimg.sh is used to create the root filesystem image by combining the selected sets (e.g., rescue.tgz, base.tgz) with service-specific configuration.
• startnb.sh is used to boot the microVM via QEMU (or compatible hypervisors) with the given kernel and image.
• Other utility files include the Makefile that simplifies the build process (e.g., make rescue, make base) and additional support scripts.
Main Components & Interactions
a. Host Build Environment:
• Build Host Tools (GNU/Linux/NetBSD): Contains build scripts (mkimg.sh, Makefile) and configuration files (etc/*, service/*).
• Post-Installation Scripts: Represent the postinst processes for each service.
b. MicroVM Image & Boot Components:
• Filesystem Sets: "sets" directory or provided tgz sets that become part of the root image.
• Boot Scripts inside the image: The service “etc/rc” files that trigger service startup on boot.
• Firmware/Bios: Items in the bios/ directory, loaded to boot the microVM.
c. Service Modules:
• Individual Service Configs: Service definitions for rescue, bozohttpd, nbakery, etc., each containing service-specific startup and configuration files.
• Common Scripts: Scripts from service/common (e.g., basicrc) that are included in all services to standardize configuration.
d. Virtual Machine Manager:
• The Python/Flask application (app/app.py) that provides a web UI for managing and launching microVMs.
e. Deployment/Orchestration:
• Kubernetes integration: Components in the k8s/ directory (Dockerfile, YAML files) that can be used for container orchestration/deployment.
f. External Tools/Dependencies:
• QEMU and other VM technology for direct booting.
• Network configuration (ifconfig scripts, routing configuration in basicrc).
Architectural Patterns & Design Principles
• Separation of Build-Time and Runtime Responsibilities:
• Post-install scripts (executed on the build host) vs. runtime initialization scripts (executed inside the microVM).
• Modular Service Design:
• Each service is self-contained with its configuration and boot scripts, making it easier to swap or extend services.
• Minimalism & Performance Optimization:
• Focused on creating a minimal image with fast boot times through optimizations like direct kernel booting using PVH.
• Extensibility:
• Using common directories (like service/common) and a clear directory structure for adding new services or modifying existing ones.
• Multi-Architecture Support:
Instructing the Principal Software Engineer
• Rectangles for scripts and modules.
• Annotations noting significant design patterns, such as “Build-time vs Runtime Concerns”, “Modular Service Architecture”, or “Direct Kernel Boot via PVH”.