ZeroShell    Forum
   Feed RSS Feed
EnglishEnglish     ItalianoItaliano     French     Spanish                Zeroshell on LinkedIn LinkedIn       Facebook      Twitter ZeroTruth an interface for Captive Portal


      What is it?
      Screenshots
      License
      Announcements
      Mailing List
      Forum
      Documentation  
      FAQ
      Hardware
      Download
      On-line Updates
      Kerberos Tutorial  
      Terms of use
      Contact me


  In greater details:
      Hotspot Router
      RADIUS Accounting
      Shibboleth SP
      Performances
      Net Balancer
      UMTS Router
      Soekris Net5501
      Proxy with Antivirus
      WiFi Access Point
      OpenVPN Client
      OpenVPN Server
      QoS
      OpenDNS
      Kerberos 5
      NIS and LDAP
      X.509 Certificates
      RADIUS
      VPN
      Firewall


Valid HTML 4.01 Transitional

OpenVPN client configuration for Windows, Linux, Mac OS X and Windows Mobile for Pocket PC

The purpose of this document is to lead the users to configure theirs OpenVPN clients to access to a VPN server. We will see how to install and configure the most used OpenVPN's GUI for Microsoft Windows, Linux, Mac OS X and Windows Mobile for Pocket PC. At the end of the document we will learn to use the OpenVPN's command line interface. This last possibility is useful, because the openvpn command, which you can execute by using the prompt (Unix Shell or Windows Prompt) accepts the same parameters and has the same behavior regardless from which Operating System you use. In addition, you could use the openvpn command in a script to automatically start the VPN connection.
More precisely, we will see how to access to a VPN server builded with ZeroShell and configured with the default parameters. To obtain an OpenVPN server with the default behavior, you only need, after you have activated Zeroshell on your network, to enable the OpenVPN service by clicking on the Enabled flag in the [VPN]->[OpenVPN] section of the Zeroshell's web interface. By default, the OpenVPN server of Zeroshell listens on the port 1194/TCP with TLS/SSL encryption and LZO compression enabled. The user authentication well be checked by using username and password credentials, but we will try the X.509 authentication as well.
For further details about the configuration of an OpenVPN server builded with ZeroShell, you can read the "An OpenVPN server using Zeroshell" how-to.


The sections in which this how-to is divided are as follows below. Keep in mind that the first section, which is related to the configuration file of OpenVPN, it is common to the other ones, because the configuration file do not depend on the GUI or Operating System that you use.

The configuration file of OpenVPN

Because the large number of parameters you can define either in the configuration file or in the command line, you could configure OpenVPN in many different manners. In any case, to obtain a connection with a Zeroshell VPN server, you only need to define a small number of them in your client's configuration file. In order to further simplify the configuration of the OpenVPN client, you could download an example of configuration file by clicking on the link OpenVPN Client configuration.The file has comments that explain the meaning of the parameters, but only 2 of them you surely need to change to obtain a VPN connection with Zeroshell:
  • remote zeroshell.example.com 1194

    You have to replace zeroshell.example.com with the hostname or the IP address of the OpenVPN server. The Zeroshell's default configuration requires that the OpenVPN service listens on the port 1194/TCP and therefore you must not modify the second parameter (1194).
  • ca CA.pem

    The ca parameter specify a file (in PEM format), that contains the X.509 Certification Authority with which the server certificate has been signed. To get the CA's X.509 certificate, you only need to click on the CA hyperlink in the Zeroshell's login page (see the screenshot). If you save the CA's certificate with the name CA.pem in the same directory of the configuration file, the you do not need to change the parameter. Otherwise, you must specify the absolute path of the file.
    Keep in mind that certificate of the Certification Authority is required also if you do not use the X.509 client authentication but the "Only Password" authentication (Default in Zeroshell).
Notice, that you will always have to manually edit the configuration file. This is because the Graphical User Interfaces that we are going to learn do not assist you in the creation and maintenance of the OpenVPN's configuration. They only help you to connect and disconnect the VPN, and ask for the username and password if they are required.

OpenVPN GUI for Windows

