Overview

This article describes how to distribute software to Mac OS X clients using the Matrix42 Empirum Agent. It covers agent installation methods, the installation dialog (AgentUI), inventory collection, and troubleshooting guidance.

The following functionality is supported:

• Manual installation of the Empirum Agent on a client
• Remote installation of the Empirum Agent via Agent Push (from OS X 10.8)
• Manual check for new software installation jobs by the user
• Display in the menu bar (red = active, grey = inactive)
• Usage of static set names for computers and workgroups — recommended for computers with changing names
• Configurable user request dialog (Z-Dialog) via Agent template
• Protocol failover for SMB and HTTP(S)
• Minimal free disk space enforcement
• Inventory via Empirum Agent (with automatic upload fallback)
• Maximum number of failed installation attempts (configurable in Agent Template)
• Installation and reinstallation triggers inventory
• Respected software package order in DDS
• DHCP Options support
• Reboot options (1 and 5)

The following software distribution command options are supported:

• Install / uninstall of software packages
• Reinstallation with previous uninstallation
• User can postpone / User can postpone n-times
• Cache locally
• Ignore Installation Time Frame

Please refer to the system requirements documentation for currently supported macOS versions.

Installation

Method 1: Agent Push (Remote Installation)

Copy the Mac Package Wizard to a Mac with administrator privileges. Use Finder to open the following share and copy the DMG image to the Mac:

smb://EmpriumServer/Empirum$/AddOns/Mac Package Wizard

Prerequisites for the Target Mac

