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.
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
$ qemu-system-x86_64
$ qemu-system-ppc
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