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
• ISTool (If you would like to make advanced changes to the installer) - http://sourceforge.net/projects/istool/
• 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.

How To Configure Your Bundle

• Download the bundle package here
• 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.
• Place your connections in one of the three Connections folders. Connections and their certificates must be contained in their own folder. The folders represent the following and import in the following order:
  • 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.

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.

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.

How to Bundle 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.

A second Global Settings file, called GlobalSettings.xml, can also be defined. While Settings.xml files only store settings for that user (being contained in a users Application Data folder), GlobalSettings.xml allows you to define settings for all users. GlobalSettings.xml 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.).

To configure Settings files, first you should setup Viscosity how you wish your users to view it, then Exit Viscosity.

Next, navigate to %appdata%\Viscosity and take a copy of Settings.xml and place it in your Preconfigure folder. 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).

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" option should not be kept, as it can cause connection ghosting.

Save your changes.

If you wish for some settings to be permanently 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.

How to Bundle Menu Icons

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:

• Create a new folder called “Example.viscositymenuitem”. Replace “Example” with the name you desire for your menu item.
• 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 Running Batch/VBS Scripts when Connected/Disconnected in Viscosity for Windows article.
• 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.

How to Compile Your Bundle

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

• Go to File->Save to save any changes you make.
• 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.

How to Compile Your Bundle 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.