Managing Legacy Kernel Extensions in macOS Using Jamf Pro

Updated: 08 April 2022

Product: Jamf Pro

With macOS 11, additional steps are needed to load and use legacy kernel extensions. This requires user approval in Security & Privacy preferences and computers must be restarted to load the kernel extension into a kernel cache. You can use the technologies in Jamf Pro to complete this additional process using MDM.

Note:

On Mac computers with Apple silicon, Rosetta 2 does not translate kernel extensions built for Intel processors. Ensure your app or software supports Apple silicon.

For more information, see the following articles from Apple's support website:

You can use both a configuration profile in the Jamf Pro interface or Jamf Pro API to execute the RestartDevice MDM command to load the legacy kernel extension cache. This process looks similar to the following:

1. Create a computer configuration profile with an Approved Kernel Extensions payload.

The profile allows you to pre-approve the required kernel extensions for the software you are installing on target computers. When the profile is installed on the computers, the kernel extensions specified in the profile are can be loaded on target computers.

2. Restart the computer using one of the following methods:

You can use the MDM Restart with Kernel Cache Rebuild option in Jamf Pro to restart the computer after installing the software.

Note:

Restarting the computer using the MDM Restart with Kernel Cache Rebuild option in Jamf Pro is the recommended restart method.

You can use the Jamf Pro API to execute the RestartDevice MDM command to restart the computer after installing the software. Jamf Pro can include the following keys with the RestartDevice MDM command:

RebuildKernelCache—This key is required to rebuild the kernel cache to include the specified kernel extension in the configuration profile.
KextPaths—This key is optional and allows you to define the specific file path of the kernel extensions file that need to be loaded on target computers. Kernel extensions that have attempted to load previously may automatically be added by macOS to the rebuilding of the kernel cache.
NotifyUser—This key is optional and prompts macOS to display a persistent Notification Center banner for a user to restart the computer. If the user does not restart the computer, the kernel cache will not be rebuilt and any required kernel extensions will not be approved until the computer is restarted. This key applies to computers with macOS 11.3 or later only.
Important:
If this key is not specified, the computer immediately restarts when the command is received and could result in data loss.
When the RestartDevice MDM command is sent to the computer, the computer restarts and the kernel cache is rebuilt to include the specified kernel extensions

General Requirements

To manage required legacy kernel extensions on computers with macOS 11 or later, computers must be enrolled with Jamf Pro 10.28.0 or later.

For computers with macOS 11 or later with Apple silicon, the following additional security features are required:

Bootstrap token for target computers escrowed with Jamf Pro
The computer requests this information from Jamf Pro before the configuration profile can be installed or the RestartDevice MDM command can be executed on the computer.
The Allow remote management of kernel extensions and automatic software updates option enabled in the Startup Security Utility (in macOS Recovery).
For more information about how to enable this setting, see Change startup disk security settings on a Mac with Apple silicon from Apple's support website.
Note:
Enrolling computers with Jamf Pro via a PreStage enrollment can automatically enable this setting. No further action is needed.

Approving Kernel Extensions Using a Configuration Profile

Log in to Jamf Pro.
Click Computers at the top of the page.
Click Configuration Profiles.
Click New.
Use the General payload to configure basic settings for the profile, including the level at which to apply the profile and the distribution method.
Select the Approved Kernel Extensions payload, click Configure, and do the following:
1. (Optional) Choose whether or not users are allowed to approve legacy kernel extensions using the following options:
  - To allow users to approve without specific approval from Jamf Pro, enable the Allow users to approve kernel extensions option.
  - If standard users should be allowed to approve kernel extensions, also enable the Allow standard users to approve legacy kernel extensions (macOS 11 or later) option.
2. Enter a Display Name and Team ID for the developer in the Approved Team IDs and Kernel Extensions settings. These values allow the kernel extensions to load on the computer.
3. (Optional) To approve specific kernel extensions from the specified developer, click Add in the Approved Kernel Extensions settings, and then enter a Display Name and Kernel Extension Bundle ID.
4. Click the Scope tab and configure the scope of the profile.
5. Click Save.

