GUIDE How to Install macOS on UNRAID [Intel/AMD] - PCI Passthrough Guide

[EliteMacx86]

How to Install macOS on UNRAID [Intel/AMD] - PCI Passthrough Guide​

Do I need a UNRAID License?​

UNRAID is available for free (trial) and offers a 30-day free trial. Once the period is over, you'll need to purchase a license to continue using the UNRAID. You may consider purchasing a license if you want to use the UNRAID any further. UNRAID has a different license mechanism. Usually, software licenses are based on the duration of usage, UNRAID license is a bit different. Different license level allows you to connect up to 6 storage devices for a Basic license, up to 12 storage devices for a Plus license, and unlimited storage devices for a Pro license. The pricing plans can be obtained on the UNRAID Official Website.

Requirements​

Following are the requirements for installing macOS on UNRAID. Please ensure you meet the requirements before proceeding with this guide.

CPU	Intel/AMD CPU. 4 Core minimum. 6 Core or more is recommended. Haswell and later is recommended. macOS Compatible CPU. See CPU Compatibility for more information.
Memory	16GB or more
Storage	A quality USB 3.0 Flash Drive larger than 1GB. (Less than 64GB is recommended for the ease). This will be the UNRAID OS USB and will be always plugged in. A dedicated SSD with at least 128GB capacity for the Array. (Two, if going for a mirror). Additional capacity is needed for storage sharing. A separate Drive is required for passthrough under macOS (either for data storage or for installing macOS).
Graphics	macOS compatible GPU for Graphics passthrough. See GPU Compatibility for more information.
Peripherals	A separate Keyboard/Mouse to use in VM. If not having a separate one, the host one can be used.
Operating System	Windows 10 or later is recommended for preparing the files and tools.
Tools	UNRAID Server OS UNRAID Bootable USB Creator Rufus OpenCorePkg

Although generally not recommended, you can use a single GPU for the Graphics passthrough in UNRAID for the macOS Virtual Machine. To use the console, you need a GPU reserved for the host. Consumer grade systems having a Dual GPU (such as IGPU+dGPU) are often a perfect fit if you want to host a single VM at a time. The IGPU can be reserved for the host and the dGPU can be configured as a passthrough for the macOS VM. The other choice is a server/workstation system which includes Onboard VGA (ASPEED).

CHAPTER 1: Create UnRaid Bootable USB​

Default Method:​

UNRAID offers a USB Flash Creator tool using which you can create a Bootable USB with ease.

1. Visit the Unraid Downloads page.
2. Download the latest Unraid Release.
3. Plug your USB Flash Drive.
4. Open UNRAID USB Flash Creator.
5. Select the version as Stable.
6. You can customize the server name if you want to. By default, it is Tower.
7. Specify the Network mode either DHCP or Static IP.
8. Ensure the Allow UEFI Boot checkbox is checked.
9. Select the USB Flash Drive from the drop-down menu.
10. Click on Write to write the image to the USB.
11. Once the process is complete, click on Close.

Manual Method:​

In case the Unraid USB Flash Creator isn't working for you, you can go with the manual route and create the Bootable USB manually using the steps provided below:

1. Visit the Unraid Downloads page.
2. Download the latest Unraid Release.
3. Plug your USB Flash Drive.
4. Open Rufus and erase your USB with the following parameters:
5. Once the USB is erased, close Rufus.
6. Extract all the contents of the Unraid xxx to the root of the USB.
7. Rename the EFI- directory to EFI in order to enable UEFI boot.
8. Right-click on make_bootable script and select Run as Administrator. When prompted, select yes.

CHAPTER 2: Download macOS​

Once you have the UNRAID Bootable USB ready, the next step is to download macOS. If you determine that your hardware is compatible according to the above-provided compatibility lists, you can start your journey by downloading the macOS of your choice for your target UNRAID host.

Requirements​

• Access to a computer with Windows installed (Online Method).
• Internet connection to download the required files.

Using this method, you can download from OS X Lion 10.7 to macOS Sonoma 14.1.1. However, these are the recovery images and therefore require an internet connection to download the full installer, during the time of installation. You'll need to have the exact Recovery image of the target OS you want to install. To download the recovery image, follow the steps below:

1. Install the latest Python from the Microsoft Store.
2. Download OpenCore Pkg.
3. Extract the downloaded file to your Desktop.
4. Move into the OpenCore-0.X.X-RELEASE/Utilities directory.
5. Right-click on the macrecovery folder and select Copy as path.

6. Open Command Prompt with Administrator Privileges.

7. Type cd and then paste the path you copied earlier in step 5 and then press enter key. The command would be the following:

cd "C:\Users\Your User Name\Desktop\OpenCore-0.X.X-RELEASE\Utiities\macrecovery"

NOTE: Replace the X with the OpenCore version. Replace Your User Name with your actual username

8. Depending on the macOS version you need (See Recovery Table below), execute the commands. When prompted, enter your password.

Recovery Table:

OS Version	Command
OS X Lion	./macrecovery.py -b Mac-C3EC7CD22292981F -m 00000000000F0HM00 download
OS X Mountain Lion	./macrecovery.py -b Mac-7DF2A3B5E5D671ED -m 00000000000F65100 download
OS X Mavericks	./macrecovery.py -b Mac-F60DEB81FF30ACF6 -m 00000000000FNN100 download
OS X Yosemite	./macrecovery.py -b Mac-E43C1C25D4880AD6 -m 00000000000GDVW00 download
OS X El Capitan	./macrecovery.py -b Mac-FFE5EF870D7BA81A -m 00000000000GQRX00 download
macOS Sierra	./macrecovery.py -b Mac-77F17D7DA9285301 -m 00000000000J0DX00 download
macOS High Sierra	./macrecovery.py -b Mac-7BA5B2D9E42DDD94 -m 00000000000J80300 download
macOS Mojave	./macrecovery.py -b Mac-7BA5B2DFE22DDD8C -m 00000000000KXPG00 download
macOS Catalina	./macrecovery.py -b Mac-CFF7D910A743CAAF -m 00000000000PHCD00 download
macOS Big Sur	./macrecovery.py -b Mac-E43C1C25D4880AD6 -m 00000000000000000 download
macOS Monterey
macOS Ventura
macOS Sonoma
Latest Version	./macrecovery.py -b Mac-E43C1C25D4880AD6 -m 00000000000000000 -os latest download

The script will start downloading the required recovery files:

9. Once the download is completed, you'll see something like below:

This will create a com.apple.recovery.boot directory inside OpenCore-0.X.X-RELEASE/Utilities/macrecovery directory.

You can find BaseSystem.dmg and BaseSystem.chunklist in OpenCore-0.X.X-RELEASE/Utilities/macrecovery/com.apple.recovery.boot directory.

NOTE: Depending on the macOS version, the script will either download BaseSystem or RecoveryImage files.

CHAPTER 3: Preparing OpenCore EFI

CHAPTER 4: Create macOS Bootable Virtual USB​

Now that we have the EFI and the recovery image ready, we'll need to copy it to our Virtual Disk so that we can boot via OpenCore. To configure the Bootable Disk, follow the steps below:

1. Right-click on This PC and select Manage.
2. Select Disk Management from the left pane.
3. While Disk Management is selected, right-click on Disk Management and choose Create VHD.
4. When prompted, specify the location of the virtual disk. Click on the Browse button and a new dialogue box will appear to specify the location of the Virtual Disk.
5. Select the desired location and also type a File name and click on Save. You can use any, for the time being, we'll use OpenCore EFI/EFI Boot/EFI.
6. Set the Virtual hard disk size as 1000MB or 1GB. We don't need more than that as the recovery image is less than 600MB.
7. Ensure that the Virtual hard disk format is set to VHD and the Virtual hard disk type is set as Fixed size (Recommended).
8. Click on OK.

Disk Management will shortly create a Virtual Disk. You can see the progress at the bottom right of the Disk Management Window.

