SD VM Launcher

SD VM Launcher is a Windows PowerShell tool for booting a Raspberry Pi SD card directly in QEMU. It is designed for cases where you have a physical SD card, want to inspect or recover the installed Linux system, and prefer a serial-console VM workflow instead of booting real Raspberry Pi hardware.

The current workflow is optimized for Ubuntu/Raspberry Pi cloud-init based images, including images that expose a small FAT boot partition as system-boot and a Linux root partition as writable.

Features

• Auto-detect Raspberry Pi boot SD cards on removable drives.
• Detect QEMU automatically from common Windows install paths.
• Configure serial console output for headless QEMU boot.
• Back up boot files before editing them.
• Restore original boot files after QEMU exits.
• Boot with QEMU virt using vmlinuz + initrd.img when available.
• Fall back to Raspberry Pi machine types when direct kernel boot is unavailable.
• List Linux users on startup through cloud-init.
• Set a startup password change for a selected Linux user through cloud-init.
• Support auto user selection for the first normal login user.

Requirements

• Windows PowerShell 5.1 or later.
• Administrator privileges.
• QEMU for Windows with qemu-system-aarch64.exe.
• A Raspberry Pi compatible SD card with a readable boot partition.

Install QEMU with winget:

winget install QEMU

Quick Start

Run one of the launcher entry points:

sd-vm-launcher.bat

or, for an elevated launch:

sd-vm-launcher.vbs

Typical flow:

1. Select 1 to scan for the SD card.
2. Select 2 to configure serial console.
3. Select 3 to start QEMU.
4. Use Ctrl+A, then X to exit QEMU.
5. Let auto-restore restore the original boot files, or select 5 manually.

Shortcut:

[4] Quick Start

This runs serial-console configuration and starts QEMU.

Menu

[1] Scan SD Card
[2] Configure Serial Console (backup + edit)
[3] Start VM (QEMU -nographic)
[4] Quick Start (2+3 auto)
[5] Restore original files
[6] Set startup password change
[7] Print users on startup
[0] Exit

User Discovery And Password Reset

For cloud-init based images, option 7 writes a temporary user-data task that prints /etc/passwd users during boot. The important section is:

===== SD VM Launcher: likely login users =====

After identifying the correct username, option 6 can schedule a password change at the next boot.

Username examples:

ubuntu
pi
root
auto

Use auto when you do not know the username. It selects the first normal login user with UID >= 1000.

The password reset keeps existing account metadata intact. It does not create a user and does not change UID, GID, home directory, shell, or group membership.

Project Structure

sd-vm-launcher.ps1       Main interactive launcher
sd-vm-launcher.bat       Batch entry point
sd-vm-launcher.vbs       Elevated Windows launcher
debug-qemu.ps1           QEMU diagnostic helper
config.json              Runtime defaults
modules/
  autodetect.ps1         SD card and Pi model detection
  configure-console.ps1  Boot file backup and serial console edits
  password-reset.ps1     cloud-init user listing and password change tasks
  restore.ps1            Restore boot files from local SD-card backups
  vm-launch.ps1          QEMU discovery and launch logic
backups/                 Local generated backups, not for source control

Configuration

config.json:

{
  "autoRestore": true,
  "baudRate": 115200,
  "qemuMemory": "2G"
}

• autoRestore: restore modified boot files after QEMU exits.
• baudRate: serial console baud rate.
• qemuMemory: memory passed to QEMU.

Safety Notes

• This tool accesses \\.\PhysicalDriveN; administrator rights are required.
• Always confirm the detected SD card before starting QEMU.
• The password-change task necessarily writes the new password into boot-partition user-data temporarily. Keep autoRestore enabled and do not commit generated backups.
• backups/ can contain real boot configuration and cloud-init data. It is ignored by .gitignore and should not be published.
• This tool is intended for systems and SD cards you own or are authorized to administer.

Known Limitations

• The virt direct-kernel path works best for Ubuntu/Raspberry Pi images with vmlinuz and initrd.img in the boot partition.
• Raspberry Pi machine fallback depends on QEMU support and the specific image.
• cloud-init actions run late in the boot process. User listing or password changes may appear several minutes after the login prompt.
• Some Raspberry Pi hardware-specific services may fail in QEMU because the VM is not real Raspberry Pi hardware.

License

No license has been selected yet. Add a LICENSE file before publishing if you want others to use, modify, or redistribute the project.