Q2Boot - Go go go Version 🚀

QEMU Quick Boot is an handy QEMU VM launcher rewritten in idiomatic, concise, and modern Go. This is a complete rewrite (hence the v2) of the original D language version, providing the same functionality with improved performance and maintainability.

Overview

Q2Boot is a command-line tool that wraps QEMU to provide a streamlined experience for launching virtual machines. It automatically configures common settings like KVM acceleration, virtio drivers, and networking while allowing customization through both configuration files and command-line options.

Features

• Zero-config startup: Works out of the box with sensible defaults
• JSON configuration: Persistent settings via ~/.config/q2boot/config.json
• Graphical and headless modes: GUI or console-only operation
• Snapshot support: Choose whether to persist changes
• Multi-architecture support: Works with x86_64, aarch64, ppc64le, and s390x
• KVM acceleration: Automatic hardware acceleration when available
• SSH-ready networking: Built-in port forwarding for easy access
• Comprehensive testing: Full test suite with >95% coverage
• Modern CLI: Built with Cobra for excellent user experience
• Cross-platform: Compiles to native binaries for multiple platforms

Examples

Booting a s390x image (very slow!)

Booting a ppc64le image

Installation

From Source

# Clone the repository
git clone https://github.com/yourusername/q2boot.git
cd q2boot
# Build the project
make build
# Install system-wide (optional)
make install

Pre-built Binaries

Download pre-built binaries from the releases page.

Quick Start

Basic Usage

The only required argument is the path to the disk image you want to boot, which can be on local disk or a remote URL. Supported remote protocols: http:// https:// ftp:// smb://

# Launch a VM with a disk image
./build/q2boot /path/to/your/disk.img
# Graphical mode
q2boot disk.img -g
# Custom CPU and RAM settings
q2boot disk.img --cpu 4 --ram 8
# Headless mode with persistent changes
q2boot disk.img -w
# Show command before running
q2boot disk.img --confirm

Exiting the VM Console

When running in headless/console mode (the default), your terminal connects directly to the VM's serial console. To exit the console, stop the VM, and return to the host OS:

• Press Ctrl-a then x.

Other useful shortcuts inside the console:

• Ctrl-a then c - Switch between the VM console and the QEMU monitor
• Ctrl-a then h - Show help for console shortcuts

Command Line Options

Configuration

Q2Boot automatically creates a configuration file at ~/.config/q2boot/config.json on first run:

{
  "arch": "x86_64",
  "cpu": 2,
  "ram_gb": 2,
  "ssh_port": 2222,
  "monitor_port": 0,
  "log_file": "q2boot.log",
  "write_mode": false,
  "graphical": false,
  "confirm": false
}

Configuration values are applied in this order (highest priority first):

1. Command-line arguments
2. Configuration file values
3. Built-in defaults

Usage Examples

Development Workflow

# Start a development VM with GUI
q2boot ubuntu-dev.img -g -c 4 -r 8
# Quick headless test (changes discarded)
q2boot test-image.img
# Persistent headless server
q2boot server.img -w --ssh-port 2223

Advanced Usage

For advanced use cases, you can pass custom arguments directly to QEMU. Use -- to forward every following argument verbatim — usually the easiest form:

# Everything after `--` is appended to the generated QEMU command
q2boot my-vm.img -- -device usb-tablet -display gtk

The --qemu-extra (-e) flag is also still accepted and can be combined with --:

q2boot my-vm.img \
  -e '-chardev' \
  -e 'socket,id=char0,path=/tmp/vhost-fs.sock' \
  -- -device 'vhost-user-fs-pci,chardev=char0,tag=myfs'

SSH Access

With the default configuration, you can SSH into your VM:

ssh -p 2222 user@localhost

QEMU Monitor Access

For debugging, you can expose the QEMU monitor over a telnet port.

# Expose the monitor on port 4444
q2boot -d my-vm.img --monitor-port 4444
# From another terminal, connect to the monitor
telnet localhost 4444

Log Monitoring

Monitor the VM's serial console:

tail -f q2boot.log

Architecture

The Go version is structured around clean, idiomatic Go patterns:

Project Structure

q2boot/
├── cmd/q2boot/          # Main application entry point
├── internal/config/    # Configuration management
├── internal/vm/        # VM implementations
├── Makefile           # Build automation
├── go.mod             # Go module definition
└── README_GO.md       # This file

