Running Batch/VBS Scripts when Connected/Disconnected
Viscosity Windows allows you to run custom Batch (.bat) or Visual Basic/VBS (.vbs) scripts when your connection connects or disconnects. This can allow you to automate common tasks, such as connecting to file servers, opening web pages, opening applications, and controlling any application that is scriptable in Batch or VBS.
Selecting Scripts To Use
Viscosity makes it easy to specify scripts to run when a connection connects or disconnects, and allows you to specify different scripts for each connection. You can specify a script like so:
- Open Viscosity's Preferences window
- Select the connection you wish to add a script to and click the Edit button
- Click the Advanced tab
- Click the Select button next to time you would like the script to run, browse to the script on your hard drive then click Open.
- Click Save.
Viscosity offers three times to run a script during the connection cycle. Before Connect will run a script right when you click to connect a connection. Connected will run a script when the connection is connected and active, and Disconnected will run a script when the connection has completed it's disconnect procedures.
Administrator or Elevated Commands
Viscosity runs as a standard user on your system, this means scripts or commands that require elevation or administrator rights to run will not work. If you wish to run scripts which require elevation to function correctly, you have a few options. The simplest method is to run Viscosity elevated, however we do not recommend this and doing so is at your own risk as it gives Viscosity more access to your system than it otherwise needs.
Alternatively, you may wish to use Viscosity's Scripting System. Instead of having a Before Connected Script in Viscosity, you can instead run your script directly, elevating it if required, and then instruct Viscosity to connect a specified connection.
You can also use OpenVPN's scripting system for running scripts requiring elevation, you can find more information on this in our Preventing Network Leaks Documentation.
Writing Scripts
Writing scripts in Windows is quite simple. Follow the instructions below to create a script.
- Open notepad by going to Start->Programs->Accessories->Notepad
- A new blank window should appear. Enter the the following as a simple script:
MsgBox "Hello There!"
- Go to File->Save.
- Change the "Save as type:" to All Files, and enter a name for your file followed by .vbs. If you are creating a Batch script, append .bat instead.
- Test the script by double clicking it where you saved it.
Accessing Connection Details
When running Viscosity 1.9 or a later, it's possible to access certain VPN connection details from your scripts. The following attributes are available:
- displayName: The display name of the VPN connection.
- ipv4Address: The IPv4 address and subnet mask assigned to the VPN connection (if applicable).
- ipv6Address: The IPv6 address and prefix assigned to the VPN connection (if applicable).
- serverIPAddress: The IP address of the VPN server. This may be an IPv4 or IPv6 address.
- interface: The network interface of the VPN connection (for example "utun10").
- username: The username used for authentication (if applicable).
These items can be accessed from batch scripts for example via standard environment variables. For example, the following batch script snippet will display these details in a separate command prompt window:
start "" cmd /c "echo I am a connection script for connection '%displayName%'. The IPv4 address is '%ipv4Address%'. The IPv6 address is '%ipv6Address%'. The server's IP address is '%serverIPAddress%'. The network interface is '%interface%'. A username of '%username%' was used.&echo(&pause"
Setting Pre-Connection Credentials
When running Viscosity 1.9 or a later, it is possible to set the username, or username & password for the connection to use.
To prefill a username to appear in the Username & Password dialog for the connection, use the following from a batch script:
@echo off echo username "My Username"
To prefill a username and password to be used for the connection and no Username & Password dialog to appear, use the following from a batch script:
@echo off echo userpass "My Username" "My Password"
Quotes are only required if there are spaces in the output. Quotes can also be included in a username or password by escaping them. For example:
@echo off userpass username password
@echo off username "\"Quoted\" user"
When running Viscosity 1.10.5 or a later it's also possible for a script to return a two-factor challenge response. A challenge returned by a script will only be used once. The same quoting/escaping rules as documented above apply.
To return just a challenge response, end your batch script with the following:
@echo off echo challenge "MyChallengeResponse"
To return a username and password as well as a challenge response, use the "userpass" command from above and specify the challenge response as a third parameter, for example:
@echo off echo userpass "MyUsername" "MyPassword" "MyChallengeResponse"
Common Tasks
The following are example VBS or Batch script snippets for common tasks. These can be combined to create your Connected/Disconnected scripts.
Mount a Network Drive
The following Batch script can be used to mount a network drive to a remote file server. 'Z:' can be changed to any drive letter you require. Place the following code in your Connected script.
@echo off
- net use Z: \\server\share
Place the following code in your Disconnected script to disconnect the network drive when the VPN connection is terminated.
@echo off
- net use Z: /delete
Display A Message To The User
The following VBS script can be used to display a message to the user when they connect. It could be used to display a welcome message, instructions or even Terms of Use for your service. Place the following code in your Connected Script.
MsgBox "Hello There!"
Open A Webpage
The following VBS script will automattically open the user's default web browser and go to the specified web page. This could be used to automatically open a company's Intranet webpage, display a welcome webpage, etc.
URL = "http://www.thesparklabs.com"
- Set objShell = CreateObject("Wscript.Shell")
- objShell.Run(URL)
Close A Program
The following VBS script will automatically close/kill a running process when run. This is handy for when you want a close a program when your VPN disconnects for example. Simply replace 'notepad.exe' below with the name of the executable you want to kill. There is a caveat to this, Viscosity must be running with the same privileges or higher than the user that started the application.
Option Explicit
- Dim objWMIService, objProcess, colProcess
- Dim strComputer, strProcessKill
- strComputer = "."
- strProcessKill = "'notepad.exe'"
- Set objWMIService = GetObject("winmgmts:" _
- & "{impersonationLevel=impersonate}!\\" _
- & strComputer & "\root\cimv2")
- Set colProcess = objWMIService.ExecQuery _
- ("Select * from Win32_Process Where Name = " & strProcessKill )
- For Each objProcess in colProcess
- objProcess.Terminate()
- Next
- WSCript.Echo "Just killed process " & strProcessKill _
- & " on " & strComputer
- WScript.Quit
- ' End of WMI Example of a Kill Process