Emaculation.com

Running Qemu-system-ppc with Mac OS/OSX guests in macOS

(Guide updated January 10th, 2021)

Introduction

Qemu-system-ppc can run the PowerPC versions of Mac OS 9.0 to 9.2 and OSX 10.0 to 10.5. Qemu can also run some OSX release previews.

The status of various guests based on the latest builds available from the forum:

Guest Default build Sound-enabled build Argument(s) Remarks
Mac OS 9.0 OK OK -M mac99 Requires rom version 5.2.1 or above, mouse wiggle to boot
Mac OS 9.1 OK OK -M mac99,via=pmu
Mac OS 9.2 OK OK -M mac99,via=pmu
Mac OSX 10.0 OK Crackle, channel issue -M mac99
Mac OSX 10.1 OK Channel issue -M mac99
Mac OSX 10.2 OK OK, but channels reversed -M mac99 -device pci-ohci,id=usb1 -device usb-mouse,bus=usb1.0 -device usb-kbd,bus=usb-bus.0
Mac OSX 10.3 OK OK -M mac99,via=pmu Sound has speed drift
Mac OSX 10.4 OK OK -M mac99,via=pmu
Mac OSX 10.5 OK OK -M mac99,via=pmu

Requirements

  • Qemu program
  • Disk images for the PowerPC versions of Mac OS or OSX you want to install

Assumptions in this guide

This guide assumes you are installing Mac OS 9.2 on a 2gb file that will act as your hard disk for Mac OS.
The CD image you install from is called MacOS9.2.iso and the hard disk is called MacOS9.2.img

Installations of other versions of Mac OS or OSX (roughly) follow the same path.
NOTE: When trying to install Mac OS 9.0.4 you need to make sure to use a version that contains a Mac OS ROM version 5.6 or above.
Also make sure to set the -M parameter to -M mac99.

If you need to boot from a real CD, see the section Booting from a real CD below.

Qemu-system-ppc installation

  • Go to http://www.emaculation.com/forum/viewtopic.php?f=34&t=8848&p=52102#p52102 and download our latest build from the official Qemu source.
  • Create a folder for Qemu-related files inside your Applications folder and unpack the download. Put your Mac OS/OSX disk images in this folder.
  • For users of Catalina and later: read the readme.txt about how to run Qemu on your host!
  • Create an empty disk image with qemu-img. Open a command prompt and navigate to your Qemu folder.
./qemu-img create -f raw -o size=2G MacOS9.2.img 
  • Open your favorite text editor and create a file called qemu.command in your qemu folder.
  • Paste the code below into the file:
#!/bin/bash
cd "$(dirname "$0")"

./qemu-system-ppc \
-L pc-bios \
-M mac99,via=pmu \
-display cocoa \
-m 512 \
-boot d \
-drive file=MacOS9.2.iso,format=raw,media=cdrom \
-drive file=MacOS9.2.img,format=raw,media=disk 
  • Save qemu.command and use a terminal to make it executable:
chmod +x qemu.command

Short explanation of the content of the file:

  • #!/bin/bash tells OSX this is a bash script
  • cd “$(dirname “$0”)” set the path for the executable to current folder

./qemu-system-ppc starts qemu with all the following as parameters:

  • -L pc-bios defines the location of bios files to be used.
  • -M mac99,via=pmu defines the mac model used(*).
  • -m 512 defines the amount of memory (in Mb) for OS9/OSX.
  • -boot d defines to boot from a drive entry marked as a cdrom, -boot c would define to boot from a drive entry marked as disk.
  • -drive file=MacOS9.2.iso,format=raw,media=cdrom defines the name, location, format, and type of image (cdrom) file to be used
  • -drive file=MacOS9.2.img,format=raw,media=disk defines the name, location, format, and type of image (disk) file to be used

