Troubleshooting macOS Management: VMware Workspace ONE Operational Tutorial

Overview

Introduction

VMware provides this operational tutorial to help you with your VMware Workspace ONE® environment. In this tutorial, you learn how to troubleshoot macOS features in a VMware Workspace ONE® UEM environment. Procedures include parsing the Unified Log, validating console settings, and deploying profiles that aid troubleshooting.

This macOS troubleshooting guide provides general troubleshooting guidance, as well as solutions to specific problems for various macOS features in Workspace ONE UEM. The exercises in this tutorial are targeted to those with previous macOS management experience in the Workspace ONE UEM product.

Audience

This operational tutorial is intended for IT professionals and Workspace ONE administrators of existing production environments. Both current and new administrators can benefit from using this tutorial. Knowledge of the following technologies is helpful:

Getting Started with macOS Troubleshooting

Introduction

This section contains a checklist for common troubleshooting scenarios and helpful background information. For more detailed troubleshooting guidance, skip this section and go straight to the other sections in this tutorial, which walk through each troubleshooting scenario step-by-step.

Using the macOS Troubleshooting Cheat Sheet

The macOS troubleshooting tips contained within this tutorial cover potential issues that might affect macOS management. If you prefer a paper format to keep at your desk, click the More button on the top menu and download the linked PDF.

Client-Side Components

Workspace ONE uses multiple components to create the entire macOS management stack. Some of these components are supplied by Apple, whereas others are value-added functionality included with your Workspace ONE licensing. With regards to components installed and running on macOS, review the following table:

Client Component Use(s)
mdmclient (process) Native MDM client running in root (daemon) and user (agent). Responsible for enacting any functionality defined in the MDM specification: profiles, apps, enrollment, and so on. Workspace ONE communicates to these two processes via Apple Push Notification Services (APNS).
dasd Duet Activity Scheduler daemon. This process monitors system health and can sometimes interrupt/delay normal activity and service startup. In some cases, this can affect things such as out-of-box enrollment.
storedownloadd (macOS before Big Sur) App Store Download Daemon. Responsible for downloading apps from the app store (for example, volume-purchased apps) and bootstrap packages.
appstored (macOS Big Sur and later) App Store download daemon. Responsible for downloading apps from the app store (for example, volume-purchased apps) and bootstrap packages.
Workspace ONE Intelligent Hub for macOS Used for value-add functionality with profiles and configuration, employee experience, and internal apps. Workspace ONE communicates with Intelligent Hub using AirWatch Cloud Messaging (AWCM).
Workspace ONE Assist Client Allows for remote control, file management, and running remote shell commands from Workspace ONE. Communicates outbound to the Workspace ONE Remote Management server and AWCM.
Unified Logging Most processes within macOS no longer write to system.log. Rather, they write to a binary file which must be queried and exported as human-readable text using command line tools. Successful troubleshooting requires proficient knowledge of how to search the unified log (which is covered in this tutorial).

Server-Side Components

macOS management in Workspace ONE makes use of numerous server/cloud-based components. It is critical to ensure that macOS has network connectivity to each of these components, as specified in the following lists of network requirements:

Remember, many of these network requirements point to DNS names, which are part of global load balancing systems. It is highly recommended that you ensure firewall rules match the network requirements exactly. Do not substitute IP addresses where DNS names are specified because this can cause troubleshooting issues at a later stage as the load-balanced services move to different IP addresses.

Understanding the Workspace ONE UEM Solution Stack

macOS Solution Stack diagram to help troubleshoot macs.

There are many communication methods and clients used to manage macOS devices. This section explores management services and clients in detail. It is important to understand these components before proceeding.

Management Services

In Workspace ONE, the entire possibility of macOS management takes place in multiple systems. Some systems include:

  • APNS (Apple Push Notification service) and AWCM (AirWatch Cloud Messaging) for realtime device notifications.
  • Workspace ONE UEM (which includes the console, device services, and API servers) for device management.
  • Workspace ONE Assist for remote control (for example, helpdesk support).
  • Workspace ONE Access and Hub Services for employee experience, single sign-on, and conditional access.
  • Workspace ONE Intelligence for reporting and automation (including partner ecosystems).
  • Carbon Black for endpoint security monitoring, quarantine, and remediation.
  • Horizon for enabling the "Mac App Gap" or Windows-based applications which need to be accessed and used by macOS users.

Management Clients

Clients communicate to Workspace ONE UEM on behalf of the device. The following components are the primary list of clients you must manage on a device as you adopt the entire solution stack:

  • mdmclient - the built-in device management client which is part of macOS.
  • Workspace ONE Intelligent Hub - the agent which communicates to Workspace ONE UEM and Hub Services to augment device management value-added functionality, the upcoming system extension for process blocking, the unified catalog, and employee experience features.
  • Assist Client - the client which facilitates remote troubleshooting sessions (remote control, remote file, and remote terminal).
  • Carbon Black Sensor - the client which provides next-generation anti-virus and anti-malware protection.
  • Horizon Client - the client which provides access to remote datacenter-hosted applications from macOS.