9. Select the newly added disk in Disk Management (Disk 1) and click on Initialize Disk.
10. Select MBR from the partition style and click on OK.
The VHD will be active and the status will be Online. As we haven't created any partition or formatted it yet, the Disk will appear as Unallocated.
11. Right-click on the Unallocated disk and select New Simple Volume.
12. Continue with the wizard steps until the Format Partition.
13. Select FAT32 under File system and type EFI in the Volume label field and click on Next. The rest of the parameters will remain unchanged i.e. default values.
14. Review the summary and click on Finish.

A new FAT32 partition will be created and available on the host computer. The new Virtual Disk will be automatically opened in the File Explorer.

15. Copy the com.apple.recovery.boot from OpenCore-0.X.X-RELEASE/Utilities/macrecovery directory and the EFI from the working directory to the root of the Virtual EFI Disk.
16. Once copied, go to This PC. Select the EFI Virtual Disk, and click on Eject.

The VHD should be detached from the host computer.

This is a one-time process. Whenever you have to change the contents of the EFI BOOT VHD or any changes in the config.plist or the EFI itself, you can mount and Eject when you're done making the changes. It will detach the connected VHD afterward.

Please note that you must eject all VHD before you can use it in any other Software, even when copying it for importing it to any other Virtualization platform.

Spoiler: Making changes in the EFI BOOT Partition

As EFI BOOT is our Virtual USB, it can be understood that you may need to make some changes in the EFI or the config.plist or change the recovery image, you can do so using the steps below:

1. Right-click on This PC and select Manage.
2. Select Disk Management from the left pane.
3. While Disk Management is selected, right-click on Disk Management and choose Attach VHD.
4. When prompted, specify the location of the EFI BOOT.vhd. Click on the Browse button and a new dialogue box will appear to specify the location of the Virtual Disk.
5. Once the location is specified, click on OK. The EFI BOOT.vhd will be attached and available in Disk Management and will also open in the File Explorer automatically.

Now that the VHD is attached, you can make the changes accordingly.

6. When you're done with making changes in the EFI BOOT, go to This PC. Select the EFI BOOT, and click on Eject. This will unmount the drive and detach it from Disk Management.

CHAPTER X: Setup BIOS​

Before you rush to install Unraid, you'll need to set up the BIOS first. Configuring your Motherboard BIOS and the Storage/Network Controller correctly is an important step to ensure you have a seamless experience using Unraid and also to ensure the installation is hassle-free and you don't have to face issues when setting up passthrough.

STEP 1: Enable Virtualization​

The very first step is to set up BIOS to have the Virtualization enabled on your system. This is because there are a few systems that have the option to Enable/Disable the Virtualization in BIOS which affects the functionality when running a Virtual Machine. To enable Virtualization, follow the steps below.

1. On your target computer, boot to BIOS. Refer to your user manual for the BIOS Key
2. Enable Virtualization. This is usually present as Intel VT-x or Intel Virtualization Technology and AMD-V option in BIOS.
3. Save & Exit Setup.

STEP 2: Verify the Virtualization​

The next step is to verify whether the virtualization is enabled or not. This step is required in order to ensure you're on the right track and you meet the hardware requirements to run a Virtual Machine. To verify the WiFi/BT detection, follow the steps below.

1. Open Task Manager using CTRL+ALT+DEL Key together on your Keyboard
2. Check the Virtualization status under the Performance>CPU section.

If you notice that the Virtualization is Disabled, you need to configure the BIOS/UEFI and enable Virtualization. Enabling the Virtualization Technology feature differs from vendor to vendor and the options differ between Intel and AMD. See STEP #1 for more information.

STEP 3: Enable SR-IOV​

This is an optional step and may not be available in every consumer motherboard. Mainly on enterprise/server grade.

STEP 4: Enable VT-d​

One of the mandatory steps that lets you enable passthrough. Without VT-d, you won't be able to passthrough any PCI Device (not even a single) to the target macOS or any other VM. VT-d is generally available for all Intel CPUs since Haswell. Please note that this particular setting is completely absent on AMD systems.

STEP 5: Enable IOMMU​

Mainly relevant/found on AMD systems.

STEP 6: Configure Storage Controller​

Whether you're using an onboard Storage Controller or an external HBA Card, the Storage Controller should be set to AHCI Mode. In addition, you must flash the HBA Card (whether PCIe or onboard (via the PCH bus)), to IT mode before installing Unraid and setting up VMs. You must ensure that the HBA Card is not running in the IR Mode.

CHAPTER X: Boot UNRAID​

Now that the BIOS has been set up and everything is ready, we can install UNRAID OS on the target system.

1. Plug your Unraid USB Flash Drive into the target system. Please make sure to use the rear I/O panel and use a USB 3.0/3.1 port for a better speed. Avoid using the front panel for stability.
2. Power On the target system.
3. Press F12 key to enter the Boot Menu. The common Boot Menu Keys are Esc (ASUS Laptops), F8 (ASUS Desktops), F9 (HP), F12 (GIGABYTE). Refer to your computer user manual, if necessary.
4. From the Boot Menu, select the USB Flash Drive with the UEFI prefix and press enter to boot.
5. When at the selection menu, select Unraid OS and press enter to boot. The Unraid OS will boot in a while.

CHAPTER X: Configure UNRAID OS​

Now that we have installed Unraid, it's time to configure the Unraid after which we'll proceed with creating a Virtual Machine and install macOS on it. These are the basic mandatory steps which should not be skipped if you want to have a seamless experience.

I. Connect to WebGUI​

1. From any other device connected to the same network your Unraid Host is connected to, navigate to http://tower.local/ in the Web Browser of your choice.

NOTE: If you have configured a different hostname in the USB Flash Creator, use that particular name instead of tower.

II. Setting a root password​

When you connect to the WebGUI, you'll immediately be promoted to set a root password.

1. Create a strong password that has at least 8 characters and a combination of alphabetic, numeric, and special characters.
2. Click on SET PASSWORD to set the password permanently.

You'll see the UNRAID Dashboard now.

Once a root password is set, you'll be automatically logged into the WebGUI.

III. Installing the License Key​

This is a completely optional step if you intend to use it for a longer period (the default trial period is 30 days).

If you already have a License Key, skip to step #4 to begin installing the License Key.

1. From the top right menu, click on Purchase Key.
2. Select the Key as per your requirement and click on BUY NOW.
3. Follow the instructions and complete the checkout.

Once you have obtained the License Key, you can install it to unlock the storage limitations.

4. From the Unraid WebGUI, navigate to Tools from the top menu.
5. From the bottom of the page, paste the License Key URL in the box and click on INSTALL KEY.

IV. Create Array​

Before you can create a Virtual Machine, you'll need to create an Array where the Virtual Machine disk(s) and ISOs will be stored. By default, TrueNAS will display No Pools message if no Pools have been created before.

1. From the Unraid Web UI, select MAIN from the top menu.
2. Select the target disk under Disk 1. If you have more disks, assign them accordingly under Disk 2 and so on.
3. Scroll down to the bottom of the page and click on the START button.
4. If the disk is not in the required format, UNRAID will prompt you to format the drive. Simply click on the FORMAT button to format the drive.

An Array will be added to the Dashboard.

V. Enable Auto Start​

By default, UNRAID will not start the Array automatically at system boot or across subsequent reboots. Therefore, when you start the macOS VM, UNRAID will throw an error. Therefore, you must set the Disks to start automatically.

1. From the Unraid Web UI, select SETTINGS from the top menu.
2. Select Disk Settings from the System Settings section
3. When the Disk Settings page, set Enable auto start to Yes.
4. Click on APPLY.

Please note that if the Host system encounters an unexpected shutdown, you'll have to start the Array manually.

VI. Edit Syslinux Configuration​

