OpenVPN on Windows notes, Copyright (C) James Yonan, 2003-2004
--------------------------------------------------------------

Please report any bugs to the openvpn-users
list.

Before you post, check out the troubleshooting
guide for more info:

http://openvpn.sourceforge.net/trouble.html

Currently, OpenVPN runs on Win 2000/XP, Linux, Mac OS X,
Solaris, FreeBSD, NetBSD, and OpenBSD, making it one of the
most portable VPN packages today.

This document is also available in HTML:

http://openvpn.sourceforge.net/INSTALL-win32.html

What's new in the 1.6 beta series
---------------------------------

THIS IS A BETA RELEASE.

This release is primarily focused on bug fixes and minor
feature improvements over 1.5.

See Change Log for more details:

http://openvpn.sourceforge.net/changelog.html

What's new in 1.5.0
-------------------

OpenVPN 1.5.0 is essentially just 1.5-beta14 with
the version number changed.

Below are the release notes which have been
built up over the course of development of
the 1.5 beta series.

The often-requested HTTP proxy feature
has been added to allow OpenVPN to connect
to its remote peer through an HTTP proxy
using the HTTP CONNECT method.
Basic HTTP authentication is supported as an
option.  For more info, see the --http-proxy
option.

The --redirect-gateway feature has been added
which redirects all IP traffic into the tunnel.

Many of the changes in this release involve
minor additions to the crypto layer.

The --secret and --tls-auth options now support
key directionality, where different keys
can be used for both data flow directions.
To use the new key directionality feature, you
must generate a new key with --genkey, then
add a direction parameter to --secret or
--tls-auth.  See the man page for details.

The --tls-auth option now accepts an OpenVPN
static key file generated by --genkey.
Freeform files can still be used with --tls-auth --
they will be hashed to generate an HMAC key.

The replay protection logic now exports two
parameters which previously were held
constant.  See the --replay-window option.

A --key-method option has been added which can
be used to select one of two different data
channel key generation methods to be used
in TLS mode.  Key method 1 is the original,
default key generation method.  Key
method 2 is new and uses the TLS PRF function.

A Certificate Revocation List capability has
been added.

None of the crypto changes affect key file or
protocol compatibility with previous releases,
however all of the new crypto options (with the
exception of --replay-window) require current
versions of OpenVPN on both sides of the connection.

OpenSSL 0.9.7c DLLs are now shipped with 1.5-beta9
and higher in response to an OpenSSL security
advisory.

An option has been added to the TAP-Win32 driver
advanced properties page that allows you to control
whether the adapter appears to Windows as
"Always Connected" or whether the connection status
is dynamically brought up and down by OpenVPN
("Application Controlled").

OpenVPN now supports the '--dev tun' option.
The TAP-Win32 driver has been extended to allow tun
device emulation.  This means that OpenVPN on
Windows can now connect with OpenVPN running
on any other platform.  For more information
see the "Notes -- TAP vs. TUN devices" section
below.

The --dev-node option is now optional when exactly
one TAP-Win32 adapter exists on a system -- such an
adapter will now be chosen automatically as
the default.

The --ifconfig option is now supported for
TAP-Win32 devices as well as TAP devices
on other platforms which OpenVPN supports.  The
--ifconfig option can be used to programatically
set the IP address and subnet mask of a
TAP-Win32 adapter.

Here is an example of how --ifconfig can simplify
configuration:

Config file for Machine A (server):

  dev tap
  ifconfig 10.3.0.1 255.255.255.0
  secret key

Config file for Machine B (client):

  remote A
  dev tap
  ifconfig 10.3.0.2 255.255.255.0
  ping 10
  secret key

It doesn't matter whether Machine A or B is
running Windows or Linux -- these config
files are essentially portable.

To tune the operation of the --ifconfig option
on Windows, the --ip-win32 option has been
added to control which Windows API/method is used
by OpenVPN to set the TCP/IP properties
on the TAP adapter.

A new --route option has been added which is
a convenience proxy for the functionally
similar but syntactically incompatible route
commands of the Windows and *nix worlds.

If you change the TAP-Win32 MTU by using
the adapter advanced properties dialog,
OpenVPN will automatically query the
adapter to get the new MTU.

Added two new options, --fragment and
--mssfix to help solve MTU fragmentation
problems.  --fragment performs internal
fragmentation and --mssfix tries to
keep TCP session packet size from
exceeding an upper bound.  Both
can be used together, i.e.:

  fragment 1400
  mssfix

--mssfix will try to keep TCP from needing
packet fragmentation in the first place,
and if big packets come through anyhow
(from protocols other than TCP), --fragment
will internally fragment them.

The --mtu-test option has been added
for empirical measurement of MTU, to assist
in determining whether the 'fragment' or
'mssfix' options should be used, and if so,
what the ideal settings should be.

The --tap-delay option has been added to delay
setting the TAP-Win32 adapter media state to
'connected' until TCP/UDP connection establishment
with peer.

The TAP-Win32 driver has been significantly
reworked for both efficiency and SMP capabilities.
As of beta8, the driver should be considered
experimental on SMP systems.  Driver versions
prior to beta8 SHOULD NOT be installed on
SMP systems.

You can now run one or more OpenVPN tunnels as a
Windows service if you select the "OpenVPN Service"
option in the installer.

See "Running as a Windows Service" below for more
details.

Also new are are right-clickable
options on .ovpn files (The windows file
extension for OpenVPN config files), including the
ability to instantiate an OpenVPN process
on a given config file.

Other changes include a new start menu
shortcut to generate a static key, and a
few other useful shortcuts.

