Using Intelligent Hub hubcli to Manage macOS Updates

Overview

VMware Workspace ONE® UEM provides a comprehensive management solution for macOS devices, supporting operating systems version 10.15 and higher. With the ability to manage Corporate-Dedicated, Corporate Owned or Employee Owned (BYOD) devices, Workspace ONE UEM offers enterprises the flexibility to meet their employees’ needs at any level.

One area where organizations require a significant amount of flexibility and customization is managing OS updates and patches. Apple regularly releases minor updates for macOS that include feature enhancements, bug fixes, and security patches. Major OS updates, released less frequently, often contain new functionality, and in some cases, a completely new code base for the OS itself. Apple has included a Software Update utility within the OS that typically requires user intervention to initiate.

Workspace ONE UEM provides IT administrators with the ability to configure Software Update utility settings, such as the following:

• How to install updates (manually or automatically)
• What updates to install (all or recommended only)
• How often to check for updates
• Restart behaviors (force restart, allow deferrals, max number of deferrals, and so on)

The Software Update utility does provide organizations with the ability to maintain updates and patches on their macOS devices. However, it is limited in two ways. First, it relies on some end user intervention when it comes to updates and patches being applied. Second, it does not provide IT administrators with the ability to control which specific updates and patches get applied.

For example, if an organization is dependent on a specialized suite of software that requires a specific version of macOS to be installed, IT administrators may wish to control the OS updates until the software can be validated on the updated platform. It might also be necessary to keep users from updating to the latest OS version as soon as the update is released. Workspace ONE UEM provides admins with the granular control needed to ensure that devices are patched and updated to meet corporate standards.

With the release of the Intelligent Hub, version 2212, Workspace ONE supports native Apple MDM commands for downloading, initiating, and managing software updates. The Workspace ONE hubcli commands provide granular control over the macOS update process. With a combination of leveraging and supporting native MDM update functionality as well as a more programmatic approach enabled by Freestyle Orchestrator, Mac Administrators have the toolset they need to fully support OS updates for their end users.

hubcli Commands

The hubcli for macOS is a client-side command-line tool built-in to Workspace ONE Intelligent Hub that provides you with an easy way to perform a limited set of configuration, API, and notification actions. It is important to remember that these actions are limited to the device on which hubcli runs. As of Intelligent Hub, version 2212, the hubcli offers the following commands:

Command	Description
sync	This command triggers Intelligent Hub to sync with Workspace ONE UEM.
notify	Using this command, IT admins can display a custom notification to the current user on the device.
config	This command allows admins to view or change certain Hub configuration settings.
logs	Admins can use this command to collect Hub diagnostics from a device and send them to the UEM console.
profiles	This command requests the UEM server to list or install assigned profiles.
restartdevice	Admins can use this command to request that UEM sends a restart command to a specific device.
sensors	With this command, users can perform certain sensor operations, like listing all sensors or triggering a sensor.
mdmcommand	This command can be used to trigger a custom command for native software update MDM actions.

Note: In this tutorial, you use the notify and mdmcommand hubcli commands. The other commands in the above list are not discussed. If you wish to explore the other commands further, you can view help for each command through a Terminal session on a managed device with hubcli <COMMAND> --help, where <COMMAND> is one of the above listed commands.

Parameters for hubcli mdmcommand

The mdmcommand provides a series of parameters that can be used to control specific macOS update actions. These parameters give IT admins granular control over the entire update process. The following table explains the purpose of each parameter.

