6.9 KiB

Executable File

Raw Blame History

QUICKSTART — DriveStage in 5 Minutes

Author: Jeremy Anderson info@dcos.net — dcos.net

This guide provisions a bootable DriveStage stick in under five minutes.

Prerequisites:

A Linux machine (any modern distribution)
A USB drive (8 GB or larger)
Root access via sudo

Step 1 — Install system dependencies

The engine requires standard Linux utilities. Install by distribution:

Debian / Ubuntu

sudo apt update
sudo apt install -y \
    parted dosfstools e2fsprogs \
    grub-pc-bin grub-efi-amd64-bin \
    util-linux rsync tar \
    smartmontools

Fedora

sudo dnf install -y \
    parted dosfstools e2fsprogs \
    grub2-pc grub2-efi-x64 grub2-tools grub2-common \
    util-linux rsync tar \
    smartmontools

Arch Linux

sudo pacman -S --needed \
    parted dosfstools e2fsprogs \
    grub efibootmgr \
    util-linux rsync tar \
    smartmontools

Step 2 — Obtain the engine

From the tarball

tar xzf drivestage-0.4.0.tar.gz
cd drivestage
chmod +x scripts/blkstage.sh

From git

git clone https://git.dcos.net/dcosnet/DriveStage.git
cd drivestage
chmod +x scripts/blkstage.sh

Step 3 — Identify the USB drive

Plug in the USB drive and identify the device node:

lsblk

Locate the device matching your USB drive's capacity. The device is typically /dev/sdb or /dev/sdc. Verify the device name carefully — the next step erases all data on the target.

For interactive selection, run the engine without a device argument and it lists removable candidates:

sudo ./scripts/blkstage.sh setup

Step 4 — Provision the drive

This erases all data on the target drive. Verify the device name.

sudo ./scripts/blkstage.sh setup /dev/sdX

Replace /dev/sdX with your device (for example, /dev/sdb).

The engine executes the following sequence:

Requests typed confirmation (you type the device basename, e.g. sdb)
Wipes existing filesystem signatures
Creates a GPT partition table with three partitions:
- ESP (FAT32, 512 MB) — UEFI GRUB binaries
- BIOS Boot (1 MB, unformatted) — GRUB i386-pc embedding
- Payloads (ext4, remainder) — ISOs and rootfs data
Formats each partition
Installs GRUB2 for both UEFI (x86_64-efi) and BIOS (i386-pc)
Writes the auto-scan grub.cfg
Creates the payload directory structure

At completion the drive is bootable and empty.

Step 5 — Add payloads

The payload partition mounts at /mnt/drivestage/payload/. Two methods:

Method A — `deploy` subcommand

# ISO — copy and done
sudo ./scripts/blkstage.sh deploy /dev/sdX ~/Downloads/ubuntu-24.04-desktop-amd64.iso

# Additional ISOs
sudo ./scripts/blkstage.sh deploy /dev/sdX ~/Downloads/archlinux-2026.08.01-x86_64.iso

# Rootfs tarball — copy and extract in one step
sudo ./scripts/blkstage.sh deploy /dev/sdX ~/Downloads/rootfs-arch-x86_64.tar.gz

Method B — Direct copy

# Payload partition is mounted at /mnt/drivestage/payload/
cp ~/Downloads/*.iso /mnt/drivestage/payload/payloads/isos/
cp ~/Downloads/rootfs-*.tar.gz /mnt/drivestage/payload/payloads/rootfs_tarballs/

# Extract tarballs (ISOs require no extraction)
sudo ./scripts/blkstage.sh scan /dev/sdX

Payload directory layout

/mnt/drivestage/payload/payloads/
├── isos/               ← .iso files (Ubuntu, Arch, Fedora, ...)
├── rootfs_tarballs/    ← .tar.gz files (extracted on first scan)
├── rootfs/             ← pre-extracted rootfs directories
├── images/             ← .img / .raw files (experimental)
└── overlay/            ← reserved for overlayfs persistence

Step 6 — List registered payloads

sudo ./scripts/blkstage.sh list /dev/sdX

Sample output:

[*] Registered payloads on this drive:

  ISOs:
    ubuntu-24.04-desktop-amd64.iso                   4.7 GB
    archlinux-2026.08.01-x86_64.iso                  1.1 GB

  RootFS Tarballs:
    rootfs-arch-x86_64.tar.gz                        850 MB

  Extracted RootFS:
    rootfs-arch-x86_64                               1.2 GB

Step 7 — Boot

sudo umount /mnt/drivestage/payload/boot/efi 2>/dev/null
sudo umount /mnt/drivestage/payload 2>/dev/null
sudo eject /dev/sdX

Boot from the USB on any machine. GRUB presents the auto-discovered payload menu:

  ====================================================
    DriveStage  —  Auto-Scan Payload Menu
    Partition UUID: a1b2c3d4-5678-90ef-1234-567890abcdef
  ====================================================

  ubuntu-24.04-desktop-amd64.iso  [casper]
  archlinux-2026.08.01-x86_64.iso  [arch]
  rootfs-arch-x86_64  [arch-rootfs]

  Drop to GRUB command line
  Reboot system
  Halt system

Select an entry to boot.

Adding payloads after initial setup

No re-provisioning required:

sudo mount /dev/sdX3 /mnt/drivestage/payload
cp ~/Downloads/fedora-workstation.iso /mnt/drivestage/payload/payloads/isos/
sudo umount /mnt/drivestage/payload

ISOs require no scan command. GRUB discovers them at boot. The scan command applies only to tarballs, which require host-side extraction (GRUB has no untar capability at boot time).

Optional — Build the GUI

cd gui/

# Install Rust via rustup if absent
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

cargo build --release
./target/release/drivestage-gui

The GUI provides a setup wizard, payload manager, bootloader switcher, menu editor, and diagnostics.

Troubleshooting

"Refusing: '/dev/sdX' contains mounted filesystem (likely your OS disk)"

The selected device hosts a mounted OS partition. Re-run lsblk and select the actual USB drive.

Verify the file resides in payloads/isos/. The auto-scan reads specific subdirectories. Run sudo ./scripts/blkstage.sh list /dev/sdX to confirm.

An ISO fails to boot

The auto-scan recognizes 30+ distro patterns. Unrecognized ISOs chainload via GRUB's loopback.cfg. If chainload fails, add a manual menuentry to /boot/grub/custom.cfg on the payload partition. Refer to BLOG.md for the architecture.

Drive does not boot on BIOS hardware

Confirm setup was run — it installs GRUB's i386-pc BIOS boot code. To reinstall:

sudo ./scripts/blkstage.sh setup /dev/sdX

This re-partitions and formats. Back up payloads first.

Drive does not boot on a Mac

Macs use 64-bit EFI. The --removable flag in grub-install --target=x86_64-efi writes /EFI/BOOT/BOOTX64.EFI, which Macs boot. Hold Option at startup and select "EFI Boot."

Next steps

BLOG.md — design rationale and architecture deep-dive
README.md — full feature list and repository layout
./scripts/blkstage.sh --help — complete CLI reference
gui/README.md — GUI build and usage

6.9 KiB Executable File Raw Blame History