Installing macOS Catalina 10.15 on Proxmox 6

This tutorial for installing macOS Catalina has been adapted for Proxmox 6 from Kholia’s GitHub project for installing into vanilla KVM. There is more documentation there which will help out with enabling extra features and diagnosing problems!

If you run into trouble, also check out the comment section of my previous tutorial on Mojave – these two versions are very similar so the problems and solutions are likely to be the same.

Requirements

I’ll assume you already have Proxmox 6 installed. You also need a real Mac available in order to fetch the OSK key.

Your Proxmox host computer’s CPU must support SSE 4.2, so for Intel your CPU must be at least as new as Nehalem, which was the first CPU generation to bear the “Core” i5/i7 branding. Older CPUs will cause the finder to repeatedly crash after installation completes (with an Illegal Instruction exception in the graphics code).

Apparently modern AMD CPUs also support SSE 4.2 and can be used with this guide without any modification (maybe Bulldozer and certainly Ryzen), but I haven’t tested this myself.

First step: Create an installation ISO

On a Mac machine, download and run fetch-macOS.py in a terminal to download the Catalina recovery image from the Apple software distribution server:

This results in a ~500MB “BaseSystem.dmg” file in the current directory. Convert that dmg into an “iso” like so:

hdiutil convert BaseSystem.dmg -format RdWr -o Catalina-installer.iso
mv Cojave-installer.iso.img Cojave-installer.iso

This is actually a raw disk image, not a true ISO, but Proxmox has better tools for picking and re-using ISO images than disk images. Upload the “ISO” to your Proxmox server’s ISO store (typically /var/lib/vz/template/iso).

It is possible to run this download script on Linux/Proxmox instead. In that case, you can replace the “hdiutil” command with one of these options:

# Install the dmg2img package and...
dmg2img BaseSystem.dmg Catalina-installer.iso

# Or use qemu-img from the qemu-utils package
qemu-img convert BaseSystem.dmg -O raw Catalina-installer.iso

Prepare a Clover image

We’ll be using Clover as a bootloader for Catalina.

Download this Clover disk image (that I built using kholia’s build script from Clover r5070), unpack it, and upload it to Proxmox’s ISO store at /var/lib/vz/template/iso. Although it has a .iso file extension, this is actually a hard disk image.

Fetch the OSK authentication key

macOS checks that it is running on real Mac hardware, and refuses to boot on third-party hardware. You can get around this by reading an authentication key out of your real Mac hardware (the OSK key). Save the first block of C code from this page as smc_read.c. In a command prompt, change into the same directory as that file and run:

xcode-select --install # If you don't already have gcc
gcc -o smc_read smc_read.c -framework IOKit
./smc_read

It’ll print out the 64 character OSK for you. Make a note of it.

Every Mac uses the same OSK, so don’t be surprised that it doesn’t look like a random string!

Create the VM

From the Proxmox web UI, create a new virtual machine as shown below.

In the Options page for the VM, ensure that “use tablet for pointer” is set to “Yes”.

In the Hardware page for the VM, add a second DVD drive at IDE0, set it to use your Catalina-installer.iso.

Don’t try to start the VM just yet. First, SSH into your Proxmox server so we can make some edits to the configuration files.

Edit /etc/pve/qemu-server/YOUR-VM-ID-HERE.conf (with nano or vim). Add this line, being sure to substitute the OSK you extracted earlier into the right place:

args: -device isa-applesmc,osk="THE-OSK-YOU-EXTRACTED-GOES-HERE" -smbios type=2 -cpu Penryn,kvm=on,vendor=GenuineIntel,+kvm_pv_unhalt,+kvm_pv_eoi,+invtsc,vmware-cpuid-freq=on,+pcid,+ssse3,+sse4.2,+popcnt,+avx,+aes,+xsave,+xsaveopt,check -device usb-kbd,bus=ehci.0,port=2

We’re telling macOS that the CPU is Penryn (it doesn’t seem to like booting otherwise), but we’re enabling all the new CPU features found in Nehalem which macOS will require, plus some optional features found in later generations (AVX/AES). A USB keyboard is added here because macOS doesn’t support QEMU’s default PS/2 keyboard.