More work as well has gone into improving MTU
configurability in the TAP-Win32 driver.
See MTU notes below for more info.

Ease of installation has been dramatically improved
with the development a real windows
installer/uninstaller using the Nullsoft Install System.

The OpenVPN Windows distribution is now packaged as a
self-installing EXE which will automatically
install/upgrade OpenVPN, OpenSSL components,
the TAP-Win32 driver, and install the OpenVPN
service wrapper.

You can now create multiple TAP-Win32 adapter instances,
to allow several VPN tunnels to run concurrently
(See OpenVPN Start Menu shortcuts).

See Change Log for more details:

http://openvpn.sourceforge.net/changelog.html

How to Install
--------------

Download and Unzip the most recent OpenVPN distribution
from:

http://prdownloads.sourceforge.net/openvpn/

Choose the most recent self-installing distribution
with an .exe extension.

You can also download a source-only distribution by
selecting a .zip or .tar.gz file.

If you are upgrading from 1.5-beta2 or earlier,
you might want to uninstall the TAP
device using the device manager (Control Panel ->
System -> Hardware), reboot, then reinstall
from the self-installing exe to be sure that
all remnants of the previous driver installation
are removed from your system.  Going forward,
the new installer is designed to make upgrading
OpenVPN and the TAP-Win32 driver as automatic
as possible.

Running OpenVPN from a console window
-------------------------------------

First, create a config file.  A sample is provided
in \Program Files\OpenVPN\config\sample.ovpn.txt

Edit this file and save to a .ovpn extension.
Now, run OpenVPN by right clicking on the
.ovpn filename and selecting "Start OpenVPN
on this config file".

You can also run from a command prompt window:

  openvpn --config sample.ovpn

Running OpenVPN as a Windows Service
------------------------------------

When OpenVPN runs as a service it will start a
separate OpenVPN process for each configuration
file it finds in the
\Program Files\OpenVPN\config directory and will
output a logfile of the same name to the
\Program Files\OpenVPN\log directory.

When installed as a service, OpenVPN
will default to manual start mode.  You
can go to the Services control panel
in Control Panel -> Administrative Tools
to start the service or to set it to Automatic
Start mode.

A sample config file has been provided in
\Program Files\OpenVPN\config\sample.ovpn.txt
which can be adapted to your needs.

Service Notes:

* When you install OpenVPN as a service, you
  are actually installing openvpnserv.exe which
  is a service wrapper for OpenVPN, i.e. it
  reads the config file directory and starts
  up a separate OpenVPN process for each config
  file.  openvpnserv.exe performs the same
  function under windows as the
  /etc/init.d/openvpn startup script does
  under linux.

* When you stop the OpenVPN service, it will
  send a terminate signal to all OpenVPN
  processes which were started by it.

* If the OpenVPN service wrapper (openvpnserv.exe)
  encounters fatal errors, it will write them
  to the windows event log, which can be
  viewed in Control Panel -> Administrative Tools
  -> Event Viewer -> Application Log. 

* If the OpenVPN processes themselves encounter
  errors, they will write them to their respective
  log files in the log file directory.

* There is a one-to-one correspondence between an
  OpenVPN process, an OpenVPN config file, an
  OpenVPN log file, and a TAP-Win32 adapter which
  represents an endpoint of a VPN tunnel.

* OpenVPN tunnels are point-to-point in their
  simplest form, but can be made point-to-multi-point
  through the use of bridging or routing
  (see below).

* Multiple OpenVPN processes can run concurrently,
  each on a different TAP-Win32 adapter.

* openvpn.exe gets all configuration
  information from its config file, not from
  the registry.

* The openvpnserv.exe program (the service wrapper)
  gets several string parameters from the registry which
  can be modified by the user.  If you change any of these
  parameters, you should be able to upgrade OpenVPN to
  a new version without the installer overwriting your changes.

  HKLM\SOFTWARE\OpenVPN

  config_dir -- configuration file directory to scan, defaults to
                "\Program Files\OpenVPN\config"

  config_ext -- file extension on configuration files, defaults
                to "ovpn"

  exe_path   -- path to openvpn.exe, defaults to
                "\Program Files\OpenVPN\bin\openvpn.exe"

  log_dir    -- log file directory, defaults to
                "\Program Files\OpenVPN\log"

  log_append -- if set to "1", multiple instantiations of an OpenVPN
                process will append onto the same log file, if set
                to "0" (default), each new instantiation will
	        truncate the previous log file

  priority   -- the windows priority class for each
                instantiated OpenVPN process, can be one of:

                (1) "IDLE_PRIORITY_CLASS"
                (2) "BELOW_NORMAL_PRIORITY_CLASS"
                (3) "NORMAL_PRIORITY_CLASS" (default)
                (4) "ABOVE_NORMAL_PRIORITY_CLASS"
                (5) "HIGH_PRIORITY_CLASS"

Bridging vs. Routing
--------------------

Bridging and routing are two methods of linking systems via
a VPN.

* Bridging advantages

    Broadcasts traverse the VPN -- this allows software that depends
    on LAN broadcasts such as Windows NetBIOS file sharing and
    network neighborhood browsing to work.

    No route statements to configure.

    Works with any protocol that can function over
    ethernet, including IPv4, IPv6, Netware IPX,
    AppleTalk, etc.

    Relatively easy-to-configure solution for road warriors.

* Bridging disadvantages

    Less efficient than routing, and does not scale well.

* Routing advantages

    Efficiency and scalability.

    Allows better tuning of MTU (see notes below)
    for efficiency.