To install OpenVPN GUI for Windows on a Microsoft Windows XP 32/64 bits, follow the steps below:
  • Download the installer from the URL http://openvpn.se/download.html. Choose he file that contains the GUI and the OpenVPN software already included;
  • Start with the installation. Select the default options and confirm the installation of the TAP-Win32 Adapter V8 device (it is a Virtual Ethernet interface used by OpenVPN).
    When the Installer has finished to work, the TrayBar contains the VPN icon with two red terminals and the Earth Globe symbol. Such terminals are yellow when OpenVPN is trying to establish the connection and they are green when you are finally connected with the VPN;
  • In the Windows Start Menu, click on [Start]->[All Programs]->[OpenVPN]->[OpenVPN configuration file directory]. You will be able to explore the folder:

    C:\Program Files\OpenVPN\config

    in which you must copy the files zeroshell.ovpn that contains the OpenVPN configuration and CA.pem that is the X.509 Certification Authority certificate. You can look at the previous section for details on how to obtain these files;

  • Edit the file zeroshell.ovpn and replace zeroshell.example.com with the hostname or the IP address of the OpenVPN router;
  • At this point, you have finished to install and configure the OpenVPN client and its GUI. With a double-click on the OpenVPN icon in the Tray Bar, you can try to start the VPN connection. A dialog box will appear and request you to type the username and the password to be authenticated (look at the note *). If the authentication step is successfully completed, then the VPN connection will be established and the two yellow terminals will become green.
By right-clicking on the OpenVPN icon in the Traybar appears a contextual menu with several useful options: Connect, Disconnect, Show Status, View Log, Edit Config, Proxy Settings. Particularly useful to solve connection problems is the item View Log that allows to know the reason of the failures.

If instead the VPN is connected (the two terminals are green), but you are not able to reach the remote LAN or Internet using the Virtual Private Network, then you should use the ipconfig /all command from the Windows Prompt. Here there is an example of the lines of output about the virtual Ethernet interface:

Ethernet adapter Local Area Connection 7:

        Connection-specific DNS Suffix  . :
        Description . . . . . . . . . . . : TAP-Win32 Adapter V8
        Physical Address. . . . . . . . . : 00-FF-AD-63-83-3D
        Dhcp Enabled. . . . . . . . . . . : Yes
        Autoconfiguration Enabled . . . . : Yes
        IP Address. . . . . . . . . . . . : 192.168.250.51
        Subnet Mask . . . . . . . . . . . : 255.255.255.0
        Default Gateway . . . . . . . . . : 192.168.250.254
        DHCP Server. . . . . . . . . . . .: 192.168.0.0
        DNS Servers . . . . . . . . . . . : 192.168.250.254
        Lease Obtained. . . . . . . . . . : 16 September 2007 19.51.37
        Lease Expires . . . . . . . . . . : 15 September 2008 19.51.37
To be sure that the IP traffic is actually routed across the VPN and hence encrypted, you must check that the IP Address and the Default Gateway assigned to the TAP Virtual Interface belong to the remote LAN you are connected. To better check this condition, you could also use the tracert /d <Remote IP Address> command: if the first hop that is printed belongs to a subnet of the remote LAN then your VPN works fine and the traffic that reaches the remote site is encrypted across Internet.

Tunnelblick for Mac OS X

A Graphical User Interface for OpenVPN on Mac OS X is a package called Tunnelblick. To install this GUI, follow the steps below:
  • Download the package from the site http://code.google.com/p/tunnelblick/. It is a disk image file which contains the GUI, the OpenVPN software, and some documentation;
  • Double-click on the .dmg file;
  • A Finder window appears on the desktop. The window contains Tunnelblick.app. Double-click it;
  • A dialog box will ask you to confirm that you wish to install Tunnelblick.app to Applications. Click the Install button;
  • A dialog box will ask if you wish to launch Tunnelblick. Click the Launch button;
  • A dialog box will ask for an administrator username/password to secure Tunnelblick. Type administrator credentials and click the OK button;
  • A dialog box will appear welcoming you to Tunnelblick. Click the Create and open configuration folder button;
  • A Finder window will open with the configuration folder. The window will contain only an alias to Tunnelblick.app. Drag the files zeroshell.ovpn and CA.pem to the window. If you don't know how to obtain these two files, please read the section The configuration file of OpenVPN
  • Double-click on the Launch Tunnelblick alias;
  • A dialog box will appear asking if you wish to check for updates to Tunnelblick automatically. Click Check Automatically or Don't Check, as you prefer;
  • Tunnelblick is now installed. Its icon appears near the clock. Click on the Tunnelblick icon, then select the [Details...] item;
  • Click on the Edit Configuration button in the dialog box which appears. Replace zeroshell.example.com with the hostname or the IP address of the VPN server. Save the configuration file and quit;
  • Start the VPN connection by clicking on the Tunnelblick icon near the clock and selecting the Connect 'Zeroshell' item;
  • A dialog box will appear asking for an administrator username/password to secure the configuration file. Type administrator credentials and click OK;
  • A dialog box will appear asking for the VPN username and password. Type the VPN username and password and click "OK" (look at the Note *). You may save them in the Keychain by putting a check in the check box.