Validating Workspace ONE UEM Console Settings

When configuring and managing Workspace ONE, some common misconfigurations can happen accidentally. This chapter provides a quick reference on where to find these common misconfigurations and how to correct them if necessary.

1. Network Settings

Network connectivity is a common issue and should be verified. Mac management with Workspace ONE requires network connectivity to a number of endpoints at a number of vendors:  Apple, VMware, Akamai, and more (depending on your particular situation). Managing a table of these endpoints in a cheat sheet would be unruly and difficult to continually manage, so instead, we have included pointers to the full list of required DNS and port names:

2. System Statuses

Use the following links to quickly verify if there are any known, reported outages at Apple or VMware:

3. Common Configuration Issues

Managing macOS requires regular maintenance, just as expected with other platforms. The following list highlights the most common configuration issues that can arise when managing devices.  

  1. If you have trouble deploying newly purchased volume licenses to machines, or devices are not proceeding through Automated Enrollment, check the following:
    1. Has Apple released new Terms of Use that must be accepted by an administrator in Apple Business Manager (or Apple School Manager)?
      See Updated Terms and Conditions for Apple Business Manager.
    2. Has the sToken for the Apple Business Manager location expired?
      Navigate to Groups & Settings > Configurations > VPP Managed Distribution and check the Valid Until date and time. If expired, click the Renew button and follow the process.
  2. If devices are not checking in for commands in a reasonable amount of time:
    1. Check the APNS Certificate Expiration Date: Navigate to Groups & Settings > Configurations > APNS for MDM and check the Valid To date. If expired, you must log in to the Apple Push Certificates portal and Renew the existing certificate.

      Caution: If you replace the certificate instead of renewing it, Workspace ONE will lose connectivity with your devices and you will be required to re-enroll those devices.

    2. Check the device-side APNS status - open Terminal.app and enter the following command: /System/Library/PrivateFrameworks/ApplePushService.framework/apsctl status
    3. Check for AWCM connectivity.  
      1. Navigate to Groups & Settings > All Settings > System > Advanced > Site URLs. Scroll down to find the AWCM Server External Hostname and then append /awcm/status to the end.
        For example, https://awcm1380.awmdm.com/awcm/status. AWCM should return OK.    
      2. In the Device Details view, ensure that the specific device in question shows AWCM Connected.

 

Getting Started with macOS Log Collection

Collecting macOS Intelligent Hub Logs

Determining the root cause is a logical first step in troubleshooting. To diagnose, it is helpful to know where to look and which logs to examine.   

For reference, most file-based troubleshooting information is found in the following files within hub logs:

  • install.log - log file generated by the built-in macOS installer process.
  • hublogs.log - Console logs related to Intelligent Hub processes and mdmclient.
  • ManagedSoftwareUpdate.log - log generated by Intelligent Hub components during Internal Application management.

1. Request Hub Logs From the Workspace ONE Console

Request Hub logs from Workspace ONE admin console to troubleshoot macs.

Workspace ONE administrators can request the Intelligent Hub to gather historical logging and deliver those logs to the Workspace ONE UEM Console:

  1. On the Device details page, click More Actions.
  2. Click Request Device Log.

2. Request Hub Logs Using Hubcli

From within Terminal.app, enter the following command line:  sudo hubcli logs --send --duration 1h

This command tells hub to send diagnostic logs to the UEM console for the past 1 hour.

3. Collect User-Generated Logs

Troubleshoot macs and Debug Session from Intelligent Hub.

End users can also generate and send logs to the Workspace ONE UEM console by using the Collect & Send Logs feature.  

Launch the Intelligent Hub:

  1. Click Help
  2. Optionally, click Debug Session > Start Session to start a debug session (verbose logging). Clicking the same path allows the user to End the debugging session prior to the 30 minute default session time.
  3. Click Collect & Send Logs.

4. Download Hub Logs in Device Details

Download Hub logs from Workspace ONE UEM admin console to troubleshoot macs.

After requesting logs from the device, you can view the logs as follows:

  1. Click Devices.
  2. Click the device to enter the Details View.
  3. Select Attachments in the drop-down menu.
  4. Select Documents.
  5. Click the Hub_Complete_Report you want to download and view.

5. Monitor Internal App Logging in Real-Time

If you are troubleshooting an issue with Internal Apps for macOS, you can easily view the logging for that in real-time on your test device (or via remote command line through Workspace ONE Assist). The following command tails the last 25 lines in the ManagedSoftwareUpdate.log file:

tail -n 25 -F /Library/Application\ Support/AirWatch/Data/Munki/Managed\ Installs/Logs/ManagedSoftwareUpdate.log

Understanding macOS Unified Logging