* Routing disadvantages

    Clients must use a WINS server (such as samba) to allow
    cross-VPN network browsing to work.

    Routes must be set up linking each subnet.

    Software that depends on broadcasts will not "see"
    machines on the other side of the VPN.

    Works only with IPv4 in general, and IPv6 in some
    special cases.

What is Bridging?

  Bridging is a technique of creating a virtual, wide-area
  ethernet LAN, running on a single subnet.

What are the fundamental differences between bridging
and routing in terms of configuration?

  When a client connects via bridging to a remote network,
  it is assigned an IP address that is part of the remote
  physical ethernet subnet and is then able to interact
  with other machines on the remote subnet as if it were
  connected locally. Bridging setups require a special
  OS-specific tool to bridge a physical ethernet adapter
  with a virtual TAP style device.  On Linux, for example,
  "brtcl" is this tool.  On Windows, select your TAP-Win32
  adapter and your ethernet adapter in Control Panel -> Network
  Connections, then right click and select Bridge Connections.

  When a client connects via routing, it uses
  its own separate subnet, and routes are set up on both
  the client machine and remote gateway so that data packets
  will seamlessly traverse the VPN.  The "client" is not
  necessarily a single machine.  It could be a subnet of
  several machines.

  Bridging and routing are functionally very similar, with
  the major difference being that a routed VPN will not
  pass IP broadcasts while a bridged VPN will. 

  When you are bridging, you must always use --dev tap
  on both ends of the connection.  If you are routing
  you can use either --dev tap or --dev tun, but you
  must use the same on either end of the connection.
  --dev tun tends to be slightly more efficient for
  the routing case.

Example running a point-to-point VPN
------------------------------------

This example will work between Windows and Windows,
Windows and Linux, or Windows and FreeBSD.

For purposes of this example, we will refer to our two
Windows machines as "A" and "B".
 
The Windows OpenVPN installer should have already installed
a TAP-Win32 adapter on each machine which you should see
in the Network Connections control panel.

We will choose the network 10.3.0.0 subnet 255.255.255.0 as
our virtual VPN subnet.

We are assuming that the network 10.3.0.0 subnet 255.255.255.0
is a new and distinct subnet from any that you are currently
using.  If it is not, choose a different subnet by
substituting something else for the "10.3.0" component of
the subnet.

It is VERY IMPORTANT that the virtual VPN subnet you use
is private and unique from any other physical or virtual
subnets in use.  If your virtual subnet clashes with your
physical subnet, the VPN will not work and there will
likely be no error messages to tell you why.

Now generate a static key on Machine A:

  openvpn --genkey --secret key

(Or use the shortcut in the start menu)

Copy this key to Machine B over a secure medium.

Now edit the config files for both ends of the connection.

On Machine A create a file config.ovpn :

  remote [IP address of B]
  dev tap
  ifconfig 10.3.0.1 255.255.255.0
  secret key
  ping 10
  verb 3
  mute 10

On Machine B create a file config.ovpn :

  remote [IP address of A]
  dev tap
  ifconfig 10.3.0.2 255.255.255.0
  secret key
  ping 10
  verb 3
  mute 10

Another important point to remember is that the addresses
used in the "remote" option are real addresses, not virtual
addresses.  Before OpenVPN is started you must be able to
ping the address given after the "remote" option.  OpenVPN
will try to connect to that address and if you can't ping
it beforehand, OpenVPN will not be able to connect to it either.

The rule of thumb to remember is that "remote" specifies
real, non-VPN addresses while "ifconfig" specifies virtual
VPN addresses.  The address used in "remote" should NEVER
be a part of the subnet defined by the "ifconfig" option.

Now the moment of truth... Type:

 openvpn --config config.ovpn

On both A and B.

Alternatively, bring up the folder
that contains the .ovpn file, right click on the
.ovpn file, and select "Start OpenVPN on this
config file".

If everything worked correctly you will now have a
point-to-point VPN connecting the two boxes.

On Machine A you can ping B with the following command:

  ping 10.3.0.2

On Machine B you can ping A with the following command:

  ping 10.3.0.1

A few notes to be aware of:

* If you are using different versions of OpenVPN on either
side of the connection, then add the following lines to both
configs:

  tun-mtu 1500
  tun-mtu-extra 32

* If one side of the connection is running on Linux, make
  sure you tell your linux firewall to allow incoming
  connections on virtual tap interfaces.  The command
  for iptables would be: 

  iptables -A INPUT -i tap+ -j ACCEPT

* Make sure that both boxes can talk to each other
  over UDP port 5000.  It is a good idea to
  ping the "remote" address in the config
  file before actually starting OpenVPN
  to confirm that it is reachable.

Troubleshooting
---------------

For solutions to common troubleshooting problems,
consult the OpenVPN Troubleshooting guide

http://openvpn.sourceforge.net/trouble.html

Setting up routing
------------------

If you set up a routed VPN, i.e. one where local and
remote subnets differ, you need to set up routing
between the subnets so that packets will transit the
VPN.

Here is a possible road warrior network configuration:

Road Warrior (Windows)

  TAP-Win32 Adapter
  10.3.0.2 subnet 255.255.255.0
  ifconfig option in OpenVPN config:

    ifconfig 10.3.0.2 255.255.255.0

Main Office, server (any OS)

  tap adapter
  10.3.0.1 subnet 255.255.255.0
  ifconfig option in OpenVPN config:

    ifconfig 10.3.0.1 255.255.255.0

  private ethernet
  10.0.0.1 subnet 255.255.255.0

The road warrior needs this route in order to
reach machines on the main office subnet:

  route add 10.0.0.0 mask 255.255.255.0 10.3.0.1 (this is a shell command)