1. From the Unraid Web UI, select MAIN from the top menu.
2. From the Boot Devices section, click on Flash and it will take you to a new settings page
3. Scroll down a bit and then locate a green text box labeled as Unraid OS in the Syslinux Configuration section.
4. In the text box, you'll see append initrd=/bzroot. We'll be replacing append initrd=/bzroot with append pcie_acs_override=downstream,multifunction video=efifbff initrd=/bzroot.
5. Scroll down to the bottom of the page and click on the APPLY button.
6. Click on the DONE button.
7. The page will redirect back to the MAIN tab. When the page loads, scroll down to the bottom and click on the REBOOT button.
8. When prompted, select PROCEED. The System will reboot in a while.

VII. Create Share​

As Unraid does not have the option to upload the ISO during the creation of a VM, creating a share becomes necessary so that you can easily store the ISOs and use them across Virtual Machines accordingly.

1. From the Unraid Web UI, select SHARES from the top menu.
2. Click on isos from the User Shares section.
3. Scroll down to the bottom of the page and change the following in the SMB Security Settings:

• Set Export to Yes.
• Set the Security to either Public or Private or Secure.
• Click on APPLY.

Now you can easily upload the required files to the isos directory.

Please note that when you set the Security to Private or Secure, you'll need to connect to the Unraid Host using the credentials (root - username and password you set).

CHAPTER X: Upload Recovery Image​

Once the Share is created, you can connect to the Unraid Host and can upload the Recovery Image along with the OpenCore we prepared in CHAPTER X of this guide.

1. On your PC or Mac, connect to the Unraid Host using the credentials.
2. Copy the Recovery.vhd you created in CHAPTER X of this guide to the isos directory.

CHAPTER X: Create a Virtual Machine​

Now that the Unraid is configured, the next step is to create a Virtual Machine and then start installing macOS. To create a Virtual Machine, follow the steps below:

If there are no VMs created on the system, a No Virtual Machines screen will be displayed.

The idea is to keep the steps simple as close to bare metal.

Main​

The Main settings specify the Virtual Machine Operating System type, boot method, CPU, and Memory.

1. From the Unraid Web UI, select VMS from the top menu.
2. Click on ADD VM. A new VM creation page will appear to add the Virtual Machine.
3. Select Linux as a Guest Operating System using the drop-down menu from the Guest Operating System list from the Linux section.
4. Toggle the Autostart button. If you want to start the macOS VM as soon as the UNRAID boots up, leave this option checked. By default, this option will be already disabled.
5. Enter a name for your Virtual Machine. You can use any. For instance, we'll be using macOS.
6. If you want to describe your Virtual Machine, you can enter a description. We'll be using macOS Sonoma for instance.
7. Set the CPU Mode as Host Passthrough. This will make the installation seamless like a bare metal install or else you will need to add a lot of parameters to the Virtual Machine Configuration which can be a tedious task. Even if you're using a CPU which is not supported natively on macOS, you can spoof the CPU ID easily using OpenCore.
8. Set the Number of Logical CPUs (Threads) to no more than half of the threads available on the host computer. The virtual core allocation should be always under 50% of the actual physical CPU Cores. Allocating more than 50% of the physical core may slow down the host computer (e.g. i5-10400 is a 6 Core CPU that has 12 Threads so allocating 6 Virtual Cores is under the 50% utilization limit).

Unlike other Virtualization platforms, UNRAID is a bit different. Instead of assigning the Cores to the VM, you need to assign the Logical CPUs/Virtual CPUs (Threads). For Hyper-Threading to work in the guest Operating System, the threads must be double the cores. The minimum number of threads should be set the Threads as 2 for the Hyper-Threading to work in the guest Operating System. For CPUs that support Hyper-Threading Technology, the threads are usually twice the cores.

9. Set the Initial Memory as 4096MB . If you have enough memory on the host system, 8192MB would be preferred. The least would be 4096MB. For the best performance, 16GB or more is recommended.
10. Set the Machine as Q35-7.2. It will be already selected by default if you're using UNRAID 6.12.6 or above.
11. Set the BIOS as OVMF and also set Enable USB boot to Yes. By default, OVMF will be already selected. As the hardware is UEFI (Haswell and later), the VM should not be set to SeaBIOS. UEFI is for newer Operating Systems and is highly recommended for macOS Virtual Machine. The other option is OVMF. As this VM is intended for macOS which does not have a TPM requirement, do not use OVMF TPM.
12. Set the USB Controller as 3.0 (qemu XHCI). By default, 2.0 (EHCI) will be selected.
13. Skip OS Install IOS section.

Disks​

The Disk settings specify the Virtual Disk type, location, and size for the target VM. You can either create a new zvol on an existing dataset or use an existing zvol or file for the VM.

Set the Primary vDisk Location to Manual and specify the location to your Recovery.vhd. In our case, the location will be /mnt/user/isos/Recovery.vhd as that's what we created when creating the share and uploaded the Recovery image to.
Set the vDisk Bus as VirtIO.
Although not mandatory, you can also set a serial number for the Virtual Drive if you want to. This step is completely optional and is generally not required for the Recovery and OpenCore.

Click on + button to add the second vDisk. This will be our Virtual Disk on which we'll be installing macOS. Skip this step if you want to use a separate physical disk for the macOS installation.
Set the vDisk size to 80GB for the macOS installation.
Set the Primary vDisk Type as raw.
Set the Primary vDisk Bus as VirtIO.
Although not mandatory, you can also set a serial number for the Virtual Drive if you want to.

Graphics​

Select Virtual as Graphics Card. This will be our display console. Until we set up a Graphics passthrough, this will act as a virtual display where you can carry out the operations in the VM, including installing the guest OS.
Select VNC as Console Protocol from the drop-down list.
Set VM Console Copy/paste to Yes.
Set VM Console AutoPort to Yes.
Select QXL (best) as Video Driver.
Although not recommended, you can set a password for the VM Console, unlike TrueNAS, if you want to. This step is completely optional and depends on your personal choice.

Select English-United States (en-us) as Console Keyboard from the drop-down list.

Sound Card​

As audio isn't required for the installation so leave it to None.

Network​

The Network settings specify the Network Adapter type, MAC Address, and the physical network interface for the VM.

The Mac Address will be automatically generated by default (randomized) so leave it as it is. You can use any other Mac Address if you want to.
Select br0 as Network Source.
Select virtio-net or virtio or vmxnet3 as Network Model.
As we'll not boot from the network, there's no need to assign any Boot Order.

USB Devices​

Leave everything default here as it is.

Uncheck the option Start VM after creation. This is because still a few parameters need to be configured before you can start the macOS Virtual Machine.

Review the Summary and click on the CREATE button. If you notice that the parameters are not set as recommended, you can still edit the options above. Review the Summary and click on CREATE.

A Virtual Machine will be added to the Virtual Machines list.

CHAPTER X: Configure Virtual Machine Parameters​

Now before you can start the Virtual Machine and proceed with the macOS installation, you'll need to configure a few parameters in order to boot the macOS installer.

Ensure the VM we created is not running.

Before you power on your VM, you'll need to configure some of the parameters in the Virtual Machine Configuration File to avoid issues and failures during the installation of macOS on VMware ESXi.

Please note that the following steps are mandatory and should not be skipped at all or it can prevent booting from macOS.

1. From the Unraid Web UI, select VMS from the top menu.
2. Click on the Linux icon and select Edit.
3. From the top right corner, toggle the FORM VIEW button to switch to XML VIEW.
4. Make the following changes in the XML file
In the XML file, find the line <clock offset='utc'> and change it to <clock offset='localtime'>. UTC is the default option. The other is Local Time. Choose accordingly.

Find the line <controller type='usb' index='0' model='qemu-xhci' ports='15'> and change it to <controller type='usb' index='0' model='qemu-xhci' ports='15'>. For some weird reasons, the default value of 15 does not work.

Scroll down at the end of the line and find </devices> and then add the following lines below it:

    <qemu:commandline>
    <qemu:arg value='-global'/>
    <qemu:arg value='ICH9-LPC.acpi-pci-hotplug-with-bridge-support=off'/>
    <qemu:arg value='-device'/>
    <qemu:arg value='isa-applesmc,osk=ourhardworkbythesewordsguardedpleasedontsteal(c)AppleComputerInc'/>
    <qemu:arg value='-cpu'/>
    <qemu:arg value='Cascadelake-Server,vendor=GenuineIntel'/>
  </qemu:commandline>

