Configuring Nudge for macOS delta upgrades

A great new feature introduced with macOS 13 Ventura is the ability for users to perform a delta upgrade. As opposed to the traditional “Install macOS Ventura.app”, which is still available, the delta upgrade takes place entirely in System Preferences’ Software Update pane and is less than half the size.

This new delta method also means that for the first time standard (non-admin) users can perform a major macOS upgrade if they are running 12.3 or higher.

Nudge is an open source application from Erik Gomez that allows MacAdmins to encourage their users to install macOS updates. Because it is no longer possible to install macOS updates without user input, a tool like Nudge is needed. Old methods to script and automate softwareupdate no longer work.

However, Nudge was written before the introduction of these new delta upgrades, and traditional configurations need adjustment to account for them. Thankfully members of the MacAdmins community worked out the needed changes. Read on for the details.

Definitions

First let me define two terms to make sure we are all on the same page.

• Updates are minor patches within the same major version. e.g. Updating from macOS 12.5 to 12.6
• Upgrades are major patches between named yearly releases. e.g. Upgrading from macOS 12 Monterey to macOS 13 Ventura.

Nudge behavior

Nudge is aware of these distinctions and evaluates whether it is an update or upgrade that is needed when macOS is below the required version. Then Nudge will either open Software Update for minor updates or launch the “Install macOS Ventura.app” for major upgrades.

However, this evaluation doesn’t cover all scenarios now that major upgrades can be delivered in delta form inside Software Update just like minor updates. An Issue has been opened and this will eventually be solved. But for now MacAdmins need to adjust their configuration to compensate.

There are at least two workarounds for this issue.

Option 1

EDIT (Sept. 4, 2023): Information about setting the majorUpgradePath key was added to this option. We recently noticed that without this key, users on older major macOS versions were not getting Nudged. I’m not sure how this was missed in original testing and I apologize for omitting it previously.

Tribruin in the #nudge channel on the MacAdmins Slack tested and shared an option that requires setting three preferences keys.

In the optionalFeatures dictionary, the attemptToFetchMajorUpgrade key needs to be set to false and the disableSoftwareUpdateWorkflow key needs to be set to true.

These settings have the effect of completely stopping Nudge from attempting to download both minor updates and major upgrade apps via softwareupdate.

Both the majorUpgradeAppPath key in the osVersionRequirements dictionary and the actionButtonPath key in the userInterface dictionary, need to be set to either /System/Library/PreferencePanes/Softwareupdate.prefpane (Tribruin’s suggestion) or /System/Library/CoreServices/Software Update.app which Nudge uses internally.

The end result is that Nudge will simply open Software Update without attempting to download anything when macOS is out of compliance. The user will then need to initiate the download (either the app, delta upgrade or minor update) themselves to start the process.

This works on Big Sur, Monterey and Ventura and is easy if you want to require a single version of macOS, e.g. 13.2, no matter which lower major or minor version a computer running.

An example configuration profile for this option is available on GitHub.

Option 2

Jad in the #nudge channel on the MacAdmins Slack was the first to suggest a different option.

In the osVersionRequirements array, the dictionary with the targetedOSVersionsRule of 12 needs to have the majorUpgradeAppPath key set to either /System/Library/PreferencePanes/Softwareupdate.prefpane (Jad’s suggestion) or /System/Library/CoreServices/Software Update.app which Nudge uses internally.

This will cause Nudge to evaluate that the major upgrade app is already on disk and simply open Software Update for the user instead of trying to download the “Install macOS Ventura.app” on computers running Monterey.

This option requires you to configure multiple dictionaries in the osVersionRequirements array to cover the scenarios for all three macOS versions that Nudge runs on: 11, 12 and 13.

The advantage of this option is that it preserves Nudge’s native ability to download updates and have them ready before prompting users.

An example configuration profile for this option is also available on GitHub.

Which option to choose

There is no right or wrong choice here. Which option to use will depend on your specific fleet and environment. I have extensively tested both scenarios and am confident either will work.

Option 1:

• Requires setting three preference keys to non-default values.
• Only requires a single osVersionRequirements dictionary.
• Changes normal Nudge behavior so that nothing is automatically downloaded and the user must manually start all downloads from Software Update before installation.
• Disables the use of Apple’s notoriously unreliable softwareupdate command line tool which may be desirable in some circumstances.

Option 2:

• Only requires setting one preference key to a non-default value.
• Requires multiple osVersionRequirements dictionaries.
• Preserves normal Nudge behavior that downloads certain updates using Apple’s softwareupdate command line tool before prompting the user for installation.

Please be aware that neither option, nor Nudge in general, has any control over what updates are available in Apple’s Software Update. If users do not see the version you nudged them to install, the problem lies with macOS itself.

A note on configuring Nudge

Nudge is highly configurable which can lead to problems when setting it up for the first time. Please read the note on the wiki about over-configuring Nudge and start small if you are new. You do not need to deploy every single preference key available or shown in the Example Assets.

Need help?

If you have any questions or need any help please join us in the #nudge channel on the MacAdmins Slack.