Routes can be conveniently specified in the OpenVPN
config file itself using the --route option:

  route 10.0.0.0 255.255.255.0 10.3.0.1 (this is an OpenVPN config file option)

If the OpenVPN server in the main office is also
the gateway for machines on the remote subnet, no
special route is required on the main office side.

On the other hand, if the main office OpenVPN server
is NOT also the gateway, then whatever machine or
router which IS the gateway must know to route
10.3.0.0 subnet 255.255.255.0 to the machine which is
running OpenVPN.

Notes -- Ethernet bridging, Windows client, Linux Server
--------------------------------------------------------

Ethernet bridging is a powerful networking capability
that allows remote systems (such as "Road Warriors")
to connect over a VPN to an ethernet LAN in such a way
that their system appears to be directly connected to
the LAN, i.e. they have an IP address taken right from
the LAN's subnet and they are able to interact with other
hosts on the LAN including sending and receiving broadcasts
and being able to conveniently browse and access the
Windows network neighborhood.

I have tested ethernet bridging with Windows clients connecting
to a Linux server.  On the linux side, basically follow the
instructions in the Ethernet bridging Mini-Howto on the
OpenVPN web site.

On the Linux side you must first set up ethernet bridging.  Here
is a configuration which I use:

#!/bin/bash

modprobe tun
modprobe bridge

openvpn --mktun --dev tap0
openvpn --mktun --dev tap1

brctl addbr br0
brctl addif br0 eth1
brctl addif br0 tap0
brctl addif br0 tap1

ifconfig tap0 0.0.0.0 promisc up
ifconfig tap1 0.0.0.0 promisc up
ifconfig eth1 0.0.0.0 promisc up

ifconfig br0 10.5.0.1 netmask 255.255.255.0 broadcast 10.5.0.255

# end of script

This script will set up ethernet bridging between eth1,
tap0, and tap1.  Change the br0 ifconfig to match the ifconfig
that would be used for eth1 under normal, non-bridged
configuration.  Use as many tapX virtual adapters as you will
have remote clients connecting.

In the firewall, add these entries to allow TAP devices
and ethernet bridges to operate:

iptables -A INPUT -i tap+ -j ACCEPT
iptables -A INPUT -i br0 -j ACCEPT
iptables -A FORWARD -i br0 -j ACCEPT

Now make an OpenVPN configuration on the server side to receive
incoming connections such as:

###################################
# OpenVPN bridge config, Linux side

local [public IP address or hostname]

# IP settings
port 8888
dev tap0

# crypto config
secret key.txt

# restart control
persist-key
persist-tun
ping-timer-rem
ping-restart 60
ping 10

# compression
comp-lzo

# UID
user nobody
group nobody

# verbosity
verb 3

# end of config
###################################

For additional clients, copy the configuration
above, but use a different port number, tapX
unit number, and secret key.

Now on the windows client side:

############################################
# OpenVPN bridge config, windows client side

remote [public IP address or hostname of server]
port 8888
dev tap

# This is the address the client will
# "appear as" when it connects to the
# bridged LAN.
ifconfig 10.5.0.5 255.255.255.0
ifconfig-nowarn

secret key.txt
ping 10
comp-lzo
verb 3

# end of config
###################################

Now run OpenVPN on both sides with the appropriate
configuration file, using the --config option.

On the Linux side, you probably want to run as a daemon,
so include --daemon and --cd [dir], where dir is
the directory that contains the key file.

If everything worked correctly, the Linux server or
any host on its subnet should be able to ping
10.5.0.5 and see the remote VPN connected client.

The Windows client should be able to ping any address
on the 10.5.0.x subnet, including addresses of other
remote, OpenVPN-bridged clients.

If Windows machines or Samba servers exist on the LAN
bridged by the Linux server (including Samba running on the
Linux server itself), the Windows client
should see them in its network neighborhood, and vice versa.

Furthermore, ethernet bridging allows for the transport
of all protocols which are compatible with Ethernet,
including IPv6 and IPX.

Ethernet bridging is a great way to work when on the
road, and I personally use it for securely connecting
to home or office from WiFi Internet cafes.

Notes -- Ethernet bridging, with the bridge occurring
on the Windows side.
-----------------------------------------------------

This configuration requires Windows XP or higher on the
bridge side.  To my knowledge, Windows 2000 does not
support bridging, however a Windows 2000 machine can
be a client on a bridged network, where the other
end of the OpenVPN connection where the bridging is
occurring is a Linux or Windows XP machine.

* First make a TAP-Win32 adapter ("tap-bridge") without setting
  any TCP/IP properties.

* Select tap-bridge and your ethernet adapter in Control Panel ->
  Network Connections, then right click and select Bridge Connections.
  I am assuming that the bridged network address is 10.0.0.0
  subnet 255.255.255.0.  The connecting client will use an
  address of 10.0.0.7.

* Note that if your ethernet adapter is a DHCP client, the act of
  bridging the connection may cause it to get a new IP address
  lease.

* Use this config on the Windows side (the side doing the bridging):

   remote [myremote]
   dev tap
   dev-node tap-bridge
   ping 5
   secret key

* Use this config on the remote (which in this case is a linux
  box but could also be a windows box).

   remote [myremote]
   dev tap
   ifconfig 10.0.0.7 255.255.255.0
   ping 5
   secret key

Notes -- Setting TAP-Win32 address/subnet automatically via DHCP
----------------------------------------------------------------

Setting the TAP-Win32 address/subnet automatically via DHCP is
a convenient method of managing IP addresses in a bridge situation,
though there are some caveats that must be handled.