(*)The mac model entry accepts 3 options for the via parameter:
mac99,via=pmu (this option supports usb mouse and keyboard)
mac99,via=pmu-adb (this allows some older Mac OS/Mac OS server builds to use a keyboard and mouse through the adb bus)
mac99,via=cuda (this is the default setting, allowing the use of the older, now less supported cuda)
Note: to run Leopard, you have to use -M mac99,via=pmu

  • Double-click qemu.command. This starts Qemu and boots the MacOS9.2.iso installation CD image.

Installation of Mac OS 9.2

To install Mac OS, you first need to partition the hard disk, so after you booted from the CD:

  • Go into the “Utilities” folder and start the “Drive Setup” program.
  • Select the entry “<not initialized>” and click “Initialize” and again in the next window.

After initialization has finished and a disk icon has appeared on the desktop, quit the program.
You can then start the installation of Mac OS. Shut down Mac OS after the installation has finished.
Please note that the initialization step has to be repeated for any NEW disk added to Mac OS.

Booting the installed Mac OS

To boot the installed Mac OS, you need to edit the qemu.command file:

  • Change the -boot d argument to -boot c.
  • Reverse the order in which your disk and cdrom entry are listed in qemu.command.

When booting with -boot c, make sure your hard disk image file is listed first. Save the file. Double-click qemu.command and Mac OS will boot from the hard disk.

Done.

Connecting other CD or disk images

You easily change CDs in Qemu-system-ppc for macOS: first drag the current CD icon to the trash. Then open the menu Machine and click change ide1-cd0 and navigate to the CD image you want to mount. Double click the image and wait for it to be mounted on the Mac OS/OSX desktop.

If you want to install software, make an image of the CD-Rom and attach it to Qemu. Add a disk after the hard disk like below to qemu.command:

"-drive file=Name-of-CD-image.iso,format=raw,media=cdrom" (without the quotes!)

or for a second hard disk:

"-drive file=Name-of-hard-disk-image.img,format=raw,media=disk" (without the quotes!)

And save the file. Start qemu.command. The CD image (if readable by Mac OS) will appear on the desktop for you to use.
A new hard disk needs to be partitioned as described above.

Changing the graphics settings

If you need to change the default screen size or colour depth, you can use the -g parameter like this:

"-g 1024x768x32"  (Without the quotes!)

Subsequent changes to the resolution can be made with default OS tools. (e.g., the Monitors control panel in MacOS or equivalent in OSX).

Sharing USB devices with the Guest

You can pass-through some devices attached to the host to the guest.
On a macOS host, you can find the required USB vendorid and productid by checking the USB devices in the System Profiler.
To allow Qemu to take control of the device the driver (kext) the host loaded for the device has to be unloaded.

Mac OS 9.0 to 10.2

Sharing an USB device with Mac OS 9.0 up to Mac OSX 10.2 is restricted to using USB 1.1 devices.
A way to push a USB 2.0 device into USB 1.1 mode is to attach it to a strictly USB 1.1 hub (as found in older Apple keyboards or regular 1.1 hubs).

For USB storage devices you might need to:

  • Run a terminal and execute: sudo kextunload /System/Library/Extensions/IOUSBMassStorageDriver.kext
  • Add: -device usb-host,vendorid=0x058f,productid=0x6387 to the command line (replace product and vendor id with what you found)

Caution: Other devices might be using other kexts (drivers), so you would need to find out which kext is loaded for the device. Some devices might be using a kext that is also in use for other host devices. If you unload such a kext, the host will loose access to those devices. A reboot will restore functionality.

Mac OS 10.3 and above

For USB storage devices you might need to:

  • Run a terminal and execute: sudo kextunload /System/Library/Extensions/IOUSBMassStorageDriver.kext
  • Add: -device usb-ehci,id=ehci -device usb-host,bus=ehci.0,vendorid=0x058f,productid=0x6387 to the command line (replace product and vendor id with what you found)

Caution: Other devices might be using other kexts (drivers), so you would need to find out which kext is loaded for the device. Some devices might be using a kext that is also in use for other host devices. If you unload such a kext, the host will loose access to those devices. A reboot will restore functionality.

