Install Windows 3.11 in QEMU

Overview

This skill provides procedural knowledge for installing and running Windows 3.11 in a QEMU virtual machine with VNC and web-based access. Windows 3.11 is a legacy 16-bit operating system that requires specific QEMU configuration for proper operation.

Pre-Installation Checklist

Before starting, verify the following:

• Check for expected file paths and naming conventions - Tests or acceptance criteria may expect specific paths (e.g., /tmp/qemu-monitor.sock vs /tmp/monitor-socket ). Review any test files or documentation first.

• Identify the disk image location and format - Common locations include /app/isos/ or /var/lib/qemu/

• Determine QEMU version compatibility - If the image is known to work with a specific QEMU version, note any compatibility flags needed

QEMU Configuration for Windows 3.11

Essential Parameters

Windows 3.11 requires specific QEMU parameters for proper operation:

qemu-system-i386
-drive file=/path/to/win311.img,format=raw,if=ide
-m 32
-vga cirrus
-vnc :1
-monitor unix:/tmp/qemu-monitor.sock,server,nowait
-snapshot
-k en-us

Critical Parameters Explained

Parameter Purpose Notes

-vga cirrus

VGA adapter type REQUIRED for Windows 3.11 display compatibility. Alternatives: -vga std . Without this, display may not work.

-m 32

Memory allocation 32MB is appropriate for Windows 3.11

-monitor unix:/tmp/qemu-monitor.sock,server,nowait

QMP monitor socket Use the expected socket path - check tests/docs for naming conventions

-snapshot

Immutable disk mode Prevents writes to the original image

-k en-us

Keyboard layout US keyboard mapping

if=ide

Disk interface IDE interface for legacy OS compatibility

Common VGA Options for Legacy Systems

• -vga cirrus

• Best compatibility for Windows 3.x/9x

• -vga std

• Standard VGA, good fallback option

• -vga vmware

• VMware SVGA (may not work with Windows 3.11)

VNC and Web Access Setup

VNC Configuration

When using -vnc :1 , the VNC server runs on port 5901 (5900 + display number).

noVNC Web Interface

To provide web-based access to the VNC session:

Install websockify: Bridges WebSocket connections to VNC

pip install websockify

Start websockify:

websockify --web=/usr/share/novnc 6080 localhost:5901

Configure nginx (if needed):

• Check existing nginx configuration with nginx -T before making changes

• Look for conflicting server blocks or port bindings

• Create a dedicated configuration file in /etc/nginx/sites-available/

Verification Strategies

1. Verify QEMU Process

ps aux | grep qemu

Confirm the process is running with expected parameters.

2. Test QMP Monitor Connection

echo '{"execute": "qmp_capabilities"}' | nc -U /tmp/qemu-monitor.sock

Expected response should include {"return": {}} .

3. Test VNC Connectivity

nc -zv localhost 5901

4. Visual Verification (Critical)

Do not mark boot completion as verified without visual confirmation. Options:

• Take a VNC screenshot using a tool like vncsnapshot

• Use a headless browser to capture the noVNC web interface

• Connect via VNC client and manually verify

5. Wait for Boot Completion

Windows 3.11 boot time varies. Wait at least 30-60 seconds before testing, not just 10 seconds.

Common Pitfalls

Missing VGA Configuration

Problem: QEMU starts but display is blank or garbled. Solution: Add -vga cirrus or -vga std to the QEMU command.

Wrong Socket Path

Problem: Tests fail to connect to QMP monitor. Solution: Check expected socket path in tests/documentation. Common paths:

• /tmp/qemu-monitor.sock

• /tmp/monitor-socket

• /var/run/qemu-monitor.sock

Nginx Configuration Conflicts

Problem: Nginx fails to start or proxy doesn't work. Solution:

• Run nginx -T to see full configuration before making changes

• Check for conflicting server blocks

• Ensure no duplicate listen directives

Premature Completion Claims

Problem: Marking tasks complete without actual verification. Solution: Always verify visually that Windows 3.11 reaches the desktop before claiming completion.

QEMU Version Compatibility

Problem: Image created for older QEMU version doesn't work correctly. Solution:

• Check if legacy machine types are needed: -M pc-i440fx-2.0

• Review QEMU changelog for breaking changes between versions

• Test with compatibility flags if available

Troubleshooting Workflow

• Check QEMU is running: ps aux | grep qemu

• Verify VNC port is open: netstat -tlnp | grep 590

• Test QMP socket: nc -U /tmp/qemu-monitor.sock

• Check QEMU logs: Run QEMU with -D /tmp/qemu.log for debugging

• Verify nginx status: systemctl status nginx and nginx -t

• Check websockify: ps aux | grep websockify

Approach Summary

• Research first: Check tests/docs for expected paths and configurations

• Configure QEMU properly: Include VGA adapter and correct socket path

• Set up access layer: VNC, websockify, nginx in sequence

• Verify each component: Test connectivity at each layer

• Visual confirmation: Always verify Windows 3.11 actually boots to desktop