The problem with getting addresses for VPN clients via DHCP is that you
only want to get the IP address and subnet mask, not the gateway.
Therefore in a bridge situation, a DHCP server must be able to
differentiate between local clients and remote VPN clients.

Dave Lau contributed a config file for ISC's dhcp3 server that does
just this.  I reproduce Dave's email describing his setup
in full below, including the DHCP server config file.

[Editors note: The 00:FF MAC prefix is not my original idea --
I got it from the Linux TAP driver.]

***********************************************

I've been using openVPN since you ported it to windows, and I must say it is
fantastic.  In just 2 short weeks of testing, I have decided to scrap my
IPSec VPN that I have been using for my small business in place of openVPN.
One thing that I have found to be immensely useful is the ethernet bridging.
I would rather bridge than route for my particular situation, because I want
my remote vpn clients to be on the same subnet as the office-bound clients
for myriad reasons.  I did not like having to manually configure IP
addresses for each client, so I elected to use a dhcp server to serve my
remote clients an IP address through the openVPN tunnel.

Rather than relying on client hostnames to distinguish between openVPN and
non-openVPN connections, I took advantage of your clever idea to create MAC
addresses for the Tap adapters as 00:FF:xx:xx:xx:xx, and I wrote my
dhcpd.conf file accordingly.  The reason this is necessary for me is that I
do not want to hand out a default gateway or DNS server to my openVPN
clients, I only want local traffic going through the tunnel.  I'm sure there
are many other possible instances in which the dhcp server would like to
handle openVPN clients differently from standard clients, so I though I
would share my dhcp server config with you on the off chance that it might
be useful to others.  This particular config is for ISC's dhcp3 server, but
I'm sure it would work with just about anything.  There is nothing
particularly clever or tricky about this config file, I just did not happen
to see any examples of it anywhere, so if this could save someone some time
and effort, that would be great:

Thank you, Jim, for writing this fantastic piece of software.

Sincerely,
Dave Lau

******************************

beefcake:~# cat /etc/dhcp3/dhcpd.conf
## If hardware address begins with 00:FF, the client is an
## openvpn tap adapter, and we do not want to assign a
## default gateway or dns server.  Assign then to a special
## subclass and configure a pool which does not hand out
## these parameters.

class "openvpn" {
     match if substring (hardware, 1, 2) = 00:FF;
 }
## end class declaration

## subnet for br0

authoritative;
subnet 172.16.0.0 netmask 255.255.255.0 {
always-broadcast on;
max-lease-time 3600;
default-lease-time 1800;
option domain-name "ezone.net";
option subnet-mask 255.255.255.0;

pool {
     deny members of "openvpn";
     range 172.16.0.150 172.16.0.254;
     option routers 172.16.0.1;
     option domain-name-servers 172.16.0.1;
     option tftp-server-name "172.16.0.209";
     }

pool {
     allow members of "openvpn";
     range 172.16.0.100 172.16.0.125;
     }

}

Notes -- Driver Stability
-------------------------

The stability of the TAP-Win32 driver is obviously of
great concern since any crash by a driver will also
crash the entire system, producing the infamous blue screen
of death (BSOD).

Between 1.5-beta1 and 1.5-beta2, significant stability
improvements have been made in the driver, and it now passes
the Windows Driver Verifier when running in its most
rigourous verification mode.  The 1.5-beta1 driver had
problems crashing on sleep/resume and I believe these
bugs have been fixed in 1.5-beta2 and higher.

Versions of the TAP-Win32 driver prior to beta8 are
NOT safe for usage on SMP (i.e. multiprocessor) systems.

Beta8 has been redesigned to be SMP-safe but more real
world testing will be required before its stability
can be assured.

Notes -- TUN devices
--------------------

Tun device support (via the --dev tun option) was first
included in OpenVPN 1.5-beta8.

A "tun" device is a virtual point-to-point IP link.

Using --dev tun also requires that you use --ifconfig
to tell OpenVPN the local and remote IP endpoints for
the point-to-point tunnel.

The --ifconfig option also calls the Windows "netsh"
command, and some problems have been reported with
this command on Win2K at lower service packet levels.

If you would like to use --dev tun but would rather
set the TCP/IP properties manually rather than having
OpenVPN try to do it automatically with netsh, follow
these steps:

* Specify --ifconfig with endpoint addresses.

* Specify the --ifconfig-noexec option.

* Manually set the network/subnet in the TCP/IP
  properties.  You should use a /30 subnet that
  encloses the addresses that were specified
  in the --ifconfig option.  The netmask, therefore,
  will be 255.255.255.252.

Notes -- TAP vs. TUN devices
----------------------------

A "tap" device is a virtual ethernet adapter, while
a "tun" device is a virtual point-to-point IP link.

As of OpenVPN 1.5-beta8, the TAP-Win32 driver supports
both "tun or "tap" style devices.

YOU CANNOT MIX --dev tun AND --dev tap ON DIFFERENT ENDS
OF THE CONNECTION.  Use one or the other consistently.

There are some caveats to be aware of when using "tun" style
devices on Windows:  the --ifconfig endpoints chosen
must be the two "middle" addresses in a 255.255.255.252
subnet.

The command

  openvpn --show-valid-subnets

will show more information about how to choose VPN endpoints
when --dev tun is used.

The other caveat concerns MTU.  On most platforms, OpenVPN
programatically sets the MTU of the tun or tap interface.
Currently on Windows, the only way to change the TAP-Win32
MTU is to go to the adapter advanced properties and do it
manually.

Because of this, the easiest choice is to leave the
TAP-Win32 MTU setting at 1500 and tell OpenVPN on
both sides of the connection to use an MTU of 1500 with
the config option:

  tun-mtu 1500

