Running in Virtual Machines

Guide to running Redox OS in QEMU and VirtualBox virtual machines

Running Redox OS in a virtual machine is the easiest and safest way to try the operating system without affecting your existing setup.

QEMU (Recommended)

QEMU is the primary development and testing platform for Redox OS and provides the best compatibility and performance.

The Redox build system includes built-in QEMU support with optimized configurations for each architecture.

Quick Start

After building Redox, you can launch it in QEMU with:

make qemu

This automatically configures QEMU with appropriate settings for your chosen architecture.

Architecture-Specific Configurations

x86-64

Default Configuration:

• Machine: Q35
• CPU: Core 2 Duo (or host CPU with KVM)
• Cores: 4
• Memory: 2048 MB
• Firmware: UEFI (OVMF)
• Storage: NVMe
• Network: Intel e1000
• Graphics: Standard VGA
• Audio: Intel HDA

Command:

make qemu

i586

Default Configuration:

• Machine: PC (i440FX)
• CPU: Pentium II (or host CPU with KVM)
• Cores: 1
• Memory: 1024 MB
• Firmware: BIOS
• Storage: ATA
• Network: Intel e1000
• Graphics: Standard VGA
• Audio: AC’97

Command:

make qemu ARCH=i586

ARM64

Default Configuration:

• Machine: virt
• CPU: max
• Cores: 1
• Memory: 2048 MB
• Firmware: UEFI (AAVMF)
• Graphics: ramfb
• USB: XHCI with keyboard and tablet

Command:

make qemu ARCH=aarch64

RISC-V 64

Default Configuration:

• Machine: virt (ACPI disabled)
• CPU: max
• Cores: 4
• Memory: 2048 MB
• Firmware: EDK2 RISC-V
• Graphics: ramfb
• Network: bridge

Command:

make qemu ARCH=riscv64gc

QEMU Customization Options

You can customize the QEMU configuration using make variables:

Hardware Acceleration

Enable KVM (Linux) or HVF (macOS):

make qemu kvm=yes

KVM/HVF is automatically enabled when the host and guest architectures match. Disable with kvm=no.

Storage Configuration

Change disk type:

make qemu disk=nvme    # NVMe (default for x86-64)
make qemu disk=ata     # AHCI/IDE
make qemu disk=virtio  # VirtIO block
make qemu disk=usb     # USB storage

Graphics Options

Change GPU type:

make qemu gpu=vga          # Standard VGA (default)
make qemu gpu=virtio       # VirtIO GPU
make qemu gpu=virtio-gl    # VirtIO GPU with OpenGL
make qemu gpu=no           # Headless (serial only)

Network Configuration

Network options:

make qemu net=no           # No network
make qemu net=redir        # User mode with port forwarding
make qemu net=rtl8139      # RTL8139 adapter
make qemu net=virtio       # VirtIO network
make qemu bridge=br0       # Bridged networking

Port forwarding (net=redir):

• SSH: localhost:8022 → guest:22
• HTTP: localhost:8080 → guest:80
• Additional: 8081, 8082, 8083, 64126

Audio Configuration

Audio options:

make qemu audio=no         # No audio
make qemu audio=ac97       # AC'97 (i586 default)
# Intel HDA is default for x86-64

CPU and Memory

Adjust resources:

make qemu QEMU_SMP=8 QEMU_MEM=4096

Debugging

GDB debugging:

make qemu gdb=yes         # Wait for GDB connection
make qemu gdb=nonblock    # Allow GDB attach without blocking

GDB will listen on port 1234.

Advanced QEMU Examples

Performance Mode

# Maximum performance with KVM and VirtIO
make qemu kvm=yes disk=virtio net=virtio gpu=virtio

Serial Console

QEMU provides serial console access by default:

Serial output is multiplexed to stdio. Use Ctrl+A, C to access the QEMU monitor.

To log serial output to a file:

make qemu qemu_serial_logfile=serial.log

QEMU Firmware Locations

The build system automatically detects firmware files:

UEFI for x86-64:

• /usr/share/ovmf/OVMF.fd
• /usr/share/OVMF/OVMF_CODE.fd
• /usr/share/qemu/edk2-x86_64-code.fd

UEFI for ARM64:

• /usr/share/AAVMF/AAVMF_CODE.fd
• /usr/share/qemu/edk2-aarch64-code.fd