In the case in which there are connection problems, select the item [Details...] to check the OpenVPN's log messages.
If you want to verify that the IP address that the VPN server has assigned to you, actually belongs to the remote LAN with which you are connected, you have to open a Mac OS X Terminal and at the prompt of the shell type the command:

ifconfig tap0

the result looks like this:
tap0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
        inet 192.168.250.1 netmask 0xffffff00 broadcast 192.168.250.255
        ether b6:da:d9:91:22:ff 
        open (pid 368)
The line that starts with inet show you that the VPN IP address assigned to you is 192.168.250.1 (by default Zeroshell issues IP addresses which belong to the subnet 192.168.250.0/24 with 192.168.250.254 as Default Gateway). To be sure that the IP traffic is actually routed across the VPN and hence encrypted, you must check that the IP Address and the Default Gateway assigned to the TAP Virtual Interface belong to the remote LAN you are connected. To better check this condition, you could also use the traceroute -n <Remote IP Address> command: if the first hop that is printed belongs to a subnet of the remote LAN (192.168.250.254 by default) then your VPN works fine and the traffic that reaches the remote site is encrypted across Internet.

KVpnc for Linux

KVpnc is a Linux frontend that is able to manage many type of VPN clients such as: Cisco VPN, IPSec, PPTP, OpenVPN, L2TP. It has also the SmartCard support. Obviously, in this document we will see only the installation and configuration of KVpnc related to OpenVPN. Binary packages of KVpnc exist for many Linux distributions such as the RPM for Suse and Fedora. For Ubuntu and Kubuntu (and other Debian derived distributions), you can easily install KVpnc with OpenVPN by using the commands:

         sudo apt-get install openvpn
         sudo apt-get install kvpnc

Notice that, unlike the other GUIs, the packages of KVpnc do not include OpenVPN, but you must install it alone. In order to make this document regardless of the Linux Distribution used, we will build and install KVpnc by compiling the source code, but if a binary package exists for your Linux distribution, you should prefer to use it without waste your time in the building process.
Because KVpnc uses the QT libraries, their presence and their include files are required in the build process. In the next steps, we will assume that the OpenVPN package is already installed. If you are not in this situation, you should read the section Build and install OpenVPN to learn to install OpenVPN.
Now we are ready to install and configure KVpnc by following the steps given bellow:
  • Download the KVpnc's source code package from the web page http://home.gna.org/kvpnc/. We'll use the release 0.8.9 of KVpnc, but you should get the latest one;
  • Extract the source code by using the command:
           tar xvfj kvpnc-0.8.9.tar.bz2
  • Build and install KVpnc by following this steps:
           cd kvpnc-0.8.9
           ./configure
           make
           sudo make install

    For some Linux distributions, the ./configure command could be unable to locate the QT libraries. In this case, you must find out where the include files and the libraries are located and specify the paths by adding the parameters --with-qt-includes=/usr/lib64/qt-3.3/include/ --with-qt-libraries=/usr/lib64/qt-3.3/lib/ to the ./configure. Of course, you should replace the path /usr/lib64/qt-3.3/ with the one in which the QT libraries are located in your Linux system;
  • Make the directory /etc/openvpn/ with the command sudo mkdir /etc/openvpn and copy in the new directory the files zeroshell.ovpn and CA.pem. How to obtain such files is described in the section The configuration file of OpenVPN;
  • To use KVpnc with unprivileged users the sudo command is required and the line
           ALL ALL=NOPASSWD:/usr/bin/kvpnc

    must be added at the end of the file /etc/sudoers (notice that you need to have administrator privileges to change this file). After that, you are able to launch the kvpnc process by using the command:
           sudo /usr/bin/kvpnc

    In this manner, the kvpnc will have the root's privileges needed to create the tap0 Virtual Ethernet Interface and add the static routes in the Kernel routing table;
  • Import the profile that allow you to create a VPN with Zeroshell by using the following command:
           
    kvpnc --openvpnimport=/etc/openvpn/zeroshell.ovpn

    By using the Profile Manager that appears, make the following configuration changes:
    • From the General options, insert in the VPN gateway field the IP address or the hostname of the VPN server;
    • From the OpenVPN options, check that the Authentication method is the SHA1 hash function and not MD5 one;
    Press [Apply] and then [Ok] on the Profile Manager. After that, save the Zeroshell profile using the [Profile]->[Save Profile...] menu item and close kvpnc interface with [File]->[Quit] menu item;
  • Start the KVpnc GUI with the command sudo /usr/bin/kvpnc and click the [Connect] button to establish the VPN connection. At this point, you are requested for the username and the password to use to authenticate your identity against the VPN server (look at the Note *).
