apple_device-management/declarative/declarations/configurations/services.background-tasks.yaml

title: Services Background Tasks
description: The declaration to configure background tasks.
payload:
  declarationtype: com.apple.configuration.services.background-tasks
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '15.0'
      allowed-enrollments:
      - supervised
      allowed-scopes:
      - system
    tvOS:
      introduced: n/a
    visionOS:
      introduced: n/a
    watchOS:
      introduced: n/a
  apply: multiple
payloadkeys:
- key: TaskType
  title: Task type
  type: <string>
  presence: required
  content: The unique identifier of the set of background tasks managed with this
    configuration. This should be a reverse DNS style identifier. The device uses
    this identifier to differentiate between tasks in different configurations.
- key: TaskDescription
  title: Task description
  type: <string>
  presence: optional
  content: A description of the set of background tasks this configuration manages.
- key: ExecutableAssetReference
  title: Executable asset reference
  type: <string>
  assettypes:
  - com.apple.asset.data
  asset-content-types:
  - application/zip
  presence: optional
  content: |-
    Specifies the identifier of an asset declaration containing a reference to the files to be used for the background task configuration. The corresponding asset must be of type `com.apple.asset.data`.

    The referenced data must be a zip archive of an entire directory that the device expands and stores in a well known location for the background task. The asset's "ContentType" and "Hash-SHA-256" keys in the "Reference" key are required.

    This zip archive should contain background task executables, scripts, and configuration files, but not the `launchd` configuration files.

    The device stores the expanded zip archive in the tamper-proof `/var/db/ManagedConfigurationFiles/BackgroundTaskServices/Services/<TaskType>` directory, where `<TaskType>` is the value of the `TaskType` key in the configuration.
- key: LaunchdConfigurations
  title: Launchd configurations
  type: <array>
  presence: optional
  content: |-
    An array of `launchd` configuration files used to run the background tasks.

    The device stores the configuration files in the tamper-proof `/var/db/ManagedConfigurationFiles/BackgroundTaskServices/LaunchDaemons` or `/var/db/ManagedConfigurationFiles/BackgroundTaskServices/LaunchAgents` directories, based on the `Context` value for each item.
  subkeys:
  - key: launchd-item
    title: Launchd item
    type: <dictionary>
    presence: required
    content: A dictionary of launchd configurations.
    subkeys:
    - key: FileAssetReference
      title: File asset reference
      type: <string>
      assettypes:
      - com.apple.asset.data
      asset-content-types:
      - application/plist
      - application/x-plist
      - application/xml
      - text/xml
      presence: required
      content: Specifies the identifier of an asset declaration containing a reference
        to the launchd configuration file for the background task. The referenced
        data must be a property list file conforming to the launchd.plist format.
        The asset's "ContentType" and "Hash-SHA-256" keys in the "Reference" key are
        required.
    - key: Context
      title: Launchd context
      type: <string>
      presence: required
      rangelist:
      - daemon
      - agent
      content: Indicates whether the device applies the launchd configuration file
        to the system daemon or system agent domain.
related-status-items:
- status-items:
  - services.background-task
  note: Each service managed by a configuration will have a corresponding status item
    that will contain a reference to the configuration.
notes:
- title: ''
  content: |-
    One or both of `ExecutableAssetReference` or `LaunchdConfigurations` needs to be present.

    If `ExecutableAssetReference` is present, the POSIX permissions of the files in the zip archive need to be set correctly. For example, executables must have the "x" bit set.

    If `LaunchdConfigurations` is present, the device stores the launchd configuration files in a secure location and loads them into launchd. When the device updates a launchd configuration, it kills and restarts any associated running tasks.

    If both `ExecutableAssetReference` and `LaunchdConfigurations` are present, and the device changes just the executable data, it kills and restarts any running tasks associated with the launchd configurations.

    > Note:
    > If an executable is an app, the device can't manage the app as it can only manage apps installed in `/Applications`. Also, the device can't use system extensions in the app as it only loads them from apps installed in `/Applications`.
examples:
- title: Configuration example
  files:
  - description: This configuration sets up a background task using a launchd daemon.
    file: examples/declarative/declarations/configurations/services.background-tasks/example1.json