Software Update settings declarative configuration for Apple devices
Use the Software Update settings configuration to enforce software updates at a certain time. For more information, see Use MDM to deploy software updates.
The Software Update settings configuration supports the following:
Minimum supported operating systems and channels: iOS 18, iPadOS 18, Shared iPad device, macOS 15 device.
Requires supervision: Yes, except the following: Enforcement keys, beta testing
OfferProgramskeys.Supported enrolment types: Device Enrolment, Automated Device Enrolment.
AutomaticActions dictionary keys
The AutomaticActions dictionary offers the keys shown below (default is Allowed and not required).
Key | Type | Merge behaviour | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Enum | The last value from the list: Allowed, AlwaysOn, AlwaysOff. | Specifies whether automatic downloads and preparation of available updates only (not upgrades and Rapid Security Responses) can be controlled by the user:
| ||||||||
| Enum | The last value from the list: Allowed, AlwaysOn, AlwaysOff. | Specifies whether automatic installation of available operating system updates only (not upgrades and Rapid Security Responses) can be controlled by the user:
| ||||||||
(macOS only) | Enum | The last value from the list: Allowed, AlwaysOn, AlwaysOff. | Specifies whether automatic installation of available security updates can be controlled by the user:
| ||||||||
In case multiple declarations include a value for the same key, the last value in the following list applied by any of those declarations takes precedence: Allowed, AlwaysOn, AlwaysOff.
RapidSecurityResponse dictionary keys for iOS, iPadOS and macOS
The RapidSecurityResponse dictionary contains the keys shown below (default is True and not required).
Key | Type | Merge behaviour | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Boolean | Logical AND operation of the values | If false, Rapid Security Responses aren’t offered for user installation. This defines whether Rapid Security Responses are automatically installed on user’s devices. | ||||||||
| Boolean | Logical AND operation of the values | If false, Rapid Security Response rollbacks aren’t offered to the user. This controls whether users have the option to remove a Rapid Security Response. | ||||||||
Independent of the Enable key, Rapid Security Responses can still be installed with the com.apple.configuration.softwareupdate.enforcement.specific declaration.
Deferrals dictionary keys for iOS and iPadOS
The Deferrals dictionaries offer different keys to configure the behaviour depending on the platform (no defaults, not required).
Key | Type | Merge behaviour | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Integer 1–90 | Maximum number of days | Specifies the number of days to defer a software update. When set, software updates and upgrades appear only after the specified delay, following the release of the software update or upgrade. | ||||||||
| Enum | The last value from the list: All, Oldest, Newest | Specifies how the device shows software upgrades to the user. When a software update and upgrade is available, the device behaves as follows:
| ||||||||
Both CombinedPeriodInDays and RecommendedCadence can be used in combination. For example, if RecommendedCadence is set to Oldest and CombinedPeriodInDays is set to 30, a user sees only software updates for the oldest release after 30 days of their publishing date.
Deferrals dictionary keys for macOS
Key | Type | Merge behaviour | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Integer 1–90 | Maximum number of days | Specifies the number of days to defer a software upgrade on the device. When set, software upgrades appear only after the specified delay, following the release of the software upgrade. | ||||||||
| Integer 1–90 | Maximum number of days | Specifies the number of days to defer a software update only (not a software upgrade or Rapid Security Response) on the device. When set, software updates appear only after the specified delay, following the release of the software update. | ||||||||
| Integer 1–90 | Maximum number of days | Specifies the number of days to defer non-operating system updates. When set, updates appear only after the specified delay, following the release of the update. | ||||||||
In macOS, an additional key is available to determine whether both standard users and local administrators can perform an update or upgrade (the default behaviour), or determine whether administrative permissions are required (default is True and not required).
Key | Type | Merge behaviour | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Boolean | Logical AND operation of the values | If true, a standard user can perform updates and upgrades. If false, only administrators can perform updates and upgrades. | ||||||||
Enforce software updates dictionary keys
The declaration offers the keys shown below (all strings and no defaults).
Key | Required | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Yes | The target operating system version to update the device to by the appropriate time. This is the operating system version number, for example, iOS 17.4. | |||||||||
| No | The target build version to update the device by the specified time, for example, 21E219. The system uses the build version for testing during seeding periods. The build version can include a supplemental version identifier, for example, 21E219a. If the build version isn’t consistent with the target operating system version specified in the | |||||||||
| No | The local date time value that specifies when to force install the software update. Use the format YYYY-MM-DDTHH:MM:SS, which is derived from RFC3339 but doesn’t include a time zone offset. If the user doesn’t trigger the software update before this time, the device force installs it. | |||||||||
| No | The URL of a web page that shows details that the organisation provides about the enforced release. | |||||||||
If a configuration specifies an operating system or build version that’s the same as or older than the current device version, then the configuration is ignored.
If multiple configurations are present with a newer operating system or build version than the current device version, the configuration with the earliest target date and time is processed first, and any others remain in the queue. When the device updates to a new version, the set of configurations are reprocessed to determine which becomes the next one to be processed.
Any available Rapid Security Responses are automatically installed if an MDM solution defines only the TargetOSVersion. To target a specific release or Rapid Security Response, an MDM solution can use the TargetBuildVersion key in addition to specifying the build, including the supplemental version identifier.
Notifications key
The Notifications key changes the default notification behaviour to show only a notification 1 hour before the enforcement time and the restart countdown (default is True and not required).
Key | Type | Merge behaviour | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Boolean | Logical AND operation of the values | If true, the device shows all software update enforcement notifications. If false, the device only shows notifications triggered one hour before the enforcement deadline, and the restart countdown notification. | ||||||||
Managing beta software updates
On unsupervised iPhone or iPad devices, only the OfferPrograms array can be used to allow users to manually enrol into beta programs the organisation has subscribed to. The beta dictionary offers the following keys (not required):
Key | Type | Default | Merge behaviour | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Enum | Allowed | The last value from the list: Allowed, AlwaysOn, AlwaysOff | Specifies whether beta program enrolment can be controlled by the user in the software update settings user interface:
| |||||||
| Array | — | Unique union of all values | An array of beta programs allowed on the device. This key must only be present if the | |||||||
| Dictionary | — | First configuration applied | The device automatically enrols in this beta program. This key must be present only if the | |||||||
In addition to sending the name of the program, the OfferPrograms and RequireProgram options require that the token of the beta program be sent to the device. This token is used with Apple to verify eligibility and receive an updated software update configuration.
To allow users to enrol using their personal Apple Account or Managed Apple Account, an MDM solution can set the ProgramEnrollment key to Allowed. This allows users to enrol into any program available to their account and additionally into any beta program specified by the OfferPrograms array. Each Program dictionary in the OfferPrograms array must consist of the following keys (all strings, all required):
Key | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| A human-readable description of the beta program. | ||||||||||
| The seeding service token that the MDM solution is part of for the organisation. This token is used to enrol the device in the corresponding beta program. | ||||||||||
If an organisation wants to allow users to participate without the need to sign in, they can set the ProgramEnrollment key to AlwaysOn. In this case users are offered all programs listed in the OfferPrograms array. They can also automatically enrol devices into a beta program using a combination of ProgramEnrollment set to AlwaysOn and defining the beta program that the device must be enrolled into with the RequireProgram dictionary. The RequireProgram dictionary requires the following keys (all strings):
Key | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| A human-readable description of the beta program. | ||||||||||
| The seeding service token that the MDM solution is part of for the organisation. This token is used to enrol the device in the corresponding beta program. | ||||||||||
In case an organisation wants to prevent users from enrolling, they can set the ProgramEnrollment key to AlwaysOff. This also unenrols the device from any beta program that it was already manually or automatically enrolled in.
Note: Each MDM vendor implements these settings differently. To learn how various Software Update settings are applied to your devices and users, consult your MDM vendor’s documentation.