If you want to verify that the IP address that the VPN server has assigned to you, actually belongs to the remote LAN with which you are connected, you have to open a terminal and at the prompt of the shell type the command:

ifconfig tap0

the result looks like this:
tap0      Link encap:Ethernet  HWaddr 26:8F:1E:31:44:DD
          inet addr:192.168.250.50  Bcast:192.168.250.255  Mask:255.255.255.0
          inet6 addr: fe80::248f:1eff:fe31:44dd/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:19 errors:0 dropped:0 overruns:0 frame:0
          TX packets:25 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:100
          RX bytes:1384 (1.3 KiB)  TX bytes:1668 (1.6 KiB)
The line that starts with inet show you that the VPN IP address assigned to you is 192.168.250.50 (by default Zeroshell issues IP addresses which belong to the subnet 192.168.250.0/24 with 192.168.250.254 as Default Gateway). To be sure that the IP traffic is actually routed across the VPN and hence encrypted, you must check that the IP Address and the Default Gateway assigned to the TAP Virtual Interface belong to the remote LAN you are connected. To better check this condition, you could also use the traceroute -n <Remote IP Address> command: if the first hop that is printed belongs to a subnet of the remote LAN (192.168.250.254 by default) then your VPN works fine and the traffic that reaches the remote site is encrypted across Internet.

OpenVPN for Windows Mobile on Pocket PC

OpenVPN for Pocket PC is still an Alpha release, but it worked fine during the test on Microsoft Windows Mobile v5.0 installed on a PDA i-Mate JASJAR (equivalent to a HTC Universal Qtek 9000). Before seeing how to install and configure this software, notice that you will have to manually modify the OpenVPN configuration file and therefore you should use Microsoft ActiveSync for editing from your Personal Computer. Another solution could be to install on your PPC the Total Commander CE that is a Freeware File Manager for Pocket PC, available at the URL http://www.ghisler.com/pocketpc.htm. This filemanager includes an Editor which allows you to edit the OpenVPN configuration file directly from your Palm Device.
Now, follow the steps below to install OpenVPN for Windows Mobile on your Pocket PC:
  • Download the OpenVPN for Pocket PC from the site http://ovpnppc.ziggurat29.com/ovpnppc-main.htm. There are two type of file: the .exe format that you can install from your Personal Computer connected to the PPC with ActiveSync; the .cab format that you can directly install on your Pocket PC. Pick the package in the format that you prefer and install it.
  • Supposing that you have installed OpenVPN for Pocket PC in the directory \Program Files\OpenVPN of the device's memory, copy the files zeroshell.ovpn and CA.pem in the folder \Program Files\OpenVPN\config. To know how to obtain these two files, read the section The configuration file of OpenVPN;
  • Edit the configuration file \Program Files\OpenVPN\config\zeroshell.ovpn to connect to your OpenVPN server:
    • Replace zeroshell.example.com with the IP address or the hostname of the OpenVPN server;
    • Replace CA.pem with the path of the file that contains the Certification Authority. In your case the path is:

             ca "\\Program Files\\OpenVPN\\config\\CA.pem"

      Notice the double quotes and the double backslashes that are requested by the syntax of this parameter;
  • Click on the icon of OpenVPN and from the submenu [Start from Config.] select zeroshell. At this point you are requested for the Username and Password (look at the Note *). If the client is authenticated against the server, the VPN connection is established.
