Viscosity allows you to run custom AppleScript 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.

Selecting AppleScript 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:

1. Open Viscosity's Preferences window
2. Select the connection you wish to add a script to and click the Edit button
3. Click the Advanced tab
   
   
   
   

   
4. 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.
5. Click Save.

Viscosity provides three opportunities 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.

Writing AppleScript Scripts

Writing your own AppleScript scripts is fairly easy thanks to Apple's AppleScript Editor application. Follow the instructions below to get started writing simple AppleScripts:

1. Open the Script Editor application. This can be found at /Applications/Utilities/Script Editor.app
2. A new script editor window should appear. Input the following as a simple script:
   
   tell application "Viscosity" to display dialog "Test Script!" buttons "OK"
   
   
   
   

   
3. Press the "Run" toolbar button to test your code. If everything is working a window should appear with the text "Test Script!".
4. Go to the File menu and select Save.
5. Select a location to save the script to, and give it a name. In this instance we are going to leave the File Format as Script. Click the Save button.
6. Now follow the steps in the section above to input the script into Viscosity.

If your AppleScript interacts with the user interface it is necessary to associate such interaction with an application using AppleScript's "tell" command. For example while tell application "Viscosity" to display dialog "Test" and tell application "Finder" to display dialog "Test" will both work, simply putting display dialog "Test" will not.

Accessing Connection Details

When running Viscosity 1.9 or a later, it's possible to access certain VPN connection details from your AppleScript 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 using the "system attribute" command. For example, the following AppleScript snippet will display these details in a dialog window:

set dialogText to "I am a connection script for connection " & (system attribute "displayName") & ". The IPv4 address is " & (system attribute "ipv4Address") & ". The IPv6 address is " & (system attribute "ipv6Address") & ". The server's IP address is " & (system attribute "serverIPAddress") & ". The network interface is " & (system attribute "interface") & ". A username of " & (system attribute "username") & " was used."
display dialog dialogText

It should be noted that AppleScript has limited support for modern text encodings. If a connection's display name or username has non-ASCII (English) characters AppleScript may not correctly interpret the characters. In this case a workaround like set displayName to do shell script "echo $displayName" can be used to read the value correctly.

Setting Pre-Connection Credentials

When running Viscosity 1.9 or a later, it is possible for a Before Connect script to return a username, or both a username and password, to use for authentication. If both a username and password are specified, these will be used for authentication instead of prompting the user (or using details stored in the Keychain). If only a username is specified, this will be pre-filled into the username field when requesting credentials from the user.

To return just a username, end your AppleScript script with the following:

return "username MyUsername"

To return both a username and password, end your AppleScript script with the following:

return "userpass MyUsername MyPassword"

Quotation marks around the username and password are required if there are whitespace characters present. These should be escaped using a backslash character, for example:

return "userpass \"My Username\" \"My Password\""

If a username or password contain quotation marks, then these will also need to be escaped. For example, to return a username of My"Username:

return "username \"My\\\"Username\""

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 AppleScript script with the following:

return "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:

return "userpass MyUsername MyPassword MyChallengeResponse"

Common Tasks

The following are example AppleScript snippets for common tasks. These can be combined using the instructions above to create your Connected/Disconnected scripts.

Connect/Disconnect To A File Server

The following AppleScript can be used to connect to a AFP (Mac) file server. Place the following code in your Connected script.

tell application "Finder"
	mount volume "afp://serveraddress/sharename" as user name "username" with password "password"
end tell

Place the following code in your Disconnected script to disconnect the file server when the VPN connection is terminated.

tell application "Finder"
	eject "sharename"
end tell

Connect/Disconnect To A Windows File Server

The following AppleScript can be used to connect to a SMB/CIFS (Windows) file server. Place the following code in your Connected script.

tell application "Finder"
	mount volume "smb://serveraddress/sharename" as user name "username" with password "password"
end tell

Place the following code in your Disconnected script to disconnect the file server when the VPN connection is terminated.

tell application "Finder"
	eject "sharename"
end tell

Display A Message To The User

The following AppleScript can be used to display a message to the user. This could be used to display a welcome message to the user, instructions, or even Terms of Use. Place the following code in your Connected script.

tell application "Viscosity" to display dialog "Welcome Message" buttons "OK" default button "OK"

Open A Web Page

The following AppleScript will automatically 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 web page, display a welcome page, etc.

tell application "Finder" to open location "https://www.sparklabs.com"

Play A Sound

The following AppleScript will play a sound file. It can be pointed at the sounds included with Mac OS X, or pointed to a custom sound file.

set playsound to POSIX path of ("/System/Library/Sounds/Glass.aiff")
do shell script ("afplay " & playsound & " > /dev/null 2>&1 &")

Run A Shell Script

The following AppleScript will allow you to run a shell script. You can use this approach to run shell scripts instead of using OpenVPN's up/down commands (which are in use by Viscosity's DNS support).

do shell script "/path/to/script.sh"

By default AppleScript scripts have the same permissions as the user using Viscosity. If you need to explicitly run a shell script with administration rights, it can be done like so:

do shell script "/path/to/script.sh" user name "username" password "password" with administrator privileges