Make sure the lines are aligned accordingly. This is very important or your changes will not be saved and the XML file may throw an error when saving. Please note that the letters are case-sensitive.


3. Locate vm_update: line and uncomment the # followed by the command_line_args: line. This is very important or your changes will not be saved and the XML file will throw an error when saving. Please note that the letters are case-sensitive.



7. Once you finish making the changes, click on UPDATE button at the bottom of the page and the changes will be saved permanently.

To ensure whether the changes were made, you can check the XML file using the steps 1-x.

CHAPTER X: Installing macOS​

Once everything is set, you're ready to clean install the desired macOS version on your UNRAID host. Please note that the host computer must be connected to the internet in order to install macOS since the BaseSystem is merely a recovery image and a full macOS installer will be downloaded during the installation. The Operating System is approximately 12GB in size. So if you're using any sort of Mobile Data make sure you have enough/sufficient plan if using a Mobile Data plan. Also, please note that as USB passthrough or any other PCI Device passthrough will not be configured during the initial stage of the installation, you definitely need a proper Ethernet (RJ45) Base-T to perform the installation. USB Hotspot or WiFi will not work unless you setup a PCI Device Passthrough first.

Installing macOS on a shared Drive​

1. From the UnRaid Web UI>VMS, select the target Virtual Machine and click on Start with console(VNC) to power on the VM.
2. The installer will load in a while and you'll see the progress with the Apple logo with a progress bar.
3. When at the Recovery screen, select your preferred language and continue
4. Select Disk Utility and click on Continue.
5. When in Disk Utility, click on View, and select Show all Devices.
6. Select AppleInc. vdisk3 Media and use the following parameters to erase the drive:

Name: Macintosh HD
Format: APFS
Scheme: GUID Partition Map

Spoiler: Installing macOS on a Dedicated Drive

ABCD

NOTES:
The target disk/partition must be GUID
APFS format is recommended for High Sierra and Later
Users who plan to use High Sierra on HDD should use macOS Journaled (HFS+) Format instead of APFS Format. Users who are attempting to install macOS Sierra and prior, should use HFS+. Either way, APFS will not be available for macOS High Sierra and newer.

6. Close Disk Utility
7. Select Reinstall macOS Sonoma and continue with the options.
8. Now select Macintosh HD and click on Continue.

NOTES:
Step #6 will format the target disk. Proceed with caution.
This will take a couple of minutes and will restart at "Less than a minute is remaining". Upon completion, the system will automatically restart. Your Mac will restart to complete the installation.

Here it ends the first phase of the installation.

When the installer reboots, the installer screen will appear and continue the second phase of the installation. During this phase, the installer will install files to your target disk and create a Recovery HD partition. Upon completion, your VM will automatically restart.

STEP 3: Finishing macOS Setup​

After several minutes of waiting and keeping yourself patient, you should see the macOS setup screen

After finishing the macOS installation, it's time to set up the macOS for the first usage with the newly installed macOS.

1. When you're at the welcome screen, continue with the basics options such as Keyboard setup, Network, Computer Account, and Privacy settings. Do not sign in to Apple ID when prompted.

Now the installation is complete! You should be logged in to your Desktop with the beautiful Wallpaper

CHAPTER 7: Post-installation​

Although, a bare metal installation might have several things working if you have followed the guide precisely, however, this is not the case with TrueNAS VM. A macOS VM involves a lot more post-install steps such as PCI passthrough by which you can gain the advantage of Graphics acceleration and such. Only a few basic things will work (such as network) and a lot of function and hardware support will lack until you fix them using the post-installation steps covered in this guide, starting with the power management.

Misc.

Add Custom Memory Info

The default memory is reported as 16GB and the speed is reported as 0MHz which is quite strange behavior. However, it can be fixed using OpenCore by adding the memory info manually.

Auto start when power on​

Because the TrueNAS Host does have a Desktop, the macOS VM needs to be started through the Web user interface every time you want to start it. However, you can set the macOS Virtual Machine to start automatically when the UnRaid Host is powered on.

1. From the Unraid Web UI, select VMS from the top menu.
2. Click on the Linux icon and select Edit.
3. From the top right corner, toggle the XML VIEW button to switch to FORM VIEW.
4. Toggle the Autostart button.

Now every time you start the UnRaid Host, the macOS VM will be automatically started. This way, after the Graphics passthrough, the experience will be almost the same as the bare metal

Remove macOS Installation Image​

After installing macOS, you no longer need to use the macOS installation image

1. From the TrueNAS Host, select Virtualization.
2. Select the target Virtual Machine from the Virtual Machines list and click on Devices.
3. Select the DISPLAY Device and click on ... and then select Delete. A new dialogue box will appear to delete the Display Device.
4. When prompted, select the Force Delete checkbox and click on Delete Device.

Remove OpenCore Recovery Image


Install OpenCore to the ESP

I. Power Management​

---

Unlike the bare metal, the power management matters. After all, it helps to achieve the highest available performance when at peak load and consumes less hardware resources when idle to save power.

How important the power management is on bare metal, it has the same importance on TrueNAS on a Virtual Machine. Luckily, with macOS Monterey and above, the Power Management is native and the Sleep/Wake, Restart and Shut Down functions perform normally.


However, if you're on Big Sur or prior, you'll need to inject the SSDT in order to enable the Power Management.

Just keep in mind that if you're on Big Sur or prior, you'll need to inject the SSDT in order to enable the Power Management.

Sleep/Wake​

The sleep/wake function slightly differs on VM as compared to Bare Metal. When you run the guest OS on a Virtual Machine the host system has to be turned on all the time. However, it is quite surprising that TrueNAS actually supports Sleep/Wake and works as expected. When in Sleep mode, you can wake up the macOS using the Mouse and/or Keyboard.

When in sleep mode, the disk will read, write, and store the data. At this time, when using the TrueNAS Host (UI), you can see that the CPU is still working at a very low frequency (13MHz) which indicates the guest OS has a working sleep function. However, the monitor and peripherals are turned off during the sleep mode. It is indeed the same as real sleep on bare metal just the host machine has to be turned on all the time is the only difference.

Restart​

The restart function works normally as of bare metal. You can restart using Apple Logo>Restart or using the Restart button from TrueNAS Host (UI). However, it is always recommended to restart from the macOS to avoid data loss.

Shut Down​

Like the restart function, the Shut Down also works normally as of bare metal. You can either shut down using the Apple Logo>Shut down or via the Power off button from the TrueNAS Host (UI). However, it is always recommended to perform Shut Down within macOS to avoid data loss.

CHAPTER X: PCI Passthrough​

---

As most of the users are interested in the GPU passthrough and due to the highest priority in the passthrough list, let's start with the GPU passthrough. As PCI passthrough is a part of the post-installation step, it is covered as a separate section due to the complexity involved.


You might wonder why USB Passthrough instead of Graphics. That's because, when you enable the GPU passthrough, you'll lose the input to the console and to perform actions (such as NVRAM reset), you'll need to have a working Keyboard/Mouse.

Although the macOS VM can be operated using a keyboard/mouse through the TrueNAS Web Interface, please note that there is actually a delay in the operation that way. For a better experience, we can assign a Keyboard/Mouse passthrough to the macOS Virtual Machine.

TrueNAS supports the addition of several USB devices. Let's understand them below:

I. GPU Passthrough​

PCI passthrough for GPU cards in TrueNAS allows a Virtual Machine (VM) to access a physical GPU card directly, bypassing the hypervisor layer. This enables a virtual machine to fully utilize the capabilities of a GPU, making it suitable for compute-intensive tasks like machine learning, high-performance computing, and computer vision. This section will walk users through setting up PCI passthrough for GPU under macOS VM in TrueNAS.