If you have connection problems, check the log file \Program Files\OpenVPN\log\zeroshell.log. Finally, to verify that the traffic is actually routed and encrypted in the VPN you need to perform a traceroute operation at a remote host: if the first hop that is reported belongs to the remote LAN (by default the VPN box has the IP 192.168.250.254), you are sure that the VPN works as you expect. Windows Mobile has not a traceroute utility and therefore you need to install one. A free software to make network debugging is ceNetTools with which you are able to make the traceroute, the ping and whois operations.

The command line of OpenVPN

If the system you are using has not a Graphical User Interface for OpenVPN, you have to use the OpenVPN's command line. This can also be used in the case in which you want to automatically start the VPN by using the startup scripts. By typing the command man openvpn from a Unix shell, the OpenVPN's manual page will be displayed. A great number of parameters are available to directly use in the command line prefixed by two consecutive hyphens (--). The same parameters (not prefixed by --) can also be specified in the configuration file. Except for a few cases, it is better to specify the parameters in a configuration file rather than having them in a too long and heavy to read command line.
This section does not examine the parameters because they are already listed and described in the manual page of OpenVPN, but it only describe how to establish a VPN with a Zeroshell OpenVPN server by using the command line:
  • Put the files zeroshell.ovpn and CA.pem in a same directory (suppose /etc/openvpn/). For details about how to obtain these files, read the section The configuration file of OpenVPN;
  • Edit the configuration file zeroshell.ovpn replacing zeroshell.example.com with the IP address or hostname of the VPN server;
  • Change the current directory to /etc/openvpn/ and exec (with root privileges) the command:

           openvpn --config zeroshell.ovpn

    At this point, you are requested for the Username and the Password (look at the Note *). If the client is authenticated against the server, the VPN connection is established.

Build and install OpenVPN

For the most operating system in which OpenVPN works, binary packages already compiled exist. Anyway, sometimes, above all for some Linux Distributions, you could need to build OpenVPN by starting with the source code. Below, it is described how to build OpenVPN:
  • Download the OpenVPN's source code from the site http://openvpn.net. Pick the latest stable release that is available (suppose the release 2.0.9 in the rest of this document);
  • Extract the files which are stored in the zipped archive that you have downloaded by using the tar command in the following manner:
           tar xvfz openvpn-2.0.9.tar.gz
  • Change the current directory to openvpn-2.0.9 with the command:
           cd openvpn-2.0.9
  • Check the system and produce the Makefiles by using the following command:
           ./configure --prefix=/usr

    If the ./configure procedure claims that the lzo libraries and headers are not found in the system, install the lzo compression software as follows below:
    • Download the source package of LZO from the site http://www.oberhumer.com/ and extract its content with the command:
             tar xvfz lzo-2.02.tar.gz
    • Change the current directory to lzo-2.02 and install the LZO software with the commands:
      • ./configure
      • make
      • make install   (This command needs to be executed with root privileges to write in /usr)
      Once installed the lzo libraries and headers, came back to the directory openvpn-2.0.9 and launch again the command
             ./configure --prefix=/usr
  • Compile the source code with the Makefiles you have just created by using the command:
           make
  • Install the binary program openvpn and its manual pages with the command:
           make install

    Because the files will be written below the system directory /usr, the last command must be executed with root privileges.


Notes

(*) The manner in which the users are authenticated depend on the OpenVPN server configuration. Zeroshell supports a multi-domain authentication system in which you have to configure the authentication source which can be a Kerberos 5 KDC (local, external and trusted) or an external RADIUS server. One of these authentication domains is set to be the default domain. The users of the default domain do not need to specify the username in the form of username@domain (ex. fulvio@example.com). Notice that the domain name is not case sensitive, because if the domain is configured to be a Kerberos V realm, it is automatically converted to uppercase.



    Copyright (C) 2005-2013 by Fulvio Ricciardi