When Apple released macOS Sierra 10.12 in 2016, it introduced a new unified logging concept on macOS.  The unified log replaced traditional Unix-style text-based logs with a single logging mechanism for user and kernel processes. The unified log takes a more developer-focused approach, capturing greater amounts of data in a compressed format in a fashion that is consistent across each Apple OS (macOS, iOS, tvOS, watchOS). The compressed format is no longer human-readable, and instead requires the use of either Console.app or the log and logger command-line utilities to read and write log entries.

When troubleshooting, the log command is the most flexible in that it allows you to gather multiple processes and subsystems simultaneously. Although much of the information required to run the log command can be found in the manual (man log), the following cheat sheet should help get you started quickly.

1. Useful Tips and Tricks to Search Logs

Following are some tips and tricks that can save you time:  

  • The log command requires "straight" quotes and not "curly" quotes. This issue can crop up during copy/paste operations.
  • You can gain additional information by adding the --info and --debug parameters to your log command line.
  • Add --archive system_logs.logarchive to search inside a SysDiagnose logarchive file.
    • Generate a sysdiagnose from the computer in question:   sudo sysdiagnose -f -n ~/Downloads
  • For more in-depth detail, you can install some of the developer debugging profiles from https://developer.apple.com/bug-reporting/profiles-and-logs/

Important: Many details in logging commands are hidden for privacy. Most likely, you will not need to enable this. However, if you intend to enable private data logging, you must send a custom settings profile with the following content (or manually fit this content into a mobileconfig file and install it):

<dict>
    <key>PayloadDisplayName</key>
    <string>Enable Private Log Data</string>
    <key>PayloadEnabled</key>
    <true/>
    <key>PayloadIdentifier</key>
    <string>com.apple.system.logging.348FA5E7-2C81-443F-92BC-8BAF301077D8</string>
    <key>PayloadType</key>
    <string>com.apple.system.logging</string>
    <key>PayloadUUID</key>
    <string>348FA5E7-2C81-443F-92BC-8BAF301077D8</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
    <key>Enable-Private-Data</key>
    <true />
</dict>

2. Predicate-Based Filtering for Log Command

Note the following text on Predicates, clipped from the manual for the log command. Predicates are the building blocks for filtering the Unified Log.  

PREDICATE-BASED FILTERING
     Using predicate-based filters via the --predicate option allows users to
     focus on messages based on the provided filter criteria. For detailed
     information on the use of predicate based filtering, refer to the
     Predicate Programming Guide:
           https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/Predicates/Articles/pSyntax.html

     The filter argument defines one or more pattern clauses following NSPred-
     icate rules. See log help predicates for the full list of supported
     keys. Supported keys include:

     eventType          The type of event: activityCreateEvent, activityTran-
                        sitionEvent, logEvent, signpostEvent, stateEvent,
                        timesyncEvent, traceEvent and userActionEvent.

     eventMessage       The pattern within the message text, or activity name
                        of a log/trace entry.

     messageType        For logEvent and traceEvent, the type of the message
                        itself: default, info, debug, error or fault.

     process            The name of the process the originated the event.

     processImagePath   The full path of the process that originated the
                        event.

     sender             The name of the library, framework, kernel extension,
                        or mach-o image, that originated the event.

     senderImagePath    The full path of the library, framework, kernel exten-
                        sion, or mach-o image, that originated the event.

     subsystem          The subsystem used to log an event.  Only works with
                        log messages generated with os_log(3) APIs.

     category           The category used to log an event.  Only works with
                        log messages generated with os_log(3) APIs.  When cat-
                        egory is used, the subsystem filter should also be
                        provided.

3. Log and Find Troubleshooting Session Time Markers

As you begin to troubleshoot an issue, you can start logging time markers directly into the unified log by using the logger command.  You can then later search for these markers by using the log command. The following represents a way to bookmark the start and end time for troubleshooting activities:

  • Log a marker in Unified Logging for troubleshooting events:   logger "[WS1-Support] Starting <activity>" and logger "[WS1-Support] Ending <activity>"
  • Search for all markers to determine troubleshooting time frames:   log show --predicate 'process=="logger" AND eventMessage CONTAINS "[WS1-Support]"'

With the list of times for troubleshooting activities output by the log command, you can later filter for events constrained to those time frames by using the --start "YYYY-MM-DD HH:MM:SS" --end "YYYY-MM-DD HH:MM:SS" parameters on your log commands.

4. Example Commands to Get You Started

  • Find any Logging Markers for the past 12 hours in a SysDiagnose:   log show --archive ~/Downloads/sysdiagnose_2020.10.06_00-55-25-0400_Mac-OS-X_iMacPro1-1_19G73/system_logs.logarchive  --predicate 'process=="logger" AND eventMessage CONTAINS "[WS1-Support]"' --last 12h
  • Filter for Events in Specific Time Slots (Based On Your Markers):   log show --archive ~/Downloads/sysdiagnose_2020.10.06_00-55-25-0400_Mac-OS-X_iMacPro1-1_19G73/system_logs.logarchive  --predicate 'process == "mdmclient" OR process == "apsd" OR process == "dasd" OR process == "storedownloadd" OR process == "appstored" OR process == "logger"' --start "2020-10-06 00:47:00" --end "2020-10-06 00:48:49"