Parameter	Description
‑‑osupdatescan	This parameter schedules a background scan for OS updates on the device.
‑‑forceupdatescan	This parameter forces the device to initiate an immediate OS update scan.
‑‑osupdate	This parameter initiates an OS update on the device. You use this parameter in conjunction with others in this table to control the behavior of the update.
‑‑productversion	You use this parameter in conjunction with ‑‑osupdate to specify a specific version of macOS to which to update.
‑‑productkey	This parameter specifies the product key of the specified version of macOS.
‑‑installaction	The ‑‑installaction parameter determines what action is taken when you use the --osupdate parameter. The available options are: Default – Downloads or installs the update. DownloadOnly – Downloads the update without installing it (minor updates only). InstallASAP – Downloads the software update and triggers a restart countdown notification. NotifyOnly – Downloads the update and notifies the user (minor updates only). InstallLater – Downloads the software update and installs it at a later time (minor updates only). InstallForceRestart – Performs the Default action, and then forces the device to restart if required by the update (minor updates only).
‑‑maxuserdeferrals	This parameter sets the maximum number of user deferrals allowed before the update is automatically installed. This is only available when you use ‑‑InstallLater and is only supported with minor OS updates (for example, 13.x to 13.y).
‑‑priority	This parameter sets the scheduling priority for downloading and preparing the update. This is only supported for minor OS updates (for example, 13.x to 13.y). The priority options are low and high.

The following are examples of how to use the mdmcommand for macOS updates.

• Request an OS update for macOS 13.1
  hubcli mdmcommand --osupdate --productversion “13.1”
• Request an OS update for macOS 13.1 to be downloaded, but not installed
  hubcli mdmcommand --osupdate --productversion “13.1” --installaction DownloadOnly
• Request an OS update for macOS 13.1 to be downloaded and allow the user to defer the installation for up to 3 days
  hubcli mdmcommand --osupdate --productversion “13.1” --installaction InstallLater --maxuserdeferrals 3

Purpose of This Tutorial

This tutorial guides you through the creation of the required sensors, scripts, and Freestyle Orchestrator workflow for managing macOS updates and patches. The tutorial is divided into two sections. The first section provides an example of managing major macOS updates using scripts, sensors, and a Freestyle Orchestrator workflow. The second section discusses using a script for managing minor macOS updates and patches.

The steps outlined in this tutorial are sequential and build upon each other. It is important that you follow the steps as described.

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. Familiarity with macOS, XML, and basic scripting is assumed. Knowledge of additional technologies such as VMware Workspace ONE® Intelligence and VMware Workspace ONE® UEM is also helpful.

Validation Environment

The content created for this operational tutorial used the following software and hardware versions for testing:

• Workspace ONE UEM version 2302
• Workspace ONE Intelligent Hub version 2301
• Apple macOS 12.6.3 (major OS update from 12.6.3 to 13.1)
• Apple macOS 13.1 (minor OS update from 13.1 to 13.2)

The content in this tutorial may be applicable to earlier Workspace ONE UEM and Hub versions, but was not specifically tested.

Software Update Device Profile

The macOS Software Update Utility regularly checks for updates and can be configured to automatically download and install OS updates. However, you may wish to have more granular control over what updates are installed on your devices. You can manage automatic updates with a device profile in Workspace ONE UEM.

In this section, you create a device profile that configures the Software Update Utility to not automatically check for updates.

Create a Software Update Device Profile

To get the desired result, perform the following steps:

1. On your desktop, double-click the Google Chrome icon.
2. Navigate to the VMware Workspace ONE UEM Console.
   For example, navigate to https://<WorkspaceONEUEMHostname> where WorkspaceONEUEMHostname is the host name of the Workspace ONE UEM console.
3. Enter your Username, for example, administrator.
4. Click Next. The Password text box is displayed.
5. Enter your Password, for example, VMware1!. Click Login.
   NOTE: If you see a Captcha, be aware that it is case sensitive.
6. Select Resources, and then click Profiles & Baselines.
7. Select Profiles.
8. From the Add dropdown menu, select Add Profile.
9. Select the Profile Platform by clicking macOS.
10. For the Context, select Device Profile.
11. Enter macOS Updates for the profile name.
12. Scroll down the list of payloads until you find Software Update, and click Add.
13. For Install macOS Updates, select Don’t automatically check for updates from the dropdown options. Notice that all other options become unavailable.
     
14. Click Next.
15. Scroll down to view Assigned Groups and click in the search box. From the list of Assignment Groups that appear, select the appropriate group. For example, select All Devices (your@email.shown.here).
16. For the Assignment Type, select Auto.
17. Click Save and Publish.
18. You should now see your macOS Update device profile within the list on the Profiles window.

