apple_device-management/declarative/declarations/configurations/softwareupdate.settings.yaml

title: Software Update:Settings
description: The declaration to configure software updates.
payload:
  declarationtype: com.apple.configuration.softwareupdate.settings
  supportedOS:
    iOS:
      introduced: '18.0'
      allowed-enrollments:
      - supervised
      - device
      allowed-scopes:
      - system
      sharedipad:
        allowed-scopes:
        - system
    macOS:
      introduced: '15.0'
      allowed-enrollments:
      - supervised
      allowed-scopes:
      - system
    tvOS:
      introduced: '18.4'
      allowed-enrollments:
      - supervised
      - device
      allowed-scopes:
      - system
    visionOS:
      introduced: '26.0'
      allowed-enrollments:
      - supervised
      - device
      allowed-scopes:
      - system
    watchOS:
      introduced: n/a
  apply: combined
payloadkeys:
- key: Notifications
  title: Software Update Notifications
  type: <boolean>
  presence: optional
  default: true
  combinetype: boolean-and
  content: |-
    If set to `true`, the device shows all software update enforcement notifications.

    If set to `false`, the device only shows notifications triggered one hour before the enforcement deadline, and the restart countdown notification.
- key: Deferrals
  title: Software Update Deferrals
  supportedOS:
    iOS:
      allowed-enrollments:
      - supervised
    tvOS:
      allowed-enrollments:
      - supervised
    visionOS:
      allowed-enrollments:
      - supervised
  type: <dictionary>
  presence: optional
  content: This object configures the deferral of software updates. Background Security
    Improvements aren't considered in `Major`, `Minor`, or `System` deferral mechanism.
  subkeys:
  - key: CombinedPeriodInDays
    title: Combined Major/Minor Update Deferral Period
    supportedOS:
      macOS:
        introduced: n/a
    type: <integer>
    presence: optional
    range:
      min: 1
      max: 90
    combinetype: number-max
    content: Specifies the number of days to defer a major or minor OS software update
      on the device. When set, software updates only appear after the specified delay,
      following the release of the software update. Available in iOS 18 and later.
  - key: MajorPeriodInDays
    title: Major Update Deferral Period
    supportedOS:
      iOS:
        introduced: n/a
      tvOS:
        introduced: n/a
      visionOS:
        introduced: n/a
    type: <integer>
    presence: optional
    range:
      min: 1
      max: 90
    combinetype: number-max
    content: Specifies the number of days to defer a major OS software update on the
      device. When set, software updates only appear after the specified delay, following
      the release of the software update. Available in macOS 15 and later.
  - key: MinorPeriodInDays
    title: Minor Update Deferral Period
    supportedOS:
      iOS:
        introduced: n/a
      tvOS:
        introduced: n/a
      visionOS:
        introduced: n/a
    type: <integer>
    presence: optional
    range:
      min: 1
      max: 90
    combinetype: number-max
    content: Specifies the number of days to defer a minor OS software update on the
      device. It also defers major updates for iOS. When set, software updates only
      appear after the specified delay, following the release of the software update.
      Available in macOS 15 and later.
  - key: SystemPeriodInDays
    title: System Update Deferral Period
    supportedOS:
      iOS:
        introduced: n/a
      tvOS:
        introduced: n/a
      visionOS:
        introduced: n/a
    type: <integer>
    presence: optional
    range:
      min: 1
      max: 90
    combinetype: number-max
    content: Specifies the number of days to defer system or non-OS updates. When
      set, updates only appear after the specified delay, following the release of
      the update. Available in macOS 15 and later.
- key: RecommendedCadence
  title: Software Update Recommended Cadence
  supportedOS:
    macOS:
      introduced: n/a
    tvOS:
      introduced: n/a
  type: <string>
  presence: optional
  rangelist:
  - All
  - Oldest
  - Newest
  combinetype: enum-last
  content: |-
    This string specifies how the device shows software updates to the user. When more than one update is available update, the device behaves as follows:

    - `All` - Shows all software update versions.
    - `Oldest` - Shows only the oldest (lower numbered) software update version.
    - `Newest` - Shows only the newest (highest numbered) software update version.
- key: AutomaticActions
  title: Automatic Software Update Settings
  supportedOS:
    iOS:
      allowed-enrollments:
      - supervised
    tvOS:
      allowed-enrollments:
      - supervised
    visionOS:
      allowed-enrollments:
      - supervised
  type: <dictionary>
  presence: optional
  content: This object configures various automatic Software Update functionality.
  subkeys:
  - key: Download
    title: Automatic downloads of available updates.
    supportedOS:
      tvOS:
        introduced: n/a
    type: <string>
    presence: optional
    rangelist:
    - Allowed
    - AlwaysOn
    - AlwaysOff
    default: Allowed
    combinetype: enum-last
    content: |-
      Specifies whether the user can control automatic downloads of available updates:

      - `Allowed` - the user can enable or disable automatic downloads.
      - `AlwaysOn` - automatic downloads are always enabled.
      - `AlwaysOff` - automatic downloads are always disabled.
  - key: InstallOSUpdates
    title: Automatic installs of OS updates.
    type: <string>
    presence: optional
    rangelist:
    - Allowed
    - AlwaysOn
    - AlwaysOff
    default: Allowed
    combinetype: enum-last
    content: |-
      Specifies whether the user can control automatic installation of available updates:

      - `Allowed` - the user can enable or disable automatic installation.
      - `AlwaysOn` - automatic installations are always enabled.
      - `AlwaysOff` - automatic installations are always disabled.
  - key: InstallSecurityUpdate
    title: Automatic installs of available security updates.
    supportedOS:
      tvOS:
        introduced: n/a
    type: <string>
    presence: optional
    rangelist:
    - Allowed
    - AlwaysOn
    - AlwaysOff
    default: Allowed
    combinetype: enum-last
    content: |-
      Specifies whether the user can control automatic installation of available security updates:

      - `Allowed` - the user can enable or disable automatic installation.
      - `AlwaysOn` - automatic installations are always enabled.
      - `AlwaysOff` - automatic installations are always disabled.
