Overview

Matrix42 macOS Inventory provides full support for inventorying Apple Mac systems. It is easy to create various configurations and installation packages to distribute to and install on Mac systems. Inventory can be initiated on a scheduled basis or at each user login.

The solution focuses on core data collection and seamless integration into the Apple ecosystem. Installations are performed via native macOS packages, and data is transferred via SMB or HTTP(S).

Prerequisites

• Refer to the Matrix42 system requirements for currently supported macOS versions
• A Mac computer is required to create the installation packages

Used Components

Configuration and Distribution

Creating an Inventory Configuration (EMC)

1. Launch the Empirum Management Console (EMC) and go to Configuration > Inventory > Inventory Configuration.
2. Open the EmpInvScan_MACOSX.xml template.
3. Click Properties. Under Client Behavior, enter the Empirum server address (IP address, DNS name, or FQDN) where inventory data should be uploaded.
4. Under Remote Login, enter the Empirum Server that communicates with the inventoried systems and the required login credentials. For domain accounts, use the format domain\username. The password is encrypted and stored in the XML file.
5. Click Configuration… in the Scheduler section to define when automatic inventory scans are performed and transferred to the server.
6. Configure Application Usage Tracking as needed:
   • Track Applications from include list: Includes files entered in the "Include files – AUT" list
   • Make users anonymous: Anonymizes data that could identify specific users
7. Save the configuration. It is stored under Empirum\Configurator\User on the Empirum server.

Server Path Examples

SMB:

Configuration file: \\192.168.100.42\Configurator$\User\EmpInvScan_MACOSX.xml
Output file:        \\192.168.100.42\EmpInv$\#DomainName#.%ComputerName%_#SysTime#.xml

HTTP:

Configuration file: http://server.dom.de:<PORT>/EmpInvScan_MACOSX_http.xml
Output file:        http://server.dom.de:<PORT>/#DomainName#.%ComputerName%_#SysTime#.xml

HTTPS:

Configuration file: https://server.dom.de:<PORT>/EmpInvScan_MACOSX_http.xml
Output file:        https://server.dom.de:<PORT>/#DomainName#.%ComputerName%_#SysTime#.xml

Distribute Mac OS X Inventory via Mac OS X Agent

Prerequisites

• Inventory configuration file (EmpInvScan_MACOSX_http.xml)
• Mac Package Wizard app (found at \\EmpriumServer\Empirum$\AddOns\Mac Package Wizard)
• ShowInventory.dmg (found at \\EmpriumServer\Empirum$\Configurator\Packages\matrix42\InventoryMacOSX\<Version>\)

Steps

1. Install the Mac Package Wizard app on a Mac OS X client.
2. Mount ShowInventory.dmg and drag & drop ShowInventory.pkg onto the Mac Package Wizard app. Follow the on-screen instructions.
3. When prompted, drag & drop EmpInvScan_MACOSX.xml into the respective text field to specify the inventory configuration.
4. After packaging, import the resulting software package into the EMC software depot.
5. Assign the Matrix42 Mac OS X Inventory package to a client or configuration group. The inventory app installs and an inventory runs on the next Empirum Agent polling cycle.

Manual Installation of Mac OS X Inventory

Prerequisites

• Inventory configuration file
• Mac Package Wizard app (found at \\EmpriumServer\Empirum$\AddOns\Mac Package Wizard)
• ShowInventory.dmg (found at \\EmpriumServer\Empirum$\Configurator\Packages\matrix42\InventoryMacOSX\16.0\)

Steps

1. Install the Mac Package Wizard app on a Mac OS X client.
2. Mount ShowInventory.dmg and drag & drop ShowInventory.pkg into the Mac Package Wizard app.
3. When prompted, drag & drop EmpInvScan_MACOSX.xml into the respective text field. To use static computer names, refer to the Static Computer and Domain Names section.
4. After packaging, open the resulting package. Mac OS X Inventory.dmg is found under <PackageID>/Data.
5. Distribute the DMG to clients (via email, shared folder, etc.).
6. On the client: mount the DMG and execute Mac OS X Inventory.pkg from within the mounted DMG. After installation, the system is included in the EMC inventory.

Running Inventory

An inventory scan runs automatically at installation. Subsequent scans follow the configured scheduler. Before each scan, the system checks the server for a more recent configuration file and uses it if found.

It is also possible to launch ShowInventory directly from the Mac's Applications folder. This application displays the collected data in a graphical interface and can save a result file for manual import into the Empirum server.

Technical Details

MX42Inventory.app

Located at: /Library/Application Support/matrix42/Inventory