If you then need to lower the MTU because of fragmentation
or router problems, use something like

  fragment 1400
  mssfix

to lower OpenVPN's tunnel carrier UDP packet size to 1400.

Notes -- MTU
------------

Setting the MTU is an important but sometimes problematic
aspect of VPN configuration.  The MTU (maximum transmission
units) is the maximum packet size in bytes that can
be sent or received by a real or virtual network adapter.

The common symptom of MTU problems is a VPN connection
which appears to start up fine, but then locks up
under real usage. 

The easiest way to solve MTU problems is by using
the --mssfix and/or --fragment options which were
added in beta8.  Typical usage would be:

  fragment 1400
  mssfix

Some notes:

* The TAP-Win32 adapter MTU defaults to 1500 which is
  the required setting for ethernet bridging.

* For some time before the Windows port of OpenVPN
  was completed, a default --link-mtu of 1300 has
  been in place for "tun" interfaces.  Because the
  Windows TAP-Win32 interface prefers an MTU of
  1500, it is essential to not rely on the
  default MTU value in this case, but to explicitly
  include 'tun-mtu 1500' on both sides of the
  connection.

* The MTU on both sides of an OpenVPN connection must
  exactly match.  On non-windows systems, the MTU
  of a tap device is usually set by the ifconfig
  command.

* The MTU of a TAP-Win32 adapter can be changed by
  going to Control Panel -> Network Connections ->
  [TAP-Win32 adapter name] -> Configure -> Advanced.

Notes -- Firewall on the Windows client
---------------------------------------

In general, it's a good idea to always protect
a VPN client or server with a firewall.

The important points for setting up firewalling
on a Windows system running OpenVPN are:

(1) Make sure that your connection to the internet
    is always firewalled, especially when you are
    running a VPN.  VPNs create trusted relationships
    between geographically disparate networks, and
    if any network on the VPN is compromised by
    a virus or worm, the exploit has the potential
    of jumping across the VPN and infecting other
    machines.
(2) You can enable firewalling
    on a given network adapter by going to
    Control Panel -> Network Connections, right-click
    on the icon that represents your link to the
    internet, select properties, go the the Advanced
    tab, and enable Internet Connection Firewall.
(3) If you are running OpenVPN as a server on a Windows
    machine, you will need to configure your firewall
    to allow incoming clients to connect to OpenVPN's
    port number which is UDP 5000 by default.
(4) In general, running OpenVPN as a client doesn't
    require any special firewall configuration,
    provided you use the --ping option to preserve
    the state of the OpenVPN connection in the
    firewall.
(5) In general, you don't need to enable firewalling
    on the TAP-Win32 adapter.  Once an IP
    packet appears to be "coming in" on the TAP-Win32
    adapter, it has already been decrypted and
    authenticated by OpenVPN, even though the
    connection between OpenVPN peers might transit
    an untrusted network such as the internet.
(6) One case where you might
    want to firewall the TAP-Win32 adapter is if you
    are connecting to an untrusted machine, or a machine
    which will route or bridge your connection with
    an untrusted network.

Notes -- Media Status
---------------------

1.5-beta2 of the driver has the Media Status patch.
This patch shows the TAP-Win32 adapter as being
"unplugged" whenever OpenVPN is not running.

Notes -- Error message from OpenVPN
-----------------------------------

OpenVPN can be on the chatty side when it comes
to error messages, and sleep-resume activity often
produces a flurry of non-fatal messages.  Most of
these messages can be safely ignored and are provided
for informational and debugging purposes only.

To suppress repeating messages, the --mute option
can be used.  For example --mute 10 will print
no more than 10 consecutive messages in the same
error class.  To suppress all error messages
except those that are fatal, use --verb 0.

Notes -- ARP/MAC Issues with the TAP-Win32 driver
-------------------------------------------------

Most TAP drivers allocate a random MAC to their virtual NIC.
If OpenVPN running on Windows disconnects and reconnects to
a remote peer, it is possible that that peer will reinitialize
its TAP device and generate a new random MAC, causing Windows to
temporarily lose access to the IP addresses exported by that
remote peer.  This is because Windows doesn't know that a given
IP address on the virtual TAP network now is associated with a
new MAC, so it tries to send packets to the old MAC, causing
them to be dropped.

Luckily, there is an easy solution to this problem.
Create a batch file with one or more of the following commands:

  arp -d [ip-address]

Where ip-address is a remote IP address at the other end of the
virtual TAP network whose access was lost due to an OpenVPN
restart.  The arp -d command will cause Windows
to "forget" the MAC address which it previously associated with
the given IP address.  Next time that IP address is used,
Windows will actively query the remote peer
(with an "arp who-has" message) to get the new MAC address.

You can also use 

  arp -d *

to purge all MAC addresses from the cache.

You can use the --up option in OpenVPN to automatically run a
given batch file immediately after TAP device initialization --
such a batch file can contain arp commands as described above.

Note that OpenVPN 1.5-beta8 and higher will execute the
"arp -d *" command automatically, unless explicitly
disabled with the --no-arp-del option.

Notes -- Limitations
--------------------

The following features which are normally available in the
Posix version of OpenVPN are either missing or implemented
differently in the Windows version as of 1.5-beta3.

(1) Only TAP virtual devices are supported on Windows, not
    TUN devices.  This means that OpenVPN on Windows can
    only connect to other platforms which also support
    TAP devices.

(2) --shaper doesn't work yet due to the lack of a
    gettimeofday library function.  This is not difficult
    to fix and could be implemented by borrowing some code
    from the cygwin library.