- key: RapidSecurityResponse
  title: Background Security Improvement Settings
  supportedOS:
    iOS:
      allowed-enrollments:
      - supervised
    tvOS:
      introduced: n/a
    visionOS:
      introduced: n/a
  type: <dictionary>
  presence: optional
  content: These configurations set user access to interacting with Background Security
    Improvement.
  subkeys:
  - key: Enable
    title: Enable Background Security Improvement Installation
    type: <boolean>
    presence: optional
    default: true
    combinetype: boolean-and
    content: |-
      If set to `false`, Background Security Improvements aren't offered for user installation. The system can still install Background Security Improvements with `com.apple.configuration.softwareupdate.enforcement.specific` configurations.

      If set to `true`, the system offers Background Security Improvements to the user.
  - key: EnableRollback
    title: Enable Background Security Improvement Rollbacks
    type: <boolean>
    presence: optional
    default: true
    combinetype: boolean-and
    content: |-
      If set to `false`, the system doesn't offer Background Security Improvement rollbacks to the user.

      If set to `true`, the system offers Background Security Improvement rollbacks to the user.
- key: AllowStandardUserOSUpdates
  title: Allow Standard User OS Updates
  supportedOS:
    iOS:
      introduced: n/a
    tvOS:
      introduced: n/a
    visionOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: true
  combinetype: boolean-and
  content: |-
    If set to `true`, a standard user can perform Major and Minor Software Updates.

    If set to `false`, only administrators can perform Major and Minor Software Updates.
- key: Beta
  supportedOS:
    macOS:
      introduced: '15.4'
      allowed-enrollments:
      - supervised
      allowed-scopes:
      - system
    tvOS:
      introduced: n/a
    visionOS:
      introduced: n/a
  type: <dictionary>
  presence: optional
  content: This object configures the beta program settings for a device.
  subkeys:
  - key: ProgramEnrollment
    supportedOS:
      iOS:
        allowed-enrollments:
        - supervised
    type: <string>
    presence: optional
    rangelist:
    - Allowed
    - AlwaysOn
    - AlwaysOff
    default: Allowed
    combinetype: enum-last
    content: |-
      Specifies whether the user can control beta program enrollment in the software update settings UI:

      - `Allowed` - the user can enroll in any applicable beta programs associated with their logged in Apple Account. If the `OfferPrograms` key is present, then the programs listed in that key are also presented to the user.
      - `AlwaysOn` - the beta programs specified by the organization are used, and the user isn't able to enroll in a beta program using their logged in Apple Account. The device is automatically enrolled into the beta program specified by the `RequireProgram` key if it's present. Otherwise, the system presents the programs listed in the `OfferPrograms` key to the user to choose which to enroll with.
      - `AlwaysOff` - The device isn't allowed to enroll in any beta programs. The system removes the device from any beta programs, if already enrolled.
  - key: OfferPrograms
    type: <array>
    presence: optional
    combinetype: set-union
    content: An array of beta programs allowed on the device. This key must only be
      present if the `ProgramEnrollment` key is set to `Allowed` or `AlwaysOn`. This
      key must not be present if the `RequireProgram` key is present. This key can
      be present on unsupervised devices where the `ProgramEnrollment` key isn't supported
      but is implicitly set to `Allowed`.
    subkeys:
    - key: Program
      type: <dictionary>
      presence: required
      content: The name and token associated with a specific beta program to be allowed.
      subkeys:
      - key: Description
        type: <string>
        presence: required
        content: A human readable description of the beta program.
      - key: Token
        type: <string>
        presence: required
        content: The Apple Business Manager or Apple School Manager seeding service
          token for the organization the MDM server is part of. The system uses this
          token to enroll the device in the corresponding beta program.
  - key: RequireProgram
    supportedOS:
      iOS:
        allowed-enrollments:
        - supervised
    type: <dictionary>
    presence: optional
    combinetype: first
    content: The device automatically enrolls in this beta program. This key must
      only be present if the `ProgramEnrollment` key is set to `AlwaysOn`. The `OfferPrograms`
      key must not be present if this key is present.
    subkeys:
    - key: Description
      type: <string>
      presence: required
      content: A human readable description of the beta program.
    - key: Token
      type: <string>
      presence: required
      content: The Apple Business Manager or Apple School Manager seeding service
        token for the organization the MDM server is part of. The system uses this
        token to enroll the device in the corresponding beta program.
related-status-items:
- status-items:
  - softwareupdate.beta-enrollment
  - softwareupdate.pending-version