App Support.

We're here to help.



Deploying Viscosity on macOS using Munki

Munki is a popular tool for managing macOS software deployment in an enterprise environment. It allows macOS administrators to manage installing and uninstalling software on end-user machines. This includes handing mass installation of software, as well as a Managed Software Center program allowing users to install and remove approved software themselves.

This article details how to deploy and manage Viscosity installations in a Munki environment. Items covered include creating a Viscosity package suitable for deployment, how to optionally include pre-configured connections and settings, how to optionally bundle in Viscosity license data, and how to optionally track the number of volume license seats in use.


Requirements

This guide assumes that you already have a operational Munki setup. If this is not the case, or you'd like to create a new setup for testing, please refer to the Munki documentation detailing how to create a demonstration setup before proceeding.

To get started you will need the following requirements:

  • A copy of the latest version of Viscosity (version 1.8.1 or higher)
  • A working Munki setup
  • The Munki tools installed and configured on your local macOS machine
  • A copy of our viscosity_managed_installer_1.1.tgz template installer package
  • Packages, a free installer editor for macOS

VPN Connection Requirements

Viscosity supports a wide range of VPN configuration types and authentication methods. Some of these setups may require user-specific authentication files, or require additional software, both of which can complicate deployment using Munki. If you don't intend on including any pre-configured VPN connections alongside Viscosity please skip ahead to the next section.

Please refer to the below items to see if any apply to your OpenVPN setup:

  • User-Specific Certificate/Key Files: If your OpenVPN setup requires that each user's connection be configured with a unique certificate/key, then it's not recommended to use Munki for VPN connection deployment. Instead, consider using the instructions here to deploy the Viscosity application and settings/license data using Munki, and then have the user download their VPN connection separately (for example from a web portal) or use Viscosity's Import From Server feature.

    An alternative is to change your OpenVPN setup to no longer rely on unique per-user certificate/key files. For example, you could instead use a shared certificate/key file for all users, along with a username and password. However from a security standpoint we strongly recommend against relying solely a username and password for authentication.

    We recommend username/password authentication be combined with an additional method such as a One Time Password (OTP), two-factor authentication prompt (for example Google Authenticator, Duo Security, or Authy code), or token device (U2F device, PKCS#11 token, etc.). Please see our Knowledge Base for some server setup examples.
  • PKCS#11 Tokens and Smartcards: If your VPN connection uses a PKCS#11 device for authentication, it's highly likely it requires a PKCS#11 driver is installed (for example OpenSC). If this is not already installed as part of the computer's base image, then it's necessary to also have Munki install it. Packaging the driver is beyond the scope of this guide, however typically you'll want to repackage the PKCS#11 driver installer, as well as the Viscosity installer created as part of this guide, together as a metapackage.
  • TAP Connections: The vast majority of OpenVPN connections are TUN (Layer 3) based. However in the event you are using a TAP (Layer 2) based OpenVPN setup in a managed environment, it's worth pre-approving Viscosity's TAP driver. For more information please refer to Apple's User-Approved Kernel Extension Loading article.

Creating a Package

Before Viscosity can be added to the Munki server, a Munki package must be created. These steps are detailed below:

  1. Download and extract the managed template installer package linked in the requirements section above.
  2. Create a bundled version of Viscosity by following the instructions in the Bundling Viscosity with VPN Connections & Preferences (Mac) guide. However instead of using the template installer package linked in that guide, use the managed template installer package downloaded in the previous step.

    If you wish to have Viscosity updates managed by Munki as well, Viscosity's "Automatically check for updates" option should be turned off before bundling in settings. It's not necessary to sign the bundled installer.
  3. Open the Terminal application and run the following command (replace /path/to with the correct path to the bundled installer template directory created in the above step):

    cd "/path/to/Viscosity Managed Installer"
  4. Enter the following command into the Terminal. Replace "1.8.1" with the version of Viscosity being used, and change the Catalog from "testing" to the correct catalog to use, before executing the command.

    /usr/local/munki/munkiimport --name="Viscosity" \
    --displayname="Viscosity" \
    --description="VPN Client" \
    --pkgvers="1.8.1" \
    --minimum_os_version="10.11" \
    --category="Internet" \
    --developer="SparkLabs" \
    --icon_path="Viscosity/Viscosity.app/Contents/Resources/Viscosity.icns" \
    --postuninstall_script="Scripts/postuninstall.sh" \
    --catalog=testing \
    --subdirectory="apps/sparklabs" \
    --unattended_install \
    --unattended_uninstall \
    "build/Viscosity Installer.pkg"
  5. Enter y to the Import this item prompt.
  6. Choose n when prompted to Edit pkginfo before upload.
  7. Enter y to the Rebuild catalogs prompt.

Deploying Viscosity

To automatically deploy Viscosity to machines as a managed install, you'll need to add Viscosity to the appropriate client manifest. The steps below assume a client manifest named "site_default" already exists:

  1. Enter /usr/local/munki/manifestutil into the Terminal
  2. Enter the command add-pkg Viscosity --manifest site_default
  3. Enter exit

To instead list Viscosity as a package end-users can install from the Managed Software Centre, add Viscosity as an optional install to the appropriate client manifest:

  1. Enter /usr/local/munki/manifestutil into the Terminal
  2. Enter the command add-pkg Viscosity --manifest site_default --section optional_installs
  3. Enter exit

Starting Viscosity at Login

If your package includes the Start Viscosity at Login setting using the instructions in the bundling article, the managed installer package will automatically install a Launch Agent to start Viscosity at login for all users.

This differs from Viscosity's standard "Start Viscosity at Login" option, which normally installs Viscosity as a Login Item for just a single user. This means that on a managed install the "Start Viscosity at Login" option in Viscosity's Preferences window will have no effect: Viscosity will always start at login. If this behaviour isn't desired, the "StartAtLogin" setting should be removed.

License Seat Tracking

Munki supports tracking the number of seats in use for a license, making it easier to monitor and enforce the number of Viscosity installations (when using optional installs) in your deployment. It only tracks installations managed by Munki, so remember to still factor in manual Viscosity installs, installs on Windows machines, etc. when calculating volume license usage.

To get started, it's necessary to first install Sal (a Munki reporting add-on) on a server (likely the same as the Munki server). Further setup information can be found on Munki's License Seat Tracking wiki page.