Networking

The latest Qemu for OSX builds emulate a network device that is supported out of the box for Mac OS 9.0 up to OSX 10.5
However, you can also use the realtek 8139 device. This requires installation of the appropriate drivers. You can download them from the Realtek site, or all drivers in one iso from here

There are several ways to get networking going in macOS hosts:

Slirp-based networking

Note: this is activated by default on Qemu-system-ppc, so doesn't need to be mentioned explicitly on the command line:

  • -device sungem,netdev=network01 -netdev user,id=network01
Running two Qemu-system-ppc instances with networking

If you want to run two instances of Mac OS/OSX simultaneously, Qemu needs to be able to tell the network devices apart. You can add a mac address to the networking device:

  • -device sungem,netdev=network01,mac=52:54:00:12:34:56 -netdev user,id=network01 (this is the default mac address)

and make sure you add a different mac address to the second instance:

  • -device sungem,netdev=network01,mac=52:54:00:12:34:66 -netdev user,id=network01

Please note that adding a mac address other than the default to the network device leads to the discovery of a new network card in OSX. You need to configure that card through the network preferences.

VMNET-based: Networking for Big Sur or Monterey hosts (enabling Appletalk networking)

Note: running Qemu with vmnet support requires you to run Qemu-system-ppc as root.

The VMNET option allows three different networking modes. We cover only the “bridging” mode as that allows the most versatile access to host and guest.

-device sungem,netdev=network01 -netdev vmnet-bridged,id=network01,ifname=name-of-the-host-network-device

(You can find the name of the host network device in the system report under networking. This will often be “en0” or “en1”)

Tap-based: Bridging one or more tap devices (enabling Appletalk networking)

Note: Tap-based networking requires the installation of tuntaposx or the tap device from Tunnelblick. This will, however, not work for Mojave or Big Sur hosts.

Add the first line to your qemu command line, run qemu with sudo, and execute the other lines in another terminal window:

  • -device sungem,netdev=network01 -netdev tap,id=network01,script=no,downscript=no
  • sudo ifconfig bridge0 create
  • sudo ifconfig bridge0 addm en0
  • sudo ifconfig bridge0 addm tap0
  • sudo ifconfig bridge0 up

Bridging a tap device: the easy way

Create a network bridge in your macOS host network settings and add your network device to the bridge. We provide two scripts in the tap-scripts folder. They assume your bridge is called bridge0. The first script adds the tap device to the brigde when qemu-system-ppc starts. The second script removes the tap device from the bridge once you stop qemu-system-ppc.

Change the qemu.command file:

  • -device sungem,netdev=network01 -netdev tap,id=network01,script=./tap-scripts/tap-up.txt,downscript=./tap-scripts/tap-down.txt

Save the command file and run it as root.
If you want, you can leave the bridge intact after you quit Qemu-system-ppc, so it is already available next time you run Qemu-system-ppc with tap networking.

Peer to peer networking between two Qemu-system-ppc instances

Qemu can use socket networking to connect two peers. The peers will have no internet access, but can exchange data between each-other. Set one guest to be a listener for network traffic:

  • -device sungem,netdev=net1,mac=52:54:00:12:34:56 -netdev socket,id=net1,listen=:1234

Set the other guest to connect to the listener:

  • -device sungem,netdev=net1,mac=52:54:00:12:34:66 -netdev socket,id=net1,connect=127.0.0.1:1234

For both instances, set the TCP/IP settings manually to a free ip address in your IP range and set the subnetmask to 255.255.255.0. No other settings have to be made.

Getting files in and out of your emulated Mac through a network connection

Note: the option below will not work on Big Sur hosts as afp support was removed, or on Catalina hosts when the shared folder is not a on HFS+ volume.

OSX 10.3/10.4 guests: Make sure you have file sharing enabled on your host and that you share some folder. Find the current IP address of your host: open the system report and click Networking. The IP address should show behind the active network connection.
Start Qemu, click Go/Connect to server. Enter

