App Support.

We're here to help.



Bundling Viscosity with VPN Connections & Preferences (Mac)

Viscosity has the ability to be bundled and distributed with settings, connections, menu actions, and license details so end-users don't need to perform any steps to setup Viscosity. They can simply install and run Viscosity and all bundled settings and data will be automatically imported.

The sections below detail how to utilise Viscosity's bundling feature.

Requirements

Connections, settings, menu items, and license details can all be included alongside Viscosity in an installation bundle that can be easily distributed to end-users so no additional actions are required by them to get started. To get started you will need the following requirements:

  • A copy of the latest version of Viscosity
  • A copy of our viscosity_installer_1.4.tgz template installer package
  • Packages, a free installer editor for macOS
  • Optional: An Apple Developer Account

Getting Started

To get started you will first need to ensure that you have the latest version of Viscosity installed and configured on the machine you'll be using for making the bundled version of Viscosity. It should be configured with the connections you wish to include in the bundled version (if applicable) and/or the settings you wish to have included (if applicable).

Next download and install the "Packages" application linked in the above section. This will be used to edit and construct an installer for Viscosity.

Finally, download and extract the template installer package also linked to in the above section. Once extracted you should see the following files and directories in the Finder:



Before the installer can be customised it is first necessary to copy the Viscosity application itself into the installer template. This can be done like so:

  1. Open the Applications folder in the Finder (or the folder where the Viscosity application is located if it was installed to a different location).
  2. Locate the Viscosity application, Right-click or Control-click on it, and select the "Copy Viscosity" option.
  3. Open the "Viscosity Installer" template folder (from the extracted package) in the Finder. Right click on the folder named "Viscosity" and select the "Paste Item" option. This will place a copy of the Viscosity application inside the "Viscosity" folder.



Once this is done pleased proceed to the following sections to being bundling Viscosity.

Bundling in Connections

Bundling Viscosity with connections is simply a matter of copying connections into place inside the appropriate folder. To get started, open the "Preconfigure" folder inside the "Viscosity Installer" template folder.



If you only wish to bundle Viscosity with settings and not any connections, please skip to the next section.

Connection Folder

Inside the Preconfigure folder there are a number of different folders for connections. Each folder deploys Viscosity connections in a different manner:

  • Connections-Overwrite: Connections in this folder will overwrite connections of the same name already listed in Viscosity. For example, if the user already has a connection named "My Connection", and there is a bundled connection named "My Connection", the existing connection will be deleted and the bundled connection imported. If a connection of that name doesn't already exist a bundled connection will be imported normally.
  • Connections-Append: Any connections in this folder will be automatically appended to the user's existing connections. If a connection already exists with the same name as a bundled connection, the bundled connection will be imported using an alternate name (for example "My Connection 1" instead of "My Connection").
  • Connections: If Viscosity already contains connections with the same name as connections in this folder, the user will be prompted with the choice to to overwrite those connections, or for them to be appended with an altered name (for example "My Connection 1" instead of "My Connection"), or not import them at all.

Make a note of the folder type you wish to use. You'll need to copy into this folder the connections you wish to bundle Viscosity with. While raw configuration files can be copied in, it is strongly recommended you copy the connections from Viscosity itself like so:

  1. Using the Finder navigate to "Your Home folder/Library/Application Support/Viscosity" (you can easily get to your Library folder by holding down the Option key and clicking on the "Go" menu in the Finder).
  2. Inside the OpenVPN directory can be found the connections created in Viscosity. Copy these into the connections folder/s you created above.

Connection Ordering

The order connections appear in Viscosity's menu can be controlled by their directory file names: Viscosity will process them in alphabetical order. By default the connections in your connections directly above will have names like "1", "2", "3", etc., however these can be named anything. For example, you may like to call the connection you want to appear at the top of the list "a", the connection under it "b", the connection under that "c", and so on.

If you are also bundling Viscosity with a preferences file (as outlined below) it is recommend the "ConnectionOrder" key and associated array be removed from the file to avoid connection ordering conflicts.

Connection Folders

As well as controlling the order connections appear in, you can also organise them into sub-directories, which will appear as folders in Viscosity's menu. For example, if you have two office locations, and you have 6 connections you wish to be grouped into folders for each location, your bundled connection folder might look something like:



The folder created in Viscosity's menu will have the same name as the directory.

Bundling in Settings

Any setting in Viscosity can be pre-set by bundling in a custom settings file. This file should be named "com.viscosityvpn.Viscosity.plist", and is a standard XML style file. It should be placed inside the Preconfigure folder inside the "Viscosity Installer" template folder. Viscosity has a great deal of options, so the process below is generally the recommended method for generating this settings file:

  1. Using the Finder navigate to "Your Home folder/Library/Preferences" (you can easily get to your Library folder by holding down the Option key and clicking on the "Go" menu in the Finder).
  2. Find the com.viscosityvpn.Viscosity.plist file and copy it into your Preconfigure folder.
  3. Recent versions of macOS store the plist file in a "binary" format, and so it's necessary to convert this to XML before editing. This can be done by running the following command in the Terminal, replacing "/path/to" with the path to your copied copy of the plist:
    plutil -convert xml1 /path/to/com.viscosityvpn.Viscosity.plist
  4. Open the copied version of the com.viscosityvpn.Viscosity.plist file using a text editor. We recommend BBEdit (a free text editor), however any plain text editor should work. You should see settings listed in key (the setting name) and value (the value of that key in tags directly below it).
  5. Only keep the settings you wish to bundle into Viscosity, and remove all other settings. It is very important to remove any settings you don't want to explicity set, as many others are machine specific and may cause issues (e.g. the "ConnectionOrder" option should not be kept, as it can cause connection ghosting). For example, a simple settings file that prevents the first-launch Welcome window from appearing, and includes the license data, would look like:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
    <key>FirstRun</key>
    <false/>
    <key>License</key>
    <string>XXXXXX</string>
    </dict>
    </plist>
  6. Save your changes.

Please note that bundling in a settings file is not compulsory: in most cases Viscosity's default settings should be fine.

Bundling in the Start Viscosity at Login Setting

It's common to have Viscosity automatically start at login so that its icon is available in the menu bar. However there is no corresponding setting in Viscosity's preferences file for this, as the Start Viscosity at Login option actually corresponds to whether Viscosity is listed as a Login Item or not.

To have the installer package automatically add Viscosity as a Login Item for the user, it's necessary to manually add a "StartAtLogin" key to the bundled settings file like so:


<key>StartAtLogin</key>
<true/>

For example, with the option added to the settings example in the prior section:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>FirstRun</key>
<false/>
<key>License</key>
<string>XXXXXX</string>
<key>StartAtLogin</key>
<true/>
</dict>
</plist>

Bundling in a License/Registration Details

For those with volume license/serial numbers, Viscosity can be bundled with your license details so end-users do not need to do anything to register Viscosity. To do this simply follow the "Bundling in Settings" steps above, making sure to register Viscosity when configuring it (before copying over the setting file).

Do not attempt to copy-paste the serial number directly into the plist. Viscosity instead stores registration data in an encoded format. Be sure to first register the installation of Viscosity you're using as the template, and then follow the "Bundling in Settings" section above to include the encoded license data.

Bundling in Menu Items

Viscosity allows for custom menu items to be added to the primary menu. These items consists of a custom icon and name, and when selected invoke a custom AppleScript script. Using this functionality you can add some basic functionality, such as opening a webpage or email client, to custom user interfaces. We encourage items such as "Support" and "My Account" options be added so users can eaisly navigate to support webpages and account status information.

Creating a Menu Item

A custom menu item cosists of a bundle name, an icon, and an AppleScript script. A menu item can be created like so:

  1. Create a new folder and name it "Example.viscositymenuitem". Replace "Example" with the name you desire for your menu item.
  2. Create the AppleScript script you wish to be invoked when a user clicks on this menu item. This script should be called "action.scpt" and placed in the folder created above. For information on how to create AppleScript scripts, as well as some examples, please refer to Running AppleScripts When Connected/Disconnected.
  3. Copy the icon you would like the menu item to have into the above folder. It should be named "icon.png", and be a 16x16 pixels PNG image.

Including the Menu Item

Custom menu items should be copied into this MenuItems folder inside the "Preconfigure" folder for the "Viscosity Installer" template directory.

Building the Installer

Once the steps above have been completed your bundled version of Viscosity can be packaged up for distribution to end-users. Before proceeding please ensure that the "Packages" software is installed as detailed in an earlier section.