Troubleshooting macOS Management

Troubleshooting macOS Enrollment

This section covers potential troubleshooting items related to macOS enrollment.  

1. Enrollment Restrictions

In Workspace ONE UEM, navigate to Groups & Settings > All Settings > Devices & Users > General > Enrollment > Restrictions and ensure that no device restrictions are in place that might be preventing enrollment.

2. Registered Devices Only

In Workspace ONE UEM, navigate to Groups & Settings > All Settings > Devices & Users > General > Enrollment > Authentication and check the Devices Enrollment Mode option. If set to Registered Devices Only, then the device must be registered in the console before it can be enrolled.

Note: macOS devices synced from Apple Business Manager (or Apple School Manager) are considered Registered and can be enrolled.

3. Device Previously Enrolled

Apple Business Manager devices that have already been enrolled cannot re-enroll without first deleting the device record in Workspace ONE UEM.  

4. Enroll Virtual Machines

When attempting to enroll a macOS virtual machine, you may notice that the enrollment fails and/or the enrollment profile generated appears to be for iOS. This is because the virtual machine must emulate physical hardware attributes in order for Workspace ONE to generate the proper enrollment profile.  

To get the necessary hardware attributes, you should run the following commands on the hardware you want to emulate:

  • Hardware Model:  ioreg -l | awk '/product-name/ { split($0, line, "\""); printf("%s\n", line[4]); }'
  • Serial Number:  ioreg -l | awk '/IOPlatformSerialNumber/ { split($0, line, "\""); printf("%s\n", line[4]); }'
  • Board-ID:  ioreg -lp IOService | awk '/board-id/ { split($0, line, "\""); printf("%s\n", line[4]); }'

Using VMware Fusion, you should enter or modify the following items in the VMX file for your virtual machine:

Note: If the VM does not boot, you might have duplicated one of the options (typically the smbios.reflectHost).

board-id.reflectHost = "FALSE"
board-id = "MAC-F22589C8"
hw.model.reflectHost = "FALSE"
hw.model = "MacBookPro6,2"
serialNumber.reflectHost = "FALSE"
serialNumber = "RM129481AGW"
smbios.reflectHost = "FALSE"

5. Date & Time Zone Incorrect

From within Terminal.app, you can enter the following commands to get date and time zone information quickly:

  • Date:  date
  • Time Zone:  sudo systemsetup -gettimezone

If the date/time/zone is incorrectly set, then you will potentially have problems with certificate checking, trust, and more.

6. Obtain Shell and Console During Setup Assistant

One method of troubleshooting during automated enrollment is to obtain console and shell access during the Setup Assistant. Although your options are limited due to the current user context, it is still useful to know these commands:

  • Press Command + Option + Control + T during Setup Assistant to open Terminal.
  • Press Command + Option + Control + C during Setup Assistant to open Console.

7. Ensure Correct Automated Enrollment Profile

If you are not seeing the expected behavior during automated enrollment, you can check the settings currently assigned to the device and optionally re-assign a new automated enrollment profile. See the following:

  • Check if enrolled via Automated Enrollment:  /usr/bin/profiles status -type enrollment
  • Check the current settings applied via Automated Enrollment:  sudo /usr/bin/profiles show --type enrollment
  • Download a new Automated Enrollment profile:  sudo /usr/bin/profiles renew -type enrollment

8. Ensure Correct Staging for Multiple Users

macOS is inherently a multi-user operating system. However, the mdmclient processes that provide the foundational management capabilities for MDM are not. When macOS is not staged properly for multiple users, you might notice that one user will get BOTH device and user profiles, whereas subsequent users are not delivered any user profiles from Workspace ONE. This behavior is a function of the mdmclient built-in to macOS and can be altered only by a specific set of configurations.

To enable multi-user functionality for macOS and Workspace ONE, the device should be enrolled using multi-user staging and then bound to Active Directory.  

For more details, review the staging configuration & enrollment process: Tech Zone Onboarding Options for macOS Tutorial.

9. Check Logging

If all else fails, start collecting log information using the command line. The following command extracts relevant detail from the Unified Log:

  • log stream --predicate 'process == "mdmclient" OR process == "apsd" OR process == "dasd"'

Additionally, if you gather a sysdiagnose file (as outlined in Understanding macOS Unified Logging), you can filter using the --archive and --last parameters to narrow down the issue.

Troubleshooting macOS Profiles

Profiles provide the most basic building blocks for macOS management in Workspace ONE. Apple defines much of the profile content in the Developer Reference for Device Management. Apple also provides an MDM for IT Administrators guide that helps admins understand the base management capabilities in all the Apple operating systems.  

This section of this tutorial aims to help you troubleshoot profile-related issues.

1. No User Profiles (Only Device Profiles)