Find the line that define the two “ISOs” (ide0 and ide2), and remove the “,media=cdrom” part from them. Add “,cache=unsafe” in its place. This will treat these as hard disks rather than DVD drives.

Save your changes, return to the Options tab, and change the boot order to put IDE2 (the Clover image) first. Your final VM configuration file should resemble this:

args: -device isa-applesmc,osk="..." -smbios type=2 -cpu Penryn,kvm=on,vendor=GenuineIntel,+kvm_pv_unhalt,+kvm_pv_eoi,+invtsc,vmware-cpuid-freq=on,+pcid,+ssse3,+sse4.2,+popcnt,+avx,+aes,+xsave,+xsaveopt,check -device usb-kbd,bus=ehci.0,port=2
balloon: 0
bios: ovmf
boot: cdn
bootdisk: ide2
cores: 4
cpu: Penryn
efidisk0: vms:vm-144-disk-1,size=128K
ide0: isos:iso/Catalina-installer.iso,cache=unsafe
ide2: isos:iso/clover-r5070.iso,cache=unsafe
machine: q35
memory: 4096
name: catalina
net0: vmxnet3=xx:xx:xx:xx:xx:xx,bridge=vmbr0,firewall=1
numa: 0
ostype: other
sata0: vms:vm-144-disk-0,cache=unsafe,size=64G
smbios1: uuid=xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx
sockets: 1
vga: vmware

Configure Proxmox

On Proxmox, run “echo 1 > /sys/module/kvm/parameters/ignore_msrs” to avoid a bootloop during macOS boot. To make this change persist across Proxmox reboots, run:

echo "options kvm ignore_msrs=Y" >> /etc/modprobe.d/kvm.conf && update-initramfs -k all -u

You must now installpatched version of Proxmox’s OVMF library in order to be able to boot Catalina.

Install Catalina

Now start up your VM.

Go to the Console tab, quickly hit Escape or F2 at the Proxmox logo to enter the OVMF configuration. If your keyboard doesn’t work, leave the Console tab, stop the VM, start the VM, then re-enter the console tab.

Follow the steps above to set the screen resolution to 1920×1080, press F10 to save your changes, and “reset” to apply the new settings (not “continue”). This step is required to avoid scrambled graphics on boot and a hang (Clover resolution must match OVMF resolution, or else the Apple logo will be off-centre and the progress bar will be smeared across the screen, resulting in a lockup).

Note that in future you’ll find that when initially started, your VM doesn’t properly apply the the 1920×1080 screen resolution until you hit “Restart Computer” in Clover when the Clover menu appears (or “Reset” on the VM). You’ll notice this happening when the “Proxmox” logo fills a large area of the screen on boot due to the low resolution.

It should now boot into Clover.

Press enter to boot the “Boot macOS Install from macOS Base System” entry and the installer should appear. Choose your language.

Our virtual hard drive needs to be erased/formatted before we can install to it, so select the Disk Utility option. Follow the steps below to format the disk:

Now we’re ready to begin installation!

After the first stage of installation, the VM should reboot itself and automatically continue installation by booting from the hard drive, then reboot itself a second time and automatically boot from “filevault prebooter”. Note that an Internet connection is required during installation, as the installer needs to download Catalina.

Answer the initial install questions, and you’ll be logged on! (Note that you’ll probably want to hold off on logging into your iCloud account until you’ve configured your SMBIOS to your liking in Clover Configurator)

It works!

Make the Clover install permanent

We’re currently booting using Clover from the attached Clover ISO. Let’s install that to the hard drive instead. Pop open Terminal and run “diskutil list” to see what drives we have available.

Use “sudo dd if=<source> of=<dest>” to copy the “EFI” partition from the Clover CD and overwrite the EFI partition on the hard disk. The Clover CD is the small disk with the “linux filesystem” on it, and the main hard disk is the one with the large Apple_APFS “Container” partition on it.

In my case these EFI partitions ended up being called disk1s1 and disk2s1 respectively, so I ran “sudo dd if=/dev/disk1s1 of=/dev/disk2s1” (N.B. if you get these names wrong, you will overwrite the wrong disk and you’ll have to start the installation over again!).

