MacOS VM installation using Unraid as host OS
- Lime Technology
- UnRAID
- AcidAnthera, and the OpenCore Bootloader team
- Dortania Team for the OpenCore Install Guide
- @Pavo-IM (Creator of original Repository / Code contributor / README.md maintainer)
- @osx86-ijb (Creator of modern README.md / Code contributor / README.md maintainer)
THIS INFORMATION/RESEARCH HAS BEEN SHARED PURELY FOR EXPERIMENTAL AND RESEARCH PURPOSES. IT IS IN NO WAY MEANT TO PROMOTE THE CIRCUMVENTION OF ANYTHING THAT BELONGS TO AND/OR ANYTHING THAT IS THE CREATION/PRIVATE PROPERTY OF ANY CORPORATE ENTITY. THE INFORMATION THAT IS DOCUMENTED AND TRANSCRIBED HERE IS PURELY FOR EDUCATIONAL PURPOSES, AND PROOF OF CONCEPT. SHOULD YOU (OR ANYONE ELSE) CHOOSE TO UTILIZE THE INFORMATION THAT YOU'VE OBTAINED FROM THIS HACKINABOX GITHUB REPOSITORY AND THAT IS WRITTEN HERE IN ANY WAY, KNOW THAT THIS DISCLAIMER SERVES AS A LEGAL PROTECTION TO US AS THE CODE REPOSITORY CREATORS/MAINTAINERS, AND THAT WE ABSOLVE OURSELVES AS SUCH FROM ANY AND ALL RESPONSIBILITIES OR SITUATIONS THAT MIGHT ARISE FROM YOUR HAVING CHOSEN TO UTILIZE ANYTHING DISCUSSED IN THIS HACKINABOX GITHUB REPOSITORY (LEGAL, OR OTHERWISE). WITH THIS BEING DISCLOSED, THE CREATOR(S) OF THIS HACKINABOX GITHUB REPOSITORY GUIDE EXPRESSLY DISCLAIM ANY AND ALL LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR OTHER DAMAGES, LOSSES, OR INJURIES RESULTING FROM THE USE, MISUSE, OR APPLICATION OF ANYTHING AT ALL DISCUSSED IN THIS HACKINABOX GITHUB REPOSITORY OR RELATED TO SUCH. THE READER AND USER ASSUMES FULL RESPONSIBILITY AND RISK FOR ANY ACTIONS TAKEN OR DECISIONS MADE BASED ON THE USE OF ANYTHING DISCUSSED IN THIS HACKINABOX GITHUB REPOSITORY, AND BY CHOOSING TO DO SO, THE USER AGREES TO INDEMNIFY, DEFEND, AND HOLD HARMLESS THE CREATORS FROM ANY CLAIMS, DEMANDS, OR DAMAGES ARISING OUT OF OR RELATING TO SUCH USE. THE CREATORS OF THIS HACKINABOX GITHUB REPOSITORY PROVIDE NO WARRANTIES OR GUARANTEE REGARDING THE SUITABILITY, RELIABILITY, OR ACCURACY OF THE TOPICS DISCUSSED WITHIN THIS HACKINABOX GITHUB REPOSITORY FOR ANY PARTICIULAR PURPOSE, AND THE USER ACKNOWLEDGES AND AGREES THAT THEY ARE PROCEEDING WITH ATTEMPTING ANYTHING DISCUSSED HERE AT THEIR OWN RISK.
This guide is for the computer user who would like to run macOS 12 Monterey (or newer) as a VM from within Unraid Server OS.
- When running macOS bare metal on an AMD cpu, a user is required to utilize patches made by AMD-OSX. Hackinabox abrogrates the need to use these patches.
- When running macOS on an AMD cpu, a user has to use amdfriend to patch binaries for certain apps to run. Hackinabox mitigates this requirement.
- Full performance/utilization of supported GPU passed through to VM.
- Ethernet works OOB via setting up VirtIO networking device in VM settings, (no need to passthrough physical Ethernet controller).
- No hassle updating.
- macOS 13 Ventura compatibility
- macOS 14 Sonoma compatibility
1) Requirements
2) Installation Procedurals
- 2.1) Getting Started
- 2.2) Making the UnRAID USB
- 2.3) Setting Up Your Unraid Server OS Host
- 2.4) Setting up your macOS VM
3) Making the Recovery based macOS Installer USB
4) Obtaining and placing the EFI on the macOS USB Installer
5) Installation of macOS from within your booted VM
6) Post-Installation Finalization
7) SSDT Setup Examples - Before & After
8) FAQ
- 8.1) This sounds great! Where do I begin?
- 8.2) This is great, but UnRaid says that it costs money on the website?
- 8.3) How do I access this server once I boot it up, and what's the deal with me not being able to boot into GUI mode?
- 8.4) Why won't my UnRaid installation boot after I install it the first time?
- 8.5) Why can't I access some devices attached to my SATA controllers?
- 8.6) Why don't some of my attached USB devices work?
- 8.7) Why am I getting "VM Creation Error - XML error: Attempted double use of PCI address 0000:03:00.0"?
- 8.8) If I don't have an existing macOS installation to use to create an offline installer of macOS, yet am already booted into unRAID, what can I do to achieve such?
- 8.9) If my VM freezes and I cannot restart it properly from within the unRAID backend and am faced with the choices of hard restarting my computer, what can/should I do?
9) Support
- Any computer running UnRAID Server OS. This technically will work for AMD OR Intel, as the OpenCore config settings and XML will work for both (just bear in mind that there will need to be modifications done to the XML file for it to work properly on Intel, and that won't be discussed here in greater detail for the time being, however that might change at a later date)
- A USB Flash Key larger than 1GB, no larger than 32GB (PS: It will need to be left inserted at all times, as this is required by UnRaid Server OS)
- The Unraid USB Flash Creator application to properly create your UnRaid Server USB key that your machine will be booted from every time.
- A dedicated drive for the UnRaid Server OS to use an "Array Device". (SSD is preferrable!)
- 1 SATA controller that you don't mind having allocated to the Host OS, as it will be unusable by the VM.
- 1 USB controller that you don't mind having allocated to the Host OS, as it will be unusable by the VM.
- macOS compatible hardware to be used in macOS via hardware passthrough. (GPU, etcetera)
- A copy of the IORegistryExplorer application for macOS that can be obtained from here:
- A copy of the MacIASL application that can be obtained from here:
- An ability to follow detailed instructions down to a meticulously accurate and minute level.
- An ability to stay extremely calm as you follow a lengthy set of instructions.
- An unbridled/unmatched zest for all things technological.
- 1.1) Double check and make sure that you can adhere to the requirements listed above. If so, then proceed to follow the rest of the instructions.
- 1.2) Download Unraid USB Flash Creator for Mac/Windows
- 1.3) Open/Run the Unraid USB Flash Creator and follow any prompts for entering your password if asked.
- 1.4) Proceed with Section 2 of this guide, and continue the process of creating your Unraid USB.
- 2.1) Under "select version", select "Stable", then Unraid 6.9.2 or whichever the newest version may be for you at your time of reading this guide.
2_-_Making_The_Unraid_USB_-_2.1.mp4
- 2.2) Next, we're going to make sure that we click on the "Allow UEFI Boot" checkbox.
2_-_Making_The_Unraid_USB_-_2.2.mp4
- 2.3) Select USB Drive that you want to create as your Unraid USB, and then click on the "Write" button under Write Image
2_-_Making_The_Unraid_USB_-_2.3.mp4
- 2.4) Wait for USB Creator to finish creating Unraid USB and then restart machine and attempt to boot from newly created Unraid USB
- 3.1) Boot from your Unraid USB
- 3.2) Select the first option to boot Unraid
- 3.3) Enter the username and password which will be "root"
- 3.4) From another device connected to the same network as your booted Unraid Server OS, go to http://tower.local in your Browser of choice
- 3.5) Select the disk to install/store the Unraid Server OS files to from the drop down menu of "Disk 1"
3-_Setting_Up_Your_Unraid_Server_OS_Host_-_3.5.mp4
- 3.6) Go the bottom of the page after selecting your disk in Disk 1 drop down menu, and click on "START" button
3-_Setting_Up_Your_Unraid_Server_OS_Host_-_3.6.mp4
- 3.7) (It will then prompt you around the same time to confirm that you want to Format the drive, make sure to agree to such!)
- 3.8) After it's finished, you're going to click on the clickable text that says "Flash"
3-_Setting_Up_Your_Unraid_Server_OS_Host_-_3.8.mp4
- 3.9) In the page that loads afterwards, scroll down to the green text box that's labeled "Unraid OS"
- 3.10) Inside of the green Unraid OS text entry box field you will see
append initrd=/bzrootWe're going to change that toappend pcie_acs_override=downstream,multifunction video=efifb:off initrd=/bzroot
3-_Setting_Up_Your_Unraid_Server_OS_Host_-_3.10.mp4
- 3.11) Scroll down to the bottom of the page and click the "APPLY" button
- 3.12) Click the button called "MAIN" at the top, and when that page loads, scroll down to the bottom, and click on the REBOOT button
3-_Setting_Up_Your_Unraid_Server_OS_Host_-_3.12.mp4
- 3.13) Once you're booted back up into your Unraid Server OS from your Unraid Server OS USB Key, click on "TOOLS", and then "System Devices"
3-_Setting_Up_Your_Unraid_Server_OS_Host_-_3.13.mp4
- 3.14) Once System Devices is loaded, you'll want to make sure to isolate your Unraid USB on it's own USB controller, away from all of the other peripherals. This should be able to be done in a "plug and play" way without having to reboot. However, if you find that it doesn't end up being possible to "plug and play" refresh the device list, then you can shut down and restart between each switching of the port. The reason this is done is to make the UnRaid USB isolated on it's own USB chipset.
- 3.15) Once that has been accomplished, make sure to select the check boxes for your GPU, GPU audio, any potential supported onboard audio chipset (if needed), as well as your network controller (WiFi), and your NVME controller (or if you have two SATA groups, bind the SSD/HDD you want), and hit the "BIND SELECTED TO VFIO AT BOOT" button at the bottom
- 3.16) **Once that is done, you will want to go back to the "MAIN" tab and go to the bottom of the page and press the "REBOOT" button.
- 3.17) Once you are rebooted into your Unraid Server OS from your Unraid USB again, head to the bottom of the MAIN tab and make sure to press the "START" button to start your array.
- 3.18) After that, we're going to go to "SETTINGS", and then select "Disk Settings"
3-_Setting_Up_Your_Unraid_Server_OS_Host_-_3.18.mp4
- 3.19) Once we're in the Disk Settings page, we're going to change "Enable auto start" to "Yes", then click the "APPLY" button
3-.Setting.Up.Your.Unraid.Server.OS.Host.-.3.19.mov
!! DISCLAIMER: DO TAKE NOTE OF LINE COUNT PLACINGS. YOURS MIGHT NOT BE THE SAME AS IN THE GUIDE DUE TO ANY POTENTIAL DIFFERENCES IN HARDWARE CONFIGURATION. TAKE NOTE OF THIS AND BE ON THE LOOK OUT FOR THE DIFFERENCES !!
- 4.1) Now we're going to head to the "VMS" tab of the backend and click on the "ADD VM" button
4-_Setting_Up_Your_macOS_VM_-_4.1.mov
- 4.2) When the Add VM page loads, we're going to select FreeBSD
4-_Setting_Up_Your_macOS_VM_-_4.2.mov
- 4.3) Once loaded, click "EDIT" button load the edit page and edit VM settings. When that next page loads, go to the "Logical CPUs" section, and select every other CPU thread combination except for CPU 0 / X (where as X is the variable for your specific core / thread count). After that, make sure to set your Max Memory. Do keep in mind that Unraid needs 4GB of RAM, so anything 4GB less than your Maximum installed RAM should be sufficient if you don't need to allocate more elsewhere. Remember to select “Q35-6.1” from the drop down selection list for “Machine” (this isn’t shown in the video below, but is still necessary!)
4-_Setting_Up_Your_macOS_VM_-_4.3.mov
- 4.4) Next, scroll down on the page and select "3.0 qemu XHCI" from the drop down menu for USB Controller. This is really personal preference regarding the selection of USB Controller, and doesn't really matter since macOS doesn't support any of them. Then make sure to select your GPU from the Graphics Card drop down menu. Then select your appropriate Audio Chipset from the drop down menu in the selection named Sound Card.
4-_Setting_Up_Your_macOS_VM_-_4.4.mov
- 4.5) Make sure that Network Bridge is set to "br0" from the dropdown menu, and Network Model is set to "virtio-net" from the appropriate drop down selection as well. Then place check marks next to the two(or more?) devices in the "Other PCI Devices" section that you want to pass through. Uncheck "Start VM after creation", and then click on the "CREATE" button PS: This is only to be done if the user isn't already passing through, or able to pass through their Ethernet Controller
4-_Setting_Up_Your_macOS_VM_-_4.5.mov
- 4.6) Click on FreeBSD icon, and choose "Edit". In the top right corner when the Edit page loads, you'll see a slider with the words "FORM VIEW" next to it. Then, click on that to change it to "XML VIEW".
4-_Setting_Up_Your_macOS_VM_-_4.6.mov
- 4.7) After the XML view has loaded, we're going to go to line 37 and remove it (the entire line, that is) per what we have selected in the image here. This is done because QEMU's topology isn't read by macOS correctly and would require the topology kernel patch from the AMD kernel patches in order for it to work otherwise
4-_Setting_Up_Your_macOS_VM_-_4.7.mov
- 4.8) Next, we're going to go to line 40 and select the text
utc, and change it tolocaltime:
4-_Setting_Up_Your_macOS_VM_-_4.8.mov
- 4.9) Scroll down to what should be line 63 and copy
multifunction =‘on’.
4-_Setting_Up_Your_macOS_VM_-_4.9.mov
- 4.10) Head to lines 130 and 132 as shown in the video and change the last zero in
function='0x0'tofunction='0x1'to match each other since they need to be changed, also. After doing this, we're going to insert a space and paste themultifunction ='on'that we copied in the previous step.
4-_Setting_Up_Your_macOS_VM_-_4.10.mov
- 4.11) Do make sure at this time to go ahead and change the
bus=0x4tobus=0x3on the line for HDMI audio in order to have it match the same bus that the GPU is located on.
4-_Setting_Up_Your_macOS_VM_-_4.11.mov
- 4.12) ATTENTION: Section 4.12 is listed here to explain in further detail that Section 4.11 above is done to make your GPU and GPU audio device be seen in the macOS VM and work correctly. Therefore, in order to achieve such, we changed our GPU audio device's logical address in this XML file to match that of the GPU's. Do note that the
sourcepart of the devices does not change, only the logical address under the source. - 4.13) Head to the bottom of the document and click at the end of
devicesand hit enter/return to make a new line and paste this:
<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>
- 4.14) After pasting in the required text into new line, please hit the "UPDATE" button. Now after hitting update button we can shut down and reboot into our Linux Live Distro of choice and continue with making the macOS Installer, if you haven't done so previously.
- 6.1) So after you've made your macOS Installer USB, please follow the OpenCore Install Guide part of their guide where one creates the OpenCore USB and places the needed files on one's USB installer EFI/ESP partition. After doing so and making sure that has been successfully done, then apply/copy/merge the OpenCore folder downloaded from this repository to your newly created macOS USB Installer's OpenCore EFI/ESP partition, making sure to MERGE and not OVERWRITE, AND to be ever mindful of the structing of both files and folder hierarchies.
- 7.1) Create your USB based macOS installer as you normally would. I suggest using the
createinstallmediamethod on macOS. - 7.2) Apply the EFI that can be obtained from this repo and in the previous step to the ESP partition of the created USB installer.
- 7.3) Start up your macOS VM, and boot from the created installer once inside of the OpenCore bootloader menu/screen.
- 7.4) Install your macOS version, making sure to reboot your UnRaid server if necessary along the way, and then boot into it after everything has finished!
- 8.1) Boot into your newly installed VM instance of macOS, yet again.
- 8.2) Once you've gone through the first time user set up and set everything up the way that you prefer and have reached the desktop UI, make sure to obtain and run "EFI Agent" by HeadKaze from their appropriate GitHub repo, making sure to grant it the permissions that it asks for when it asks.
- 8.3) Mount both the macOS Installer USB EFI/ESP partition that contains the OpenCore EFI files that you've booted from, and mount the Internal EFI/ESP of the installed macOS drive as well.
- 8.4) Copy the "EFI" folder on the root of the macOS Installer USB to the root of the installed macOS drive.
- 8.5) Next, we're going to want to set up our hardware via inputting the correct information and values into the correct locations using both IORegistryExplorer to obtain the appropriate Address locations and naming, and MaciASL to edit the SSDT files and place in our hardware's corresponding information. Remember to test your changes non destructively so you don't bork your EFI, and have a working backup EFI to boot from!
- 8.6) Mount your installed macOS EFI/ESP partiton again using EFI Agent.
- 8.7) Obtain and open IORegistryExplorer if you haven't already. (Preferrably the newest version if one has an Apple Developer account, although any version of at least 2.x should suffice.)
- 8.8) Obtain and open MaciASL if you haven't already.(Preferrably the version from Acidanthera's GitHub repo.)
- 8.9) Load each of the SSDT's in MaciASL, working on them one at a time, replacing the information per your own hardwares addresses and devices names, so as not to convolute the process.
- 8.10) In each loaded SSDT, look for the corresponding Address and Device Name, and copy both sets of information to the corresponding SSDT that you are working on. (See below in Section #9 for SSDT Setup Examples)
- 8.11) After all have been replaced, you should be good to go, so you'll want to go ahead and shut down your VM and restart your UnRaid Server OS again, if need be. (For Example: if one is using a Navi based GPU, there's a Vendor Reset Bug that exists. This can be mitigated by using the Vendor Reset Bug fix plugin that's availble via the appropriate location).
- 8.12) Go back into your UnRaid Server VM's, and start the macOS VM.
- 8.13) Boot from your installed version of macOS without having to use the Installer USB, and profit!
- 9.1a) SSDT-ARPT.aml Before Editing:
- 9.1b) SSDT-ARPT.aml After Editing:
- 9.2a) SSDT-GFX.aml Before Editing:
- 9.2b) SSDT-GFX.aml After Editing:
- 9.3a) SSDT-NVME.aml Before Editing:
- 9.3b) SSDT-NVME.aml After Editing:
- 9.4a) SSDT-PLUG.aml Before Editing:
- 9.4b) SSDT-PLUG.aml After Editing:
- 9.5a) SSDT-XGE.aml Before Editing:
- 9.5b) SSDT-XGE.aml After Editing:
- 9.6a) SSDT-XHC.aml Before Editing:
You can begin by making sure that you can adhere to the requirements outlined in this guide
That is correct, however there is a 30 day free trial, and the cheapest version costs $60 USD. Gotta pay to play the game, right?
3) How do I access this server once I boot it up, and what's the deal with me not being able to boot into GUI mode?
In order to access your UnRaid Server OS page for the UnRaid server via tower.local (default name) or the IP address given by your network, you must connect to such from a browser on another device attached to the same network
Due to requirements from the creators of UnRaid, the USB boot key created to boot UnRaid the first time around must be both booted from every time, and left inserted in the USB port at all times
Per how UnRaid operates, 1 SATA controller must be allocated to the Host OS, thereby making it unsuable by a VM
Per how UnRaid operates, 1 USB controller must be allocated to the Host OS, thereby making it unusable by a VM
7) Why am I getting "VM Creation Error - XML error: Attempted double use of PCI address 0000:03:00.0"?
If you're seeing this error, maybe with a different number in the set of numbers as well, it's because function is set on the incorrect line, and bus might be set incorrectly as well. Double check your double check, and set them to the appropriate correct lines.
8) If I don't have an existing macOS installation to use to create an offline installer of macOS, yet am already booted into unRAID, what can I do to achieve such?
Use Macinabox from SpaceinvaderOne
9) If my VM freezes and I cannot restart it properly from within the unRAID backend and am faced with the choices of hard restarting my computer, what can/should I do?
Forcefully restarting the machine and or hard resetting your machine and not choosing to shut down using the option to do so in the unRAID backend can result in data corruption, and the potential need to remake the unRAID USB drive. At all costs, you should always make sure to use the SHUTDOWN button within the unRAID backend to shutdown your computer, instead of hard restarting. It also would be wise to make sure to have a 1/1 clone or backup of your unRAID installation, just in case the need should arise. However, if you do find yourself needing to hard restart your machine, there is a potential that the VM's tab will not be present when you go to look for it. If that ends up being the case/situation for you, just re-enable it from the appropriate location nested within Settings.
For support, please join the Official UnRaid Discord Server or the UnRaid Forums.