To build the installer containing your bundled version of Viscosity please follow the steps below:

  1. Double-click on the "Viscosity Installer" file located in the "Viscosity Installer" template folder. It should automatically open in the Packages application. If it doesn't the Packages application can be manually launched and the file opened.
  2. Go to the "Build" menu and select the "Build" option. The package should now build. If an error occurs please make sure that all files inside the "Viscosity Installer" template are in their correct location.
  3. Switch back to the Finder and open the "build" folder inside the template folder. Your newly build installer bundle should be there with the name "Viscosity Installer.pkg".



The "Viscosity Installer.pkg" installer can now be distributed to your end users.

Signing the Installer (Optional)

macOS includes a security feature called Gatekeeper. Gatekeeper is on by default, and requires that applications and installers downloaded from the Internet be "code signed" using an Apple issued certificate. Users attempting to run the installer generated above may receive the following message if they have downloaded it from a website or received it remotely (such as via email):



A user receiving the "“Viscosity Installer.pkg” can’t be opened because it is from an unidentified developer." error can still run an unsigned installer by right-clicking on it and selecting the "Open" option. They can then click the "Open" button that now appears.

To avoid the above message entirely the installer can be signed using an Apple issued "Developer ID Installer" certificate. This is the recommended approach, and requires signing up for an Apple Developer Program account if you or your organisation does not already have one. Anyone can sign up, however membership is not free (it is currently $99 USD at the time of writing). For more information please visit the Apple Developer Program website.

Once you have an Apple Developer Program membership, you can create and download a "Developer ID Installer" certificate using the instructions below. Please be aware that Apple regularly makes changes to the account section and so you may need to vary these steps where appropriate.

  1. Log into the Apple Developer Program website
  2. Click on the "Certificates, Identifiers & Profiles" section. From the drop down menu located at the top left select "OS X" to change to the macOS section.
  3. Click on the "+" button to the right. Select "Developer ID" in the production section and click "Continue". Select "Developer ID Installer" and click "Continue".
  4. Follow the instructions to generate a CSR file and then click "Continue". Upload the CSR file and then click "Continue" again.
  5. Click the "Download" button to download your new certificate. Locate the downloaded certificate and double-click it to import it into the Keychain.
  6. Locate the certificate in the Keychain Access application and make a note of its name (you will need this below). It should be named something like "Developer ID Installer: Your Name (ABCDE12345)".

The above instructions only need to be followed once. Once completed the steps below can be used to sign the installer each time a new one is made:

  1. Open the Terminal application (located at /Applications/Utilities/Terminal)
  2. Enter the following command and press Enter. Make sure you replace "Developer ID Installer: Your Name (ABCDE12345)" with the correct certificate name found in the steps above. Replace "/path/to/" with the path to the built installer.
    productsign --sign "Developer ID Installer: Your Name (ABCDE12345)" "path/to/Viscosity Installer.pkg" "path/to/Viscosity Installer Signed.pkg"
  3. If prompted click the Allow button to allow the productsign tool access to the certificate.
  4. If successful a "Viscosity Installer Signed.pkg" installer should now be present.

The "Viscosity Installer Signed.pkg" installer can be renamed if desired and distributed to end users.

Notarizing the Installer (Optional)

If you plan on distributing your installer to users running macOS 10.15.4 or later, and you've signed the installer using the instructions above, then it is also recommended the installer be notarized. Notarization involves uploading the installer to Apple's servers so they can scan it for any malicious components and security issues.

Software that isn't notarized will display a Gatekeeper error message on macOS 10.15.4+ and be blocked from running. To avoid this message your signed installer can be notarized using the steps below.

  1. Download and install the Command Line Tools for Xcode. If Xcode is already installed, this can be done by running the following command in the Terminal, and then clicking the "Install" button. This command only needs to be run once.
    xcode-select --install
  2. Update the following command with your correct Apple developer details and path to your installer. Then run the command in the Terminal.

    The password should not be your Apple ID password, but instead an "App-Specific" password. You can generate an App-Specific password by logging into your Apple ID account, clicking on the "Generate password..." link, and entering a label (e.g. "Viscosity Installer").

    The "asc-provider" value should be the "Short Name" of your Developer ID. This is typically just the name of your Developer ID without spaces. For example, the short name version of "My Company Inc" would be "MyCompanyInc".

    xcrun altool --notarize-app \
    --primary-bundle-id "com.sparklabs.pkg.ViscosityInstaller" \
    --username "[email protected]" \
    --password "password" \
    --asc-provider "DeveloperIDShortName" \
    --file "path/to/Viscosity Installer Signed.pkg"
  3. Wait until you receive an email from Apple indicating the notarisation was successful. Generally this takes a few minutes.
  4. You can optionally staple the notarisation to your package (for when installing the package on computers with no internet connection) with the following command:
    xcrun stapler staple "path/to/Viscosity Installer Signed.pkg"

