QEMU Q.E.D.

About QEMU QED

QEMU (Quick EMUlator) is a powerful and flexible open-source command line application for computer emulation and virtualization. It is potentially of great use to archivists, conservators, and other digital preservation practitioners in need of recreating legacy computing systems, whether to interact with or migrate software-dependent data. But it is also a complex application with a vast range of configuration options. QEMU QED is intended to lower the barrier to first-time users by breaking down QEMU use into more digestible concepts and recipes.

Dylan Lorenz's post/paper "Floating Time with QEMU at the Denver Art Museum" provides an excellent, use-case-oriented overview of QEMU's advantages, complexities, and the need for a community-driven resource to guide new users through QEMU's thorough but often scattered existing documentation.

QEMU QED is a work-in-progress. For full QEMU docs, check out the project's official website.

Install QEMU

Recommendations for installing QEMU on different operating systems.

QEMU QED recommends using the most up-to-date version possible, but may specifically recommend earlier versions based on compatibility with certain operating systems. Example commands will note when they are tested or recommended for certain versions.

BitCurator/Ubuntu

QEMU can easily be installed in any Ubuntu-based system like BitCurator (or the Windows Subsystem for Linux) using common package managers, but the version installed will depend on the package manager used.

apt will currently install QEMU v2.11 from the Ubuntu repositories:

apt install qemu

Homebrew can be used to quickly install a more recent version, QEMU v4.1:

brew install qemu

See the official docs for recommendations for other Linux systems.

MacOS

QEMU (v4.1) is best installed on MacOS via Homebrew

brew install qemu

Windows

The QEMU project does not officially maintain Windows installers but recommends binaries provided by their contributor Stefan Weil.

Weil's installers are named by date rather than version, see the History notes to match installers to desired version. QEMU QED recommends the most recent installer available for QEMU v4.1.

Weil's binaries can also be installed using the Chocolatey package manager:

C:\> choco install qemu

Calling/using QEMU

QEMU is technically a bundle of applications that emulate several different computing platforms or architectures. The first step in using QEMU is to decide which architecture is to be emulated, which will determine the command used to invoke QEMU from a command line terminal.

This is not as complicated as it sounds. The best method is to figure out the target operating system you are trying to emulate (e.g. Windows 95) and work backwards. Generally, only a few platforms/commands are currently relevant for legacy material from the PC era.

$ qemu-system-i386

Emulates the Intel x86 32-bit architecture. (aka "i386", "x86", "x86_32", or "IA-32") Relevant for IBM/PC/MS-DOS, all Windows systems up until 64-bit Windows XP, and many Linux, BSD, or other open source operating systems from, roughly, the late 1980s through the mid-2000s.

$ qemu-system-x86_64

Emulates Intel x86 64-bit architecture. (aka "x86_64", "x64") Can be used to run more recent PC operating systems like any Windows system newer than Windows XP 64-bit, or again many Linux, BSD, or other open source systems.

$ qemu-system-ppc

Emulates the PowerPC architecture. Mostly relevant to emulate certain legacy MacOS versions (9.2.2, early OSX), some Linux systems.

All platforms currently supported by QEMU are documented here, but again these will largely be used in edge cases for more specialized hardware.

For the purpose of this guide, QEMU QED examples will use qemu-system-i386, except in specific recipes where required.


Boot a CD-ROM

qemu-system-i386 -cdrom filename.iso

qemu-system-i386
calls the program and specifies the i386 system architecture
-cdrom
tells the program you are sending it a CD-ROM type of file
filename.iso
path and name of the input file

Boot a hard disk image

qemu-system-i386 -drive file=filename.img

qemu-system-i386
calls the program and specifies the i386 system architecture
-drive
tells the program you are sending it a file mimicking a hard disk drive
file=filename.img
path and name of the input file; QEMU is file extension-agnostic, so this could be .dd, .qcow, .dmg, etc.

Creating and Manipulating Disk Images

Disk images are files that act as storage devices. They contain files, folders, and directory structures. It is often necessary to create or modify a disk image before building a qemu machine.

Get Info About a Disk Image

qemu-img info Win2k.img

This command extracts and displays relevant information about a disk image in plain text, including file format, disk size (actual and virtual), etc.

qemu-img
calls the qemu program to work with images
info
instructs the program to retrieve and display metadata
Win2k.img
path, name and extension of the input disk image

tested with QEMU v2.11, v3.1, v4.1

Create an Image

qemu-img create Win2k.img 20G

