> ## Documentation Index
> Fetch the complete documentation index at: https://silmaril.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed rollout

> Prepare a configuration profile and package for deployment through MDM.

export const macosRelease = {
  "version": "0.3.22",
  "build": "1077",
  "guardianEnabled": false,
  "minimumOS": "macOS 14 or later",
  "dmgUrl": "https://downloads.silmaril.dev/macos/releases/0.3.22/1077/Silmaril-0.3.22-1077-guardian-disabled.dmg",
  "pkgUrl": "https://downloads.silmaril.dev/macos/releases/0.3.22/1077/Silmaril-0.3.22-1077-guardian-disabled.pkg",
  "mdmZipUrl": "https://downloads.silmaril.dev/macos/releases/0.3.22/1077/Silmaril-0.3.22-1077-guardian-disabled-MDM.zip",
  "mdmChecksumUrl": "https://downloads.silmaril.dev/macos/releases/0.3.22/1077/Silmaril-0.3.22-1077-guardian-disabled-MDM.zip.sha256",
  "mdmSHA256": "86efaf60414339c97c5fcaac86d98b215f44010798f58e83ea3850b1243fd92a"
};

<a id="mdm-rollout" />

## Add Silmaril to the existing configuration

Keep each Mac in its existing device configuration. Add the Silmaril profile and app to that configuration, scoped to the intended devices with a tag, group, or label.

Preserve existing controls such as CIS settings, FileVault, Falcon, and Okta Device Trust. Silmaril is a separate profile within the existing deployment structure. Never merge its payloads into unrelated baseline profiles.

## Before you begin

Use this path for Jamf Pro, Iru, and Fleet. Deploy the Stable {macosRelease.version} (build {macosRelease.build}) Guardian Disabled PKG with the completed universal profile below. End users do not configure the connection.

Assign the profile and the app to the same intended devices. A shared tag, group, or label does not set install order.

For each rollout cohort, keep the app unassigned or its install policy disabled until that cohort shows the profile installed. Expanding the rollout repeats this staging. Adding devices to an assignment that already installs the app does not recreate the order.

You need MDM administrator access, an enrolled Mac running {macosRelease.minimumOS}, and the vendor management agent where required.

| Item | Owner |
| - | - |
| Shared installer and standard configuration profile | Provided by Silmaril |
| Deployment-specific API URL and API key | Supplied by Silmaril. Customer IT places both in the profile |
| Optional Dashboard URL and Firewall ID | Supplied by Silmaril when needed |
| Assignments, rollout, update deployment, optional policy choices, and validation | Customer IT |

## Release bundle

Download the <a href={macosRelease.mdmZipUrl}>release MDM ZIP</a> and the SHA-256 sidecar published with that ZIP.

**Expected result**<br />
The ZIP checksum matches <code>{macosRelease.mdmSHA256}</code>.

**If this differs**<br />
Stop and use the ZIP whose digest matches that value. A mismatched archive is not the Stable MDM artifact.

The standard release profile includes notification and login permissions while leaving application settings unmanaged. It does not assign update ownership. The customized starter below adds deployment connection values and explicitly sets MDM update authority. Install one profile or the other, never both.

For an existing Guardian Disabled deployment with separate Silmaril profiles, install the completed universal profile and confirm delivery, then remove the old split profiles through MDM. Confirm removal and recheck the intended managed values before expanding the rollout.

<Warning>
  A delivered profile or a successful package install does not mean endpoint protection is active. After the PKG is installed, [verify](/docs/macos/verify) the app, the managed connection, and current Protection activity.
</Warning>

<a id="vendor-guides" />

## Vendor guides

Each guide adds Silmaril to the existing configuration. It does not replace that configuration. The guides cover upload, assignment, verification, updates, and removal.

* [Jamf Pro](/docs/macos/jamf)
* [Iru (formerly Kandji)](/docs/macos/iru)
* [Fleet](/docs/macos/fleet)

<a id="managed-template" />

<a id="published-profiles" />

## Required configuration

[Download the complete profile template](https://silmaril.dev/docs/macos/Silmaril-Managed.template.mobileconfig). Silmaril supplies both required values: the API URL and API key. Other application preferences are [optional settings](/docs/macos/settings#optional-settings).

The template is the universal device profile (`PayloadIdentifier` `dev.silmaril.mdm.managed`, display name Silmaril Managed). Its application-settings payload states that omitted keys remain unmanaged. The template includes notification permission and launch at login. Save the completed file as `Silmaril-Managed.mobileconfig` and upload that file.

Managed credentials are readable by MDM administrators. Restrict access to the completed profile. A managed API key requires a forced valid HTTPS API URL. Rotate the URL and key together.

<Steps>
  <Step title="Fill in required values">
    Open the complete template in a plain-text XML editor. Replace its existing `mcx_preference_settings` key and dictionary with the XML below, then fill in both placeholders. Keep `SilmarilUpdateAuthority` set to `mdm` so IT controls updates.

    ```xml theme={"theme":"github-light-default"}
    <key>mcx_preference_settings</key>
    <dict>
      <key>silmaril.apiURL</key>
      <string>REPLACE_WITH_SILMARIL_API_URL</string>
      <key>silmaril.apiKey</key>
      <string>REPLACE_WITH_SILMARIL_API_KEY</string>
      <key>SilmarilUpdateAuthority</key>
      <string>mdm</string>
    </dict>
    ```

    **Expected result**<br />
    Both placeholders contain the exact URL and API key supplied by Silmaril, and update authority remains `mdm`.

    **If this differs**<br />
    Do not upload a profile with unresolved placeholders. Obtain the deployment URL and key from Silmaril. MDM update authority disables the in-app updater. Your MDM still needs to deploy each PKG update.
  </Step>

  <Step title="Validate the completed profile">
    Preserve every profile and payload identifier, UUID, permission payload, and surrounding payload. Save the complete file as `Silmaril-Managed.mobileconfig`, then run the validation commands on your administrator Mac.

    ```bash theme={"theme":"github-light-default"}
    plutil -lint Silmaril-Managed.mobileconfig || exit 1
    if grep -Eq 'REPLACE_WITH_|PLACEHOLDER_' Silmaril-Managed.mobileconfig; then
      echo "Unresolved placeholder found" >&2
      exit 1
    fi
    ```

    **Expected result**<br />
    `plutil` reports the file is OK, and the command exits 0.

    **If this differs**<br />
    A lint failure or the message `Unresolved placeholder found` means the file is not ready to upload. Correct the XML and keep the supplied identifiers. Never invent identifiers to bypass a conflict.
  </Step>

  <Step title="Upload through MDM">
    Upload the whole completed profile. Assign the profile and PKG to the same intended devices, and confirm profile delivery before deploying the PKG. For a later cohort, leave the app unassigned or disabled until those Macs show the profile installed. End users do not configure the connection. Continue with the vendor guide for [Jamf Pro](/docs/macos/jamf), [Iru](/docs/macos/iru), or [Fleet](/docs/macos/fleet).

    **Expected result**<br />
    The completed profile is installed on the pilot Macs before the <a href={macosRelease.pkgUrl}>Stable PKG</a> is deployed. That PKG is {macosRelease.version} ({macosRelease.build}), Guardian Disabled.

    **If this differs**<br />
    Wait until the profile install has completed. Deploying the PKG first leaves the Mac outside this order. Optional keys, if used, are added inside the same `mcx_preference_settings` dictionary. See [Managed settings](/docs/macos/settings).
  </Step>
</Steps>