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