Now shut down the VM, and remove both the Clover and the Catalina installer drives from the Hardware tab. On the Options tab, edit the boot order to place SATA0 as the first disk. Boot up. If everything went well, you should see the Clover boot menu, and you can select “Boot macOS from Main” to boot Catalina.

Sleep management

I found that I was unable to wake Catalina from sleep using my mouse or keyboard. You can either disable system sleep in Catalina’s Energy Saver settings to avoid this, or you can manually wake the VM up from sleep from Proxmox by running:

qm monitor YOUR-VM-ID-HERE 
system_wakeup
quit

“Prohibited” sign on boot

On a regular Hackintosh this is typically a sign that the boot drive can’t be read, but that situation is difficult to encounter with this VM setup. Nevertheless, I receive a “prohibited” sign during boot in perhaps 1 out of 20 system boots at random (maybe a timing bug?) If this happens, just hit “reset” for the VM to retry  (no need to stop and start).

If you get it persistently, something is going wrong with the boot. You can boot macOS in “verbose” mode by hitting space on the macOS option in Clover and ticking the verbose option. This’ll give you a log during booting that can narrow down when the problem occurs.

Editing your Clover/EFI settings

You can use the Clover Configurator tool (Global Edition) to edit your Clover “config.plist” configuration file, which is stored in the hard drive’s EFI partition. This tool should mount the EFI partition for you. If you want to mount it without using Clover Configurator, first check the device name of the EFI partition in the terminal:

~$ diskutil list
/dev/disk0 (external):
#: TYPE NAME SIZE IDENTIFIER
0: GUID_partition_scheme 512.1 GB disk0
1: EFI EFI 209.7 MB disk0s1
2: Apple_HFS Main 511.8 GB disk0s2

Then you can mount it like so:

sudo mkdir /Volumes/EFI
sudo mount -t msdos /dev/disk0s1 /Volumes/EFI

Note that if you upgrade Clover in the future, you must untick the “AudioDxe” driver during installation, because this causes Clover to hang.

Video performance

Because there is no guest video acceleration available for macOS, video performance is poor.

In Google Chrome in the guest you will need to toggle off the setting to “use hardware acceleration when available” to improve issues with elements not being drawn or flickering (especially video). Safari may be a better choice.

macOS’s built in “Screen Sharing” feature offers dramatically better framerates and latency than Proxmox’s browser-based VNC console, so if you have a real Mac to act as a viewing console, you can enable that in the VM’s “Sharing” settings and connect to the VM using the Screen Sharing app from your Mac instead:

Apparently Screen Sharing is also compatible with VNC clients like RealVNC, so you should be able to connect to it from Linux or Windows consoles using RealVNC.

The real magic bullet for video performance is to pass through a compatible video card using PCIe passthrough (though note that Catalina does not support most NVidia cards). This offers near-native performance. You can read more about how I’m using PCIe passthrough on my own installation here.

USB passthrough

Since I want to use this as my primary computer, I want to use a USB keyboard and mouse plugged directly into Proxmox, rather than sending my input through the web VNC console.

Proxmox has good documentation for USB passthrough. Basically, run “qm monitor YOUR-VM-ID-HERE”, then “info usbhost” to get a list of the USB devices connected to Proxmox:

qm> info usbhost
Bus 3, Addr 12, Port 6, Speed 480 Mb/s
Class 00: USB device 8564:1000, Mass Storage Device
Bus 3, Addr 11, Port 5.4, Speed 12 Mb/s
Class 00: USB device 04d9:0141, USB Keyboard
Bus 3, Addr 10, Port 5.1.2, Speed 12 Mb/s
Class 00: USB device 046d:c52b, USB Receiver
Bus 3, Addr 9, Port 14.4, Speed 12 Mb/s
Class 00: USB device 046d:c227, G15 GamePanel LCD
Bus 3, Addr 8, Port 14.1, Speed 1.5 Mb/s
Class 00: USB device 046d:c226, G15 Gaming Keyboard

In this case I can add my keyboard and mouse to USB passthrough by quitting qm, then running:

