New macOS Software Management Features
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 terms of AirWatch integration.
- Console Requirements: For 9.3+
- Minimum Agent Version: 3.0 for macOS
Enabling Software Management
- 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 will be requested to enable File Storage. Information to enable is this available here.
- On-Prem deployments will need to enable CDN. Additional information on enabling CDN can be found here.
Pre-Requisite - Before uploading macOS File to AirWatch
All primary macOS software file types 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 it to the AirWatch 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
The pkginfo file is genetrated with the VMware AirWatch Admin Assistant tool for macOS. This tool is a GUI wrapper for a Munki command-line utility and is used to generate the pkginfo metadata file for a given application file.
The VMware Admin Assistant Tool is available in the AirWatch Console, and at https://awagent.com/AdminAssistant/VMwareAirWatchAdminAssistant.dmg. The Admin Assistant is built with an auto-update mechanism, which updates the Assistant to the latest version based on the AppCast.XML file available here.
Generating 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 for the application installer files to parse.
Upload an application installer file by dragging and dropping a .pkg, .dmg, .mpkg, or .app file into the labeled field, or browse the local files on the machine in order to find an installer file.
Note: If the file is .app, it will be converted into a .dmg for deployment.
Once the file is selected and uploaded, the Assistant will automatically start parsing process the process. Additional files can be added 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 they can be easily retrieved during the Software Distribution procedure.
Demo: VMware AirWatch Admin Assistant for macOS
3rd Party Integration - Autopkg
There are multiple ways to obtain the metadata/pkginfo file aside from using the Admin Assistant. As VMware AirWatch has integrated a widely used open source tool, Munki, there are already multiple integrations available today using tools that have ready-made best-practice guides for software including recommended configuration options. These guides are developed and maintained by the Munki user community. One such community resource is AutoPkg, where administrators can look for recipes of commonly used third-party software and automatically pull the latest version of the software from their respective official hosted website. Additionally, there are tools such as AutoPkgr which provide a GUI for Autopkg, giving a better user-experience and integration to periodically check for updates to the third-party software and to notify the admin of the available updates.
Demo: Using AutoPkg for macOS Software Distribution
For administrators using existing Munki setup and want to move to AirWatch
If preferred, administrators can continue using existing file storage servers to store applications/software. Administrators can add existing applications with a direct link of the application on an already configured Munki Repository server. AirWatch can reference the file at the provided link. This method of adding software is advantageous because it will not require an upload of an application file to AirWatch, which consumes AirWatch File Storage space. When using an existing file repository, administrators will only have to upload the existing pkginfo file to the AirWatch Console. Any additional modifications to the deployed application can be made in the AirWatch UI once the pkginfo file has been uploaded successfully.
Uploading a macOS Application to the AW Console:
- 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 the app deployment. The proceeding screens will display any available configurations present in the pkginfo file (for example, a pkginfo from AutoPkg may contain an install_check script). Additional deployment configurations can be defined, and will be merged with the existing configurations
- If the pkginfo file has one or more key and configuration that are not exposed in the UI, they will not be affected. This feature is important as it allows administrators to upload pkginfo files with keys that would be supported by the Munki client but would not be configurable in the UI. Any changes in the UI will be merged with the existing keys.
How to customize deployment?
Pre/Post Install Scripts:
A common reason to repackage software is to perform additional configuration tasks or to install additional items.
A technique to avoid repackaging is to add pre-install scripts and/or post-install scripts to the configuration of an item. These scripts can take care of some of the tasks which previously may have required repackaging to implement.
An Exit Code of 0 will define the script as successfully executed in order 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 installation 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. On first launch of TextWrangler, the user is prompted for admin credentials so that some additional 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. This method, however, can quickly become tedious as newer versions of TextWrangler are released. An alternative to repackaging is to implement a post-install script that copies the command-line tools from the TextWrangler bundle to their intended locations.
After uploading the appropriate files to AirWatch, pre/post install scripts can be configured for the app in the Scripts tab of the Application Details. Simply paste the script into the appropriate field 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 on the software's file type. If needed options to override the default values are available in the AirWatch Console.Remove Copied Items
Used primarily for software installed from a .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 software installed from a .pkg
- Uses receipts and analyzes the packages to remove
- Tries to determine what files were installed via the Bom file
- Deletes receipt
- Will only remove if package is not associated with any other files or programs
- Future Console releases will show the receipts that Munki check for in the UI
Can be used for any installer type
- Written in shell script
- Used to perform custom uninstall operations if needed
- If the Admin has a customized deployment of an app, they will 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 through 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 defined on a per-application level so that they are evaluated prior to the download and installation of a software. There are some built-in conditions supported by the integrated open source Munki library that VMware AirWatch will support with the first phase. Several of the commonly used conditions can instead be scoped through AirWatch Smart Groups. Some of these conditions include OS Version and Machine Type.
VMware AirWatch will be implementing additional conditions in the future for more flexibility.
Currently available built-in attributes for conditional comparison:
|arch||string||Processor architecture. e.g. 'powerpc', 'i386', 'x86_64'.||
|os_vers||string||Full OS Version e.g. "10.7.2"||
|os_vers_major||integer||Major OS Version e.g. '10'||
|os_vers_minor||integer||Minor OS Version e.g. '7'||
|os_vers_patch||integer||Point release version e.g. '2'||
|machine_model||string||'Macmini1,1', 'iMac4,1', 'MacBookPro8,2'||
|machine_type||string||'laptop' or 'desktop'||
|ipv4_address||array of strings||This contains current IPv4 addresses for all interfaces.||
|munki_version||string||Full version of the installed munkitools||
|serial_number||string||Machine serial number||
|date||UTC date string||Date and time. Note the special syntax required to cast a string into an NSDate object.||
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, this format 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 they must be cast from ISO 8601 strings:
date > CAST("2013-01-02T00:00:00Z", "NSDate")
How to manage updates?
Updates can be managed similarly to the other platforms in the AirWatch Console. If a new version of the file needs to be added, perform the following:
- Navigate to Apps & Books > Native
- Click on the App that requires an update. Clicking the app will navigate to the Details View page.
- In the top right side, click "Add Version"
- Upload the new installer for the new app version
- Upload the new pkginfo file for the new version
- Make any additional changes and then save the configuration
How to troubleshoot issues?
The AirWatch Console will show report macOS app installation data from a device in several locations:
- Apps & Books > Applications > Native > Internal. Click onto the Application to drill into Application Details > Devices Tab. The grid in this tab will display installation statuses for each device.
- Devices & Users > Devices > List View. Click on a device to drill into Device Details > Troubleshooting Tab. The grid on this tab will show activity on the device and provides filtering options to show information 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
- Once 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 will not receive the updated options as these can only be updated when an "InstallApplication" command. This is the only command that can update the locally cached PKGInfo files on the device. In order to update the scripts, administrators will have to manually select all of the devices which have the software installed and repush the command. Repushing the command will update the respective cached PKGinfo file with the latest information.
Note: Repushing the command will NOT reinstall the application unless there is a change in the software version. Munki is has mechanisms in place to not reinstall software when the application is already installed.
- If a package has a dependency on another package or software then an administrator will have to manually provide a required key in the pkginfo of the package with a dependency. Providing the key in the pkginfo is the only way for Munki to recognize if there are any dependencies, and determine the sequence of installation steps for such dependent packages. Unless otherwise specified, packages are installed in random order. Such package installation will fail if a package dependency is not met during the installation.
Example: Netbeans requires that Java be present and installed on the machine. Netbeans will not implicitly install Java while installing the Netbeans software package. Even if administrators attempt to install Netbeans without utilizing Munki or using standalone Munki, the installation will fail and will prompt the administrator to first install Java before installing Netbeans.
- For packages which have the same receipts array with same version even on an upgraded package, Munki will not be able to detect that a new package is an upgraded package. The reason is that the receipt array has the same version as the previous package. The impact of duplicated receipts arrays is that the packages will not be installed on User machines as Munki cannot determine that a new version needs to be installed.
Note: The best solution for packages with duplicate versions in the Receipts Array is to use an Autopkg Recipe, which adds an installs array in the pkginfo. This method allows Munki to detect upgraded packages; alternatively an administrator can manually add an installs array into the pkginfo.
Example: Wireshark is an example of a package which has identical receipts which contain the same version, thus Munki cannot detect the when upgraded packages are deployed.
Other Languages: 日本語