Beta Documentation for macOS Software Management

Previously, most macOS applications or software were deployed via Product Provisioning File/Actions. As of AirWatch 9.3, all macOS application file types (.dmg, .pkg, .mpkg, .app) can be managed through the Internal Applications section. This new framework leverages the popular Mac Admin community tool, Munki, to handle deployment and configuration logic. As such, a large part of this documentation will be borrowing from the Munki Documentation, but modified to be presented in AirWatch integration terms.

 

Pre-Requisite - How to enable the feature?

  • Navigate to Settings > Devices & Users > Apple > Apple macOS > Software Management
  • Enable Software Management , there is a check in place to verify if File Storage is enabled at this page. If there is no File Storage, the admin would be requested to enable File Storage. Information to enable is available here
  • If you have an On-Prem deployment you will also need to enable CDN. Information here

 

Pre-Requisite - Before uploading macOS File to AirWatch

All primary macOS software filetypes will now be uploaded through Internal Applications (.pkg, .dmg, .mpkg). A .pkg file can be a Bootstrap Package or can be managed through full lifecycle management (this feature). In order to configure Advanced Management options for macOS software and for effective desired state management, which is achieved through the integrated Open-Source Munki library in the AirWatch Agent, a metadata file must be generated for the file separately before uploading to the console. Munki's deployment logic is built on the concept of pkginfo files, which are xml/plist files that contain metadata, configuration information, and more for a given application file. AirWatch requires this pkginfo file along with the application file to manage the deployment in the Console.

VMware Admin Assistant Tool

Generate the pkginfo file with the VMware AirWatch Admin Assistant tool for macOS. This tool is a GUI wrapper for a Munki command-line utility to generate the pkginfo metadata file for a given application file.

The VMware Admin Assistant Tool is available in the AirWatch Console, and athttps://awagent.com/AdminAssistant/VMwareAirWatchAdminAssistant.dmg. The Admin Assistant is also built with an auto-update mechanism, which updates to the latest version based on the AppCast.XML file available at https://awagent.com/AdminAssistant/VMwareAirWatchAdminAssistant.xml

Generate a pkginfo metadata file using the Admin Assistant

  1. Download and install the Admin Assistant tool to a macOS device or VM
  2. Open the Assistant. The Assistant dialog will ask you to upload the application installer files for the Assistant to parse.

  3. Upload an application installer file by dragging and dropping a .pkg, .dmg, .mpkg, or .app file into the labeled field, or browse your local files for an installer file. If the file is .app, it will be converted into a .dmg for deployment.

  4. When you drop or select a file, the tool will automatically start the process. You can add more files during this time if needed.

  5. Once the parsing is complete, the tool will prompt to reveal the parsed metadata files in Finder. Store the metadata files in a local folder where you can easily retrieve them during the Software Distribution procedure.

Demo: VMware AirWatch Admin Assistant

 

3rd Party Integration - Autopkg

There are multiple ways to obtain the metadata/pkginfo file aside from using the Admin Assistant. Since we've integrated a famous and widely used open source tool - Munki - there are already multiple integrations available today using tools that have ready-made recipes for softwares including recommended configuration options developed and maintained by the community. One such tool is AutoPkg, where administrators can look for recipes of commonly used third-party software that pulls the latest version from the respective official hosted website. Additionally, there are tools such as AutoPkgr which provide a GUI for Autopkg, giving a better user-experience and integrations to periodically check for updates to the third-party softwares and notify the admin. 

Demo: Using AutoPkg for macOS Software Distribution

 

What if I have an existing Munki setup and want to move to AirWatch?

You can add the existing application with the direct link of the application on your current Munki Repository server. This is advantageous since it will not require an actual upload of the file to AirWatch, taking up AirWatch File Storage space - you can continue to use your existing file storage server if you prefer. AirWatch will reference the file to the link you provide. Then you will only have to upload the existing pkginfo file and make any additional modifications in the AirWatch UI.  

 

 

Upload a macOS Application to the AW Console:

macOS Applications are now managed in Apps & Books > Applications > Native > Internal

  1. Navigate to Apps & Books > Applications > Native > Internal
  2. Click Add Application
  3. Upload app/software file (.pkg, .mpkg, .dmg)
  4. Continue to the next screen and Upload the pkginfo .plist file
  5. Continue to customize deployment, the proceeding screens will display any configurations present in the pkginfo file (for example, a pkginfo from AutoPkg might contain an install_check script already). You can add any additional deployment configurations, and it will be merged with the existing configurations
    • If the pkginfo file has more keys and configurations that are not exposed in the UI, they will not be affected. This is important so that admins can upload pkginfo's with keys that would be supported by the Munki client but won't be configurable in the UI. Any changes in the UI will be merged with the existing keys. In future console releases, we will be adding more of these keys to the UI so that everything can be eventually configured from the Console.

 

How to customize deployment?

Pre/Post Install Scripts

A common reason to repackage software is to perform additional configuration tasks or install additional items.

A technique to avoid repackaging is to add a pre-install script and/or a post-install script to the configuration for an item. These scripts can take care of some of the tasks you may have previously needed to resort to repackaging to implement.

An Exit Code of 0 will mark the script as successfully run to allow Munki to continue.

NOTE: Failure of the pre-install script will abort the installation attempt. Failure of the post-install script will log errors, but the install will be considered complete.

Pre/Post-Install Script Logging

echo statements will be logged to /Library/Application Support/AirWatch/Data/Munki/Managed Installs/Logs/ManagedSoftwareUpdate.log

Example - TextWrangler Post Install Script

TextWrangler, a popular text editor, is distributed as a "drag-n-drop" disk image containing the TextWrangler application. But on first launch of the TextWrangler application, the user is prompted for admin credentials so some command-line tools can be installed. One approach to avoid this prompt is to repackage TextWrangler so that the applications and command-line tools are installed up front. But this can quickly become tedious as newer versions of TextWrangler are released.

An alternative is to implement a post-install script that copies the command-line tools from the TextWrangler bundle to their intended locations.

After uploading the files to AirWatch Internal Applications, you can configure these scripts in the Scripts tab of the Application Details. Simply paste the script and AirWatch will format it to be used by Munki.

postinstall.png

 

Uninstall Methods

There are multiple options available for uninstallation of software. The appropriate option will be selected by default by the VMware Admin Assistant tool based off the file type. Nevertheless, there is an option to override the value if needed on the console as well.

Remove Copied Items

  • Used primarily for .dmg
  • Pulls from items_to_copy array[dicts] in the pkginfo file
    • All file paths in this array will be deleted
  • Future Console release will show the paths in the items_to_copy array in the UI

Remove App

  • Pulls from installs array[dicts] in the pkginfo file
    • All file paths in this array will be deleted
  • Future Console release will show the paths in the installs array in the UI

Remove Packages

  • Used primarily for .pkg
  • Uses receipts and analyzes the packages to remove
    • Tries to determine what all files were installed via Bom file
    • Deletes receipt
  • Will only remove if package is not associated with something else too
  • Future Console release will show the receipts Munki will check for in the UI

Uninstall Script

  • Can be used for any installer type
  • Written in shell script
  • Used to perform custom uninstall operation if needed
    • If the Admin has a customized deployment of an app, they would need to also write a corresponding uninstall script to remove their custom configurations

 

Install or Uninstall Verification

With some software, the Admin needs to configure what exactly defines a Successful Install or Uninstall. Munki allows this via setting an Install or Uninstall Check Script

Install Check Script - If present, this script is executed to determine if an item needs to be installed. A return code of 0 means install is needed; any other return code causes install to be skipped.

Uninstall Check Script - If present, this script is executed to determine if an item needs to be uninstalled. A return code of 0 means uninstall is needed; any other return code causes uninstall to be skipped.

 

Conditions

Conditions can de defined at a per-application level to be evaluated prior to download and install of the software. There are some built-in conditions supported by the integrated open source munki library that we will be supporting with the first phase. However, several of the commonly used conditions can be instead scoped through AirWatch Smart Groups, such as OS Version or Machine Type

We will be following up with additional conditions in the future for more flexibility.

Built-in Conditions

Currently available built-in attributes for conditional comparison:

Attribute Type Description Example Comparison
hostname string Hostname hostname == "Lobby iMac"
arch string Processor architecture. e.g. 'powerpc', 'i386', 'x86_64'. arch == "x86_64"
os_vers string Full OS Version e.g. "10.7.2" os_vers BEGINSWITH "10.7"
os_vers_major integer Major OS Version e.g. '10' os_vers_major == 10
os_vers_minor integer Minor OS Version e.g. '7' os_vers_minor == 7
os_vers_patch integer Point release version e.g. '2' os_vers_patch >= 2
machine_model string 'Macmini1,1', 'iMac4,1', 'MacBookPro8,2' machine_model == "iMac4,1"
machine_type string 'laptop' or 'desktop' machine_type == "laptop"
ipv4_address array of strings This contains current IPv4 addresses for all interfaces. ANY ipv4_address CONTAINS '192.168.161.'
munki_version string Full version of the installed munkitools munki_version LIKE '*0.8.3*'
serial_number string Machine serial number serial_number == "W9999999U2P"
date UTC date string Date and time. Note the special syntax required to cast a string into an NSDate object. date > CAST("2013-01-02T00:00:00Z", "NSDate")

Example :

machine_type == "laptop" AND os_vers BEGINSWITH "10.7"
date > CAST("2016-03-02T00:00:00Z", "NSDate")

Notes:

Dates in conditions: The date string must be written in UTC format, but is interpreted as a local date/time. The condition date > CAST("2013-01-02T00:00:00Z", "NSDate") is True if the local time is after midnight local time on 02 Jan 2013.

Literal types in comparisons

  • Strings are delimited by either single or double-quotes: os_vers BEGINSWITH "10.7"

  • Integers have no quotes: os_vers_major == 10

  • Booleans are indicated as TRUE or FALSE (and have no quotes, or they'd be strings!): some_custom_condition == TRUE

  • Dates are possible, but you need to cast them from ISO 8601 strings: date > CAST("2013-01-02T00:00:00Z", "NSDate")

 

How to manage updates?

Updates can be managed similar to the rest of the platforms on the console. If a new version of the file needs to be added, do the following:

1. Navigate to Apps & Books > Native

2. Click the App you want to update, this will take you to the Details view

3. In the top right, click "Add Version"

4. Upload the new installer of the new version

5. Upload the new pkginfo file of the new version.

6. Make any additional changes and then save

 

How to troubleshoot issues?

The AirWatch Console will show report data from the device in a few locations

  • Apps & Books > Applications > Native > Internal. Click the Application to drill into Application Details > Devices Tab. This grid will show install statuses for each device
  • Devices & Users > Devices > List View. Click a device to drill into Device Details > Troubleshooting Tab. This grid will show activity from the device and provides filtering options to only show info relating to Software Distribution

Munki Logs can also be directly accessed on the device

  • /Library/Application\ Support/AirWatch/Data/Munki/Managed\ Installs/Logs/ManagedSoftwareUpdate.log

Known Caveats

  • Once the software has been published and installed on a few devices, if any of the configuration options such as "install script", "uninstall script" etc.. are changed, devices which already have the application installed successfully do not get the updates as there isn't a separate command apart from "InstallApplication" that can update the locally cached PKGInfo files on the device. Admin would have to manually select all devices which have the software installed, to repush the command. That will update the respective cached PKGinfo file with the latest information. NOTE : This will NOT re-install the application (unless there is a change in the version), Munki is smart to not re-install when it knows the application is already installed

  • If there is a dependency of a package on another package or software then an admin will have to manually provide requires key in the pkginfo of the package which is dependent on other package. This is the only way for Munki to know dependencies for packages, if there are any, and it will take care of the sequence of installation of such dependent packages. Otherwise, if not specified, packages are installed in random fashion and such packages installation will fail if the package that it is dependent on is not installed prior to it.

    ExampleNetbeans require you have Java already installed on the machine. Netbeans will not implicitly install Java for you while installing the package. Even if you try to install Netbeans without using Munki or using standalone Munki, it will fail and will ask you to first install Java and then install Netbeans.

  • For packages which have the same receipts array with same version even on upgraded package, Munki will never be able to detect that the new package is upgraded package. The reason is simple, the receipt array is same and has the same version as previous package. The impact is that you will be able to upload the latest package of that software on AirWatch Console and assign them to existing SmartGroups, but they will never get installed on the Users machines because Munki will think it's already installed.

    The best solution for such kind of packages is to use an Autopkg Recipe, which adds an installs array in the pkginfo and that way munki is able to detect upgrade. Or else an admin manually adds installs array in the pkginfo.

    Example: Wireshark is an example package which has the same receipts with same version on all of their packages and thus Munki cannot detect the upgrades.

 

 

 

 

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.