afp://ip-address-of-your-host. 

At Connect as select Registered user and enter your user name and password for your host. Then select a shared folder from the list and click OK. You can now read and write files to the shared folder that appeared on your desktop.

Note: for other Mac OS 9.x/OSX guests, see the port forwarding solution below.

Forwarding ports to the host (only needed when using the slirp network option)

NOTE: in macOS host, you need to run Qemu as root for port forwarding to work for port numbers below 1024, so it is best to forward a higher port number.

You can provide services running on the guest to the host by forwarding ports to the host.

Running a web server

To provide access to e.g., a webserver running in the guest you can use:

  • -device sungem,netdev=network01 -netdev user,id=network01,hostfwd=tcp::8080-:80

The webserver running on the guest is then accessible through http://name-or-ip-adress-of-host:8080 from other machines running on your network.

Getting files in and out of the guest with FTP
  • -device sungem,netdev=network01 -netdev user,id=network01,hostfwd=tcp::2121-:21

Forwarding port 21 to the host allows running an ftp server (such as Netpresenz, available from the macintosh garden site) on an Mac OS 9.x guest and read/write access to the file system of the guest. Make sure to use an FTP client capable of active transfer mode on the host (such as Filezilla, we are dealing with an old guest system after all.) For access to a Mac OS X guest, enable the ftp service.
You can access the guest by connecting to ftp://name-or-ip-adress-of-host:2121 from other machines running on your network.

Multiple port forwarding

You can forward multiple ports:

  • -device sungem,netdev=network01 -netdev user,id=network01,hostfwd=tcp::2121-:21,hostfwd=tcp::8080-:80

You can also forward ports for Appletalk over tcp/ip. Note you would have to run Qemu as root for this, which is not advisable.

  • -device sungem,netdev=network01 -netdev user,id=network01,hostfwd=tcp::548-:548,hostfwd=tcp::387-:387

Booting from a real CD

To boot from a real CD, you first need to insert the CD and unmount it using e.g., Diskutility.
Next, run Qemu as root. So add sudo in front of ./qemu-system-ppc and set -cdrom /dev/cdrom in your command file.
Example command line:

#!/bin/bash
cd "$(dirname "$0")"
sudo ./qemu-system-ppc \
-L pc-bios \
-M mac99 \
-m 512 \
-boot d \
-cdrom /dev/cdrom 

If the CD was not unmounted correctly, Qemu tells you the commands you need to enter (in e.g., another terminal window) to unmount the CD. For example:

qemu-system-ppc: -cdrom /dev/cdrom: If device /dev/disk5 is mounted on the desktop, unmount it first before using it in QEMU
qemu-system-ppc: -cdrom /dev/cdrom: Command to unmount device: diskutil unmountDisk /dev/disk5
qemu-system-ppc: -cdrom /dev/cdrom: Command to mount device: diskutil mountDisk /dev/disk5

The CD might stay unmounted after you stop Qemu. You can use diskutility to mount it again and eject it. Or use the terminal command Qemu suggests for mounting the CD.

Creating new disk image in OSX with DiskUtility

You can make new disk images which Qemu will use as hard drive, on which you can install Mac OS/OSX.
Open Disk Utility, create a new image like this:

  • Click New image
  • At save as, first select your qemu folder, and then name the image as e.g., “OSX-Jaguar.img”
  • Size: Custom. Choose 6 Gb
  • Set the format : Mac OS Extended (journaled)
  • Set encrypting : none
  • Set Partitions : Hard disk
  • Image format : read/write disk image
  • Click “Create”

This creates an image called “OSX-Jaguar.img”

Changing the mounted cdrom/floppy image

In Mac OS guest: First drag any mounted CD from the desktop into the trash.

Through the Machine menu:

  • Select Machine/Change ide1-cd0
  • Navigate to the CD image you want to mount
  • Select the CD image and click Open.