This is most likely not a profile issue, but rather an enrollment issue. Generally, this behavior indicates that a device was improperly staged—check the staging configuration & enrollment process: Tech Zone Onboarding Options for macOS Tutorial.

Note: Multi-user macOS management requires multi-user staging and Active Directory binding.

2. No User or Device Profiles

If there are no profiles (user or device) in your environment, verify the following.

  1. Check that the device gets push notifications by attempting to send one via the console.
  2. Check that the APNs certificate is still valid as described in Validating Workspace ONE UEM Console Settings.
  3. Check Network Connectivity to APNS and AWCM
  4. Check the Event Log by browsing to Devices > List View > Select the Device (switch to Device Details View) > More > Troubleshooting and review the Event Log and Command Queue.
    Reminder: The content of these views can be filtered.
  5. Check Logging (using Terminal or a SysDiagnose file) as follows:
    1. sysdiagnose:   sudo sysdiagnose -f -n ~/Downloads
    2. Log Streaming:   log stream --predicate 'process == "mdmclient" OR process == "apsd" OR process == "dasd"'

3. Troubleshoot the Privacy Preferences Profile:

To troubleshoot the Privacy Preferences (or TCC or PPPC) behavior on macOS, you must stream all events related to Privacy Preference Policy Control prompts:

  • log stream --debug --predicate 'subsystem == "com.apple.TCC" AND eventMessage BEGINSWITH "AttributionChain"'
  • log stream --debug --predicate 'subsystem == "com.apple.TCC" AND eventMessage BEGINSWITH "AttributionChain" OR eventMessage CONTAINS "synchronous to com.apple.tccd.system"'

You can also read the TCC Databases using Terminal.app. Before attempting to manually review these files, ensure that Terminal.app is granted full control by MDM or manually in System Preferences. After granting permissions, run the following commands:

  • echo ".dump" | sudo sqlite3 /Library/Application\ Support/com.apple.TCC/TCC.db
  • echo ".dump" | sudo sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db

Troubleshooting macOS Bootstrap Packages

This section covers common troubleshooting steps for macOS Bootstrap Packages.

1. Bootstrap Package Troubleshooting

A bootstrap package is a lightweight distribution package created by a Workspace ONE administrator. The intent of a bootstrap package is to silently deliver and install a small baseline set of agents to onboard macOS for a user. For example, an administrator can use the bootstrap package to install a distribution package containing the chef, puppet, or saltstack agents.    

Note: Bootstrap Packages install through the InstallEnterpriseApplication command during the Await Configuration phase of device enrollment. Because of this, there is no confirmation of a successful install, other than to audit the ApplicationList sample that the device returns later on.  

The following outlines some potential fixes for Bootstrap packages:

  1. Is the package fairly small in size?
    It is best practice is to keep the bootstrap package as small as possible so that it installs quickly.
  2. Is the bootstrap package a signed Distribution type package?
    1. The package must be signed with an Apple Developer ID Installer Certificate. Only the package needs to be signed, not the app because the Apple Gatekeeper does not check apps installed through MDM.
    2. The package must be a distribution package (product archive), not a flat component package.
  3. Is Workspace ONE configured to attempt installing the Intelligent Hub also?
    Navigate to Devices > Devices Settings > Apple > Apple macOS > Intelligent Hub Settings. Some older versions of macOS could not install two bootstrap packages simultaneously—In this situation, all bootstrap packages would fail to install on the device. If the Install Hub After Enrollment switch is set to Enabled, try setting it to Disabled.    

Volume Purchase App Troubleshooting

As organizations deliver volume-purchased apps from Apple Business Manager, some unexpected issues may arise. This article addresses some common issues affecting volume-purchased app delivery.

1. Newly Purchased Apps Not Syncing to Workspace ONE UEM

This error is typically the result of one of the following issues:

  • Delays in Apple Business Manager from when you purchase the app to when the licenses are allocated to the Location Token.
  • Apple has released new Terms & Conditions in Apple Business Manager. 
    • To resume syncing, log in to Apple Business Manager with an account granted the Administrator role, and accept the updated Terms & Conditions.
  • The location token downloaded from Apple Business Manager and uploaded to Workspace ONE UEM has expired. 
    • Download a new server token from Apple Business Manager (under Settings > Apps & Books) and upload it to Workspace ONE UEM.

2. Device-Based Licensed Apps Not Installing

If you have assigned an app to a device using device-based assignment, one of the following could be an issue:

  • If the user is getting a prompt to log in with an Apple ID, there is most likely an assignment that was made to the user before the device-based assignment was created. 
    • Unassign the app from the user completely before you attempt to reassign the app to the device.
  • Ensure that an adequate number of licenses are available to assign to the device.
  • Ensure that the device has access to vpp.itunes.apple.com.
  • The location token downloaded from Apple Business Manager and uploaded to Workspace ONE UEM has expired. 
    • Download a new server token from Apple Business Manager (under Settings > Apps & Books) and upload it to Workspace ONE UEM.

3. Volume-Purchased Apps Not Removing from macOS