qm set YOUR-VM-ID-HERE -usb1 host=04d9:0141
qm set YOUR-VM-ID-HERE -usb2 host=046d:c52b

This saves the devices to the VM configuration for you. It’s possible to hot-add USB devices, but I just rebooted my VM to have the new settings apply.

You can also pass through USB devices by passing through an entire USB controller using Proxmox’s PCIe passthrough feature.

FileVault 2

Scrambled login prompt with FileVault

FileVault disk encryption is a little janky at the moment. It takes a long time (a couple of minutes) for the password prompt to appear on boot, and then the graphics are scrambled so you have to enter your password blind.

If you really want to use it, be certain to keep a copy of your recovery key and keep your backups up to date!

Upgrading from Mojave

First make a backup or snapshot of your system! Catalina has a new disk layout that separates user data from the system partition, so there’s a higher than normal chance of the installer destroying everything.

Update Clover to r5070 by running the Clover installer. Choose the Customise option. Choose:

  • Install for UEFI booting only
  • UEFI drivers section:
    • Recommended Drivers: Tick all, except untick AudioDxe (it causes Clover to hang)
    • Filesystem drivers: Tick ApfsDriverLoader
    • Memory fix drivers: Tick OsxAptioFix3Drv
    • FileVault 2 drivers: Tick all
    • Additional drivers: Tick PartitionDxe

Update any kexts you have installed (Lilu, WhateverGreen, etc). Now reboot to check that Mojave still boots properly using this updated Clover install.

If you’re using any PCIe passthrough devices (particularly video cards) you’ll probably want to disable those and set “vga: vmware” instead, so you can install using Proxmox’s web console. This avoids installer problems triggered by flaky video card passthrough.

Now you can upgrade to Catalina by adding the Catalina-intaller.iso as a DVD drive, editing the VM config to replace “media=cdrom” with “cache=unsafe” and booting from that. You can probably also just install Catalina from the Mac App Store, but I haven’t tested that approach myself.

After upgrading, you may find that on boot you are dropped into the UEFI shell instead of booting Clover. If so, you can manually find and run Clover (e.g. by running “fs0:” “cd EFI\CLOVER “CLOVERX64.efi”), then use Clover’s “Boot Menu Options” menu to remove the Clover UEFI entries and re-add them.