Note: you can also mount floppy images this way.

Through the Qemu monitor:

  • Select View/Compat monitor from the Qemu menu
  • Type “info block” to find the name of the CD drive in Qemu (most likely: ide1-cd0)
  • Type “eject ide1-cd0”
  • Type “change ide1-cd0 /path/to/name-of-cd-image.iso” (note the forward slashes!)
  • Close the Qemu Monitor by selecting View/VGA

Also see the qemu documentation here: https://www.linux-kvm.org/page/Change_cdrom

Mounting a real cd

NOTE 1: you need to unmount the real cd from the desktop (using e.g., disk utility) before using it in Qemu.
NOTE 2: you have to run Qemu as root to access a real CD. (See above at booting from a real CD.)

  • Run Qemu as root
  • Open the Qemu Monitor by selecting View/Compat monitor from the Qemu menu
  • Type “info block” to find the name of the CD drive in Qemu (most likely: ide1-cd0)
  • Type “change ide1-cd0 /dev/cdrom” (note the forward slashes!)
  • Close the Qemu Monitor by selecting View/VGA from the Qemu menu

Experimental builds and features

Qemu is being actively developed. This means that some new features can become available that are not yet incorporated into the official source code. Currently there are several such developments, in various states of reliability:

-Sound support.

You can download some of these experimental builds for our forum under Experimental builds : http://www.emaculation.com/forum/viewtopic.php?f=34&t=9028

-File sharing with the host
-Mouse tablet driver

You can download drivers enabling these features here: https://www.emaculation.com/forum/viewtopic.php?t=11973

Various utilities

Script to prepare a hard disk image for use with OSX Server 1.2v3 or Developer preview 2.

  • Remove the # in front of the desired disksize:

#!/bin/sh

TARGET_IMAGE=Mac_OS_X_Server_1.0-4G.img

#1G
DISKSIZE_IN_BLOCKS=2097152

#2G
#DISKSIZE_IN_BLOCKS=4194304

#4G
#DISKSIZE_IN_BLOCKS=8388608

PRIMARY_PARTITIONSIZE_IN_BLOCKS=`expr $DISKSIZE_IN_BLOCKS - 512 - 16384 - 64`

echo $PRIMARY_PARTITIONSIZE_IN_BLOCKS

pdisk $TARGET_IMAGE -initialize
pdisk $TARGET_IMAGE -createPartition MOSX_OF3_Booter Apple_HFS 64 16384
pdisk $TARGET_IMAGE -createPartition SecondaryLoader Apple_Loader 16448 512
pdisk $TARGET_IMAGE -createPartition “0x000001FF 0x0008 0x00” Apple_Rhapsody_Inst 16960 $PRIMARY_PARTITIONSIZE_IN_BLOCKS


Currently known issues

  • Tap networking does not work in Mojave/Big Sur
  • Restart doesn't work in Mac OS. Use Shut Down and restart Qemu.
  • Qemu will not boot Mac OS when memory is set to 64Mb or less.
  • Sound only works reasonably well in Mac OS 9 / Mac OSX 10.0 guests.
  • Sound will not work in Mac OS guests with memory set to 1024Mb or more, due to virtual memory being turned off automatically.

Useful additional command line arguments

  • -k en-us sets the keyboard language (see below for possible languages)

The language codes available are:
ar de-ch es fo fr-ca hu ja mk no pt-br sv
da en-gb et fr fr-ch is lt nl pl ru th
de en-us fi fr-be hr it lv nl-be pt sl tr

  • -rtc base=localtime sets the guest time to the local machine time
  • -full-screen sets the guest to run full screen
  • -prom-env “auto-boot?=false” stops boot at the openbios prompt
  • -prom-env “boot-args=-v” shows verbose boot messages with OSX guests
  • -prom-env “vga-ndrv?=false” disables loading the default VGA driver
ppc-osx-on-qemu-for-osx.txt · Last modified: 2024/02/05 12:55