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.
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.
How To Configure Your Bundle
- Download the bundle package - 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.
- 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. If you wish to bundle Viscosity with a license key, make sure you register Viscosity from Preferences->About using your license details. 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 Custom 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:
- 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 Controlling Viscosity with Scripting (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.
Creating an MSI (Microsoft Installer)
Some deployment tools require an MSI. At this time, we do not provide MSI's for Viscosity, but one can be creating 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, grab the latest published stable release here (At the time of writing, 3.10).
Next, grab the example WiX configuration and copy it to a new folder: viscosity_msi.wxs
Grab 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 3).
Next, build the MSI. To do this, run the following commands:
- "C:\Program Files (x86)\WiX Toolset v3.10\bin\candle.exe" viscosity_msi.wxs
- "C:\Program Files (x86)\WiX Toolset v3.10\bin\light.exe" viscosity_msi.wixobj
A new file should be generated called "viscosity_msi.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.
- 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.