From 8a473cc1c2971681b741589c89444f38546f1124 Mon Sep 17 00:00:00 2001 From: CyberMind-FR Date: Mon, 27 Apr 2026 11:22:41 +0200 Subject: [PATCH] docs(wiki): Add Multiboot Live OS announcement and documentation - Add announcement banner on wiki home for v2.2.3 multiboot release - Create wiki/Multiboot.md with full multiboot documentation - Add Multiboot and Eye Remote links to sidebar navigation - Update sidebar version to v2.2.3 - Document Eye Remote Pi Zero as USB gadget for ESPRESSObin boot - Add partition layout, boot flow, and troubleshooting docs Co-Authored-By: Claude Opus 4.5 --- .claude/HISTORY.md | 23 ++++ image/multiboot/README.md | 109 ++++++++++++++-- wiki/Home.md | 14 +++ wiki/Multiboot.md | 253 ++++++++++++++++++++++++++++++++++++++ wiki/_Sidebar.md | 6 +- 5 files changed, 391 insertions(+), 14 deletions(-) create mode 100644 wiki/Multiboot.md diff --git a/.claude/HISTORY.md b/.claude/HISTORY.md index 99cdeb33..3283c643 100644 --- a/.claude/HISTORY.md +++ b/.claude/HISTORY.md @@ -5,6 +5,29 @@ ## 2026-04-27 +### Session 67 — Multiboot Wiki & Eye Remote Docs (v2.2.3) + +**Feature:** Wiki documentation for multiboot live OS and Eye Remote integration + +**Description:** +Added comprehensive wiki documentation for the multi-architecture boot system, including the new Multiboot wiki page, home page announcement banner, and sidebar navigation updates. + +**Files Created:** +- `wiki/Multiboot.md` — Full documentation for multiboot live OS + +**Files Modified:** +- `wiki/Home.md` — Added announcement banner for v2.2.3 multiboot +- `wiki/_Sidebar.md` — Added Multiboot and Eye Remote links, bumped version +- `image/multiboot/README.md` — Added Eye Remote integration section + +**Changes:** +- Eye Remote Pi Zero architecture documented with ASCII diagrams +- Partition layout and boot flow explained +- Build instructions and GitHub Actions CI docs +- Troubleshooting section for common boot issues + +--- + ### Session 66 — Multiboot GitHub Action (v2.2.3) **Feature:** GitHub Actions workflow for automated multiboot image builds diff --git a/image/multiboot/README.md b/image/multiboot/README.md index aa4b0784..7c352139 100644 --- a/image/multiboot/README.md +++ b/image/multiboot/README.md @@ -1,11 +1,41 @@ -# SecuBox Multi-Boot Storage System +# SecuBox Multi-Boot Live OS ## Overview -Multi-architecture bootable storage for Pi Zero Eye Remote that supports: -- **ARM64**: ESPRESSObin/MOCHAbin via U-Boot -- **AMD64**: Any x86_64 UEFI system -- **Shared Data**: Cross-architecture application data +Multi-architecture bootable live operating system with RAM-based execution and shared persistent data. Designed for: + +- **Live Demo/Recovery** — Boot from USB for demonstrations, repair, or factory reset +- **Pi Zero Eye Remote** — USB mass storage gadget presenting bootable image to MOCHAbin/ESPRESSObin +- **Portable Installation** — Boot on any ARM64 or AMD64 system with persistent data + +### Supported Architectures +- **ARM64**: ESPRESSObin, MOCHAbin, Armada boards via U-Boot +- **AMD64**: Any x86_64 UEFI system (PC, laptop, server) +- **Shared Data**: Cross-architecture persistent storage + +## Use Cases + +### 1. Eye Remote USB Boot (Pi Zero W) +The Pi Zero runs Eye Remote firmware and presents this image as USB mass storage. +ESPRESSObin/MOCHAbin boots directly from the USB storage. + +``` +┌─────────────┐ USB OTG ┌─────────────────┐ +│ Pi Zero W │◄────────────────►│ ESPRESSObin │ +│ Eye Remote │ mass_storage │ U-Boot │ +│ (32GB uSD) │ 16GB multiboot │ boots from USB │ +└─────────────┘ └─────────────────┘ +``` + +### 2. Direct USB Boot +Flash to USB stick, boot any ARM64/AMD64 system directly. + +### 3. Demo/Recovery Mode +Pre-configured SecuBox environment for: +- Live demonstrations +- System recovery and repair +- Factory reset and cloning +- Installation to eMMC/NVMe ## Partition Layout (16GB+ recommended) @@ -88,13 +118,68 @@ gunzip -c /boot/efi/flash/secubox-emmc.img.gz | dd of=/dev/mmcblk0 bs=4M status= ## Build +### Build Multiboot Image ```bash -# Build complete multi-boot image -./build-multiboot.sh --size 16G --output secubox-multiboot.img +# Build complete multi-boot image (16GB default) +sudo ./build-multiboot.sh --size 16G --output secubox-multiboot.img -# Build AMD64 rootfs only -./build-amd64-rootfs.sh --output rootfs-amd64/ - -# Build ARM64 rootfs only -./build-arm64-rootfs.sh --output rootfs-arm64/ +# With desktop environment +sudo ./build-multiboot.sh --size 32G --desktop --output secubox-multiboot-desktop.img ``` + +### Build Individual Components +```bash +# AMD64 rootfs only +sudo ./build-amd64-rootfs.sh --output rootfs-amd64/ + +# ARM64 rootfs only (uses existing ESPRESSObin tooling) +# See board/espressobin-v7/ +``` + +### GitHub Actions +The `build-multiboot.yml` workflow automates CI builds with: +- Configurable image sizes (8/16/32GB) +- Optional desktop environment +- Automatic release publishing + +## Eye Remote Integration + +### Preparing SD Card for Pi Zero + +```bash +# 1. Flash Eye Remote base image +sudo dd if=output/secubox-eye-remote-*.img of=/dev/sdX bs=4M status=progress + +# 2. Expand root partition to fill card +sudo parted /dev/sdX resizepart 2 100% +sudo resize2fs /dev/sdXp2 + +# 3. Copy multiboot image as storage +sudo mount /dev/sdXp2 /mnt +sudo cp output/secubox-multiboot.img /mnt/var/lib/secubox/eye-remote/storage.img +sudo umount /mnt +``` + +### Gadget Configuration +The USB mass_storage gadget presents `/var/lib/secubox/eye-remote/storage.img` to the connected host. ESPRESSObin U-Boot detects it as a USB drive and boots from it. + +## Troubleshooting + +### Not Booting from Eye Remote +1. Check storage.img exists: `ls -lh /var/lib/secubox/eye-remote/storage.img` +2. Verify gadget status: `systemctl status secubox-eye-gadget` +3. Check USB connection: `dmesg | grep usb` + +### ESPRESSObin U-Boot Commands +``` +usb start +usb dev 0 +ls usb 0:1 +load usb 0:1 $loadaddr boot.scr +source $loadaddr +``` + +## Version History + +- **v2.2.3** — GitHub Actions CI, Eye Remote integration docs +- **v2.2.2** — Initial multiboot system with ARM64 + AMD64 support diff --git a/wiki/Home.md b/wiki/Home.md index c1ffb984..fafdbc97 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -6,6 +6,20 @@ Complete security appliance solution ported from OpenWrt to Debian bookworm. Des --- +> **NEW v2.2.3 — Multi-Boot Live OS with Eye Remote Integration** +> +> Dual-architecture bootable image (ARM64 + AMD64) with RAM-based execution and shared persistent storage. Boot from USB or use Pi Zero Eye Remote as USB gadget to boot ESPRESSObin/MOCHAbin. +> +> **Features:** +> - Boot any ARM64 (U-Boot) or AMD64 (UEFI) system from one USB stick +> - Pi Zero presents multiboot image as USB storage for ESPRESSObin boot +> - RAM-based live execution — minimal I/O, perfect for USB gadgets +> - Shared data partition accessible from both architectures +> +> See [[Multiboot]] for documentation | [Download v2.2.3](https://github.com/CyberMind-FR/secubox-deb/releases/tag/multiboot-v2.2.3) + +--- + ## 🔴 BOOT — Quick Start ### VirtualBox (2 Minutes) ⭐ diff --git a/wiki/Multiboot.md b/wiki/Multiboot.md new file mode 100644 index 00000000..31eb60db --- /dev/null +++ b/wiki/Multiboot.md @@ -0,0 +1,253 @@ +# Multi-Boot Live OS + +**SecuBox v2.2.3** — Dual-architecture bootable live system with RAM-based execution. + +--- + +## Overview + +Multi-architecture bootable live operating system supporting both ARM64 (U-Boot) and AMD64 (UEFI) systems from a single image. Designed for: + +- **Live Demo/Recovery** — Boot from USB for demonstrations, repair, or factory reset +- **Pi Zero Eye Remote** — USB mass storage gadget presenting bootable image to MOCHAbin/ESPRESSObin +- **Portable Installation** — Boot on any ARM64 or AMD64 system with persistent data + +### Supported Architectures + +| Architecture | Boot Method | Target Boards | +|--------------|-------------|---------------| +| **ARM64** | U-Boot | ESPRESSObin, MOCHAbin, Armada boards | +| **AMD64** | UEFI GRUB | Any x86_64 PC, laptop, server | +| **Shared** | — | Cross-architecture persistent storage | + +--- + +## Use Cases + +### 1. Eye Remote USB Boot (Pi Zero W) + +The Pi Zero runs Eye Remote firmware and presents the multiboot image as USB mass storage. ESPRESSObin/MOCHAbin boots directly from the USB storage. + +``` +┌─────────────┐ USB OTG ┌─────────────────┐ +│ Pi Zero W │◄────────────────►│ ESPRESSObin │ +│ Eye Remote │ mass_storage │ U-Boot │ +│ (32GB uSD) │ 16GB multiboot │ boots from USB │ +└─────────────┘ └─────────────────┘ +``` + +**Setup:** +1. Flash Eye Remote image to SD card (32GB recommended) +2. Copy multiboot image to `/var/lib/secubox/eye-remote/storage.img` +3. Connect Pi Zero to ESPRESSObin via USB OTG +4. ESPRESSObin U-Boot detects USB storage and boots SecuBox + +### 2. Direct USB Boot + +Flash multiboot image to USB stick, boot any ARM64/AMD64 system directly. + +```bash +# Flash to USB drive +xzcat secubox-multiboot-2.2.3.img.xz | sudo dd of=/dev/sdX bs=4M status=progress +``` + +### 3. Demo/Recovery Mode + +Pre-configured SecuBox environment for: +- Live demonstrations to customers +- System recovery and repair +- Factory reset and cloning +- Installation to eMMC/NVMe + +--- + +## Partition Layout + +| Part | Type | Size | Mount | Purpose | +|------|------|------|-------|---------| +| 1 | EFI (FAT32) | 512MB | /boot/efi | UEFI + U-Boot boot files | +| 2 | ext4 | 3GB | / (ARM64) | SecuBox ARM64 live rootfs | +| 3 | ext4 | 3GB | / (AMD64) | SecuBox AMD64 live rootfs | +| 4 | ext4 | 8GB+ | /srv/data | Shared application data | + +### Boot Files (Partition 1) + +``` +/boot/efi/ +├── EFI/ +│ └── BOOT/ +│ ├── BOOTX64.EFI # GRUB for AMD64 +│ └── grub.cfg # GRUB config +├── Image # ARM64 kernel +├── initrd.img # ARM64 initramfs +├── dtbs/ # ARM64 device trees +├── boot.scr # U-Boot script (ARM64) +├── grub/ +│ └── grub.cfg # GRUB config (AMD64) +├── vmlinuz # AMD64 kernel +├── initrd-amd64.img # AMD64 initramfs +└── flash/ + └── secubox-emmc.img.gz # eMMC flasher image +``` + +--- + +## Boot Flow + +### ARM64 (ESPRESSObin/MOCHAbin) + +1. U-Boot loads `boot.scr` from partition 1 +2. Kernel + initrd from partition 1 +3. Rootfs from partition 2 +4. Mounts partition 4 as /srv/data +5. Bind-mounts shared paths + +### AMD64 (UEFI) + +1. UEFI loads GRUB from EFI/BOOT/BOOTX64.EFI +2. GRUB loads vmlinuz + initrd from partition 1 +3. Rootfs from partition 3 +4. Mounts partition 4 as /srv/data +5. Bind-mounts shared paths + +--- + +## Shared Data Structure + +``` +/srv/data/ +├── etc/ +│ └── secubox/ # Shared configs +│ ├── api.toml +│ ├── users.json +│ ├── tls/ +│ └── modules/ +├── var/ +│ └── lib/ +│ └── secubox/ # Application state +│ ├── crowdsec/ +│ ├── haproxy/ +│ ├── wireguard/ +│ └── dpi/ +├── srv/ +│ └── secubox/ # Service data +│ ├── mitmproxy/ +│ ├── nginx/ +│ └── certs/ +└── log/ + └── secubox/ # Shared logs +``` + +--- + +## Building + +### Build Multiboot Image + +```bash +# Build complete multi-boot image (16GB default) +sudo ./image/multiboot/build-multiboot.sh --size 16G --output secubox-multiboot.img + +# With desktop environment +sudo ./image/multiboot/build-multiboot.sh --size 32G --desktop --output secubox-multiboot-desktop.img +``` + +### GitHub Actions CI + +Automated builds via `.github/workflows/build-multiboot.yml`: +- Configurable image sizes (8/16/32GB) +- Optional desktop environment +- Automatic release publishing on tags + +--- + +## Eye Remote Integration + +### Preparing SD Card for Pi Zero + +```bash +# 1. Flash Eye Remote base image +sudo dd if=output/secubox-eye-remote-*.img of=/dev/sdX bs=4M status=progress + +# 2. Expand root partition to fill card +sudo parted /dev/sdX resizepart 2 100% +sudo resize2fs /dev/sdXp2 + +# 3. Copy multiboot image as storage +sudo mount /dev/sdXp2 /mnt +sudo cp output/secubox-multiboot.img /mnt/var/lib/secubox/eye-remote/storage.img +sudo umount /mnt +``` + +### Gadget Configuration + +The USB mass_storage gadget presents `/var/lib/secubox/eye-remote/storage.img` to the connected host. ESPRESSObin U-Boot detects it as a USB drive and boots from it. + +--- + +## Flash to eMMC + +From either architecture: + +```bash +secubox-flash-emmc # Interactive installer + +# Or manual: +gunzip -c /boot/efi/flash/secubox-emmc.img.gz | dd of=/dev/mmcblk0 bs=4M status=progress +``` + +--- + +## Default Credentials + +| Service | Username | Password | +|---------|----------|----------| +| Web UI | admin | secubox | +| SSH | root | secubox | +| User | secubox | secubox | + +--- + +## Troubleshooting + +### Not Booting from Eye Remote + +1. Check storage.img exists: `ls -lh /var/lib/secubox/eye-remote/storage.img` +2. Verify gadget status: `systemctl status secubox-eye-gadget` +3. Check USB connection: `dmesg | grep usb` + +### ESPRESSObin U-Boot Commands + +``` +usb start +usb dev 0 +ls usb 0:1 +load usb 0:1 $loadaddr boot.scr +source $loadaddr +``` + +### AMD64 Not Booting + +1. Verify UEFI boot mode (not Legacy/CSM) +2. Check Secure Boot is disabled +3. Select USB drive in boot menu (F12/F2/ESC) + +--- + +## Downloads + +- [Latest Release](https://github.com/CyberMind-FR/secubox-deb/releases/latest) +- [v2.2.3 Multiboot](https://github.com/CyberMind-FR/secubox-deb/releases/tag/multiboot-v2.2.3) + +--- + +## Version History + +| Version | Changes | +|---------|---------| +| **v2.2.3** | GitHub Actions CI, Eye Remote integration, wiki docs | +| **v2.2.2** | Initial multiboot system with ARM64 + AMD64 support | + +--- + +*See also: [[Eye-Remote]] | [[ARM-Installation]] | [[Live-USB]]* diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md index c8154cf8..ed4dac66 100644 --- a/wiki/_Sidebar.md +++ b/wiki/_Sidebar.md @@ -1,12 +1,14 @@ -**[SecuBox](Home)** | [FR](Home-FR) | [DE](Home-DE) | [中文](Home-ZH) | **v1.6.0** +**[SecuBox](Home)** | [FR](Home-FR) | [DE](Home-DE) | [中文](Home-ZH) | **v2.2.3** ### 🔴 BOOT — Getting Started -* [[Live-USB-VirtualBox|VirtualBox]] ⭐ `run-vbox.sh` +* [[Multiboot|Multi-Boot Live OS]] ⭐ **NEW** +* [[Live-USB-VirtualBox|VirtualBox]] `run-vbox.sh` * [[Live-USB-QEMU|QEMU]] 🖥️ `run-qemu.sh` * [[Live-USB]] | [FR](Live-USB-FR) | [DE](Live-USB-DE) | [中文](Live-USB-ZH) * [[Installation]] | [FR](Installation-FR) | [DE](Installation-DE) | [中文](Installation-ZH) * [[ARM-Installation|ARM / U-Boot]] | [FR](ARM-Installation-FR) | [DE](ARM-Installation-DE) | [中文](ARM-Installation-ZH) ⚡ * [[ESPRESSObin]] | [FR](ESPRESSObin-FR) | [DE](ESPRESSObin-DE) | [中文](ESPRESSObin-ZH) +* [[Eye-Remote|Eye Remote (Pi Zero)]] 📡 * [[QEMU-ARM64]] 🖥️ ### 🟢 ROOT — Configuration