Introduction

Scripting and Plugins

Using a client-side up/down script

In this recipe, we will use very simple up and down scripts on the client side to show how

OpenVPN calls these scripts. By logging messages to a file, as well as the environment variables, we can easily see which information OpenVPN provides to the up and down scripts.

Getting ready

Install OpenVPN 2.1 or higher on two computers. Make sure the computers are connected over a network. Set up the client and server certificates using the first recipe from Chapter 2. For this recipe, the server computer was running Fedora 12 Linux and OpenVPN 2.1.1. The client was running Windows XP SP3 and OpenVPN 2.1.1.

How to do it...

1.Create the server configuration file:

proto udp port 1194 dev tun

server 192.168.200.0 255.255.255.0

tls-auth /etc/openvpn/cookbook/ta.key 0

persist-key persist-tun keepalive 10 60

topology subnet

user nobody

group nobody # nogroup on some distros

daemon

log-append /var/log/openvpn.log

save it as example6-1-server.conf.

154

Chapter 6

2.Start the server:

[root@server]# openvpn --config example6-1-server.conf

3.Create the client configuration file:

client proto udp

remote openvpnserver.example.com port 1194

dev tun nobind

tls-auth "c:/program files/openvpn/config/ta.key" 1

ns-cert-type server

script-security 2

up "c:\\program\ files\\openvpn\\scripts\\updown.bat" down "c:\\program\ files\\openvpn\\scripts\\updown.bat"

Note the backslashes: when specifying the ca, cert, key, and tls-auth directives, forward slashes can be used, but not for the up and down scripts! Save it as

example6-1.ovpn.

4.Next, on the Windows client, create the batch file updown.bat:

@echo off

echo === BEGIN '%script_type%' script === >> c:\temp\openvpn.log echo Script name: [%0] >> c:\temp\openvpn.log

echo Command line argument 1: [%1] >> c:\temp\openvpn.log echo Command line argument 2: [%2] >> c:\temp\openvpn.log echo Command line argument 3: [%3] >> c:\temp\openvpn.log echo Command line argument 4: [%4] >> c:\temp\openvpn.log echo Command line argument 5: [%5] >> c:\temp\openvpn.log echo Command line argument 6: [%6] >> c:\temp\openvpn.log echo Command line argument 7: [%7] >> c:\temp\openvpn.log echo Command line argument 8: [%8] >> c:\temp\openvpn.log echo Command line argument 9: [%9] >> c:\temp\openvpn.log set >> c:\temp\openvpn.log

echo === END '%script_type%' script === >> c:\temp\openvpn.log

155

Scripting and Plugins

5. Finally, start the OpenVPN client:

After the client successfully connects to the OpenVPN server, the log file c:\temp\openvpn.log contains an output similar to the following:

=== BEGIN 'up' script ===

Script name: ["c:\program files\openvpn\scripts\updown.bat"] Command line argument 1: [Local Area Connection 2]

Command line argument 2: [1500] Command line argument 3: [1541]

Command line argument 4: [192.168.200.2] Command line argument 5: [255.255.255.0] Command line argument 6: [init]

Command line argument 7: [] Command line argument 8: [] Command line argument 9: [] 7

…

script_type=up

[dump of environment variables]

…

=== END 'up' script ===

When the client disconnects from the server, the script is called again, with the exact same command-line parameters, but now the script_type is set to down.

Note that the first command-line argument contains the name of the TUN device. On Linux and Mac OS systems, this will generally be tun0 or tun1 but on Windows platforms, it is the actual name of the TAP-Win32 adapter.

How it works...

After the initial connection is made with the OpenVPN server, but before the VPN is fully established, the OpenVPN client calls the up script. If the up script returns with an exit code not equal to zero, the connection sequence is aborted.

Similarly, when the connection is shut down the down script is executed after the VPN connection has been stopped.

156

Chapter 6

Note the use of the double backslashes (\\) in the up and down directives: OpenVPN translates the backslash character internally and hence it needs to be specified twice. The backslash between c:\\program and files is required as otherwise OpenVPN cannot find the up and down scripts.

There's more...

In this section, we will see some more advanced tricks when using up and down scripts, including a sample script to verify the remote hostname of a VPN server.

Environment variables

The script used in this recipe merely writes out all the environment variables to a file. These environment variables contain useful information about the remote server, such as the certificate common_name. An extension to this script would be to check whether the certificate common_name matches the remote hostname. The IP address of the remote hostname is available as trusted_ip.

Calling the 'down' script before the connection terminates

The down script is executed after the actual connection to the OpenVPN server has been stopped. It is also possible to execute the script during the disconnect phase before the connection to the server is dropped. To do this, add the following directive to the client configuration file:

down-pre

Advanced: verify the remote hostname

A more advanced usage of an up script would be to verify that the remote hostname matches the remote IP address, similar to the way that a web browser verifies the address of secure websites. On Linux systems, this can easily be done using a shell script as an up script:

#!/bin/bash

# reverse DNS lookup server_name=`host $untrusted_ip | \

sed -n 's/.*name pointer \(.*\)\./\1/p'` if [ "$server_name" != "$common_name" ] then

echo "Server certificate does not match hostname." echo "Aborting"

exit 1

fi

But on Windows, this is trickier to achieve without resorting to tools such as 'PowerShell' or 'Cygwin'.

157