Multiboot - CyberMind-FR/secubox-deb GitHub Wiki

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.

# 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

# 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

# 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:

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

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]] ](/CyberMind-FR/secubox-deb/wiki/[[ARM-Installation) | Live-USB