UEFI for RISC-V:

• /usr/share/qemu-efi-riscv64/RISCV_VIRT_CODE.fd
• /usr/share/edk2/riscv/RISCV_VIRT_CODE.fd

VirtualBox

VirtualBox provides an alternative virtualization option with a graphical interface.

VirtualBox support is less mature than QEMU. Some features may not work correctly.

Quick Start

After building Redox, create and launch a VirtualBox VM:

make virtualbox

This will:

1. Delete any existing “Redox” VM
2. Create a new VM with recommended settings
3. Convert and attach the hard drive image
4. Start the VM

VirtualBox Configuration

The automated setup configures:

Setting	Value
Memory	2048 MB
Video Memory	32 MB
Storage Controller	Intel AHCI (SATA)
Network	NAT with Intel PRO/1000 MT Desktop (82540EM)
Audio	Intel HD Audio
USB	Disabled (recommended for compatibility)
Keyboard	PS/2
Mouse	PS/2

Manual VirtualBox Setup

If you prefer to configure VirtualBox manually:

1. Create a new VM

   • Name: Redox
   • Type: Other
   • Version: Other/Unknown (64-bit)
2. Configure system settings

   • Base Memory: 2048 MB or more
   • Processors: 1 or more
   • Enable I/O APIC
3. Configure display

   • Video Memory: 32 MB
   • Graphics Controller: VBoxVGA or VMSVGA
4. Attach storage

   1. Create a SATA controller
   2. Convert the Redox image to VDI format:
      VBoxManage convertfromraw build/x86_64/harddrive.img build/x86_64/harddrive.vdi
      
   3. Attach the VDI file to the SATA controller
5. Configure network

   • Adapter 1: Enabled
   • Attached to: NAT
   • Adapter Type: Intel PRO/1000 MT Desktop
   • Enable cable connected
6. Configure audio

   • Enable Audio
   • Audio Controller: Intel HD Audio
7. Disable USB

   USB support should be disabled for better compatibility with Redox.

VirtualBox Network Capture

The automated setup enables network packet capture:

cat build/x86_64/network.pcap | wireshark -k -i -

VirtualBox Serial Log

Serial output is logged to:

build/x86_64/serial.log

Comparison: QEMU vs VirtualBox

Feature	QEMU	VirtualBox
Performance	Excellent with KVM/HVF	Good
Compatibility	Best	Good
Setup	Automated via Makefile	Automated via Makefile
GUI	Optional (GTK/SDL)	Native GUI
Debugging	Built-in GDB support	Limited
Multi-arch	x86, ARM, RISC-V	x86 only
Recommended For	Development, testing	Desktop evaluation

Live ISO vs Hard Drive Image

Redox can boot from either format:

Live ISO

Build and run:

make live=yes qemu

Advantages:

• No installation required
• Boot from CD-ROM
• Safe for testing

Disadvantages:

• Read-only system
• No persistence
• Slower boot

Hard Drive Image

Build and run:

make qemu

Advantages:

• Faster boot
• Persistent storage
• Full system installation

Disadvantages:

• Requires disk image creation

Troubleshooting

QEMU fails to start

Check firmware installation:

ls /usr/share/ovmf/OVMF.fd
ls /usr/share/qemu/edk2-*.fd

Install the appropriate UEFI firmware package for your distribution:

• Ubuntu/Debian: ovmf qemu-efi-aarch64 qemu-efi-arm
• Fedora: edk2-ovmf edk2-aarch64
• Arch: edk2-ovmf edk2-armvirt

Black screen after boot

Try different GPU options:

make qemu gpu=virtio
make qemu gpu=no serial=yes

No network connectivity

Check network configuration:

make qemu net=redir  # Use port forwarding
make qemu net=no     # Disable network

Poor performance

Enable hardware acceleration:

make qemu kvm=yes              # Linux
# Or for macOS, HVF is auto-detected

And use VirtIO devices:

make qemu kvm=yes disk=virtio net=virtio

VirtualBox VM won't boot

• Ensure USB is disabled
• Try switching graphics controller
• Check that the VDI conversion succeeded
• Verify SATA controller is set to AHCI

Next Steps

Running on Real Hardware

Ready to install Redox on physical hardware

Building Redox

Learn how to build Redox from source