Managing Major macOS Updates

Introduction

Major macOS updates can be a disruptive experience for end users. These updates sometimes take up to an hour to complete, which can potentially leave the user without access to work resources during the update process. IT admins must balance the need to maintain their fleet of devices with accommodating the end user’s needs. It is important to provide the end user with as much flexibility as possible while ensuring that the update gets applied within a time frame that is acceptable to your organization’s policies.

For this exercise, you upgrade macOS Monterey, version 12.6.3 (and below) to macOS Ventura, version 13.1. The steps in this exercise can be adjusted for any combination of supported versions.

In this section, you use a combination of sensors and scripts to create a Freestyle Orchestrator workflow that notifies the end user of a pending update, gives them options for deferrals, and forces the update once a specified deadline has been reached.

You create the following resources in Workspace ONE UEM:

Resource Name	Resource Type	Description
macos_version	Sensor	A sensor that checks the macOS version currently installed on the device. This is used to determine if the device requires the update.
current_date	Sensor	This sensor checks the current date and time on the device. This determines if the device has reached the deadline for installing the update.
macos_install_majorupdate	Script	This script notifies the user that an update is required, and it begins the download/install process. The user does not have the option to defer the update.
macos_notify_majorupdate	Script	This script notifies the user that an update is required, and gives the user the option to begin the download and install process, or to defer the update until later.

These four resources are used in a Freestyle Orchestrator workflow that manage the download and installation of the major update across your macOS devices. The process outlined in this document is designed to serve as an example. It is only one of several ways that this can be accomplished using the hubcli and Freestyle Orchestrator.

The following diagram explains the steps of the workflow. You will configure the workflow later in this sections.

1. The workflow executes on the macOS device.
2. The macos_version sensor checks what version of macOS is installed on the device. If the version is NOT 13.1 or 13.2, the workflow proceeds to step 3. If it is 13.1 or 13.2, the workflow exits.
3. The update_deadline sensor checks to see if the current date on the device is before the required install date for the update. If current date is before the required install date, the workflow proceeds to step 4. Otherwise, it proceeds to step 5.
4. The workflow executes the macos_notify_majorupdate script. This script notifies the user of the impending update, and gives them the opportunity to proceed or defer the update for later. If the user decides to proceed, the script initiates the download of the installer and begins the update. If the user defers the update, the script exits, and the workflow exits.
5. The workflow executes the macos_install_majorupdate script. This script notifies the user of the impending update, and then initiates the download and installation of the update. It forces the device to restart.

Create Smart Group for Device Updates

To target devices that are currently running macOS Monterey (12.6.x), you use a Smart Group within Workspace ONE UEM to assign the devices to the workflow. A Smart Group is a customizable group that allows you to group specific platforms, devices, and users together for the purpose of application, policy, profile, and provisioning assignment.

In this exercise, you create a Smart Group to be used for assignment of the update workflow.

To get the desired result, perform the following steps:

1. In the Workspace ONE UEM console, select Groups & Settings. Expand Groups and select Assignment Groups. Click Add Smart Group.
2. Enter macOS Major Update for the group name.
3. From the list of available criteria, expand Ownership. Click Selected and ensure that Corporate is the only item with a check mark.
4. Expand Platform and Operating System. From the drop down, select Apple macOS. Change the condition to Less Than, and select macOS Ventura 13.0.0.
    
5. Click Save.

Configure Sensor to Check macOS Version on Devices

The workflow requires a mechanism for determining if the update is required on a device. This is done with a sensor that retrieves the current version of macOS installed on the device. The workflow compares the installed version with the update version.

To get the desired result, perform the following steps:

1. In the Workspace ONE UEM console, select Resources, and select Sensors.
2. Click Add and select macOS from the dropdown menu.
3. Enter macos_version for the sensor name, and click Next.
   NOTE: Sensor names must be in all lower case letters, and cannot include spaces.