Restarting Computers using MDM Restart with Kernel Cache Rebuild

You can restart computers by using the MDM Restart with Kernel Cache Rebuild option in Jamf Pro.

In Jamf Pro, click Computers at the top of the sidebar.
Click Policies in the sidebar.
Click New .
Click the Restart Options payload under the Options tab.
From the Restart Options pane, click Configure.
Select MDM Restart with Kernel Cache Rebuild under Reboot Method.
(Optional) Define the file path of the kernel extension you want to enable after restart.
Best Practice:
Jamf recommends defining the path to your kernel extension to ensure macOS loads all desired extensions after the computer restart.
1. Click Add .
2. Enter the kernel extension path into the KEXT PATH field.
3. Click Save.
Select the No User Logged In Action and User Logged In Action that best fits your environment.
Best Practice:
Jamf recommends configuring theUser Interaction settings of your policy when performing an automated restart. Options such as Deferral Type and messages can be configured to meet the needs of your environment and users.

Restarting Computers using the Jamf Pro API

You can send the RestartDevice MDM command to computers using the Jamf Pro API and Terminal on a computer that can contact the Jamf Pro server.

Important:

Endpoints that include the term "preview" are subject to future changes.

The process involves the following steps using the Jamf Pro API:

Obtaining the management ID of target computers
Sending the RestartDevice MDM command to target computers.

Note:

These steps should be completed after the software that requires kernel extension permission has been installed on the target computer.

Obtaining the Management ID

You can access the management ID of target computers only in the Jamf Pro API by executing a command in Terminal similar to the following:

curl --location --request GET 'https://YOUR_JAMF_PRO_URL/api/preview/computers' --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

The response contains information about the computer, including the management ID.

The default response contains information for 100 computers. If you have more than 100 computers in your environment, you can add the following to the endpoint URL to expand the response:


`?page=#`	Retrieves a specified page in the response
`?page-size=###`	Increases the number of computers contained in each page of the response. The maximum number is 2000.

To expand the response, execute a command in Terminal similar to the following example:

curl --location --request GET 'https://YOUR_JAMF_PRO_URL/api/preview/computers?page=2&page-size=2000' --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

This response will return the second page of computers. Each page lists 2,000 computers.

Sending the RestartDevice MDM command

You can enter the management ID of the target computer into a command to restart the computer via MDM.

The following code sample demonstrates how to restart a computer:

curl --location --request POST 'https://JAMF_PRO_URL/api/preview/mdm/commands' \
--header 'Authorization: Bearer JAMF_PRO_AUTH_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientData": [
        {
            "managementId": "A9C3D1F0-DCB2-4D52-84C6-D5AD60140B04",
            "clientType": "COMPUTER"
        }
    ],
    "commandData": {
        "commandType": "RESTART_DEVICE",
        "rebuildKernelCache": "true",
        "kextPaths": [
            "kext1",
            "kext2",
            "kext3"
        ],
        "notifyUser": "true"
    }
}'

Computers are immediately restarted via MDM and the kernel cache is rebuilt to include the specified kernel extensions. If the NotifyUser key is set to true, the following scenarios dictate how the notification is displayed to users and when the computer restarts:

If no user is logged in to the computer, the computer immediately restarts without displaying a notification
If a user is currently logged in to the computer, a persistent Notification Center banner is displayed requesting them to restart the computer.
If Fast User Switching is enabled on the computer and the login screen is displayed, a notification is displayed to the next user that logs in requesting them to restart the computer regardless of any currently logged in user status.
If the computer does not have macOS 11.3 or later, the computer immediately restarts without displaying a notification.

Note:

If the user does not restart the computer, the RestartDevice MDM command is still acknowledged as successful in the computer's management history information in Jamf Pro.