Creating an Installer on Linux

If you are dynamically creating packages for users instead of by hand (for example, if every user needs a different set of certificate files, or a different serial number), you may need to create these packages on Linux if your server infrastructure is Linux based. The following instructions outline how to create a bundled installer package on Ubuntu, and should work with other Linux distributions as well.

Before getting started you'll need to have created a bundled installer using the steps above to use as a base. You can then follow the steps below to convert this base installer to a format we can use on Linux.

  1. Follow the steps above to create an installer to use as a base and upload it to your Ubuntu machine. These steps will assume this is called "Viscosity Installer.pkg".
  2. Install xar using the following commands:
    wget https://github.com/downloads/mackyle/xar/xar-1.6.1.tar.gz
    tar -xvzf xar-1.6.1.tar.gz
    cd xar-1.6.1
    ./configure
    make; sudo make install
  3. Extract the base installer using the following command:
    xar -x -f "Viscosity Installer.pkg"
    cd Viscosity_Installer.pkg
    mkdir ScriptsDir; cd ScriptsDir
    cat ../Scripts | gunzip -dc |cpio -i
    rm ../Scripts

We have now finished extracting the installer package, and the above contents can be used as a template for dynamically creating installer bundles.

You can now edit the contents of the "Preconfigure" directory (in the current working directory), such as by replacing the license file, replacing connection certificates, modifying the available connections, etc. Once it has been customised please proceed to the steps below to re-create the installer.

  1. Make sure the current working directory is the ScriptsDir directory.
  2. Run the following commands to package up the updated contents:
    find . | cpio -o --format odc --owner 0:80 | gzip -c > ../Scripts
    cd ..; rm -R ScriptsDir
  3. Run the following commands to create the installer from the updated template:
    xar --compression none -cf "../Viscosity Installer (New).pkg" *

Signing the Installer on Linux

If you have created a signed base installer using the previous instructions, you can also create signed installers on Linux. First it is necessary to copy your Apple Developer ID identity to the Linux computer by following the instructions below:

  1. Open the Keychain Access application on macOS
  2. Locate the private key in the Keychain Access application. It should be named something like "Your Name Installer". Make sure it's the private key (rather than the public key).
  3. Right click on it and select the Export menu option. Make sure the File Format is set to "Personal Information Exchange (.p12) and Save the file. Enter a password to protect the file with when prompted.
  4. Copy the exported file to your Ubuntu machine.
  5. On the Ubuntu machine it's now necessary to convert the key file to a format that can be used for signing, as well as extract the signing certificates from the base installer:
    mkdir certs
    xar -f "Viscosity Installer.pkg" --extract-certs certs
  6. Enter the password protecting the file when prompted:
    openssl pkcs12 -in "My Name Installer.p12" -nodes | openssl rsa -out key.pem

You now have the codesigning files required to sign installer bundles on Linux. The instructions above can be followed to create a customised installer bundle on Linux. Once you have the bundle, the instructions below can be used to sign it.

  1. Enter the following commands to create a signature:
    : | openssl dgst -sign key.pem -binary | wc -c > siglen.txt
    xar --sign -f "Viscosity Installer (New).pkg" --digestinfo-to-sign digestinfo.dat --sig-size `cat siglen.txt` --cert-loc certs/cert00 --cert-loc certs/cert01 --cert-loc certs/cert02
    openssl rsautl -sign -inkey key.pem -in digestinfo.dat -out signature.dat
  2. Now enter the following commands to apply the signature
    xar --inject-sig signature.dat -f "Viscosity Installer (New).pkg"
    rm -f signature.dat digestinfo.dat siglen.txt

The installer package should now be signed and can be distributed to end users.