• An administrative user account (Administrator) or a root account with a non-empty password is required
• The following special characters are not allowed in the administrator password: single quotation marks ('), double quotation marks ("), spaces
• For Mac OS X Server versions, use the Server-Admin account
• Remote Login (SSH) must be activated with at least one administrative user allowed (System Settings > Sharing)
• The NetBIOS name and workgroup in System Settings > Network > [Primary Adapter] > WINS must match the computer name and workgroup name in Empirum
• A working name resolution is required

Prerequisites for Empirum

Create a Mac computer object via one of the following methods:

• Manual setup (operating system: Mac OS X Desktop or Mac OS X Server)
• Inventory via Empirum Inventory Mac (see the Mac OS Inventory Step by Step Guide)

Then configure agent distribution:

• Create and configure an Agent Template
• Assign the Mac computer to a configuration group
• Assign the Agent Template to the configuration group

Push Steps

1. Launch the Matrix42 Management Console and go to Management > Administration.
2. Right-click a Configuration Group, choose New Group, and name it (e.g. Client).
3. Drag and drop a Mac computer from the Apple Macintosh Computers filter to the new group.
4. Drag the previously created Agent Template to the new configuration group.
5. The Empirum-AgentPush service writes the Agent Template assignment to <Computername>.ini.
6. Right-click the computer and select Push Agent. The Empirum Push Wizard opens.
7. Click Add, enter the Username and Password, confirm the password, then click OK.
8. Click Next. Select or deselect computers as needed.
9. Click Push. The Empirum-AgentPush service connects to the target and installs the Mac Empirum Agent.
10. To verify: right-click the computer or configuration group, select Show Log, and click the Agent Push Log tab.

Method 2: Manual Installation

Prerequisites

• An Agent Template with Mac OS compatibility must have been created and assigned to the configuration group
• The Mac Package Wizard app and the EmpirumAgent.pkg package must be available on the administrator Mac

Locate the required files on the Empirum server:

Mac Package Wizard:  \\EmpriumServer\Empirum$\AddOns\Mac Package Wizard
EmpirumAgent (DMG): \\EmpriumServer\Empirum$\Configurator\Packages\matrix42\EmpirumAgent_for_Mac\xx.x\

Manual Installation Steps

1. Use Finder on the administrator Mac to mount: smb://EmpirumServer/Empirum$
2. Mount EmpirumAgent.dmg and drag & drop EmpirumAgent.pkg to the Mac Package Wizard app.
3. When prompted, drag & drop the Agent Template.xml into the respective text field.
4. Optionally include Staticcomputername.plist to set a fixed computer name at first agent start.
5. After packaging, open the resulting package. Mac OS X Agent.dmg is found under <PackageID>/Data.
6. Distribute the DMG to clients (via email, shared folder, etc.).
7. The client mounts the DMG and executes Mac OS X Empirum Agent.pkg from within the mounted DMG.

# Determine workgroup:
system_profiler SPNetworkLocationDataType | grep SMB -A 3 | grep Workgroup | cut -d : -f 2 | sed -e 's/ //g'

# Determine NetBIOS name:
system_profiler SPNetworkLocationDataType | grep SMB -A 3 | grep NetBIOSName | cut -d : -f 2 | sed -e 's/ //g'

# View current settings:
less /Library/Preferences/SystemConfiguration/com.apple.smb.server.plist

Method 3: Installation via Silverback

Requirements

• macOS EmpirumAgent 2009.0 or newer
• Silverback 20.0.2 or newer

Obtain the installer package from the Marketplace. You also need a Silverback configuration file that enables the initial server connection. If a defaultAgentConfig.xml exists on the server, or an agent template is assigned to the client, the corresponding template is downloaded and applied automatically after installation.

Silverback Configuration File Structure

<dict>
    <key>CommonParameters</key>
    <dict>
        <key>Servername</key>
        <string>{FallbackServer}</string>
        <key>Username</key>
        <string>{Username}</string>
        <key>Password</key>
        <string>{Encrypted Password}</string>
    </dict>
    <key>Protocols</key>
    <array>
        <dict>
            <key>Type</key>
            <string>{ProtocolType}</string>
            <key>Servername</key>
            <string>{Servername}</string>
            <key>Port</key>
            <string>{Port for http(s)}</string>
        </dict>
    </array>
</dict>

Allowed values for ProtocolType: SMB, HTTP, HTTPS

Installation Dialog (AgentUI)

The Mac Empirum Agent can display a user installation request dialog (Z-Dialog). Configure this in the EMC under Configuration > Empirum Agent > Agent UI > User Installation Request Interface (Z-Dialog).

Supported Settings

• Display installation request interface
• Default dialog behavior: Always enforce / User interaction possible
• Close installation request after <x> seconds
• Install automatically after timeout

Dialog Display

The installation dialog shows:

• A table of pending actions (package icon, name, version, planned action, status)
• A countdown until automatic execution or automatic postponement
• Time until the next polling
• Remaining installation duration
• Remaining number of postponements (if applicable)

Each package displays one of five statuses:

Limiting Postponements

Use the distribution option User can postpone n-times to control user deferral:

• Option not set → user cannot postpone
• Option set without a value → user can postpone without limit
• Option set with a value → user can postpone up to that number of times

Reboot Option

If #Reboot=1 or #Reboot=5 is set in the package's setup.sh, the agent interprets it and reboots in combination with the Agent Template settings. The reboot can occur immediately or after user confirmation.

Inventory

The UEM Agent includes an embedded hardware and software inventory that collects data once a day. The data transfer to the server is initiated by the UEM Agent independently of the Empirum Inventory configuration. The embedded inventory uses the default EmpInvScan_MACOSX.xml file, which is read from the User share as configured in Empirum.

For more details on the Empirum Inventory for macOS review the dedicated article.

The EmpirumAgentInventory.app is located at:

/Library/Application Support/matrix42/EmpirumAgent/

To troubleshoot inventory operations, filter Console.app by Inventory.

Initial Inventory

Upon installation, the agent automatically performs an initial inventory and uploads the result file to the EmpInv$ directory specified in the Agent Template. Protocol failover is also applied.

Manual Inventory

From the GUI Agent menu, select Start Inventory. The result file is uploaded immediately using the agent's connection settings.

Daily Inventory

The agent inventories the system once per day at the first polling after midnight (0:00). For example, if the last inventory ran at 23:59, a new one is triggered at the next polling after 0:00.

Troubleshooting

Troubleshooting Tools

Key Directories and Files

Cache directory: /Library/Caches/EmpirumAgent/

• DDS
• DDC
• User
• Values
• Log
• Packages

Agent configuration files: /Library/Application Support/Matrix42/Empirum/

• AgentConfig.xml
• package.plist — local installation database
• NotificationDataStore.plist — information database for the GUIAgent
• MX42Database.plist — persistent state across restarts (last inventory date, last status log date)
• installedpackages.txt — must be updated manually if a package is removed outside of Empirum

Agent binaries: /Library/Application Support/Matrix42/EmpirumAgent/

Collecting Support Information

Users can collect all relevant logs as a ZIP archive on their Desktop:

1. Click the Agent symbol in the macOS menu bar
2. Select Save Support Information

The agent saves a ZIP archive with all relevant logs to the user's Desktop.

Removing the Empirum Agent Manually

Use the Uninstall.sh script from the DMG (run with administrative permissions). Alternatively, run the following commands in Terminal:

sudo launchctl unload /Library/LaunchAgents/com.Matrix42.GUIAgent.plist
sudo rm -f /Library/LaunchAgents/com.Matrix42.GUIAgent.plist
sudo launchctl unload /Library/LaunchDaemons/com.Matrix42.EmpirumD.plist
sudo rm -f /Library/LaunchDaemons/com.Matrix42.EmpirumD.plist
sudo rm -fR /Library/Application\ Support/matrix42/Empirum
sudo rm -fR /Library/Caches/EmpirumAgent
sudo rm -fR /Library/Application\ Support/matrix42/EmpirumAgent

Software Distribution Packages

Package software into a DMG image to avoid file structure corruption. DMG images can be created with the Apple Disk Utility.

Agent Connection Status

A grey icon in the menu bar means software distribution cannot be performed. Common causes:

• Incorrect credentials (username or password)
• Wrong server address
• Invalid server certificate (HTTPS)
• System not connected to the network

For detailed diagnostics, open Console.app, select system.log, and filter by Empirum Agent Transport.

Software Distribution Issues

If the agent is not installing software, check the following in order:

1. Confirm the agent icon is not grey (connection issue). If grey, see Agent Connection Status.
2. Use Activity Monitor to confirm EmpirumAgent is running (select All Processes).
3. Open Console.app and filter by Empirum Agent. Look for these error patterns:

[Configuration] Error Download of required files failed.
[Configuration] DDC        ← 0 = failed, 1 = success
[Configuration] DDS
[Configuration] INI
[Configuration] Mac.Inc.sh
[Configuration] AgentTemplate

If the DDC value is 0, check whether the system is activated in the EMC and whether the files are present in the server directories.

Additional checks:

• Package not flagged for OS: Log entry: [Installation] Warning: Software package SOFTWAREPACKAGE is not for clients of this OS X version
• Package download failed: Check whether the package exists under /Library/Caches/EmpirumAgent/Packages after polling, and verify the DMG structure on the server.
• Package already installed at same version: The agent skips installation if version/revision is unchanged. Create a new package with an updated version to trigger reinstallation.
• Manually removed package: Delete the corresponding entry from /Library/Application Support/Matrix42/Empirum/installedpackages.txt to restore consistency.

Do Not Disturb Behavior

When macOS Do Not Disturb is active:

• If Postpone automatically is enabled, the EMC log shows: Postponed: Do not disturb active
• Postponement counters are decremented even during Do Not Disturb, but no software is installed
• If the user has disabled Empirum Agent notifications in System Settings > Notifications, the EMC log shows: Postponed by user — enable Install automatically or disable Display installation request interface to ensure installation proceeds
• If Ignore Installation Time Frame is set for a package, all pending actions execute regardless of Do Not Disturb

macOS 10.15 Catalina and Later: Full Disk Access

Since macOS 10.15 Catalina, Apple requires explicit Full Disk Access for the Empirum Agent when using SMB transport:

1. Go to System Settings > Security > Data Protection > Full Disk Access
2. Click the + button
3. Navigate to /Library/Application Support/matrix42/EmpirumAgent and add EmpirumAgent.app
4. Restart the agent