Install native macOS apps

Relution allows native macOS applications to be uploaded centrally to the App Store and distributed to managed Macs. The supported file formats are .pkg (installer package) and .dmg (disk image). Reliable, unattended distribution depends on the interplay of a suitable package format, a correct detection rule, and valid signing. The following sections describe these components in detail.

PKG and DMG compared #

The choice of package format determines how an app is installed and whether the process can be automated.

A .pkg is the more robust format for automated distribution, because the installation routine is contained within the package itself and can run silently in the background. Scripts inside the package can perform additional steps, such as creating configuration files. During the upload, Relution reads the package’s Distribution file and takes the product ID and version from it. Packages without a Distribution file (plain component packages) are rejected as an unsupported file.

A .dmg is a disk image. It is only suitable for distribution if it contains a single application (.app) that is copied to /Applications. Images with an interactive installation assistant or multiple items cannot be installed unattended.

One essential difference concerns the distribution channel: .pkg apps are installed directly via the MDM protocol, whereas .dmg apps are deployed via the macOS Companion. This requires the macOS Companion to be switched on under Settings → Relution Client Apps with Enable macOS companion. The macOS Companion is not available on Macs running a macOS version earlier than 12 or on Macs with User Enrollment; DMG apps cannot be distributed to these devices.

Note: If an app is available both as a .pkg and as a .dmg, the .pkg is preferable for centralized distribution.

Add a native app in Relution #

Native macOS apps are created in the menu under Apps → App Store. The Add button opens the Add a new app dialog. Under Source, the Native app option is selected.

After clicking Next, the .pkg or .dmg file is uploaded via Choose file. Add details then opens the Add app form.

The following entries are required in the form:

• Internal name: For .pkg files, the product ID is taken from the Distribution file. For .dmg files, the file name is pre-filled as a placeholder and is replaced by a unique name. If an app with the same internal name already exists, saving creates a new version of that app.
• Version name: For .pkg files, the version is taken from the Distribution file; for .dmg files, it is entered manually.
• Detection rules: At least one detection rule is entered in the section of the same name – without a detection rule, the app cannot be saved (see the section on the detection rule below).

After specifying the desired Release status, the app is created via Save.

Version management and release status #

Native macOS apps also support release management: different versions of an app can be made available in parallel to different groups of people. For example, one version can be in productive use while a new version is tested by a selected group, without affecting the remaining users.

Each version goes through one of the following states:

• Release: the version that is regularly distributed and installed via the Relution Agent.
• Development or Review: states used for versions that are tested before release.
• Archive: state of a previous version that has been superseded by a newer released version.

Except for the Archive status, each release status can only contain one version of the app.

Testing a new version in parallel #

To test a new version alongside the existing released version, it is uploaded via the Add new version button and initially set to the Development or Review state. For .pkg files, the internal name of the new version must match that of the existing app. For .dmg files, a mismatch can be allowed with Ignore internal app name mismatch.

A date can be entered for the new version in the Go Live date field. The version only switches to the Release status automatically on that day if an App Release Workflow → is active and the version in the Review status has passed all release steps. Without an active release workflow, the date only serves as a target date, and the version is set to the Release status manually (see below).

Both versions remain visible in the app properties in the meantime; users with the appropriate permission can already view, install, and test the new version on endpoints.

Manual go-live #

If the new version is in the Review status, it is moved to the Release status on the app detail page via the Release button. If it is still in Development, the change is made via Move to → Release. An already released version is then automatically moved to the Archive state. Released versions of global apps cannot be moved to a different state.

Detection rule via the bundle identifier #

The detection rule tells Relution how to recognize the installed state of an app. For native macOS apps, the Package Name rule type is available for this purpose. It contains the bundle identifier of the installed app (e.g. com.vendor.appname); letters, digits, dots and hyphens are allowed. This value is used to check in the device’s list of installed apps whether the app is already present and whether an installation is considered successful.

Detection rules are created in the Detection rules section via Add new detection rule – in the Add app form during the upload, and for existing apps on the app detail page in the Settings tab. Optionally, a version check also compares the installed version: under Operator, Version is equal to (=) or Version does not equal (≠) is selected, and the version is entered under Value. An app can have several detection rules, for example if a package installs several apps. The app is only considered installed if all rules match.

The most reliable way to determine the correct bundle identifier is via a Mac that is already managed:

1. The app is installed manually once on a Mac that is managed in Relution.
2. In the Relution portal, the device is opened under Devices → Inventory.
3. On the Installed apps tab, the app is located. The bundle identifier is shown in the Internal name column.
4. This value is entered in the Package name field of the detection rule.

Alternatively, the bundle identifier can be read directly on the Mac via the Terminal:

osascript -e 'id of app "App-Name"'

If the path of the application is known, the value can also be read from the package metadata:

mdls -name kMDItemCFBundleIdentifier -raw /Applications/App-Name.app

If the detection rule is to be determined before an installation, the contents of a .pkg can be inspected with a third-party tool such as Suspicious Package. Such a tool shows the bundle identifier in addition to the install paths and contained scripts, without the package having to be run.

Note: Third-party tools serve analysis purposes only. The authoritative bundle identifier remains the value reported in the Relution inventory after an installation.

Alternatives without a working detection #

For some native apps, Relution cannot reliably check the installed state – for example because no unique bundle identifier is available or the package places the app in an atypical location. Automatic installation via App compliance is not suitable in these cases: Relution only recognizes a PKG or DMG app as installed if all detection rules are met. Otherwise, the installation is scheduled again with every compliance check.

Two options work without a reliable detection rule:

• Provisioning via the Relution App Store: The app is made available to users in the Relution Agent and installed there manually. Because the installation is actively triggered, no automatic state check is required.
• Distribution via an action: The Deploy Relution store app action on selected devices or groups triggers the installation specifically. The install command is transmitted to the device and executed there, independent of a detection rule.

Signing and notarization #

macOS uses Gatekeeper to check whether software comes from a trusted source. Packages that are neither signed nor notarized by Apple may be blocked or require user interaction – which prevents unattended distribution.

• Signing: The package is signed with a valid Developer ID. This makes the origin traceable and rules out tampering.
• Notarization: The package has additionally been checked by Apple (notarized). Only then is it accepted on current macOS versions without a warning.

Whether a package is correctly signed and notarized can be verified on the Mac in the Terminal:

spctl --assess --type install -vv /path/to/App.pkg
pkgutil --check-signature /path/to/App.pkg

Note: If an installation fails silently only for individual packages, missing signing or notarization is one of the most common causes.

Troubleshooting via logs and device logging #

If an installation remains unsuccessful, the causes can be narrowed down via logging.

Device logging in Relution #

Device logging is switched on for a single device in the global organization: the device is selected in the device inventory, and Activate device based logging is set via Manage device logging for the time specified under Duration (in minutes). During this period, commands such as the app installation are logged together with the device’s response. The captured Device logs are downloaded as a file in the same dialog. This makes it visible whether an install command has reached the device and with which status it was acknowledged.

Installation logs on the Mac #

In addition, the Mac’s system logs provide information about the installation process. The progress of a PKG installation is logged locally and can be evaluated in the Terminal:

tail -n 100 /var/log/install.log

For live observation during an installation, the live stream of the system log is suitable:

log stream --predicate 'process == "installer"' --info

These outputs reveal whether the package was unpacked, a script was executed, or the process was aborted by Gatekeeper.

Uninstallation #

Native macOS apps that were installed through Relution can also be uninstalled through Relution – both .pkg and .dmg apps. This requires a bundle identifier (detection rule) that uniquely addresses the app on the device. Without a valid bundle identifier, no uninstallation is triggered. As with installation, the removal runs over different channels depending on the format – .pkg via MDM, .dmg via the macOS Companion – but the procedure in the portal is identical.

There are two ways to uninstall:

• Specifically via an action: The Remove app action on selected devices or groups uninstalls the app. In the device’s command history, the operation appears as Remove <bundle identifier>.
• Automatically when the assignment no longer applies: If an app that was installed automatically via App compliance (checkbox in the Auto install column) is no longer required after the policy is changed or removed, Relution uninstalls it automatically. Unlike on iOS, the macOS App compliance configuration offers no option to switch this uninstallation off.

Apps without a bundle identifier, as well as apps installed manually – outside of Relution – cannot be removed through Relution. For .dmg apps, the macOS Companion is additionally required; if it is disabled or cannot be used on the device (macOS earlier than version 12, User Enrollment), uninstallation through Relution is not possible. In these cases, the removal is implemented via a script that quits the app and removes the associated directories, distributed specifically to the affected devices or groups via an action.