When a VPP app for macOS is no longer scoped to the device or user, or the device is enterprise wiped, the app is not removed from macOS. This is by design in macOS versions prior to macOS 11 (Big Sur), as these earlier versions of macOS did not support any commands to remove the application.

For More Information on Troubleshooting

If you are still experiencing issues with volume-purchased applications, refer to the Volume Purchase Program (VPP) Troubleshooting Guide or contact VMware support directly.

Introduction to Troubleshooting Non-Store Apps

Non-store macOS applications are delivered from Workspace ONE UEM by the Workspace ONE Intelligent Hub. As such, there are some basic prerequisites for macOS software delivery to work. If the prerequisites are not met, there might be unexpected behavior due to the specific installer package that must be worked around.

1. Prerequisites

Non-store macOS apps require the following to work correctly:

Note: AWCM provides notifications to the Intelligent Hub to trigger real-time non-store app installation. In the absence of AWCM, the Intelligent Hub reverts to a scheduled interval to check for new app installation commands.

Determining When to Install Non-Store Apps

When determining whether to install a non-store macOS application, Workspace ONE uses the following information from the manifest PLIST (or the configuration in the console).

Note: The Install Check Script and Installs Arrays are the most flexible methods for determining installation status.

1. Install Check Script

Whether entered in the Scripts tab in the console or entered manually in the PLIST file, the script should exit with a zero (0) return code to trigger an install. The script should include a shebang statement (such as #!/bin/zsh) at the beginning.

2. Installs Array

This key-value pair in the PLIST file specifies identifying information about a binary or file which should be directly compared to determine if the correct version of an app is installed. The installs list can contain any number of items. These can be applications, Preference Panes, Frameworks, or other bundle-style items, Info.plists, or simple directories or files. For more information, see How Munki Decides What Needs To Be Installed.

3. Receipts Array

When a package is installed, the installer leaves a receipt and bill of materials file on the machine. Some packages parsed by the Workspace ONE Admin Assistant will include detail on what receipts will be dropped by the installer in the PLIST file. When a PLIST file lacks the install check script or installs array, the lack of specified receipt(s) triggers an install. For more information, see How Munki Decides What Needs To Be Installed.

 

Troubleshooting Non-Store App Installer Problems

This section lists some of the common problems you might encounter when installing a non-store macOS app.

1. Incorrect Application Name in the Application Catalog

Sometimes an installer package parsed by the VMware Workspace ONE Admin Assistant generates a PLIST file where the application name is incorrect. It is also possible that organizations refer to software by a common or colloquial name that is easily recognized by end users. In either case, administrators can change the name displayed in the Intelligent Hub application catalog before uploading the PLIST to Workspace ONE UEM.

1.1. Open the PLIST Generated by Admin Assistant

Open With
  1. In Finder, browse to the PLIST file for the app in question (usually in ~/Documents/Workspace ONE Admin Assistant/<app name>-<version> ).  
  2. Right-click the PLIST file and select Open With and then select an editor (such as BBEdit).

1.2. Modify PLIST File

Modify the string value for the name key-value pair.  

2. Installers with No Package Version

Sometimes an installer package parsed by the VMware Workspace ONE Admin Assistant generates a PLIST file where the version shows Please Edit Me. This problem must be fixed before uploading the PLIST to Workspace ONE UEM.

2.1. Open the PLIST Generated by Admin Assistant

Open With
  1. In Finder, browse to the PLIST file for the app in question (usually in ~/Documents/Workspace ONE Admin Assistant/<app name>-<version> ).  
  2. Right-click the PLIST file and select Open With and then select an editor (such as BBEdit).

2.2. Modify Plist File

Modify the string value for the version key-value pair.  

3. Installers Requiring Configuration Files

Rather than reading configuration data from CFPreferences or NSUserDefaults (which can be managed by profiles), some installers look for configuration information in specific, hardcoded file locations to pre-configure the software for the end user. This section shows how you can accomodate this scenario in Workspace ONE UEM.

3.1. Option 1: Create a Pre-Install Script

Use a Pre-Install script to create the file and populate the contents of that file dynamically. This method eliminates the need to repackaging software to include the configuration file. In the following example script, edit the following:

  1. PATH string.
  2. The ini or xml file name in lines 4 through 6.
  3. The file contents (between the EOM lines).
#!/bin/sh
PATH="/tmp/your-app"
/bin/mkdir -p "$PATH"
/usr/bin/touch "$PATH/cfg.ini"
/bin/chmod 644 "$PATH/cfg.ini"
/bin/cat > "$PATH/cfg.ini" <<- EOM
[customer]
Code=COMPANY_CODE
EOM

3.2. Option 2: Use Items_To_Copy Array

For DMG-style installers that use scripts with hard-coded paths, use the items_to_copy array in the PLIST. To make this work, you must include the following XML content in the PLIST and make the following modifications:

  1. Include the destination directory where you want to copy the files from the mounted DMG (basically, a staging area on the file system).
  2. Include the mode value to set permissions on the copied file.
  3. Include the source item on the mounted DMG.
    Note: You might need to include folder structures if the item is in a subfolder on the mounted DMG.
<key>installer_type</key>
<string>copy_from_dmg</string>
<key>items_to_copy</key>
<array>
    <dict>
        <key>destination_path</key>
        <string>/tmp/</string>
        <key>mode</key>
        <string>644</string>
        <key>source_item</key>
        <string>Installer.pkg</string>
    </dict>
    <dict>
        <key>destination_path</key>
        <string>/tmp/</string>
        <key>mode</key>
        <string>755</string>
        <key>source_item</key>
        <string>scripts/install_unattended.sh</string>
    </dict>
</array>

Troubleshooting Per-App Tunnel on macOS

If a Per-App Tunnel problem occurs on macOS, there are a number of places to troubleshoot. This section of the tutorial covers where to troubleshoot on macOS at a high level. Depending on the problem, there might be steps that should be performed on the Unified Access Gateway. However, troubleshooting the Unified Access Gateway is outside the scope of this tutorial. Workspace ONE UEM administrators should contact VMware Support for assistance when troubleshooting Per-App Tunnel, Workspace ONE Tunnel, or the Unified Access Gateway.

This section covers a high-level set of initial troubleshooting steps.

1. Open Workspace ONE Tunnel

Troubleshoot macs and Workspace ONE Tunnel on mac os.
  1. Click the Launchpad on the Dock.
  2. Click VMware Tunnel.

2. Ensure Tunnel is Configured

Confirm Workspace ONE Tunnel macOS application is configured to troubleshoot macs.
  1. Ensure that the Device Configured status shows Configured. This indicates that Workspace ONE Tunnel has received configuration data from Workspace ONE UEM. If the status is not configured, try one of the following:
    • Check the Device Traffic Rules and Save and Publish the rules again.
    • Check the last seen value for the device in the Workspace ONE UEM console. Is the device communicating with Workspace ONE UEM?
    • Validate that other MDM commands are being sent to the device. Create an assignment (smart) group containing the single device and attempt to send it a new profile payload.
  2. Ensure that the Internet status shows Connected. If Tunnel cannot connect to the Internet, it probably cannot connect to the Unified Access Gateway.
    • Validate that the device has a working Ethernet or Wi-Fi connection (IP address, subnet mask, gateway, and DNS addresses are present).
    • Validate DNS resolution: Open Terminal and enter nslookup uag.fully.qualified.domain to ensure that an IP address is resolved.
    • Validate Connectivity to UAG: Within Terminal, enter nc -vz uag.fully.qualified.domain uagport (such as nc -vz uag.company.com 443).
  3. Ensure that the Enterprise Network status shows ConnectedIf Workspace ONE Tunnel is disconnected from the Enterprise network, apps cannot use Per-App Tunnel. This might indicate an issue with Workspace ONE Tunnel connecting to the Unified Access Gateway or an issue with Device Traffic Rules.
    • The remainder of this section details how to troubleshoot Tunnel connectivity.

3. Validate Per-App VPN Profile

Validate per-app VPN profiles to troubleshoot macs.
  1. Click System Preferences.
  2. Double-click Profiles.
  3. Scroll through the left panel.
  4. Click the Per-App VPN profile that was created.
  5. Ensure that the VPN App Layer Service details are correct, especially the VPN Remote Address and the OnDemand Enabled value.
    • If the profile is missing or misconfigured, check the profile configuration and re-push the profile to the device from within the UEM Console Device Details view (on the Profiles tab).

4. Validate Advanced Tunnel Information

LC-DEP-MBP-8G8WM-10.15.1
  1. Open the Workspace ONE Tunnel client and click the VMware Tunnel menu.
  2. Click Whitelisted Applications.
  3. Verify that the list of allowlisted applications matches the settings configured in the Device Traffic Rules.
  4. From the VMware Tunnel menu (#1), click Diagnostics.
  5. Click Enable Debug to get verbose information.
  6. Review Diagnostics information.
  7. Click Disable Debug when troubleshooting is complete.

Troubleshooting SSO Extensions

SSO Extensions are still a relatively new concept with not many vendors publishing SSO Extensions for macOS as of today. If you do start beta testing an extension, here's a quick list of possible troubleshooting steps to help determine issues.

1. Logging Commands

As you troubleshoot the SSO extensions, the following command line will stream all Events related to the Kerberos SSO Extension and additional Apple-built SSO Extension binaries. If you are using an SSO extension from another identity provider (such as Okta or Azure Active Directory), you must also add the appropriate predicate parameters in the following command:

  • log stream --debug --predicate '(subsystem == "com.apple.Heimdal") OR (subsystem == "com.apple.AppSSO") OR (subsystem == "org.h5l.gss") OR (subsystem == "com.apple.network")'

2. Other Command Line Tools

  1. Show all shared web credentials associated with any apps using AASA or SSO Extensions:
    • /System/Library/PrivateFrameworks/SharedWebCredentials.framework/Support/swcutil show
  2. Determine if SSO Extension is loaded:  
    • pluginkit -vvv -m -i <SSO Extension App ID>

 

Troubleshooting Workspace ONE Assist

VMware provides Workspace ONE Assist to help you remotely support your macOS fleet. To troubleshoot, check the following.

1. Check Prerequisites

Check that the following pre-requisites have been made:

  1. Has the user provided screen recording permissions to the client-side assist app?
  2. Has the Assist client application been downloaded and installed on the Mac which needs remote assistance?

2. Analyze the Logging

From within Terminal.app, run the following command to find out what's going on:

  • log stream --predicate '(process == "tccd" AND eventMessage CONTAINS "com.aetherpal") OR process == "awcmd" OR process == "assistd" OR process == "AssistCore"'

Troubleshooting Intelligent Hub Processes

The Workspace ONE Intelligent Hub for macOS provides a good deal of functionality to augment the built-in mdmclient functionality. This section illustrates a number of methods you can use to troubleshoot Intelligent Hub for macOS.  

Important: The primary method to gather Hub-related logging is to Request Hub Logs from the device.

1. General Log Streaming

Stream events related to Hub,  awcm, Software distribution, and so on. (Internal Apps, NOT VPP)

  • log stream --predicate 'process == "awcmd" OR process == "apsd" OR subsystem BEGINSWITH "com.vmware.hub"'

2. Hub Process Blocking (Currently in Beta - Version 2010)

Stream events related to Hub Process Blocking (System Extension)

  • log stream --debug --predicate 'subsystem == "com.vmware.hub.security" OR process == "com.airwatch.mac.agent.EndpointSecurity" OR process == "hubd" OR process == "IntelligentHubAgent" or process == "endpointsecurityd"'

3. Sensors (Currently in Tech Preview - Version 2010)

If you are troubleshooting sensors with Hub 2010, the following commands are helpful:

  1. View the list of sensors downloaded to Hub:
    • sudo hubcli sensors --list
    • sudo hubcli sensors --list json
  2. Note: Sensors Require a client-side Feature Flag  
    • sudo plutil -insert MacOsSensorsCliListValueFeatureFlag -bool YES /Library/Application\ Support/AirWatch/Data/com.vmware.hub.flags.plist
  3. Trigger a sensor run on-demand:
    • sudo hubcli sensors --trigger <sensor_name>      

Summary and Additional Resources

Conclusion

This operational tutorial provided general troubleshooting guidance and solutions to specific problems for various macOS features in Workspace ONE UEM.

Terminology Used in This Tutorial

The following terms are used in this tutorial:

application store A user interface (UI) framework that provides access to a self-service catalog, public examples of which include the Apple App Store, the Google Play Store, and the Microsoft Store.
auto-enrollment Auto-enrollment simplifies the enrollment process by automatically enrolling registered devices following the Out-of-Box-Experience.
catalog A user interface (UI) that displays a personalized set of virtual desktops and applications to users and administrators. These resources are available to be launched upon selection.
cloud Asset of securely accessed, network-based services and applications. A cloud can also host data storage. Clouds can be private or public, as well as hybrid, which is both private and public.
device enrollment The process of installing the mobile device management agent on an authorized device. This allows access to VMware products with application stores, such as Workspace ONE Access (formerly VMware Identity Manager).
identity provider (IdP) A mechanism used in a single-sign-on (SSO) framework to automatically give a user access to a resource based on their authentication to a different resource.
mobile device management
(MDM) agent
Software installed on an authorized device to monitor, manage, and secure end-user access to enterprise resources.
one-touch login A mechanism that provides single sign-on (SSO) from an authorized device to enterprise resources.
service provider (SP)
A host that offers resources, tools, and applications to users and devices.
virtual desktop The user interface of a virtual machine that is made available to an end user.
virtual machine A software-based computer, running an operating system or application environment, that is located in the data center and backed by the resources of a physical computer.

For more information, see the VMware Glossary.

Additional Resources

For more information about Workspace ONE, explore the VMware Workspace ONE Activity Path. The activity path provides step-by-step guidance to help you level-up in your Workspace ONE knowledge. You will find everything from beginner to advanced curated assets in the form of articles, videos, and labs.

Additionally, you can check out the VMware Workspace ONE and VMware Horizon Reference Architecture which provides a framework and guidance for architecting an integrated digital workspace using VMware Workspace ONE and VMware Horizon. 

 

About the Author

This tutorial was written by:

  • Robert Terakedis, Senior Technical Marketing Manager, End-User-Computing Technical Marketing, VMware

Feedback

The purpose of this tutorial is to assist you. Your feedback is valuable. To comment on this tutorial, contact VMware End-User-Computing Technical Marketing at euc_tech_content_feedback@vmware.com.

Filter Tags

Workspace ONE Workspace ONE UEM Document Operational Tutorial Intermediate macOS Manage