App Support.

We're here to help.



Bundling Viscosity with VPN Connections & Preferences (Windows)

Viscosity has been designed so it can be bundled with pre-configured connections and preferences so you can distribute a single installer, ready to go to your clients and customers, friends or family.

Requirements

You require a few things in order to bundle Viscosity for Windows:

  • Inno Setup Unicode: http://www.jrsoftware.org/isdl.php#stable
  • The latest version of Viscosity for Windows.
  • Your connections. We highly recommend you use connections that have been exported from Viscosity, or taken from your Viscosity Preferences folder, located at C:\Users\<Your username>\AppData\Roaming\Viscosity\OpenVPN or C:\Documents and Settings\<Your username>\Application Data\Viscosity\OpenVPN if you use Windows XP. You can access this folder on all OSes by typing “%appdata%\Viscosity” directly into the address bar of an explorer window.

Getting Started

  • Download the bundle package for Viscosity 1.9+: win_bundle_example.zip
  • Extract the bundle somewhere to your computer
  • Place the latest version of the Viscosity for Windows installer in this folder, ensuring it remains named "Viscosity Installer.exe".


  • Go into the "Preconfigure" folder. Place your Settings.xml and GlobalSettings.xml files in this folder. Please scroll down further for how to configure Settings and GlobalSettings.

Bundling in Connections

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 of Viscosity to shared PCs.

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 you will need to run a bundled installer as the user who will use Viscosity and alter the bundled setup.iss file accordingly. If that user does not have Admin rights to install Viscosity, you will need to push configuration files by other means, for example via Group Policy. Instead, consider using the instructions here to deploy the Viscosity application with settings/license data, 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 will need to be pushed by other means. Packaging the driver is beyond the scope of this guide. Also note that Viscosity on Windows 10 2004 onwards supports many devices via the cryptoapicert command without the need for additional drivers or libraries.

Connections

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 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.


Connection Ordering

The order connections appear in Viscosity's menu can be controlled by their folder 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 above) 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, you may have a connection for users to use from Home, and several to use from Work. You can organise your directory structure in a Connections folder like the following:


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

Bundling in Settings

Any setting in Viscosity can be pre-set by bundling in a custom settings file. This file is stored at %appdata%\Viscosity\Settings.xml. Viscosity has a great deal of options, so the process below is generally the recommend method for creating this file.

  1. First, configure Viscosity how you wish in the GUI. If you wish to bundle Viscosity with a license key, make sure you register Viscosity from Preferences->About using your license details. Exit Viscosity.
  2. Next, navigate to %appdata%\Viscosity and take a copy of Settings.xml and place it in your Preconfigure folder.
  3. Open the copy of Settings.xml using a text editor, we recommend Notepad++ (A free text editor), however any editor should be fine. You should see settings listed in key (the setting name), and string (the value of the key in the tags directly below it).
  4. Only keep 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 explicitly set, as many others are machine specific and may cause issues. For example, the "ConnectionOrder" and "Launch" options should not be kept, as it can cause some issues being machine specific options.

    <?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>BlockIPv6</key>
    <string>YES</string>
    <key>License</key>
    <string>XXXXXX</string>
    </dict>
    </plist>
  5. Save your changes.

Global Settings

Viscosity settings are stored per-user on a system. If you wish for some settings to be set for ALL users, you can define a GlobalSettings.xml file. Make a copy of your edited Settings.xml file, then rename it to GlobalSettings.xml within your Preconfigure folder. Edit this file and make the changes you wish. Remember, anything you set in GlobalSettings.xml will be set for a user each time they start Viscosity, so setting the system tray icon for example is not generally advised as many users like different look and feels.

The GlobalSettings.xml file acts by importing its settings for a user each time Viscosity is started. It is stored in the installation directory for Viscosity (generally C:\Program Files\Viscosity\GlobalSettings.xml), which of course required Administrator Privileges to modify after installation.).

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 settings xml. 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.

Bunding in Menu Items

Viscosity allows for custom menu items to be added to the primary menu. These items consist of a custom icon and name, and when selected invoke a custom batch (.bat) 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 to be added so users can easily navigate to support webpages and account status information.