21 thoughts on “Installing macOS Catalina 10.15 on Proxmox 6”

  1. Hi, a 1000 thanks for this updated tutorial ! I’d like to give it a try. Now, being a total novice in this, I already need to ask advice as to the first step…
    How do I download the python script from the website? There’s no download option and if a copy paste all the lines in a terminal window, nothing happens… Thanks for your indulgence, I really want to make this work.

  2. Hi again thanks. It actually worked when doing save as from your link here provided, not when doing so when being on the GitHub page.
    Does this script download the image on a specific place ? I’m unable to find it in my downloads folder, nor from the external volume from which i launched the script.
    This is what i have in terminal :

    Choose a product to download (1-6): 1
    % Total % Received % Xferd Average Speed Time Time Time Current
    Dload Upload Total Spent Left Speed
    100 463M 100 463M 0 0 639k 0 0:12:22 0:12:22 –:–:– 669k
    It says 100% downloaded but still giving current speed ?

  3. I’ve followed this guide on my proxmox node i run at work for fun, proxmox 6.0-5. I can get the VM to boot up and it appears to boot fine and make it to the hard drive format/selection screen, but there is something wrong with the display. It only occupies the top third of the screen and is striped across the NoVNC console window like there’s a bad VGA cable connected to a monitor. Not sure how to describe it. The first picture in this article is fairly similar to what i see: https://ccm.net/faq/6495-monitor-issue-flickering-or-waves

    I’ve tried changing the display option under Hardware and changed the resolution in the OVMF bios but still no luck. Any ideas what could be going on?

    1. You need to select “restart computer” the first time that Clover appears per cold-boot in order to have the resolution applied.

  4. According to your instructions: “After the first stage of installation, the VM should reboot itself and automatically continue installation by booting from the hard drive, then reboot itself a second time and automatically boot from “filevault prebooter”. ”

    ….I’m trying for the n-th time to install OSX on Proxmox (tried multiple times following the Mojave tutorial)! Each and every time I’m facing the same issue: once the machine reboots after the first stage of the installation completes, it simply boots again into Clover where I am seeing the same option as before (“Boot macOS Install from macOS Base System”).

    No matter what I change, I keep facing the same issue…and obviously changing the boot order breaks things even more.

    Not sure at this point how to proceed! Any help is appreciated, and of course THANK YOU for the very elaborate tutorial.

    1. You can solve this issue by hitting F2 to enter the UEFI setup, and picking one of the other options on the Boot Manager to boot from. I don’t know why this happens for some people and not others (it doesn’t happen for me).

    2. Hmm, I had the same issue. Clover wasn’t recognizing my boot drive after installation. I used the build of Clover here: https://github.com/foxlet/macOS-Simple-KVM and it worked however.

      Have to say I don’t understand why though, the version of Clover here as well as the one in kholia’s repo is not working for me – doesn’t detect my disk after installation. I have used the instructions in kholia’s repo before with success, but ran into this issue for the first time with the new Clover version.

      From what I can see the Clover in the Simple KVM repo is also 5070, so strange. Also I’m using Ubuntu so that might make a difference. Just thought I’d mention this here in case others run into the same problem.

      1. Can you check Disk Utility and see what partition type you ended up with? GPT?

        You can fix this one by editing the boot menu in the UEFI settings, but the reason why this helps out is a mystery.

        1. Yeah, it’s GPT.

          I’ll try that. Also I compared the contents of qcow2 image from the repo with yours and the main difference is that they have an apfs.efi file in there. I tried creating a new Clover image, which still wasn’t able to detect the drives on boot, but after adding apfs.efi it could.

          I think that apfs.efi used to be added in older Clover versions but it’s not in the newer one, there’s just ApfsDriverLoader.efi now. So whoever built that image must have left the old files there. Don’t know why it can’t automatically detect the disk with just ApfsDriverLoader.efi though.

  5. Awesome stuff – can’t wait to try this for Catalina!

    According to this checkin:

    https://github.com/kholia/OSX-KVM/commit/72783d8d4c0d6a6ff1b1f711b0b407f0226effa4

    Mojave+ now support the QEMU VirtIO drivers:

    “`
    ### Using virtio-blk-pci with macOS
    Newer macOS (namely Mojave+) have support for some virtio drivers.
    This can be enabled by applying the following change to `boot-macOS-NG.sh` to
    get some performance gain.
    diff
    – -device ide-hd,bus=sata.4,drive=MacHDD \
    + -device virtio-blk-pci,drive=MacHDD \
    “`

    Is this something you could add to your guide? Have you tried with this?

    Also – is there any risk or danger from using this method on older MacOS versions? (e.g. Mojave, High Sierra, Sierra, Yosemite etc.)? Will Clover 5070 work?

    1. I’ve heard that virtio doesn’t work in the installer so it doesn’t seem worth the trouble. You’d have to toggle it back off again to install system updates.

      Clover 5070 should be backwards compatible (it certainly boots Mojave).

      1. From what I’ve read, the virtio disk driver is meant to have *significant* performance gains.

        I’m fine to turn it on after the installer is run.

        How should I go about doing that? Is it simply a case of changing the hardware configuration in the Proxmox GUI? Or I assume there’s something else I need to do on the config/Apple side?

        1. Edit the VM config file to replace sata1 with virtio0, it’ll be applied on the next launch. You shouldn’t have to do anything in macOS. Run a benchmark in the guest before and after.

  6. Curious – have you (or anybody else) tried using this guide under Redhat oVirt?
    It’s another KVM-based distro – so I guess it’s similar in some ways to Proxmox.
    However, would you need to make a separate OVMF patch for it? And how about things like ignore_msrs?
    Could you take a machine created on Proxmox and transfer it over, or are things too different?

    1. Use the vanilla QEMU source that my tutorial is based on:

      https://github.com/kholia/OSX-KVM

      They use my patched OVMF binary. You can use either my or their Clover builds freely (mine is set to 1920×1080 resolution and theirs enables Verbose boot mode by default, no other differences). You should be able to share your installed VM freely across those platforms.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.