🖥️ LoopAware Legacy Boot Drive

Boot bridge for Supermicro servers that can't boot from NVMe drives directly.

Creates a minimal EFI boot environment that discovers OpenZFS pools and hands off to existing Proxmox boot entries.

⚡ Quick Start

# List available USB drives
python -m usb_creator list-drives

# Create bootable USB (requires root)
sudo python -m usb_creator create --device /dev/sdX --yes

📋 Table of Contents

• Problem & Solution
• Features
• Hardware Compatibility
• How It Works
• Installation
• Usage
• Development
• Testing
• Documentation
• Why This Works for 10 Years
• License

---

🎯 Problem & Solution

The Problem

Supermicro servers with older BIOS (like the X10SLM-F) cannot detect NVMe drives for boot:

┌─────────────────────────────────────────────────────────────┐
│  Supermicro X10SLM-F + E3-1271 v3                        │
├─────────────────────────────────────────────────────────────┤
│  ❌ BIOS: NVMe drives not visible for boot               │
│  ✅ PCIe: NVMe drives detected by OS                     │
│  💰 Budget: Can't afford expensive DOM modules            │
└─────────────────────────────────────────────────────────────┘

The Solution

A boot bridge that:

1. Provides EFI boot capability (so BIOS can see the USB)
2. Imports ZFS pools on NVMe drives
3. Discovers existing boot entries (what Proxmox installed)
4. Hands off to selected entry - NOT replacing Proxmox's boot system

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│   USB Boot      │────▶│   ZFS Pool       │────▶│   Proxmox       │
│   (EFI)         │     │   (NVMe x2)     │     │   Boots         │
└──────────────────┘     └──────────────────┘     └──────────────────┘

---

✨ Features

Feature	Description
🔄 Boot Bridge	Passes through to existing Proxmox boot entries
🛡️ No Boot Entry Management	We never create/maintain boot entries
⏱️ Auto-Boot	5-second timeout with intelligent default selection
🔌 NVMe Support	Built-in NVMe drivers (not as modules)
📦 ZFS Native	Full OpenZFS pool discovery
🔀 Mirror Support	Handles ZFS RAID1 (mirror) configurations
🔒 Reliability First	Designed for 10+ years of maintenance-free operation

---

🖥️ Hardware Compatibility

Supported Hardware

Component	Status	Notes
Supermicro X10SLM-F	✅ Tested	Primary target platform
CPU E3-1271 v3 (Haswell)	✅ Tested
NVMe via PCIe x4	✅ Tested	Samsung, Intel, WD compatible
ZFS Mirror (RAID1)	✅ Tested	Dual NVMe configuration
USB 16GB	✅ Tested	ADATA and generic supported
WD Enterprise SATA	✅ Compatible	Future expansion

Boot Modes

• UEFI Mode: Primary boot mode
• Legacy BIOS: Via CSM (Compatibility Support Module)

---

⚙️ How It Works

Architecture

flowchart TB
    subgraph USB["USB Boot Drive"]
        A[EFI Partition] --> B[Kernel + Initramfs]
        B --> C[Boot Bridge]
    end
    
    subgraph NVMe["NVMe Drives"]
        D[ZFS Pool Mirror] --> E[rpool/ROOT/pve-1]
        E --> F[vmlinuz + initrd]
    end
    
    C -->|zpool import| D
    C -->|discovers| F
    C -->|kexec handoff| G[Proxmox Boots]
    
    style USB fill:#f9f,stroke:#333
    style NVMe fill:#bbf,stroke:#333
    style G fill:#bfb,stroke:#333

Boot Flow

1. USB Boot → BIOS sees USB as EFI boot device
2. Kernel Loads → Linux kernel with NVMe + ZFS built-in
3. Pool Import → zpool import -a discovers ZFS pools
4. Entry Discovery → Scans /boot for kernel/initrd pairs
5. User Selection → 5-second timeout, auto-selects newest
6. Handoff → kexec -l loads kernel, kexec -e boots

Key Insight

We do NOT create our own boot entries. We just read what Proxmox already created.

---

📦 Installation

Prerequisites