qemu-img
calls the qemu program to work with images
create
instructs the program to produce a new image (will be "raw" by default)
Win2k.img
defines the path and file name to store the image
20G
defines the size of the image as 20 gigabytes. K, M, G, and T can be used to create kilo-, mega-, giga-, or terabyte size disk images.

tested with QEMU v2.11, v3.1, v4.1

Increase Disk Image Size

qemu-img resize Win2k.img +20G

qemu-img
calls the qemu program to work with images
resize
instructs the program to increase or decrease the size of an existing disk image
Win2k.img
defines the path and file name to store the image
+20G
defines the size of the increase. To decrease, read the documentation because this may corrupt the disk image.

tested with QEMU v2.11, v3.1, v4.1

Create a Derivative Copy-on-Write Disk Image

qemu-img create -f qcow2 -o backing_file=Input_Win2k.img Output_Win2k.qcow2

This command takes an input disk image and creates a "copy-on-write" copy of that image. When running from a derivative copy-on-write image, QEMU will refer back to the original base copy but only write changes to the derivative, leaving the base copy unchanged.

qemu-img
calls the qemu program to work with images
create
instructs the program to produce a new image
-f qcow2
specifies the output disk image format as "qcow2", a format native to the QEMU project (it is the second version of the format; legacy "qcow" files may be encountered and have similar functionality but .qcow2 is recommended)
-o backing_file=Input_Win2k.img
specifies the "base copy" (path, name, and extension) for the output derivative image
Output_Win2k.qcow2
path, name and extension for the new output disk image (QEMU is extension-agnostic; qcow2 files can use .img, .dd, .image, etc.)

Notes

1. Moving, deleting or altering the base copy will corrupt any derivative copy-on-write image based on it!!

Copy-on-write images are wonderful for testing and disposable work. If keeping derivative copy-on-write files, it is highly recommended to set the original base copy image to read-only.

2. Copy-on-write files can be chained off of each other - that is, -o backing_file= can specify a qcow2 file that is itself a derivative of another image.

Use qemu-img info --backing-chain input_image.qcow2 to see details of all disk images in the backing chain.

tested with QEMU v2.11, v3.1, v4.1

Recipes

The following are QEMU "recipes": example commands recommended and explained by QEMU QED contributors for installing the listed operating system. Hard disk drive and installation media disk images (floppies, CD-ROMs) must be created or sourced by the user - these recipes essentially serve as recommendations for assembling certain hardware and settings.

Contributors should also note QEMU version used with their recipe, as this may affect command syntax or available options.

Windows 98

qemu-system-i386 -drive file=Win98.img -cdrom Win98Install.iso -m 512 -soundhw sb16 -vga cirrus -net nic,model=pcnet -boot d

qemu-system-i386
calls the program and specifies the i386 system architecture
-drive file=Win98.img
loads the specified file as a hard drive (ideally, a blank disk image)
-cdrom Win98Install.iso
loads the specified file (a bootable Windows 98 installation CD-ROM) into the CD-ROM drive
-m 512
gives the emulated computer 512 MB of RAM
-soundhw sb16
gives the emulated computer a SoundBlaster 16 sound card
-vga cirrus
gives the emulated computer a Cirrus Logic video card
-net nic,model=pcnet
gives the emulated computer an AMD PCNET ethernet adapter
-boot d
directs the emulated computer to boot from the CD-ROM drive rather than the hard disk drive for installation; remove or switch to -boot c after successful install

tested with QEMU v2.11, v3.1

Windows XP (32-bit)

qemu-system-i386 -drive file=WinXP.img -cdrom WinXPInstall.iso -m 512 -soundhw ac97 -vga cirrus -net nic,model=rtl8139 -enable-kvm -boot d

qemu-system-i386
calls the program and specifies the i386 system architecture
-drive file=WinXP.img
loads the specified file as a hard drive (ideally, a blank disk image)
-cdrom WinXPInstall.iso
loads the specified file (a bootable Windows XP installation CD-ROM) into the CD-ROM drive
-m 512
gives the emulated computer 512 MB of RAM
-soundhw ac97
gives the emulated computer an Intel AC'97 compatible sound card
-vga cirrus
gives the emulated computer a Cirrus Logic video card
-net nic,model=pcnet
gives the emulated computer a RealTek RTL8139 ethernet adapter
-enable-kvm
allows QEMU to use KVM virtualization, emulated machine will run more efficiently (will likely require admin privileges on the host computer)
-boot d
directs the emulated computer to boot from the CD-ROM drive rather than the hard disk drive for installation; remove or switch to -boot c after successful install

tested with QEMU v2.11, v3.1