VMDirectPath I/O - also called PCI Passthrough, allows the GPU device to be accessed directly by the guest operating system on a virtual machine. This method is the simplest way to consume a GPU and only allows the GPU card to be dedicated to one virtual machine, although a single virtual machine can make use of multiple GPUs in passthrough mode.

Unlike VMware and Proxmox VE, you don't need the GPU VBIOS (ROM) for the Graphics Passthrough. It's automatically fetched via the TureNAS itself. One of the advantages of using TrueNAS. This makes the passthrough more seamless than other platforms in the industry.

Before you can set up GPU passthrough, let's talk about the requirements first.

For a GPU passthrough, the main requirement is having a macOS Compatible GPU. Please note that the compatibility still applies, unlike bare metal. If you're using the latest macOS (Monterey and newer), you'll need a 400 or 500 series AMD GPU at least. You can definitely use a legacy GPU but you'll have to patch them using OCLP in order to drive them under macOS. If you want a great experience, you'll have to use an AMD driver-free (native) Graphics Card. A lot of options are available from the 500 series (such as RX 460/470/480 or 560/570/580/590). As always, the GPU choice depends on the workload you have.

Also, if you have an NVIDIA GPU and using macOS High Sierra or prior, you'll need to install the NVIDIA WebDrivers in order to enable the acceleration.

Please note that when you disable the console, you also lose input to the monitor connected to the TrueNAS host.

Isolate GPU​

1. From the TrueNAS UI, select System Settings from the left pane and then choose Advanced.
2. Scroll down and click on Configure on the Isolated GPU Device(s). When the system displays a warning, click on Close. A new dialogue box will appear to isolate the GPU Device ID
3. Select the Intel/AMD/NVIDIA GPU from the GPUs drop-down menu and click on Save. TrueNAS will take some time to isolate the GPU Device ID.

Disable VGA Driver​

If the VGA driver is claimed by the TrueNAS Host, you'll not get the complete display on the monitor connected to the target GPU for display. You'll only have the display when macOS boots up. The OC picker and the verbose will not be displayed on the monitor at all. Moreover, you'll need to use a VNC or a similar remote application to login and operate the Mac. The Display console will be also stuck at verbose. However, the system will have a graphics acceleration. In order to get the proper display on your monitor, you'll have to turn off/remove the built-in virtual display.

If you don't disable/remove the DISPLAY Device, it will act as Dual monitor when macOS boots up.

1. From the TrueNAS Host, select Virtualization.
2. Select the target Virtual Machine from the Virtual Machines list and click on Devices.
3. Select the DISPLAY Device and click on ... and then select Delete. A new dialogue box will appear to delete the Display Device.
4. When prompted, select the Force Delete checkbox and click on Delete Device.

You should see the DISPLAY Device removed from the Devices list.

5. Connect the monitor using DP or HDMI
6. Restart the TrueNAS Host to make the required changes.
7. Power On macOS VM.
8. Reset NVRAM twice to avoid the [PCI configuration begin] error when booting the macOS Virtual Machine.
9. Boot to/into macOS.

Once the VBIOS is loaded successfully from the GPU, the DCUI will disappear and you should see the Apple logo with a progress bar or the verbose on your monitor.

When you turn off the macOS VM, the monitor will have the TrueNAS console displayed on the monitor and when you start the macOS VM, it will automatically switch to macOS VM.

I. AMD​

Native GPU Passthrough

Legacy GPU Passthrough

GPU Spoof
Here we have used WX4100 as an example which is an unsupported GPU under macOS and requires a Fake Device ID (spoof) to work/to achieve the Graphics acceleration

APU Passthrough
APU passthrough is slightly different from IGPU and dGPU passthrough. Unlike bare metal, the requirements are same. All you need is NootedRed.kext to drive the APU. See AMD GPU Graphics for more information.
No with the efforts of Noot, a new kext has been developed

II. Intel​

For Intel, only IGPUs are supported at the moment. No ARC GPUs of course as none of them are supported

IGPU Passthrough​

You can use IGPU passthrough under macOS. However, you'll not be able to use a monitor and can only use Console/VNC to get the display.

III. NVIDIA​

Following GPU passthrough types are supported on macOS VMs using TrueNAS. Depending on the

Native GPU Passthrough​

Native NVIDIA GPUs that do not require a WebDriver, i.e. Kepler based Cards (such as GT710) not only work OOTB (a reason why we recommend using native cards) but have proper Graphics acceleration with full QE/CI. In addition, the display on the monitor can be driven as well. The display is quite crisp as of bare metal and the performance is so high that it doesn't feel you're on VNC/Remote but on a bare metal machine. It's just so fluid and the experience is amazing. The performance is simply unmatched.

Unsupported GPU Passthrough​

Although once supported at the time of High Sierra, the Pascal series GPUs did not have any support further. However, with the introduction of OCLP, it is now possible to use unsupported cards that require WebDriver, i.e. Pascal Cards (such as GTX 1070Ti) works fine after patching the system with OCLP. The GPU works with proper Graphics acceleration with full QE/CI. In addition, the display on the monitor can be driven as well. However, due to the driver limitations itself, only OpenGL is supported at the moment. Unlike the native GPU passthrough, the display is quite crisp as of bare metal and the performance is so high that it doesn't feel like you're using it on a VM but on a bare metal machine. It's just so fluid and the experience is amazing. The performance is simply unmatched.

Legacy GPU Passthrough​

Although it is highly recommended to use a native, macOS compatible GPU for passthrough, there can be cases where you would want to use a legacy GPU for passthrough. For such cases, you can use OCLP to patch the system volume to enable the Legacy GPU passthrough on the latest macOS version.

GPU Spoof​

Unlike bare metal, GPU spoofing is also supported on macOS VMs using TrueNAS. The steps are the same as bare metal. As TrueNAS does not support spoofing Device ID, you'll have to use OpenCore for Device ID spoof. You can either use DeviceProperties or SSDT to spoof the Device ID for your GPU. See GPU Spoof for more information.

​

If you do not see the GPU in the PCI Device list, make sure you have enabled Virtualization and VT-d in BIOS/UEFI.

​

Unsupported GPU Passthrough​

Although the GPU passthrough does not require OpenCore when you have a macOS compatible GPU with native support under macOS, you may need to use OpenCore if you plan to use an unsupported GPU such as APU,

Although you can passthrough the PCI Devices, the compatibility and the limitations still apply to macOS.

​

USB Passthrough
On some of the Ryzen based systems, its a bug that when you select the PCI Devices for passthrough, it starts to jump as soon as you select the PCI Devices. To fix, use the filter search box and type the PCI Device name and then select it respectively. This is typically because of the PCI Devices connected to the same bridge/device node.

II. Storage Passthrough​

Unfortunately, unlike the VMware Workstation, there is no option to choose the Virtual Disk type (such as IDE/SATA or NVMe) in ESXi at the time of creating a Virtual Machine. The Virtual Disk created on the ESXi host is recognized as SATA type under macOS. When using Thick provisioning, delayed zeroed, the speed test for an SK Hynix PC801 (OEM) which has similar specs as the consumer drive (P41 Platinum) offering 3500 MB/s Read and 3000 MB/s Write speeds respectively on a PCIe Gen3 (x4) onboard NVMe Slot. As per the datasheet, the drive offers up to 7000 MB/s Read and 4700 MB/s Write for a 512GB variant on a Gen4 (x4) NVMe slot.

The speed of the Virtual Disk is close to the Gen3 pass-through and a bare metal install:

SATA Passthrough​

Although it's very clear that UNRAID is for storage purposes and the onboard SATA/SAS ports will be used for the disks for pools, you can still passthrough the onboard SATA/SAS ports on the PCH bus. However, this isn't considered a very safe practice and is only recommended for all-flash storage setups, unless you have multiple SATA/SAS ports or HBA Card to connect your pool disks. This is because you might need to add the disks to the onboard SATA/SAS ports on the PCH bus for Storage Pool(s) in UNRAID. Also, please note that once you start the macOS VM, you'll lose all access to the SATA/SAS Devices in UNRAID and all such Devices will be only available under the macOS VM.