(3) Windows doesn't support Posix-style signals directly, however
    when OpenVPN is run from a command prompt window,
    keyboard shortcuts have been set up to simulate signals
    using the following mapping: F1:USR1 F2:USR2 F3:HUP F4:TERM.
    When running as a service, the OpenVPN service wrapper
    will send a terminate signal to all OpenVPN subprocesses when
    it gets a stop signal from the SCM (Service Control Manager).

Notes -- Differences between TAP-Win32 driver and CIPE driver
-------------------------------------------------------------

The TAP-Win32 driver distributed with OpenVPN 1.5-beta5 and
later is derived from Cipe-Win32 2.0-pre15 with some
significant changes:

(1)  Stability is much improved, especially with sleep/resume,
     using Michael Clarke's patch which upgrades the driver
     to NDIS5, properly implements sleep/resume OIDs, and fixes
     a race condition between AdapterTransmit and IRP_MJ_READ.

(2)  Added Christof Meerwald's "Media Status" patch which shows
     a given TAP-Win32 adapter as being "unplugged" when it is
     not currently open by an OpenVPN instance.

(3)  Modified the MAC generation code to follow the Linux
     algorithm for generating MACs, using 0:FF:XX:XX:XX:XX
     where XX:XX:XX:XX is random.

(4)  Added code to lock the TAP device so that only one
     OpenVPN instance can have it open at a time.

(5)  Added an MTU parameter which acts like the ifconfig
     mtu parameter under Linux.  The MTU defaults to
     1500 and can be changed through the adapter advanced
     properties dialog.

(6)  Set up the driver to keep track of its Rx/Tx stats
     rather than depending on userspace to set them.

(7)  Ran the driver through the windows driver verifier
     with all testing modes enabled, including low-resource
     simulation mode.  Based on the resulting bug checks,
     I was able to fix a number
     of problems including using MmGetSystemAddressForMdlSafe
     instead of MmGetSystemAddressForMdl, fixing several places
     in the code where the return status of
     NdisAllocateMemory is not checked, and making the flags
     match between NdisAllocateMemory and NdisFreeMemory calls.

(8)  Renamed the driver so that it shows up as a "TAP-Win32" adapter
     in the network control panel, and does not conflict with the
     CIPE driver.

(9)  Brought the driver up to SMP standards (beta8), redid
     the packet queueing subroutines as a circular queue
     for better efficiency and more straightforward
     locking semantics under SMP.

(10) Fixed dangling IRP bug that could potentially
     cause a bug check if driver was unloaded or disabled
     while still open by a userspace process (beta8).

(11) Fixed bug that rendered an adapter instance unusable
     if a userspace process tried to read a packet
     of data but provided a buffer that was too small
     to completely return the packet (beta8).

(12) Added several new ioctls to return interesting status
     information back to userspace, such as currently
     configured MTU value, driver version number,
     and extended error status information (beta8).

(13) Added "tun" device emulation (beta8).

(14) Adapter media state is now controlled directly from
     userspace using the TAP_IOCTL_SET_MEDIA_STATUS ioctl.

(15) An option has been added to the TAP-Win32 driver
     advanced properties page that allows you to control
     whether the adapter appears to Windows as
     "Always Connected" or whether the connection status
     is dynamically brought up and down by OpenVPN
     ("Application Controlled").

(16) To a certain extent, backwards compatibility with NT 4 has
     been sacrificed in the interest of better usability and
     stability on Win2K/XP.

Notes -- Manual configuration of the TAP-Win32 adapter
------------------------------------------------------

On XP Go to Start -> Control Panel -> Network Connections.

On Win2K, go to Start -> Settings -> Control Panel ->
Network (and Dial-up) Connections.

You should see a "TAP-Win32 Adapter" with a name like
"Local Area Connection 3".  Right click and rename
this to something shorter and without embedded spaces
such as "my-tap".

Now right click again and select properties.

Select Internet Protocol (TCP/IP) from the list
and click on Properties.

Set the IP address and subnet mask of your
new TAP device.  For the example below we
will use an IP of 10.3.0.1 and a subnet mask
of 255.255.255.0.  Other fields can be left
as they are.

Note also that the command line tool
netsh can do many of these same functions.

For example, the following command will set the IP
and subnet for my-tap:

  netsh interface ip set address my-tap static 10.3.0.1 255.255.255.0

This setting is persistent across reboots.

Notes -- List available TAP-Win32 adapters
------------------------------------------

Type:

  openvpn --show-adapters

at a command prompt.

You should see a list that looks like this:

Available TAP-Win32 devices:
[1] 'my-tap'

You can list all network interfaces with the
Windows "ipconfig" command, and all TAP-Win32
interfaces should be included among them.

Notes -- Windows and TAP device naming
--------------------------------------

Basically what happens when you install the
TAP-Win32 driver is that you get a new network adapter
that shows up in your network control panel.  You right
click on the TAP adapter and set the TCP/IP properties,
i.e. IP address and netmask.  Then you rename the TAP
adapter icon to something like "my-tap" and reference
it using the --dev-node option in OpenVPN.

Windows also has command line utilities to accomplish
these same kinds of tasks such as devcon, netsh,
and ipconfig.

Notes -- Building from source
-----------------------------

This section is for developers only.

You will need the following:

(1) MinGW/MSYS environment
    http://mingw.sourceforge.net/

(2) OpenSSL library
    http://www.openssl.org/

(3) LZO library
    http://www.oberhumer.com/opensource/lzo/

(4) Windows DDK (available only from Microsoft)
    http://www.microsoft.com/whdc/ddk/winddk.mspx

(5) Nullsoft Install System (optional)
    http://www.nullsoft.com/free/nsis/

