Skip to content

osVersionRequirements

Jump to bottom Edit New page
PyroGX edited this page Nov 1, 2024 · 38 revisions

OS Version Requirements

Preferences

osVersionRequirements

  • Type: Array
  • Default Value: []
  • Required: Yes
  • Version: v1.0 and later

The required components necessary to enforce an Operating System version through Nudge.

Specify one array to enforce a single Operating System version across all machines or specify multiple arrays for specific enforcements.

aboutUpdateURL

  • Type: String
  • Default Value: []
  • Required: No
  • Version: v1.0 and later

A single URL, enabling the More Info button URL path. While this accepts a string, it must be a valid URL (http://, https://, file://).

Note: If this value is passed with aboutUpdateURLs, the aboutUpdateURLs key will be ignored.

aboutUpdateURLs

  • Type: Array
  • Default Value: []
  • Required: No
  • Version: v1.1.0 and later

A list of arrays, enabling localization of the More Info button URL path. Please see the aboutUpdateURLs wiki article for more information.

Note: If this value is not passed, the more_info button will be hidden.

actionButtonPath

  • Type: String
  • Default Value: ""
  • Required: No
  • Version: v1.1.6 and later

A path to a URI for opening alternative actions, like Jamf Self Service items or Munki Self Service items.

Note: When using this key, you will lose the dynamic capability for updateDevice supporting minor / major upgrades, so it will be up to your separate tool to handle this logic.

Do not pass an empty string with this key, or you will get the following error in the Nudge logs:

actionButtonPath contains empty string - actionButton will be unable to trigger any action required for major upgrades

You can have multiple actionButtonPath per osVersionRequirement dictionary, allowing you to have multiple paths for minor and major upgrades.

Note: If you use actionButtonPath in both osVersionRequirements and the original one in userInterface, Nudge v1.1.6 will ignore the one in userInterface

majorUpgradeAppPath

  • Type: String
  • Default Value: ""
  • Required: No
  • Version: v1.1.3 and later

The full path to a standalone macOS installer for a major upgrade. See the Major Upgrade App Path Examples section for potential configurations of this preference and other related settings.

requiredInstallationDate

  • Type: String or Date (see description)
  • Default Value: ""
  • Required: No
  • Version: v1.1.16 and below only

The required installation date for Nudge to enforce the required operating system version.

Note: If you are using a MDM profile and passing the original Date key, you must change to utilizing String as Apple requires ISO8601 formatted dates

  • v2.0 and later - You can now pass two formats of strings to specify UTC (YYYY-MM-DDTHH:MM:SSZ) or local time (YYYY-MM-DDTHH:MM:SS)

    • Example UTC - 2025-01-01T00:00:00Z
    • Example local - 2025-01-01T00:00:00

  • v1.1.16 and previous - You must follow a standard date format as YYYY-MM-DDTHH:MM:SSZ

    • Example: "2023-03-31T17:00:00Z"

The type specified for this preference is dependent on the method of configuration used with Nudge.

  • JSON configuration: A string is required and deadlines are in UTC time (previous to v2.0).

  • Jamf Pro Custom Schema: A string is required for Jamf's JSON Schema Manifest and deadlines are in local timezone (previous to v2.0).

  • Configuration Profile: Either a date key (for a UTC deadline) or a string key (for a local timezone deadline) will work.

Configuration Profile examples:

Deadline in UTC time (all computers worldwide have the same deadline at 5:00 p.m. UTC)

<key>requiredInstallationDate</key>
<date>2023-03-31T17:00:00Z</date>

Deadline in local time (e.g. all computers have a deadline of 5:00 p.m. in their local timezone)

<key>requiredInstallationDate</key>
<string>2023-03-31T17:00:00</string>

requiredMinimumOSVersion

  • Type: String
  • Default Value: ""
  • Required: Yes
  • Version: v1.1.3 and later

The required minimum operating system version.

Note: When passing versions such as 11.2.0 it will be normalized to 11.2. It is recommended to remove the trailing zero from the version number.

targetedOSVersions (Deprecated)

  • Type: Array
  • Default Value: []
  • Required: No
  • Version: v1.0 only

The versions of macOS that require a security update.

You can specify single version or multiple versions, but they must be within an array.

Examples:

"targetedOSVersions": [
  "11.0"
]
"targetedOSVersions": [
  "11.0",
  "11.0.1",
  "11.1",
  "11.2"
]

targetedOSVersionsRule

  • Type: String
  • Default Value: ""
  • Required: No
  • Version: v1.1.0 and later

For more documentation please see the targetedOSVersionsRule wiki article

The required minimum operating system version. Rules take the following precedence:

  • full OS match (example: device is running 11.5.1 and rule is 11.5.1)
  • major OS match (example: device us running 11.5.1 and rule is 11)
  • default match (example: device is running 11.5.1 and rule is default or targetedOSVersionsRule key is not present)

Note: Passing identical rules will result in "undefined" behavior. Currently with v1.1.0, the last identical rule will be honored. Passing a value of "default" is identical to not passing this key, allowing concurrent deployments of Nudge v1.0 and v1.1.0 in the same environment.

Examples:

"targetedOSVersionsRule": "11.5.2"
"targetedOSVersionsRule": "11"
"targetedOSVersionsRule": "default"

Examples

Example Configuration - JSON

This example allows an admin to support both v1.0 and v1.1.0 behavior

{
    "osVersionRequirements": [
      {
        "aboutUpdateURL": "https://apple.com",
        "requiredInstallationDate": "2021-07-30T00:00:00Z",
        "requiredMinimumOSVersion": "11.5.2",
        "targetedOSVersions": [
          "11.0",
          "11.0.1",
          "11.1",
          "11.2",
          "11.2.1",
          "11.2.2",
          "11.2.3",
          "11.3",
          "11.3.1",
          "11.4",
          "11.5",
          "11.5.1"
        ],
        "targetedOSVersionsRule": "default"
      }
    ]
}

Example Configuration - Mobile

This example allows an admin to support both v1.0 and v1.1.0 behavior

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>PayloadContent</key>
    <array>
      <dict>
        <key>PayloadDescription</key>
        <string>Configures osVersionRequirements preferences</string>
        <key>PayloadDisplayName</key>
        <string>Nudge Preferences</string>
        <key>PayloadIdentifier</key>
        <string>com.github.macadmins.Nudge.preferences.example.osVersionRequirements</string>
        <key>PayloadOrganization</key>
        <string></string>
        <key>PayloadType</key>
        <string>com.github.macadmins.Nudge</string>
        <key>PayloadUUID</key>
        <string>CA02957C-7472-446B-9F77-3E0414405556</string>
        <key>PayloadVersion</key>
        <integer>1</integer>
        <key>osVersionRequirements</key>
        <array>
          <dict>
            <key>aboutUpdateURL</key>
            <string>https://apple.com</string>
            <key>requiredInstallationDate</key>
            <date>2021-07-30T00:00:00Z</date>
            <key>requiredMinimumOSVersion</key>
            <string>11.5.2</string>
            <key>targetedOSVersions</key>
            <array>
              <string>11.0</string>
              <string>11.0.1</string>
              <string>11.1</string>
              <string>11.2</string>
              <string>11.2.1</string>
              <string>11.2.2</string>
              <string>11.2.3</string>
              <string>11.3</string>
              <string>11.3.1</string>
              <string>11.4</string>
              <string>11.5</string>
              <string>11.5.1</string>
            </array>
            <key>targetedOSVersionsRule</key>
            <string>default</string>
          </dict>
        </array>
      </dict>
    </array>
    <key>PayloadDescription</key>
    <string>Configures Nudge application</string>
    <key>PayloadDisplayName</key>
    <string>Nudge</string>
    <key>PayloadIdentifier</key>
    <string>com.github.macadmins.Nudge.example.osVersionRequirements</string>
    <key>PayloadOrganization</key>
    <string>Nudge</string>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>2F54F734-132D-4539-B583-F1DCF23DB5EB</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
  </dict>
</plist>

Major Upgrade App Path Examples

No. Desired Behavior macOS Account Type* userInterface : actionButtonPath optionalFeatures : attemptToFetchMajorUpgrade osVersionRequirements : majorUpgradeAppPath
1 Execute custom Munki Self Service or Jamf Self Service policy Administrator

Standard User		 Munki:
"actionButtonPath": "munki://updates",

Jamf Pro:
"actionButtonPath": "jamfselfservice://content?entity=policy&id=1&action=execute", 		Ignored due to actionButtonPath Ignored due to actionButtonPath
2 Launch pre-cached macOS standalone installer Administrator Not included / Removed false /Applications/Install macOS Monterey.app
3 Cache and launch macOS standalone installer Administrator Not included / Removed true /Applications/Install macOS Monterey.app

*For Mac computers with Apple silicon, the user must be a Volume Owner. (See also: Schedule an OS Update)

Notes on each row's configuration:

  1. When using userInterface : actionButtonPath, you will lose the dynamic capability for updateDevice supporting minor / major upgrades, so it will be up to your separate tool to handle this logic.
  2. Requires a major macOS installer to be pre-cached and for the user to have local administrative rights.
  3. Leverages softwareupdate --fetch-full-installer to download the macOS standalone installer and requires the user to have local administrative rights.
Add a custom footer
Home
Getting Started
Common Issues
New Features
User Deferrals
Command Line Arguments
Preferences
Jamf Pro Guide
Logging
Clone this wiki locally