Isolate the SATA Device

1. From the UNRAID WebUI, select Tools>System Devices.
2. Select the target SATA Controller from the PCI Devices list. You can also see the IOMMU group just left to the PCI Device.
3. Once the PCI Device is selected, click on BIND SELECTED TO VFIO AT BOOT. A message should appear "ALERT: Changes saved. Reboot to take effect." You'll also see a message asking to reboot at the top.
4. Scroll down to the bottom and click on DONE.
5. Restart the UNRAID Host to make the required changes. You can restart using DASHBOARD. When prompted, click on PROCEED.

Add the SATA Device to the VM

1. When the UNRAID Host reboots, login into the UNRAID Server.
2. From the UNRAID Web UI, select VMS from the top menu.
3. Select the target Virtual Machine from the Virtual Machines list and click on Edit.
4. Scroll down to the bottom of the page. You should see a new PCI Device listed under the Devices list. Select the target SATA Controller from the Other PCI Devices list.
5. If you want, you can assign a Device Order but it is not mandatory.
6. Click on UPDATE.
7. Power On macOS VM.
8. Reset NVRAM twice to avoid the [PCI configuration begin] error when booting the macOS Virtual Machine.
9. Boot to/into macOS.

You should see the SATA Controller under macOS and the connected devices should be available now.

Results:

Please note that when a PCI Device is physically removed from the UNRAID Host, you must also delete that particular PCI Device from the VM or it will throw an error when you try to power on the VM.

NVMe Passthrough​

Although you cannot passthrough the host NVMe as that's what the TrueNAS host is using, you can definitely passthrough a separate drive intended to use under macOS. You can either use this NVMe for the purpose of installing macOS on it or for storing your other data, just like a bare metal install.

Isolate the NVMe Device

1. From the UNRAID WebUI, select Tools>System Devices.
2. Select the target Non-Volatile memory controller from the PCI Devices list. You can also see the IOMMU group just left to the PCI Device.
3. Once the PCI Device is selected, click on BIND SELECTED TO VFIO AT BOOT. A message should appear "ALERT: Changes saved. Reboot to take effect." You'll also see a message asking to reboot at the top.
4. Scroll down to the bottom and click on DONE.
5. Restart the UNRAID Host to make the required changes. You can restart using DASHBOARD. When prompted, click on PROCEED.

Add the NVMe Device to the VM

1. When the UNRAID Host reboots, login into the UNRAID Server.
2. From the UNRAID Web UI, select VMS from the top menu.
3. Select the target Virtual Machine from the Virtual Machines list and click on Edit.
4. Scroll down to the bottom of the page. You should see a new PCI Device listed under the Devices list. Select the target NVMe Controller from the Other PCI Devices list.
5. If you want, you can assign a Device Order but it is not mandatory.
6. Click on UPDATE.
7. Power On macOS VM.
8. Reset NVRAM twice to avoid the [PCI configuration begin] error when booting the macOS Virtual Machine.
9. Boot to/into macOS.

You should see the NVMe under macOS now

NOTE:
Do not share the dataset drive (either on the SATA/SAS/NVMe) on the macOS VM. This will cause intermittent freezes and the Virtual Disk on which macOS is installed, couldn't be found either. This is really dangerous.

Disk Passthrough​

Other than the macOS virtual boot drive, if you need a separate disk to meet your needs, you can add a virtual disk to your macOS VM, without the need of any other physical disk. Sounds interesting? Let's see how

Although the disk media is reported as rotational, it is not. The speed is 1462 and 802 MB/s respectively. Whereas, with the VirtIO, the speed is quite fast, similar to a bare metal

If you want to add any disk passthrough to the macOS VM, you can do that without the need for an extra physical disk. The same dataset disk can be used to create a disk passthrough of the desired capacity.

STEP 1: Create a Zvol

1. From the TrueNAS UI, select Datasets from the left pane.
2. From the Datasets window click on Add Zvol. A new dialogue box will appear to add the Zvol.
When at the Add Zvol dialogue box, use the following parameters to create a Zvol:

Zvol name:
Comments:
Size for this zvol:


3. Enter a name for your Zvol name. You can use any. For instance, we'll be using Virtual Disk
4. If you want to add any comment, to describe the Zvol, you can enter it here. We'll be skipping for now
5. Set the required size for the zvol you wish/want to allocate.
6. Depending on the resources and performance, choose one of the disk provisions as described below. We'll choose Thick Provisioning as that's the default option and is highly recommended. You don't need to configure this option unless you want to use Thin Provisioning which is not recommended.

Thick Provisioning
By default, the disk provisioning is set to Thick provisioned. This will allocate all the disk space once you create the Zvol. Although Thick provisioned can take a much longer time to create the virtual disk as compared to Thin Provisioning, it can enhance the performance of the virtual disk as it zeros out all blocks immediately during provisioning and also requires all of the physical disk space to be available right now. This process can be a lot slower and time-consuming if you're low on the hardware resources. If you do not want to allocate all the space now, select Sparse, and the virtual disk starts small and grows as you add data to it. Choose as you would like. We highly suggest using Thick Provisioned, if you do not plan to use a dedicated separate disk for installing macOS.

Thin Provisioning
Thin Provisioning, also known as Sparse in TrueNAS. In the Thin Provisioning type, the virtual disk size starts small and automatically grows as you add data to it, to the maximum capacity set during the creation of a Zvol. Unless you're low on resources, we don't recommend using this provisioning type as the performance is quite slow.

7. Leave the rest options as it is and click on Save.

You should see a new Zvol listed under the Dataset node.

STEP 2: Add Virtual Disk to macOS VM

1. From the UNRAID Host, select VMS.
2. Select the target Virtual Machine from the Virtual Machines list and click on Edit.
3. Find the line Primary vDisk Location and click on + button. A new dialogue box should appear to add the Disk.
4. Select the vDisk Location from the drop-down menu. Typically the Array you have made to store the files.
Define the size of the vDisk i.e 10M, 1G, 10G or any other size as per your choice.
Select raw as the vDisk Type from the drop-down menu.
Select VirtIO as the vDisk Bus from the drop-down menu.
6. If you want, you can assign a Device Order but is not mandatory.
If you want, you can also assign a Serial to the vDisk, however, it is not mandatory.
7. Click on Save.

You should see a new PCI Device listed under the Devices list.



Once you finish adding the disk, restart the TrueNAS Host to make the required changes. Until you restart the TrueNAS Host, you'll not be able to attach the disk to the macOS VM.
9. Power On macOS VM.
10. Reset NVRAM twice to avoid the [PCI configuration begin] error when booting the macOS Virtual Machine.
11. Boot to/into macOS.

When we enter the system, the macOS will prompt you to initialize the disk. However, to use the disk under macOS, you'll need to initialize the disk by formatting the virtual disk in a required format which macOS supports.

12. When you get the disk initialization prompt, click on Initialize
13. Select the newly added disk in the Disk Utility and use the following parameters to erase the disk. The new virtual disk will appear as
14. Click on Done. A new disk should appear on your Desktop now.
15. Quit Disk Utility


NOTE:

• Ensure that the Force size option is not checked. By default, the TrueNAS restricts creating a zvol that brings the pool to over 80% capacity. This can lead to a decrease in the pool performance and therefore it is not recommended.

Deleting a Virtual Disk​

In case you no longer want to use the Virtual Disk under macOS, you can delete the Zvol to save some disk space for the other VM.

1. Boot to macOS
2. Backup your data as necessary.
3. Shut down macOS.
4. From the TrueNAS UI, select Datasets from the left pane.
5. From the Datasets window select the target Zvol and click on Delete. A new dialogue box will appear to delete the Zvol.
6. When prompted, enter the path for the Zvol. Select the Confirm checkbox and click on Delete Zvol.
7. From the TrueNAS Host, select Virtualization.
8. Select the target Virtual Machine from the Virtual Machines list and click on Devices.
9. Select the DISK and click on ... and then select Delete. A new dialogue box will appear to delete the Disk.
10. When prompted, select Delete zvol device and enter the Disk name. Select the Force Delete checkbox and click on Delete Device.