It should be noted that Visual C++ is NOT required.
The open-source MinGW compiler is used to build the
userspace component of OpenVPN, and the DDK is used
to build the driver component.

First build the usermode component of OpenVPN
from the top-level directory of the OpenVPN
source distribution:

Edit makefile.32 with the location of
your OpenSSL and LZO distributions.  Note that
it is only necessary to build these distributions,
not to install them.

Note that the makefile accepts a 'dynamic'
or 'static' target, depending on the way
you want to link with the OpenSSL library.

By default the makefile will attempt to
dynamically link with OpenSSL.

Type:
  make -f makefile.w32

This will build the user mode component of OpenVPN.

Now build the TAP-Win32 kernel driver:

Go to Start -> All Programs -> Development Kits -> Windows DDK
  -> Build Environments -> Win Free Build Environment

Use the Checked Build Environment if you want a debugging version.

A command prompt window will open.  Go to the tap-win32 directory
of the OpenVPN distribution.

Type:
  build -cef

This will build the kernel driver in the i386 directory.

At this point you will have built:

.\openvpn.exe -- openvpn daemon
.\tap-win32\i386\tapdrvr.sys -- TAP-Win32 kernel driver

Copy openvpn.exe to a directory in your path.
If you build dynamically with OpenSSL, copy the OpenSSL
DLLs to a directory in your path.

If you want to build a self-installing EXE, consult
the NSIS install script (openvpn.nsi) in the
install-win32 directory.  You will need to edit
openvpn.nsi to reflect the setup of your
development environment.

See instructions below for installing the kernel driver.

Notes -- Manual Install/Update/Uninstall of the TAP-Win32 kernel driver
-----------------------------------------------------------------------

This is best done using devcon.exe, a DDK sample which is distributed
with the self-installing form of OpenVPN on Windows.  Cd to the
directory which contains OemWin2k.inf and tapdrvr.sys.

To install:
  devcon install OemWin2k.inf TAP

To update:
  devcon update OemWin2k.inf TAP

To uninstall:
  devcon remove TAP

By installing multiple times, you will create
additional TAP-Win32 adapter instances, which can
be used for multiple concurrent VPN tunnels.

It is also possible to install using Control Panel ->
Add New Hardware, and it is possible to uninstall
using Control Panel -> System -> Hardware -> Device
Manager.

Notes -- OpenVPN Performance Benchmarks
---------------------------------------

All tests with OpenVPN 1.5-beta2 on systems
locally connected to a 100Mbps LAN using
UDP tunnel transport, TAP devices
with an MTU of 1500, and no compression.

[---------------------]
[     TEST #1         ]
[---------------------]

Linux 2.4.21 P2 266Mhz <-> Linux 2.4.21 P4 2.4Ghz

OpenVPN Blowfish tunnel
-----------------------

FTP get on 266Mhz

 33128460 bytes received in 23.1 secs (1.4e+03 Kbytes/sec)
 33128460 bytes received in 25.7 secs (1.3e+03 Kbytes/sec)

FTP send on 266MHz

 33128460 bytes sent in 16.9 secs (1.9e+03 Kbytes/sec)
 33128460 bytes sent in 15.8 secs (2e+03 Kbytes/sec)

OpenVPN plaintext tunnel
------------------------

FTP get on 266Mhz

 33128460 bytes received in 9.75 secs (3.3e+03 Kbytes/sec)
 33128460 bytes received in 9.65 secs (3.4e+03 Kbytes/sec)

FTP send on 266MHz

 33128460 bytes sent in 8.21 secs (3.9e+03 Kbytes/sec)
 33128460 bytes sent in 9.65 secs (3.4e+03 Kbytes/sec)

Direct FTP without OpenVPN
--------------------------

FTP get on 266Mhz

 33128460 bytes received in 4.73 secs (6.8e+03 Kbytes/sec)
 33128460 bytes received in 4.75 secs (6.8e+03 Kbytes/sec)

FTP send on 266MHz

 33128460 bytes sent in 4 secs (8.1e+03 Kbytes/sec)
 33128460 bytes sent in 3.93 secs (8.2e+03 Kbytes/sec)

[---------------------]
[     TEST #2         ]
[---------------------]

Linux 2.4.21 P2 266Mhz <-> Win XP SP1 P4 2.2 Ghz

OpenVPN Blowfish tunnel
-----------------------

FTP get on Win XP

 33128460 bytes received in 19.14Seconds 1731.03Kbytes/sec.
 33128460 bytes received in 19.11Seconds 1733.84Kbytes/sec.

FTP send on Win XP

 33128460 bytes sent in 23.46Seconds 1411.94Kbytes/sec.
 33128460 bytes sent in 23.44Seconds 1413.09Kbytes/sec.

OpenVPN plaintext tunnel
------------------------

FTP get on Win XP

 33128460 bytes received in 11.31Seconds 2930.17Kbytes/sec.
 33128460 bytes received in 11.89Seconds 2786.95Kbytes/sec.

FTP send on Win XP

 33128460 bytes sent in 11.72Seconds 2827.38Kbytes/sec.
 33128460 bytes sent in 10.71Seconds 3094.67Kbytes/sec.

Direct FTP without OpenVPN
--------------------------

FTP get on Win XP

 33128460 bytes received in 5.55Seconds 5971.24Kbytes/sec
 33128460 bytes received in 5.39Seconds 6148.56Kbytes/sec

FTP send on Win XP

 33128460 bytes sent in 4.90Seconds 6765.05Kbytes/sec
 33128460 bytes sent in 4.91Seconds 6751.27Kbytes/sec
