Configuration - axivo/opencore GitHub Wiki

This document provides additional information and examples for OpenCore end-user configuration file format, used to set up the correct functionalities of the macOS operating system and should not be considered a substitute to documentation.

We recommend using Visual Studio Code with the Python extension.

You can install Visual Studio Code with Homebrew:

~$ brew install --cask visual-studio-code

To clone a specific release, run:

~$ git clone -b <release tag> --depth 1 https://github.com/axivo/opencore.git

The <release tag> can be 1.2.0, for example.

To clone the repository with Python 2 support, run:

~$ git clone -b 1.2.6 --depth 1 https://github.com/axivo/opencore.git

To clone the repository with Python 3 support, run:

~$ git clone https://github.com/axivo/opencore.git
~$ cd opencore

The following OpenCore components are installed by default:

• AppleMCEReporterDisabler (optional, for dual processors)
• OpenCorePkg
  • OcBinaryData, needed for OpenCanopy

OpenCanopy is a graphical OpenCore user interface that runs in External PickerMode and relies on OpenCorePkg OcBootManagementLib, similar to the built-in text interface. See the bugtracker issue details for current development status.

There are no default property values within OpenCore. Only failsafe values, which tries to reduce the harm on your system when the configuration is corrupted.

The goal is to make the OpenCore configuration as user-friendly as possible, while understanding the settings to be applied. Therefore, OpenCoreBuild class contains a list of all OpenCore failsafe settings (updated by repo maintainers), while setup.py configuration file contains a list of custom end-user settings to be updated into config.plist file.

This results in a very compact file, containing only the changes to default OpenCore settings, easy to read and understand by end-user.

For additional information, see the Build Options documentation.

Contains a list of kext dictionaries, which will configure and add the kexts into EFI tree. Example of installing ASPP-Override, Lilu and WhateverGreen kexts:

build.kexts = [
    {
        'project': 'ASPP-Override',
        'properties': {
            'ExecutablePath': '',
            'MinKernel': '21.4.0'
        },
        'repo': 'dortania',
        'version': '1.0.1'
    },
    {
        'project': 'Lilu',
        'repo': 'acidanthera',
        'version': '1.4.9'
    },
    {
        'project': 'WhateverGreen',
        'repo': 'acidanthera',
        'version': '1.4.4'
    }
]

The project, repo and version keys define the Github download link for each specified kext.

The following failsafe properties are used, unless specified into build.kexts dictionary:

properties = {
    'Arch': 'x86_64',
    'BundlePath': '<project>.kext'),
    'Comment': '',
    'Enabled': True,
    'ExecutablePath': 'Contents/MacOS/<project>'),
    'MaxKernel': '',
    'MinKernel': '',
    'PlistPath': 'Contents/Info.plist'
}

Contains a list of patch dictionaries, which will configure and add the patches into EFI tree. Example of installing SurPlus patches:

build.patches = [
    {
        'Base': '_early_random',
        'Comment': 'SurPlus 1',
        'Find': build.unhexlify('00 74 23 48 8B'),
        'Identifier': 'kernel',
        'Limit': 800,
        'MinKernel': '20.4.0',
        'Replace': build.unhexlify('00 EB 23 48 8B')
    },
    {
        'Base': '_register_and_init_prng',
        'Comment': 'SurPlus 2',
        'Find': build.unhexlify('BA 48 01 00 00 31 F6'),
        'Identifier': 'kernel',
        'Limit': 256,
        'MinKernel': '20.4.0',
        'Replace': build.unhexlify('BA 48 01 00 00 EB 05')
    }
]

The following failsafe properties are used, unless specified into build.patches dictionary:

properties = {
    'Arch': 'x86_64',
    'Base': '',
    'Comment': '',
    'Count': 1,
    'Enabled': True,
    'Find': b'',
    'Identifier': '',
    'Limit': 0,
    'Mask': b'',
    'MaxKernel': '',
    'MinKernel': '',
    'Replace': b'',
    'ReplaceMask': b'',
    'Skip': 0
}

Contains a list of dictionaries with new property keys and values applied to default OpenCore settings. For a detailed explanation of each section, property keys and values, please refer to official documentation.

Example of updating the BoardProduct property key with a custom Mac-27AD2F918AE68F61 value, into setup.py file:

settings = {
    'PlatformInfo': {
        'SMBIOS': {
            'BoardProduct': 'Mac-27AD2F918AE68F61'
        }
    }
}

This will add into config.plist the following code:

<key>PlatformInfo</key>
<dict>
    <key>SMBIOS</key>
    <dict>
        <key>BoardProduct</key>
        <string>Mac-27AD2F918AE68F61</string>
    </dict>
</dict>

To create your EFI directory tree and config.plist, run:

~$ /usr/bin/python3 -B setup.py

This will create the following tree, with all required files:

Volumes
└── EFI
    └── EFI
        ├── BOOT
        └── OC
            ├── ACPI
            ├── Bootstrap
            ├── config.plist
            ├── Drivers
            ├── Kexts
            ├── Resources
            │   ├── Audio
            │   ├── Font
            │   ├── Image
            │   └── Label
            └── Tools

To modify the content of your config.plist file, simply insert the property keys and values you wish to update, into setup.py configuration file. For a quick example, see opencore/examples directory.

Once the directory tree is created and config.plist validated, update the EFI directory contents where your OpenCore based operating system resides:

~$ diskutil list /dev/disk0
/dev/disk0 (internal, physical):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:      GUID_partition_scheme                        *500.1 GB   disk0
   1:                        EFI EFI                     209.7 MB   disk0s1
   2:                 Apple_APFS Container disk2         499.9 GB   disk0s2

~$ sudo diskutil mount /dev/disk0s1
Password:
Volume EFI on /dev/disk0s1 mounted

~$ ls -lh /Volumes/EFI/EFI
total 3
drwxrwxrwx  1 floren  staff   512B 19 Nov 17:56 BOOT
drwxrwxrwx  1 floren  staff   1.0K 19 Nov 17:56 OC

~$ rm -rf /Volumes/EFI/EFI
~$ cp -a Volumes/EFI/EFI /Volumes/EFI/

~$ sudo diskutil unmount /dev/disk0s1
Volume EFI on disk0s1 unmounted

From macOS Mojave, reboot into Recovery:

~$ sudo nvram "recovery-boot-mode=unused"
~$ sudo reboot recovery

In Recovery, open a terminal and mount the OpenCore EFI volume:

~# diskutil list /dev/disk0
/dev/disk0 (internal, physical):
   #:                       TYPE NAME                    SIZE       IDENTIFIER
   0:      GUID_partition_scheme                        *500.1 GB   disk0
   1:                        EFI EFI                     209.7 MB   disk0s1
   2:                 Apple_APFS Container disk2         499.9 GB   disk0s2

~# diskutil mount /dev/disk0s1
Volume EFI on /dev/disk0s1 mounted

~# ls -lh /Volumes/EFI/EFI
total 3
drwxrwxrwx  1 floren  staff   512B 19 Nov 17:56 BOOT
drwxrwxrwx  1 floren  staff   1.0K 19 Nov 17:56 OC

Set the boot partition and reboot:

~# bless --mount /Volumes/EFI --setBoot
~# reboot