4. For Language, select Bash.
5. For Execution Context, select System.
6. Enter the following into the Code textbox:
   #!/bin/bash

osvers=$(/usr/bin/sw_vers -productVersion)
echo $osvers
    
7. Click Next, and click Save.
   NOTE: For this exercise, it is not necessary to assign the script to an assignment group. The script is assigned as part of the Freestyle Orchestrator workflow later in this tutorial.

Configure Sensor to Compare Current and Required Install Dates

If you are required to ensure that updates are applied by a certain date, you need to create a script that compares the device’s current date to the required install date.

To get the desired result, perform the following steps:

1. In the Workspace ONE UEM console, select Resources, and select Sensors.
2. Click Add and select macOS from the dropdown menu.
3. Enter update_deadline for the sensor name, and click Next.
   NOTE: Sensor names must be in all lower case letters, and cannot include spaces.
4. For Language, select Bash.
5. For Execution Context, and select System.
6. Enter the following into the Code textbox:
   #!/bin/bash

# enter the required date on which the update must be installed. Enter the date as YYYYMMDD
update_deadline=20230201

# gets current date from the device
current_date=$(date +"%Y%m%d")

# compares current date to the required install date
if [[ "$current_date" > "$update_deadline" ]] ;
then
    echo "true"
else
 echo "false"
fi
    
7. Click Next, and click Save.
   NOTE: For this exercise, it is not necessary to assign the script to an assignment group. The script is assigned as part of the Freestyle Orchestrator workflow later in this tutorial.

Create Script to Notify User of Pending Update

This script sends a notification to the logged on user to let them know there is a pending update. The user can either begin the update or defer it for a later time. The script uses the hubcli notify command to the send the notification, and the mdmcommand to start the update. The following flags are available for use with the hubcli notify command.

Flag	Description
‑t, ‑‑title	This sets the title of the notification box. It is a required flag.
‑s, ‑‑subtitle	This flag sets the subtitle for the notification box.
‑i, ‑‑info	This sets the informative text for the notification box
‑a, ‑‑actionbtn	This flag includes an action button in the notification box and sets the label for the button.
‑b, ‑‑script	Use this flag to set a bash script to execute when the user clicks the action button.
‑c, ‑‑cancelbtn	This provides an alternate label for the cancel button. Clicking this button closes the notification box.

To get the desired result, perform the following steps:

1. In the Workspace ONE UEM console, select Resources, and then click Scripts.
2. Select Add, and click macOS.
3. Name the script macos_notify_majorupdate. Leave App Catalog Configuration disabled, and click Next.
4. Set the Language to Bash, and the Execution Context to System.
5. Set the Timeout to 30.
6. Enter the following into the Code textbox:
   #!/bin/bash

   /usr/local/bin/hubcli notify -t "Update to macOS Ventura" -s "This may take up to 1 hour." -i "Your machine will restart automatically. You will be notified when your device will be restarted. You have until Feb. 28th to update your device." -a "Begin" -b "/usr/local/bin/hubcli mdmcommand --osupdate --productversion 13.1 --installaction InstallASAP" -c "Update Later"
   
   NOTE: You can change the behavior of the notification box by modifying the various flags mentioned earlier within the script.

7. Click Next, and click Save.
   NOTE: For this exercise, it is not necessary to assign the script to an assignment group. The script is assigned as part of the Freestyle Orchestrator workflow later in this tutorial.

Create Script to Initiate the Update Download and Installation

This script notifies the logged in user that a pending update is about to be installed. Then, the script initiates the download and installation of the update. The user does not have the option to defer the update.

To get the desired result, perform the following steps:

1. In the Workspace ONE UEM console, select Resources, and then click Scripts.
2. Select Add, and click macOS.
3. Name the script macos_install_majorupdate. Leave App Catalog Configuration disabled, and click Next.
4. Set the Language to Bash, and the Execution Context to System.
5. Set the Timeout to 30.
6. Enter the following into the Code textbox:
   #!/bin/bash

