> For the complete documentation index, see [llms.txt](https://docs.we360.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.we360.ai/deployment-and-it-ops/deploy/agent-deployment-hub/mass-deployment/macos-mdm/filename-independent-config.md).

# When MDM changes the PKG filename

Prepare tenant configuration before deployment when an MDM changes the original macOS stealth installer filename.

If your MDM changes the stealth installer's original portal filename, the app may install without the tenant configuration it needs. Providing that configuration is a **probable workaround** for this specific issue, not a confirmed fix for every MDM installation failure.

Check `/tmp/zs-postinstall.log` on a pilot Mac. If `PACKAGE_PATH` shows a different filename from the original portal download and tenant setup is missing, follow this procedure. It doesn't fix missing privacy permissions, network access, or a blocked package installation.

## Before you start

* Use the original portal-generated `.pkg` filename for the intended tenant. A generic name such as `zs-arm64.pkg` doesn't contain the configuration.
* Use macOS 12 or newer.
* Your MDM must support a root/system shell script that completes **before** the PKG installation. A separate, ordered script job is suitable; a built-in package pre-install field isn't required.
* Pilot the sequence on one Mac before expanding the deployment scope.

{% hint style="warning" %}
The original filename, decoded JSON, and configured script contain a tenant credential. Keep them private. Don't put configured scripts in public source repositories or tickets, and don't enable script-content logging or shell tracing in MDM. Use a separate configuration and device scope for each tenant. The script replaces any existing `/Library/Preferences/zs.json`.
{% endhint %}

## 1. Decode the package name once

On your IT preparation Mac, run this block in Terminal. At the prompt, paste the **original portal filename**, including `.pkg`, and press Return. Don't include a directory path or a browser-added `(1)` suffix.

```sh
(
    set +x
    set -eu
    printf 'Original portal PKG filename: ' >&2
    IFS= read -r PKG_NAME
    JSON=$(printf '%s' "${PKG_NAME%.pkg}" |
        /usr/bin/base64 -D |
        /usr/bin/plutil -convert json -o - -- -)
    printf '%s\n' "$JSON" | /usr/bin/sed "s/'/\\\\u0027/g"
)
```

If any error appears, stop and check the original filename. Successful output is one JSON line containing `tid` and `skey`, and possibly other fields such as `t`. Copy the entire line. The command escapes any apostrophe as `\u0027` so that you can paste the JSON between single quotes without changing the credential value. Reading the filename at a prompt keeps it out of the command text saved in shell history.

This is an interactive **IT preparation step**, not an MDM payload. Neither the preparation command nor the deployed script needs the PKG file to be present.

## 2. Edit the single JSON variable

Copy this script into a plain-text file named `install-zs-config.sh`. Replace the marked `ZS_JSON` placeholder with the JSON you copied. The script contains no tenant credential until you configure that variable. It parses the JSON but doesn't check whether the tenant ID or key is correct.

{% code title="install-zs-config.sh" %}

```sh
#!/bin/sh
set +x
set -eu
umask 077

[ "$(/usr/bin/id -u)" -eq 0 ] || {
    printf '%s\n' 'MDM must run this script as root.' >&2
    exit 1
}

# Replace this placeholder with the complete JSON configuration on one line.
# Keep the surrounding single quotes; apostrophes are escaped as \u0027.
ZS_JSON='REPLACE_ME_WITH_DECODED_JSON'

config=$(/usr/bin/mktemp)
trap '/bin/rm -f "$config"' 0

printf '%s\n' "$ZS_JSON" > "$config"
/usr/bin/plutil -convert json "$config" >/dev/null
/usr/bin/install -S -o root -g wheel -m 0644 \
    "$config" /Library/Preferences/zs.json

printf '%s\n' 'Saved /Library/Preferences/zs.json'
```

{% endcode %}

For example, using dummy values only:

```sh
ZS_JSON='{"tid":"example-tenant","skey":"example-key","t":1234567890}'
```

Keep the surrounding single quotes and the JSON's double quotes. Paste the output as one line, without Markdown fences or terminal messages. Don't replace `\u0027` with a literal apostrophe. Save the file as plain text with LF line endings. You don't need to edit any other variable.

## 3. Deploy the script before the PKG

1. Upload the configured script to your MDM using its private script storage.
2. Select **root/system** execution, not the signed-in user, with `/bin/sh` as the interpreter. The script requires no logged-in user, input, `sudo`, or password prompt.
3. Scope it only to the intended tenant's pilot Mac. Require a successful script exit before starting the PKG job. Malformed JSON or an unchanged placeholder causes the script to fail before replacing the configuration.
4. After the script succeeds, deploy the signed PKG through your normal MDM package workflow. You don't need to rename, expand, or rebuild the PKG.

The script writes the complete JSON to `/Library/Preferences/zs.json`, with owner `root`, group `wheel`, and permissions `0644`, so the user-session app can read it. It doesn't install the app, restart it, or change privacy permissions.

## 4. Verify the pilot

* Confirm the MDM script exits with status `0` and reports `Saved /Library/Preferences/zs.json`. A nonzero status is a failed job; resolve it before proceeding with the PKG.
* Check the file metadata without printing the credential:

  ```sh
  /usr/bin/stat -f '%Su:%Sg %Lp' /Library/Preferences/zs.json
  ```

  Expected output: `root:wheel 644`.
* After package installation, confirm the device appears online under the intended tenant in the portal. A successful file write alone doesn't verify app startup, permissions, or data upload.
* If the pilot still fails, retain the MDM job result and review the installation log privately with support before expanding the scope. Don't attach the configured script or JSON to a public ticket.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.we360.ai/deployment-and-it-ops/deploy/agent-deployment-hub/mass-deployment/macos-mdm/filename-independent-config.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
