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
- Download and install the Admin Assistant tool to a macOS device or VM
Open the Assistant. The Assistant dialog will ask you to upload the application installer files for the Assistant to parse.
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.
When you drop or select a file, the tool will automatically start the process. You can add more files during this time if needed.
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
- Navigate to Apps & Books > Applications > Native > Internal
- Click Add Application
- Upload app/software file (.pkg, .mpkg, .dmg)
- Continue to the next screen and Upload the pkginfo .plist file
- 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.
- Save the configurations and assign to a Smart Group and define the behavior on unenrollment
How to verify on the console that an app is assigned
In the Internal Applications List View, click the app to go to Application Details then click the Devices tab. All assigned, enrolled, devices should appear in this list.
How to verify on the device locally that an app is assigned
All assigned apps should be shown in the /Library/Application\ Support/AirWatch/Data/Munki/Managed\ Installs/manifests/device_manifest.plist in the managed_installs array
Furthermore, all assigned apps will have their corresponding pkginfos contained in the catalog plist located at /Library/Application\ Support/AirWatch/Data/Munki/Managed\ Installs/catalogs/device_catalog.plist
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.
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
- 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
- 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
- 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 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.
Currently available built-in attributes for conditional 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 '
|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")|
machine_type == "laptop" AND os_vers BEGINSWITH "10.7"
date > CAST("2016-03-02T00:00:00Z", "NSDate")
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
Integrity Check Failed
In the munki logs you may see a section such as:
Feb 12 2018 16:24:25 -0500 Verifying package integrity...
Feb 12 2018 16:24:25 -0500 ERROR: Hash value integrity check for BBEdit-12.0.2.dmg failed.
Feb 12 2018 16:24:25 -0500 WARNING: Can't install BBEdit because the integrity check failed.
Feb 12 2018 16:24:25 -0500 **Checking for removals**
If you see this, check that the pkginfo you have uploaded is correct for the corresponding application file. You can inspect the XML by clicking the radio button next to the Application in Application List View > View XML.
Cannot upload .dmg, .mpkg, or .pkg for advanced management
If you are on 9.2.3, you will need to contact support to have a DB script ran to enable the feature.
If you are on 9.3+, the feature should be turned on already. The feature also requires File Storage and CDN to be configured. Information to enable is available here and here. Please contact support if you need assistance.
Please note, this feature also requires the device have Agent 3.0.0+ installed. This version should be seeded automatically into 9.3. If you are on 9.2.3, you will also need to request Support seed the Agent build in your environment if not already done.
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.
Example: Netbeans 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.