You should no longer see the target DISK listed under the Devices list.

NOTE:

• Before you delete the Zvol, please ensure you have the necessary backups as it is nearly impossible to recover the data from ZFS once you delete the Zvol.

Results:




Please keep in mind that do not change the NVMe positions, either for the VMware ESXi on which is installed or for the passthrough device. If you do so, the VM will become invalid and the ESXi Server will take a much longer time to boot.

In addition, when doing a storage passthrough, the compatibility for macOS remains the same (i.e. unsupported drives will result in KP)

U.2 Passthrough
The U.2 can be passthroughed like NVMe. If you're using a dedicated HBA/RAID Card, you'll need to install compatible drivers under macOS to enable the support.

III. USB Passthrough​

By default, the USB support is absent and does not work under macOS and it is not shared either. Unless you set up a USB passthrough, you will not be able to use any USB Device in the macOS VM including the Keyboard and Mouse even in the Console.

Unfortunately, unlike TrueNAS, UNRAID does not provide the flexibility of the whole USB Controller passthrough to the macOS VM when the Host system has only one USB Controller (XHCI/EHCI/UHCI) which is already occupied by the UNRAID Host. You'll need at least two USB Controllers for proper use in the VM. However, in case, if the UNRAID Host does not have two separate USB Controllers, you can use individual USB Passthrough. The only downside of this method is you cannot have the entire USB Controller which will support HotPlug like a bare metal. However, you can still passthrough the individual USB Devices as per your needs.

In order to utilize all the functions of a WiFi Card, WiFi alone is not enough. Bluetooth also needs to function. As Bluetooth is on USB protocol, you must passthrough the USB Controller/Devices so that we can add our Bluetooth Device to macOS. Moreover, using the Keyboard and Mouse, you can have full control of your macOS VM just like a bare metal install.

Individual USB Passthrough​

Using the individual USB passthrough method, you can have the USB Devices shared between the TrueNAS Host and the macOS VM (not both at the same time), and a single USB Controller can share different USB Devices as per the need. With the macOS Virtual Machine, you would need a Keyboard, Mouse, and Bluetooth mainly. Moreover, you will not have to map the USB Ports under macOS and that's another advantage.

1. From the UNRAID Web UI, select VMS from the top menu.
2. Select the target Virtual Machine from the Virtual Machines list and click on Edit.
3. Scroll down a little. Select the required USB Device (typically Keyboard, Mouse, and Bluetooth) from the USB Devices list.
4. If you want, you can assign a Device Order but not mandatory. Do not set the USB Devices as optional Devices.
5. Click on UPDATE.
6. Select the target Virtual Machine from the Virtual Machines list and click on Edit.
7. From the top right corner, toggle the FORM VIEW button to switch to XML VIEW.
8. Find the line <controller type='usb' index='0' model='qemu-xhci' ports='15'> and change it to <controller type='usb' index='0' model='qemu-xhci' ports='15'>. For some weird reasons, the default value of 15 does not work.
9. Click on UPDATE.
10. Restart the UNRAID Host to make the required changes.
11. Power On macOS VM.
12. Reset NVRAM twice to avoid the [PCI configuration begin] error when booting the macOS Virtual Machine.

Once you start the macOS VM, the Keyboard, and Mouse will start working within the OC menu. When we enter the system, we also find that our all shared USB Devices can be recognized normally. After the USB passthrough, we can use the Keyboard and Mouse to operate the macOS Virtual Machine.

NOTE:

• To add or remove the USB Devices, you must stop the macOS Virtual Machine before you can do that.

Results:

USB Controller Passthrough​

Although you can passthrough individual USB Devices to the macOS VM, you may wish to passthrough the USB Controller itself so that all the USB Devices on the host system are available to the macOS VM at once. However, please note that once you start the macOS VM, you'll lose all access to the USB Devices in UNRAID and all such Devices will be only available under the macOS VM. If you have multiple VMs, a separate USB Controller is required for the USB Passthrough for each VM. This can be very efficient as each VM can occupy one.

Unlike TrueNAS, UNRAID does not support the passthrough of a USB Controller when its the only one which exists on the Host system. Therefore, you would need at least two USB Controllers on the Host system, either via PCIe slot or onboard. One of the USB Controllers will be pre-occupied by the UNRAID itself and the second USB Controller for the target macOS VM. In case, if the Host does not have two separate USB Controllers, you can use individual USB Passthrough. The only downside of this method is you cannot have the entire USB Controller which will support HotPlug like a bare metal. However, you can still passthrough the individual USB Devices as per your needs.

Isolate the USB Device

1. From the UNRAID WebUI, navigate to Tools>System Devices.
2. Select the target USB controller from the PCI Devices list. You can also see the IOMMU group just left to the PCI Device.
3. Once the PCI Device is selected, scroll down and click on BIND SELECTED TO VFIO AT BOOT. A message should appear "ALERT: Changes saved. Reboot to take effect." You'll also see a message asking to reboot at the top.
4. Scroll down to the bottom and click on DONE.
5. Restart the UNRAID Host to make the required changes. You can restart using DASHBOARD. When prompted, click on PROCEED.

Add the USB Device to the VM

1. When the UNRAID Host reboots, login into the UNRAID Server.
2. From the UNRAID Web UI, select VMS from the top menu.
3. Select the target Virtual Machine from the Virtual Machines list and click on Edit.
4. Scroll down to the bottom of the page. You should see a new PCI Device listed under the Devices list. Select the target USB controller from the Other PCI Devices list.
5. If you want, you can assign a Device Order but it is not mandatory.
6. Click on UPDATE.
7. From the top right corner, toggle the FORM VIEW button to switch to XML VIEW.
8. Find the line <controller type='usb' index='0' model='qemu-xhci' ports='15'> and change it to <controller type='usb' index='0' model='qemu-xhci' ports='15'>. For some weird reasons, the default value of 15 does not work.
9. Click on UPDATE.
10. Power On macOS VM.
11. Reset NVRAM twice to avoid the [PCI configuration begin] error when booting the macOS Virtual Machine.
12. Boot to/into macOS.

You should see the USB Controller under macOS and the connected devices should be available now.


After the USB passthrough, we can use the Keyboard and Mouse to operate the macOS Virtual Machine. When we enter the system, we also find that our all USB Devices can be recognized normally.

Results:

IV. Network (NIC) Passthrough​

The default network under UNRAID (VirtIO) is driver-free under macOS as it is being shared. Depending on the NIC speed, the macOS will also have the same speed as the native NIC speed i.e. 1GbE, 2.5GbE, 5GbE, or 10GbE.

Onboard NIC​

As the Onboard NIC will be occupied by the TrueNAS Server/host, you cannot pass through directly it to macOS. You'll need a separate NIC Card for the passthrough. However, the NIC can be shared and can facilitate the internet function via DHCP configuration. If you have a separate NIC, you can simply install it and enable the NIC passthrough. In case the host has multiple NIC(s), you can enable the passthrough with one of those.

Isolate the Ethernet Device

1. From the UNRAID WebUI, navigate to Tools>System Devices.
2. Select the target Ethernet controller from the PCI Devices list. You can also see the IOMMU group just left to the PCI Device.
3. Once the PCI Device is selected, click on BIND SELECTED TO VFIO AT BOOT. A message should appear "ALERT: Changes saved. Reboot to take effect." You'll also see a message asking to reboot at the top.
4. Scroll down to the bottom and click on DONE.
5. Restart the UNRAID Host to make the required changes. You can restart using DASHBOARD. When prompted, click on PROCEED.

Add the Ethernet Device to the VM

