Troubleshooting macOS Update Management in Workspace ONE UEM

During the latter part of last year, we released an update to Workspace ONE UEM that included a new feature for supporting OS updates on macOS devices. The macOS Update Management framework provides organizations with the means to easily identify available macOS updates, and the granular control required for deploying those updates to devices. The new feature has been embraced by customers since its release, but it also has raised some questions, specifically around troubleshooting. In this post, I’ll discuss some basic steps you can use to monitor and troubleshoot updates with macOS Update Management.

Make Sure the Device is Receiving and Responding to Commands

After an update is assigned, Workspace ONE UEM schedules the ScheduleOSUpdate command for the device. However, the command will not be queued until the device responds to a DeviceInformation query, which might not happen immediately depending on your configured device check-in cycle. If you are troubleshooting a device with an assigned update, you can issue a Device Information command from the Workspace ONE UEM console. This will send an immediate DeviceInformation query. You can do this by navigating to Device Details and selecting More Actions → Device Information.

Note: The ScheduleOSUpdate command can only be issued once in a 24-hour cycle. If the command has recently been sent, initiating a DeviceInformation query may not trigger another ScheduleOSUpdate command.

Once you have issued the DeviceInformation query, you can navigate to Device Details → Troubleshooting to confirm the ScheduleOSUpdate command was processed by the device. Check the Event Log for “Schedule OS update” events.

Verify the Command was Received by the Device

If you want to ensure the command is being received by the device, launch Console.app on the device prior to sending the ScheduleOSUpdate command. Start streaming the logs, and search for the text “ScheduleOSUpdate”. When the device receives the command, you will see entries in the system log like the following. If an error occurs, it will be reported in the HTTP response.

Verify that Updates are In Progress on the Device

There are two methods for determining if updates are properly progressing on the device. Which method you use is decided by the type of update, either minor or major. A minor update is an update where the major version of the OS remains the same; for example: macOS 13.x to macOS 13.y. A major update is any macOS update where the OS major version changes; for example, macOS 13.x to macOS 14.x.

Minor Updates

If you are troubleshooting a minor update, you can use Console.app to validate that the update is in progress. Like earlier, start streaming the logs and set the search filter to “portionComplete”. If the update is proceeding properly, you should see frequent messages indicating the current progress. In some cases, the device might process the ScheduleOSUpdate command successfully, but not initiate the download. If this is due to a temporary issue, the ScheduleOSUpdate command will be processed again the next time it is queued on the device.

Major Updates

To check the progress of a major update, you need to open Terminal.app and follow a 3-step process to monitor the progress. Once you have initiated the update, open Terminal.app, and start by determining the appropriate download folder by entering the following command.

sudo find /private/var/folders -type d -name “downloads”

This command will return a list of folders, most of which will show an error of “Operation not permitted”. Find the folder that does not display this error and copy the folder path. 

Then enter the following two commands one at a time, substituting the exact path you found in the previous step.

sudo su

du -sh /private/var/folders/zz/zyxvpxvq6csfxvn_n00000s0000068/C/com.apple.SoftwareUpdate/swcdn.apple.com/content/downloads

These commands will return the total size of the download folder. Running the commands periodically will confirm that the download is in progress. 

Once the download is complete, the above command will return a size of 0. When complete, you will find the OS installer in the Applications folder.

Verify the Results of the OSUpdateStatus Query

In the Workspace ONE UEM console, you can check the status of a device update by navigating to the Device Details → Updates tab. You can initiate an OSUpdateStatus command to obtain the latest status on an update. You can initiate this command by clicking the button on the screen. The last three columns on this screen provide status details on the update. The Deferrals Left column represents the number of user deferrals (if configured) left in the update. The Status column shows the current status of the update process, and the Last Update column informs you of the last time the status has been updated. This last column will show “Not Reported” for assigned updates, and “Not Started” for unassigned updates unless the status collected is currently in progress.

You can periodically click the Query Update Progress button to get the latest status on the update.

Summary

The macOS Update Management feature provides IT admins with the mechanisms for managing system updates to the macOS devices in their enterprise. It provides a framework for downloading and installing updates, or granularly controlling those steps independently. This feature enables automated update cycles that align with an organization’s needs. And using the various steps outlined in this post can assist with monitoring update progress and basic troubleshooting of issues with updates.

If you want to know more about using macOS Update Management, check out this tutorial on Tech Zone.