Skip to content

Configuration

Jump to bottom
Floren Munteanu edited this page Apr 5, 2023 · 69 revisions

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.

Recommended Editor

We recommend using Visual Studio Code with the Python extension.

Visual Studio Code

You can install Visual Studio Code with Homebrew:

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

Repo Clone

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

OpenCore Components

The following OpenCore components are installed by default:

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.

Default Settings

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.

Custom Settings

For additional information, see the Build Options documentation.

Variable build.kexts

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'
}

Variable build.patches

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
}

Variable settings

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>

File setup.py

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

Boot Partition

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

An AXIVO Original Production

Clone this wiki locally