A custom menu item consists of a bundle name, an icon, and a batch script. A menu item can be created by a few simple steps:

  1. Create a new folder called “Example.viscositymenuitem”. Replace “Example” with the name you desire for your menu item.
  2. Create the batch script you wish to be invoked when the user clicks on this menu item. This script must be called “action.bat”, and placed in the folder created above. For information on how to create batch scripts, as well as some examples, please refer to the Controlling Viscosity with Scripting (Windows) article.
  3. Copy the icon you would like the menu item to have into the folder created above. It must be named “icon.png” and should be a 16x16 pixel PNG image.

In order to include your new menu items, the viscositymenuitem folders must be placed in a new folder called MenuItems created in the Preconfigure bundle folder.

Compiling

  1. Go back to the top directory of the bundle, right click "setup.iss" and select "Open with Inno Setup" (or your preferred text editor.
  2. You can alter the values of "AppName", "AppPublisher", "AppVersion", "AppPublisherURL", "AppSupportURL", "AppUpdatesURL" and the Languages section to reflect your company and requirements. It is not necessary to generate a new GUID for your installer unless you wish it to have an uninstaller.
  3. If you are using MenuItems or GlobalSettings, ensure to uncomment the installation lines by removing the semi-colon in front of them.


  4. If your bundle is only intending to install the bundle for a single user, ensure to comment out the installation to Managed, and uncomment the installation to {userappdata}
  5. Go to File->Save to save any changes you make.
  6. Go to Project->Compile Project

Your bundled installer will now be located in the Output Folder. We recommend you test the installer to ensure it has the desired effect.

Compiling on Ubuntu

Compiling your bundle on Ubuntu can be useful if you do not have access to a Windows computer, you wish to compile bundles on the fly or automatically on an Ubuntu (or similar) server.

To get your Ubuntu server ready, you will first require Wine and InnoSetup.

First install Wine:

sudo apt-get install wine

Next, install InnoSetup:

wget http://www.jrsoftware.org/download.php/is.exe
wine ./is.exe “/SP-“ “/VERYSILENT”


To compile your bundle on Ubuntu, first complete all steps above to setup your bundle including configuring your setup.iss file. Then, change into your bundle folder and run the following command:

wine "C:\Program Files (x86)\Inno Setup 5\ISCC.exe" "./setup.iss"

You can then find your compiled setup.exe in ./Output/setup.exe. As above, we recommend you test the installer to ensure it has the desired effect.

Creating an MSI (Microsoft Installer)

Some deployment tools may require an MSI instead of an EXE installer. At this time we do not provide pre-built MSIs for Viscosity, however one can be created by wrapping the Viscosity Installer executable using one of the various packaging tools.

One way to wrap Viscosity's installer into an MSI is using the WiX Toolset. First, install the .NET Framework Developer pack from Microsoft's website. Then install the latest version of WiX (version 4.0 at the time of writing) using the following command:

dotnet tool install --global wix

Next, grab the example WiX configuration and copy it to a new folder: viscosity_msi.wxs

Open the viscosity_msi.wxs file using a text editor. Update the ProductVersion on line 1 to match Viscosity's current version. On line 3, replace the text "UPGRADECODE" with a unique UUID. Every time you build a new MSI installer for a new version of Viscosity you should generate a new UUID. You can generate a unique UUID by typing the uuidgen command in the Command Prompt (if the Windows SDK is installed), or by typing the New-Guid command into a PowerShell prompt.

Now download the latest version of Viscosity here and copy it to the same folder as viscosity_msi.wxs. Either rename the Viscosity Installer to match the ExeSourceFile name defined in the wxs config (Viscosity Installer.exe), or change the ExeSourceFile constant in viscosity_msi.wxs (line 2).

Next, build the MSI. To do this, change your command prompt into the directory containing viscosity_msi.wxs and the Viscosity installer, then run the following command:

wix build -o "Viscosity Installer.msi" "viscosity_msi.wxs"

A new file should be generated called "Viscosity Installer.msi". You should then be able to deploy Viscosity using this MSI package.

Please Note: If you intend to use MSI to update your installation as well, you will need to plan ahead. Please check the WiX Toolset documentation on upgrading as this script does not include it.

Signing the Installer (optional)

Once your new bundle is built, you may notice when you run it that Windows treats the installer as untrusted, or the installer may even be blocked from running by SmartScreen. In order for your installer to be trusted by Windows, it must be signed.

First, you will need a Code Signing certificate. These are available for purchase from most CAs where you buy purchase SSL certificates for your website and range in price. Please note you do not need an EV Certificate, only a basic Code Signing certificate.

Once you have purchased your certificate, it should be sent to you, or available for download, as a pfx or p12 file. Save this somewhere and keep it safe. You will also need to check with your certificate supplier for the address to their time stamping server. This should be something like http://timestamp.yourcertificatesupplier.com.

Next, you will need a copy of SignTool. This is included in the Microsoft SDK, download and install it from here.

Alternatively, some code signing certificate suppliers also provide a simple tool for code signing, you may wish to make use of this to save some time.

Once you have all of the above, code signing your installer is quite easy, simply open a Command Prompt and run the following command:

"C:\Program Files (x86)\Windows Kits\10\bin\x64\signtool.exe" /tr <url for timestamp server> /td sha256 /fd sha256 /f C:\path\to\your\certificate.pfx /p <certificatepassword> C:\Path\to\your\ViscosityInstaller.exe

You should see output that the file is successfully signed, you can check this by right clicking the installer and selecting Properties, you should then see a Digital Signatures tab.

Enterprise Deployment

Your bundled installer can be run silently. To do so, run your installer with the flags:
/SP- /VERYSILENT

If you are deploying Viscosity without a user logged in, make sure to include the /NORUN option in your setup.iss file.

We also recommend if running the installer unattended, or without a desktop accessible to the installer, that any requirements are installed before running the Viscosity Installer. If you do not pre-install requirements, we also recommend running the installer with the /NORESTART flag, as well as adding this option in your setup.iss file.

It is also common for many packaging tools to not have access to the Windows certificate store for driver signing. This may block installation of the Viscosity driver or the Viscosity service. The driver will automatically install itself after installation if this occurs on Windows 10+, so there are no additional steps needed in this scenario, however the first connection may take longer. If the service is blocked, you may need to instruct your package management tool to install and start the service post installation using a tool like sc.exe which is built into Windows.

Starting Viscosity at Login

If your package includes the Start Viscosity at Login setting in the Settings.xml file, Viscosity will set Start at Login for the user at first launch. Alternatively, the registry option can be uncommented into the setup.iss template.

If the setup.iss template option to enable Start at Login is enabled machine-wide, this will disable control of the option in Viscosity unless a user has Admin rights on the machine to disable this option via Task Manager.

Updating Viscosity

To update an existing installation of Viscosity, simply create a new package using the same steps above and deploy it. If you do not want to include updated settings or preferences and only update Viscosity, you only need to push the Viscosity installer. Viscosity will detect a new/updated preconfiguration folder on first launch if one is included with an update.

If you are using a Managed bundle, this can be updated. To do so, delete the existing bundle and replace it with a new one. This can be done to update connections or settings.

If your users do not have Administrator rights, we recommend bundling Viscosity with the AutoUpdate setting disabled, and push updates via your preferred package manager.

Uninstalling Viscosity

To uninstall Viscosity, remove the application via Apps and Features, and then remove ProgramData\Viscosity if you have used a Managed Viscosity install for all users.

Viscosity Requirements

As of Viscosity 1.10, Viscosity requires the following extra requirements that, while usually already on your system, may need to be installed:

  • .NET 4.8
  • VC Runtime 2015-2019 (x64, x86 or arm64 depending on architecture of Windows)
  • (Optional) Microsoft Edge WebView2 Runtime (For SSO/SAML Support)

Viscosity's installer will automatically install these if they are missing.

Optional components are not installed by default. To install these, they must be checked at the components screen when installing, or if installing silently, include the following flag when running the installer:
/INSTALLOPTIONAL

If optional components are missing but required for a function in Viscosity, Viscosity will prompt the user that the component is missing and provide instructions on where to download and install the missing optional component from. Components generally require elevated permissions to install, so keep this in mind when pushing Viscosity out in an enterprise environment without installing optional components if users might need them.