# notify the user of impending update and restart
/usr/local/bin/hubcli notify -t "Update to macOS Ventura" -s "An update is required for your device." -i "Your machine will restart automatically. This may take up to 1 hour."

# initiate the download of the update and restart the device to complete the update
/usr/local/bin/hubcli mdmcommand --osupdate --productversion 13.1 --installaction InstallASAP
   
   NOTE: You can change the behavior of the notification box by modifying the various flags mentioned earlier within the script.
7. Click Next, and click Save.
   NOTE: For this exercise, it is not necessary to assign the script to an assignment group. The script is assigned as part of the Freestyle Orchestrator workflow later in this tutorial.

Deploy Freestyle Orchestrator Workflow to Manage Major Updates

Freestyle Orchestrator is a workflow orchestration platform integrated into Workspace ONE UEM that allows IT administrators to create low-code workflows for handling resource deployments that have complex conditions or sequencing. The Freestyle Orchestrator workflow that you create for this exercise manages the major update process by ensuring that the correct action is taken at the appropriate time on the specified devices.

NOTE: When the workflow is published and executed on a device, the user receives notification of the pending update, and in some cases, is given the option to defer the update until later. It is important to note that the download and installation process takes time to complete. Between the initial notification and the restart notification, the end user does not see any visible activity on their device. It is important to communicate this to the end users, to set appropriate expectations and ensure that they do not experience data loss.

For more information about using Freestyle Orchestrator to manage macOS devices, see the Getting Started with Freestyle Orchestrator on macOS Devices operational tutorial on VMware Tech Zone.

To get the desired result, perform the following steps:

1. In the Workspace ONE UEM console, select Freestyle, and then select New.
   NOTE: If this is the first time you are using Freestyle Orchestrator, click Get Started on the Getting Started with Workflows screen.
    
2. Name the new workflow macOS Major Update.
3. Select macOS as the platform.
    
4. Next to Smart Groups, click the search box. From the list of Assignment Groups that appear, select the appropriate group. For this exercise, use the smart group you created earlier called macOS Major Update.
5. In the workflow UI, click the plus sign (+) and select Condition. Name the condition check_macos_version.
6. From the Select dropdown, select Sensor. Search for the sensor you created earlier called macos_version. Select Does Not Include and enter 13.0, 13.1, 13.2, and click Then.
7. Click Add, and select Condition. Name the condition notify_or_install.
8. From the Select dropdown, choose Sensor. Search for the sensor you created earlier called update_deadline. Select Equals and enter True, and click Then.
9. Click Add, select Resource, and then click Script.
10. Search for the application you created earlier called macos_install_majorupdate, and click Select.
11. Select the Then operator for the condition you created earlier called notify_or_install.
     
12. In the Admin Panel, click Else.
13. Click Add, select Resource, and then click Script.
14. Search for the script you created earlier called macos_notify_majorupdate, and click Select.
15. With your workflow complete, click Publish.
     
16. When the workflow executes on the device, the end user receives several notifications. The first comes from Intelligent Hub, and provides the user with the option to defer the update until later. If the user decides to proceed with the update, they receive additional notifications from macOS, including one that alerts when the device is ready to restart.
     

Managing Minor macOS Updates

Introduction

Although it is possible to manage minor macOS updates the same way as you did with major updates, it can also be handled in a much simpler fashion. The hubcli mdmcommand offers additional flexibility when it comes to minor updates. You can utilize the --maxuserdeferrals flag to specify the maximum number of user deferrals allowed before the update is automatically installed.

As with the major macOS updates, there are several ways that minor macOS updates can be managed and executed. The process listed in this tutorial should serve as an example, which you can modify per the needs of your organization.

The following exercise purposely does not use Freestyle Orchestrator, in order to show you an alternative method of managing updates. This exercise utilizes only a simple script for notifying the end user and executing the update.

Create Smart Group for Device Updates

To target devices that are currently running macOS Ventura (13.0 to 13.1), you use a Smart Group within Workspace ONE UEM to assign the devices to the script. A Smart Group is a customizable group that allows you to group specific platforms, devices, and users together for the purpose of application, policy, profile, and provisioning assignment.