1. When the UNRAID Host reboots, login into the UNRAID Server.
2. From the UNRAID Web UI, select VMS from the top menu.
3. Select the target Virtual Machine from the Virtual Machines list and click on Edit.
4. Scroll down to the bottom of the page. You should see a new PCI Device listed under the Devices list. Select the target Ethernet controller from the Other PCI Devices list.
5. If you want, you can assign a Device Order but it is not mandatory.
6. Click on UPDATE.
7. Power On macOS VM.
8. Reset NVRAM twice to avoid the [PCI configuration begin] error when booting the macOS Virtual Machine.
9. Boot to/into macOS.

You should see the Ethernet Controller under macOS and the connected devices should be available now.



NOTES:

• When doing a NIC passthrough, you'll need to install the required driver (.kext) under macOS if your NIC requires an additional driver for macOS, unless the NIC has native support (driver-free) under macOS (such as Intel I225-V). The driver can be obtained from the vendor's site or if the community has already a driver, you could use that. If it requires Device ID spoofing, you'll have to spoof it using either DeviceProperties or SSDT which can be loaded via OpenCore.

Results:

10GbE/25GbE/40GbE​

As the Onboard NIC will be occupied by the TrueNAS Server/host, you cannot pass through directly it to macOS. You'll need a separate NIC Card for the passthrough. However, the NIC can be shared and can facilitate the internet function via DHCP configuration. Although the network can be shared using the VirtIO (driver name), you may wish to use the high-speed NIC or onboard (such as 10GbE), (if you have one) for fast file transfer sharing, and for that, you'll have to passthrough the specific NIC under macOS.

NOTE:

• Due to the unavailability of VT-d under macOS as it is being used by the host system (TrueNAS), you cannot drive NICs which require VT-d. This includes several cards from Aquantia (AQC107, AQC113), Mellanox (), and Intel (I225-V, XL710), etc. For NICs like AQC107, luckily there is a Kernel Patch which can be injected via OpenCore and the NIC can be driven normally as you would on a bare metal machine.

1. Mount the ESP
2. Open the config.plist using OCAT
3. Add the following patch under the Kernel>Patch section of your config.plist. In addition, you'll need to specify the MinKernel to 23.0.0 to ensure that the kext is only loaded on macOS Monterey and above.

Arch	Identifier*	Comment	Find	Replace	Mask	ReplaceMask	MinKernel	Count	Enabled
Any	com.apple.driver.AppleEthernetAquantiaAqtion	CaseySJ - Fix alloc_dma_buffer (including Sonoma)	4889C741 B8030000 00	4889C741 B8130000 00	F8FFC7FF FFFFFFFF FF	00000000 00100000 00	21.0.0	3	YES
Any	com.apple.driver.AppleEthernetAquantiaAqtion	CaseySJ - Fix IOBufferMemoryDescriptor::withOptions	BA000000 00BF0000 0000	BA000200 00BF1300 0000	FFFF00FF FFFFF0FF FFFF	00000000 00001000 0000	21.0.0	3	YES

4. Save config.plist
5. Restart macOS

See Network driving cards for more info.

The implementation is the same as AMD Systems as it lacks VT-d which is now a must requirement in order to drive several hardware under newer macOS versions (typically Monterey and later).

Results:

V. WiFi Passthrough​

If you're using a WiFi/BT which has native support (driver-free) under macOS, the WiFi should work normally as it would on a bare metal install once you enable the WiFi passthrough. One of the reasons why it is recommended to use hardware that has native support under macOS. Following are the steps to enable WiFi passthrough under macOS:

Isolate the WiFi Device

1. From the UNRAID WebUI, navigate to Tools>System Devices.
2. Select the target Network controller from the PCI Devices list. You can also see the IOMMU group just left to the PCI Device.
3. Once the PCI Device is selected, click on BIND SELECTED TO VFIO AT BOOT. A message should appear "ALERT: Changes saved. Reboot to take effect." You'll also see a message asking to reboot at the top.
4. Scroll down to the bottom and click on DONE.
5. Restart the UNRAID Host to make the required changes. You can restart using DASHBOARD. When prompted, click on PROCEED.

Add the WiFi Device to the VM

1. When the UNRAID Host reboots, login into the UNRAID Server.
2. From the UNRAID Web UI, select VMS from the top menu.
3. Select the target Virtual Machine from the Virtual Machines list and click on Edit.
4. Scroll down to the bottom of the page. You should see a new PCI Device listed under the Devices list. Select the target Network controller from the Other PCI Devices list.
5. If you want, you can assign a Device Order but it is not mandatory.
6. Click on UPDATE.
7. Power On macOS VM.
8. Reset NVRAM twice to avoid the [PCI configuration begin] error when booting the macOS Virtual Machine.
9. Boot to/into macOS.

You should see the Network Controller under macOS and the connected devices should be available now.



12. You should see the WiFi under macOS now


The native functions such as App Store, AirDrop, Handoff, and iServices are available and work as expected.

As the Bluetooth function is handled by a USB bus, see USB Passthrough for more info.

As Bluetooth is based on USB protocol, we already passthrough it above. As a result, the WiFi/BT works as expected

Results:

BCM94360NG

BCM94352Z

NOTES:

• If you're on macOS Sonoma, the Broadcom WiFi is broken due to the removal of necessary kexts and as a result, you'll require OCLP to patch the system volume. This applies to every Broadcom WiFi, with or without the native support under macOS. See Enabling Broadcom WiFi on macOS Sonoma for more information.
• If you're not using a WiFi/BT that has native support (driver-free) under macOS (such as BCM94360NG), the requirements are pretty much the same as the bare metal install. One of the examples is BCM94352Z, which requires AirPortBrcmFixup.kext to drive WiFi under macOS and you'll have to use OpenCore to load the kexts under macOS.
• Intel-based WiFi Cards would require OpenCore+Intel WiFi kext and will function normally as it would on a bare metal install. The passthrough steps are similar to Broadcom.

IV. Thunderbolt Passthrough​

Finally, it's the Thunderbolt time. Yes, don't be surprised so much. The VM also supports Thunderbolt Passthrough including onboard and AIC.

NOTE:
It should be noted that whatever device(s) require the VT-d function, cannot work, at least under macOS due to the unavailability of VT-d. The same applies to the other Operating Systems as well. However, other Operating Systems can work normally.

Results:

macOS Updates​

---

The macOS updates can be installed and processed normally, worry-free, just like a bare metal machine with OpenCore Bootloader using the Software Update mechanism from the System Preferences. As always, you must update the OpenCore and the related kexts before applying any updates to the system. See updating macOS for more information.

Updating UNRAID Host​

The TrueNAS updates can be applied to the Host machine normally, as usual. Make sure the host has access to the internet via DHCP and then you can simply update the TrueNAS using System Settings>Update menu. Once the updates are downloaded and ready, reboot the host to process the updates.

Troubleshooting​

---

A very fast, stable internet connection is required due to the offline installer. Being an online installer, the installer fetches the InstallAssistant.pkg for the desired macOS version. If there are frequent dropouts, the download will fail and the installation will be terminated with the reason

Validation errors: VM X does not exists​

Here, the X could be any VM ID. Make sure you're editing the correct VM. You can get the VM ID using the service vm query command in the CLI. Once you get the correct VM ID

Stuck at [PCI configuration begin] error when booting the macOS Virtual Machine.​

Whenever you make any changes in the Virtual Machine, be it either a Graphics Passthrough, a USB Device, or any other PCI Device Passthrough, make sure to restart the TrueNAS Host to avoid the [PCI configuration begin] error when booting the macOS Virtual Machine.

When you update the VM Settings in the FORM VIEW, the additional changes are lost you made in the XML VIEW

No Display/Stuck at TianoCore screen on the connected monitor​

If you're using GPU passthrough, make sure to remove the Display Device from the target Virtual Machine. See GPU passthrough for more information.

No Virtual Disk in Disk Utility ​

Once you add the disk (Zvol), restart the TrueNAS Host to make the required changes. Until you restart the TrueNAS Host, you'll not be able to attach the disk to the macOS VM.

 

[alalrodiinob]

Unraid in the beginning, truenas in the end. What is going on?

 

[alalrodiinob]

I want to try in on unraid.

 

[EliteMacx86]

The guide will be updated soon.