Key Components

• Configuration Management: Viper-based settings with JSON persistence
• VM Abstraction: Clean interface-based design for different architectures
• Command Line Interface: Cobra-powered CLI with excellent UX
• Error Handling: Proper Go error handling with meaningful messages
• Testing: Comprehensive test suite with good coverage

Generated QEMU Command

Q2Boot generates commands similar to:

qemu-system-x86_64 \
  -M q35 -enable-kvm -cpu host \
  -smp 2 -m 4G \
  -drive file=disk.img,format=qcow2,if=none,id=disk0 \
  -device virtio-blk-pci,drive=disk0,num-queues=2 \
  -netdev user,id=net0,hostfwd=tcp::2222-:22 \
  -device virtio-net-pci,netdev=net0

Development

Building from Source

# Clone the repository
git clone https://github.com/ilmanzo/q2boot.git
cd q2boot
# Install dependencies
make deps
# Build in debug mode
make build
# Build optimized release
make release
# Cross-compile for multiple platforms
make build-all

Available Make Targets

• make build - Build the binary
• make release - Build optimized release binary
• make build-all - Cross-compile for multiple platforms
• make test - Run tests
• make test-coverage - Run tests with coverage report
• make fmt - Format code
• make vet - Run go vet
• make lint - Run golangci-lint (if available)
• make clean - Clean build artifacts
• make install - Install to /usr/local/bin
• make help - Show all available targets

Running Tests

# Run all tests
make test
# Run tests with coverage
make test-coverage
# Run benchmarks
make benchmark

Code Quality

The project follows Go best practices:

• gofmt for consistent formatting
• go vet for static analysis
• golangci-lint for comprehensive linting
• Comprehensive test coverage
• Clear error messages
• Proper interface design

Contributing

We welcome contributions! Here's how to get started:

Reporting Issues

1. Check existing issues first
2. Provide system information (OS, QEMU version, Go version)
3. Include error messages and logs
4. Provide steps to reproduce

Pull Requests

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes following Go best practices
4. Add tests for new functionality
5. Ensure all tests pass: make test
6. Update documentation if needed
7. Submit a pull request

Development Guidelines

• Code Style: Follow standard Go conventions and gofmt
• Testing: Add unit tests for new features and bug fixes
• Documentation: Update README and inline docs for public APIs
• Error Handling: Use proper Go error handling patterns
• Interfaces: Design clean, minimal interfaces

System Requirements

Runtime Requirements

• Linux, macOS, or Windows
• QEMU installed and in PATH
• KVM support (Linux) for hardware acceleration
• guestfs-tools for automatic architecture detection (optional, package may be named libguestfs-tools).
• Sufficient RAM for host + VM requirements

Build Requirements

• Go 1.21 or later
• Make (for build automation)
• Git (for version information)

Differences from D Version

The Go version offers several improvements over the original D implementation:

Performance

• Faster startup time
• Lower memory usage
• Better resource management

Maintainability

• Clear separation of concerns
• Interface-based design
• Comprehensive test coverage
• Standard Go project structure

User Experience

• Better error messages
• Improved CLI with Cobra
• Configuration validation
• Version information

Development Experience

• Standard Go tooling
• Easy cross-compilation
• Automated testing
• Consistent formatting

FAQ

Q: How does this compare to the original D version? A: The Go version provides the same functionality with better performance, maintainability, and user experience.

Q: Can I run multiple VMs simultaneously? A: Yes, use different SSH ports: q2boot -d vm1.img --ssh-port 2222 and q2boot -d vm2.img --ssh-port 2223

Q: How do I create a disk image? A: Use qemu-img create -f qcow2 disk.img 20G or make create-test-disk for a test image.

Q: What's the difference between snapshot and write mode? A: Snapshot mode (default) discards all changes when the VM exits. Write mode saves changes permanently.

Q: How do I exit the VM serial console? A: Press Ctrl-a followed by x to quit QEMU and return to your host terminal.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• QEMU - The amazing virtualization platform
• Cobra - Excellent CLI framework
• Viper - Configuration management
• Original D language implementation by Andrea Manzini
• Contributors and testers who help improve Q2Boot

Happy virtualizing with Go! 🎉🐹

If you find Q2Boot useful, please consider giving it a ⭐ on GitHub!