In this exercise, you create a Smart Group that is used for assignment of the update script.

To get the desired result, perform the following steps:

1. In the Workspace ONE UEM console, select Groups & Settings. Expand Groups, select Assignment Groups, and click Add Smart Group.
2. Enter macOS Minor Update for the group name.
3. From the list of available criteria, expand Ownership. Click Selected and ensure that Corporate is the only item with a check mark.
4. Expand Platform and Operating System. From the drop down, select Apple macOS. Change the condition to Less Than, and select macOS Ventura 13.2.0. Click the plus sign (+) and select Apple macOS, Greater Than or Equal To, and macOS Ventura 13.0.0 from their respective dropdowns.
    
5. Click Save.

Create Script to Notify User of Pending Minor Update

This script sends a notification to the logged-on user to let them know there is a pending update. The user is given the opportunity to either begin the update or defer it for a later time. A maximum number of deferrals is configured within the script. The hubcli notify command is used to send the notification, and the mdmcommand to start the update.

To get the desired result, perform the following steps:

1. In the Workspace ONE UEM console, select Resources, and then click Scripts.
2. Select Add, and click macOS.
3. Name the script macos_notify_minorupdate. Leave App Catalog Configuration disabled. Click Next.
4. Set the Language to Bash, and the Execution Context to System.
5. Set the Timeout to 30.
6. Enter the following into the Code textbox:
   #!/bin/bash

# send the user a notification about the update
/usr/local/bin/hubcli notify -t "Update to macOS Ventura" -s "This may take up to 1 hour." -i "Your machine will restart automatically. You will be given the option to defer the update up to three times."

# begin the download process and set the maximum number of user deferrals
/usr/local/bin/hubcli mdmcommand --osupdate --productversion 13.2 --installaction InstallLater --maxuserdeferrals 3
    
7. Click Next.
8. Click Save.
9. In the Scripts list, check the new script you just created, and click Assign.
10. Click New Assignment.
11. Enter macOS Minor Updates for the Assignment Name.
12. Next to Select Smart Groups, click in the search box. From the list of Assignment Groups that appear, select the appropriate group. For this exercise, use the smart group you created earlier called macOS Minor Update, and click Next.
13. Check Run Periodically and select an appropriate interval for your environment. For the purpose of this exercise, select 24, and then click Add.
     
14. Click Save & Publish, and then Publish.
15. When the script executes on the device, the end user first receives an Intelligent Hub notification alerting them to the pending update. The user then receives a notification from macOS when the update is ready to install. The second notification provides the user with the option to defer the update.

Summary and Additional Resources

Introduction

This operational tutorial provided examples of how to use the Intelligent Hub hubcli to manage major and minor macOS updates.

Procedures included:

• Creating a Smart Group to target devices for major and minor updates
• Creating required scripts and sensors for managing updates
• Deploying a Freestyle Orchestrator workflow for managing major updates
• Using scripts to manage minor macOS updates

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 can find everything from beginner to advanced curated assets in the form of articles, videos, and labs.

For more information on macOS, see Understanding macOS Management.

You may also wish to read these additional operational tutorials from macOS on VMware Tech Zone.

• Configuring Basic macOS Management
• Getting Started with Freestyle Orchestrator on macOS Devices
• Managing Updates with the macOS Updater Utility
• Distributing Scripts to macOS Devices
• Deploying a Third-Party macOS App

Changelog

The following updates were made to this guide:

Date	Description of Changes
03/01/2023	Initial publication

About the Author and Contributors

This tutorial was written by:

• Michael Bradley, Senior Technical Marketing Architect, End-User-Computing Technical Marketing, VMware

Considerable contributions were made by the following subject matter experts:

• Paul Evans, Product Line Manager, End-User-Computing Technical Marketing, VMware

Feedback

Your feedback is valuable.

To comment on this paper, contact VMware End-User-Computing Technical Marketing at euc_tech_content_feedback@vmware.com.