# Install dependencies
pip install -e ".[dev]"

# Or use the virtual environment
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Build Boot Environment

# Build initramfs (already done - see output/)
make -C src/boot_env/initrd

Create Bootable USB

# 1. List available drives (safe - read only)
python -m usb_creator list-drives

# 2. Create bootable USB
sudo python -m usb_creator create --device /dev/sdX --yes

---

📖 Usage

Basic Usage

# List USB drives
python -m usb_creator list-drives

# Create bootable USB
sudo python -m usb_creator create --device /dev/sdb --yes

Boot Menu

When booting from USB:

==============================================
  LoopAware Legacy Boot Bridge
==============================================

Select boot entry (auto-boot in 5s):
  > [1] 6.17.0-pve-1 (default)
       Pool: rpool
       Dataset: rpool/ROOT/pve-1
       Kernel: vmlinuz-6.17.0-pve-1

Keys: [1-9] Select  [Up/Down] Navigate  [Enter] Boot

Boot Entry Selection Priority

1. Default boot entry (ZFS bootfs property)
2. Most recent kernel (by mtime)
3. First bootable entry
4. Fallback to menu

---

🛠️ Development

Project Structure

loopaware-legacy-boot-drive/
├── src/
│   ├── usb_creator/       # USB drive creation CLI
│   ├── boot_bridge/       # ZFS discovery & boot menu
│   └── boot_env/          # Kernel & initramfs
├── tests/
│   ├── testinfra/         # Host-level tests (123 tests)
│   └── molecule/          # VM-based tests
├── docs/                   # Documentation
└── LICENSE                # GPL v2

Commands

# Setup
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/testinfra/     # Fast (13s)
molecule test              # Slow (VM-based)

# Linting
ruff check .
mypy src/

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

---

🧪 Testing

Test Coverage

Category	Tests	Status
Boot Bridge	27	✅ Passing
USB Creator	19	✅ Passing
Edge Cases	19	✅ Passing
BIOS/UEFI	39	✅ Passing
Hardware Specific	19	✅ Passing
Total	123	✅ All Passing

Test Types

• Unit Tests: Individual component testing
• Integration Tests: Full workflow validation
• Hardware Tests: Platform-specific validation
• Molecule Tests: VM-based scenarios

Running Tests

# All tests
pytest

# Fast tests only
pytest tests/testinfra/

# Specific category
pytest tests/testinfra/test_boot_bridge.py

---

📚 Documentation

Documentation Structure

docs/
├── index.md                    # This file
├── installation.md             # Detailed installation
├── usage.md                   # Usage guide
├── hardware.md                 # Hardware compatibility
├── development.md             # Developer guide
├── testing.md                 # Testing documentation
├── troubleshooting.md         # Common issues
└── architecture/
    ├── boot-flow.md          # Boot process
    ├── zfs-discovery.md     # ZFS discovery
    └── kexec-handoff.md     # kexec mechanism

Building Docs

# Install documentation dependencies
pip install mkdocs mkdocs-material

# Serve locally
mkdocs serve

# Build
mkdocs build

---

🎯 Why This Works for 10 Years

Key Design Decisions

1. Passive Discovery

   • We never create boot entries
   • We just read what Proxmox created
   • Proxmox updates don't affect us

2. Kernel-Level Handoff

   • Uses kexec for direct memory execution
   • No intermediate bootloader
   • No NVRAM modification

3. No BIOS Modification

   • Stock BIOS works fine
   • No risk of brick
   • USB is easily replaceable

4. Proxmox Maintains Its Own Boot

   • Proxmox updates its kernel
   • Proxmox updates its boot entries
   • We just discover them

The 10-Year Promise

If Proxmox still works in 10 years, so do we.

Because:

• Proxmox maintains its boot entries
• We discover, we don't create
• Kernel updates don't break discovery
• kexec is stable and upstream

---

📄 License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

---

🆘 Support

• Issues: https://forgejo.loopaware.com/fredrick/loopaware-legacy-boot-drive/issues
• Redmine: https://redmine.loopaware.com/projects/30
• Email: it@loopaware.com

---

Made with ❤️ by LoopAware