This app performs an inventory scan and saves the result locally on the Mac without uploading it to the server. To run a manual scan:

1. Ensure the directory /Library/Caches/EmpirumInventory/InventoryReports exists. Create it if needed — this is where the result XML is saved.
2. Launch MX42Inventory.app with a double-click or from the command line:

/Library/Application\ Support/matrix42/Inventory/MX42Inventory.app/Contents/MacOS/MX42Inventory

To produce a compressed (ZIP) result file:

/Library/Application\ Support/matrix42/Inventory/MX42Inventory.app/Contents/MacOS/MX42Inventory ZIP

Filter log output in Console.app using the keyword MX42Inventory.

MX42HelperTool.app

Located at: /Library/Application Support/matrix42/Inventory

This app handles uploading scan result files to the server and manages the inventory schedule.

Upload via the Mac OS X Agent

The Empirum Agent is used as an upload fallback in two cases:

• A configuration file is available but the direct server connection fails
• No configuration file is available at all

Administrators can install Inventory on macOS clients without a configuration file, relying entirely on the agent for uploads.

Static Computer and Domain Names

When switching networks or connecting via VPN, computer and workgroup names on Mac systems can change. This prevents correct identification of the system in Empirum, causing software distribution and inventory issues. Static names resolve this by locking the computer name and workgroup at first run.

The StaticComputername.plist is included in the DMGs of both the EmpirumAgent and ShowInventory, and is used by default for agent push and manual installations.

How It Works

On the first run, the agent or inventory app copies StaticComputername.plist to:

/Library/Application Support/matrix42/Inventory/

It then writes the current computer name and workgroup/domain into the plist. From that point on, all software distribution and inventory operations use these locked values. The file is not modified during updates or reinstallations.

Plist Structure

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>StaticComputername</key>
    <string></string>
    <key>StaticWorkgroup</key>
    <string></string>
</dict>
</plist>

The values can be edited manually or via script. Simply update the two string fields as needed.

Manual Inventory (Command Line)

The inventory can be triggered manually from the command line — useful for scripting or launching from an external source such as a USB stick.

MX42Inventory.app/Contents/MacOS/MX42Inventory [options]

Custom Software Inventory

You can inventory user-defined software packages by placing a shell script in:

/Library/Application Support/matrix42/Inventory/

The script output is interpreted by Inventory and written as a software entry in the result XML.

Script Requirements

• The script filename must begin with CustomInvSoftware
• The script must not produce any output other than the result (no echo for debugging, etc.)
• Output must follow this exact format:

echo "ProductName:Sampleapp; ProductNameShort:Sampleapp; Version:1234; Developer:SampleVendor; InstDate:2020-03-18 12:05:23; Revision:0"

An empty output ensures no package is added to the result XML.

User-Defined Values

The inventory can read out user-defined values configured in the Management Console. These values are always executed as shell commands, so scripts written in a single line are also supported.

Example:

File Search (Filescan)

The file search feature allows inventory to detect software files that are not located in the /Applications directory — including plugins, kernel extensions, system extensions, driver extensions, and other executables.

When a file is found, its metadata (name, manufacturer, version) is read out and written as a software entry in the inventory result file. The following metadata fields can be overridden in the configuration:

• Application name
• Manufacturer
• Version

File size and checksum are not considered.

Example configuration:

The file is searched in the following directories by default:

• /Library/Application Support
• ~/Library/Application Support
• /Library/DriverExtensions
• /Library/Extensions
• /Library/SystemExtensions
• /Library/Frameworks

Additional Information

The Empirum Inventory can collect additional information from a computer, which is displayed in the Empirum Console when viewing the computer's properties.
Empirum supports up to 30 custom information fields. The display names shown in the UI are configured in the General Properties of the Empirum Console.
To populate a custom field locally on a computer, a file named CustomValues.plist must be placed at /Library/Caches/Inventory/Custom on each target computer.
The CustomValues.plist file uses a key-value structure. Only the key CustomXX (where XX is the field number) and its corresponding string value are evaluated by the inventory.

FAQ

Is it possible to perform unscheduled scans?

Yes. Use MX42Inventory.app for a manual scan without upload (see the MX42Inventory.app section above).

To perform a scan with upload: close MX42HelperTool.app. The launchd process will relaunch it and perform a complete inventory including upload to the EMC.

Is it possible to update a configuration without redistributing and reinstalling?

Yes, if a configuration file path is specified in the configuration. Before each scan, the configuration file is copied locally from the server and used for that scan. Note that scheduler settings can only be changed by reinstalling the package.

Is an offline inventory possible?

Yes. Use the manual inventory command line interface described in the Manual Inventory (Command Line) section.