Gert Döring - IPv6 Payload Patch for OpenVPN

IPv6 Payload Patch for OpenVPN 2.1 and 2.2

Latest News

The IPv6 payload patch has been rebased to OpenVPN 2.2.0 - so get the 2.2 sources, and apply the patch there. See "The Patch Sets" below.

Background

As of OpenVPN v2.1, OpenVPN has limited support for transporting IPv6 packets (IPv6 payload):

in TAP mode, OpenVPN will transport ethernet frames, and will not care whether there is IPv4 or IPv6 inside. No support for automatically configuring the endpoints, though.
in point-to-point TUN mode, OpenVPN can transport IPv6 packets with the --tun-ipv6 option. No support for configuring the IPv6 endpoints and routes from within OpenVPN either, you need to run external ``up'' scripts.
in point-to-multipoint TUN mode (``TUN server mode''), there is no support for IPv6 yet.

OpenVPN v2.1 has no support for transporting VPN packets over IPv6 transport (``IPv4, IPv6 or Ethernet inside, IPv6 outside'') either, but there are other people already working on this, so I did not touch this field. See here for JuanJo's OpenVPN-over-IPv6 patch. My patch and JuanJo's patch are mostly compatible and can be used together, to get IPv6-in-OpenVPN-over-IPv6.

OpenVPN v2.2 does not contain the patch for OpenVPN itself, but it has the necessary patches for the Windows TAP driver, and the v2.2.2 package contains a signed tap driver that can be used on Win7-64 to make things work.

OpenVPN v2.3 will have both patch sets incorporated to provide a fully IPv6 capable OpenVPN. We expect the first alpha release of v2.3 to happen at FOSDEM2012 in February 2012 (but if you're impatient, get the sources from openvpn git).

The Features

The patch set below adds support for transporting IPv6 payload in point-to-multipoint (P2MP) TUN server mode. That is, you run a single OpenVPN instance on the VPN server side, and multiple clients connect to it.

Every client is assigned a single IPv6 address by the server, coming from a shared transfer network between all clients and the server. Usually this would be a common /64, but theoretically a smaller subnet could also be used (not implemented yet).

This is analogous to the IPv4 option ``--topology subnet'', implemented by OpenVPN 2.1 and up, and unlike the old ``net30'' topology that allocates a dedicated /30 per client. Since IPv6 subnets are ``big enough'' by definition, the extra effort of defining different topology options and writing the implementation could be avoided. (Depending on operating system capabilites and configured IPv4 topology, the actual tunnel interface will be configured as ``point-to-point'' or ``network'', but logically it's always a shared subnet for all clients).

If a whole subnet is to be routed to a network ``behind'' an OpenVPN client (in addition to the single host address allocated automatically), this can be done with ``iroute'' and per-client configuration (--client-config-dir dir).

No automatic support for ``receive a whole prefix from the server, do something smart with it'' (as in ``configure on internal ethernet, setup radvd, ...'') exists in the client implementation yet. If needed, this could be achieved by scripts on the client side in combination with something like ``push setenv-safe MYNETWORK 2001:db8:1::/64'' (see man page) in the server's per-client configuration.

The Configuration

new options for the server side:

option what it does

server-ipv6 2001:db8::/64 sort of a macro - enables IPv6 server mode, sets up local IPv6 addresses for the TUN interface on the server (ifconfig-ipv6 $prefix::1 $prefix::2), sets up ifconfig-ipv6-pool and tun-ipv6 accordingly

ifconfig-ipv6 2001:db8:5::1 2001:db8:5::2 interface configuration for TUN interface, usually setup automatically via ``server-ipv6'' on the server side and via automatic push from the server to the client.
The first address given is used for the ``tun'' interface (``ifconfig'' on the operating system side), the second address is used as a route gateway for operating systems that do not know how to setup a route to an interface without an explicit gateway IP address.

ifconfig-ipv6-pool 2001:db8:6::7/64 hand out IPv6 addresses from the specified pool with the specified netbits (/64) to the clients. Do not use IPv6 addresses lower than the one specified (in this example: ::1 to ::6 are reserved for other purposes). Usually setup automatically by ``server-ipv6''.
caveat: the implementation is currently tied to ``ifconfig-pool'' - that is, IPv6 addresses are always allocated and released together with IPv4, and if the IPv4 pool is full, no IPv6 address can be allocated either. Needs cleanup when IPv4 is finally dead.

ifconfig-pool-persist file sec not a new option, but now also used to store ``ifconfig-ipv6-pool'' assignments (for information, not used on reading)

iroute-ipv6 2001:db8:a0::/60 route an IPv6 prefix to a specific client (goes to per-client configuration file, needs ``route-ipv6'' statement to install the route from the OS to the OpenVPN server)

route-ipv6 2001:db8:1000::/60 similar to ``route'' for IPv4 - route this prefix from the operating system to the OpenVPN process, and subsequently across the tunnel. Needed to complement ``iroute-ipv6'' on the server side, and pushed to the client to get packets to the ``internal network'' routed through the tunnel.

push route-ipv6 ... tell the client to route the specific prefix via the OpenVPN tunnel

ifconfig-ipv6-push 2001:db8:1001::1 Push ``ifconfig-ipv6'' config to client, and route the specified IPv6 address to that client. To be used from ccd/ per-client configuration, analogous to ``ifconfig-push'' for IPv4.

tun-ipv6 enable IPv6 routing on the tunnel. Not strictly a new option, but was only implemented in point-to-point mode so far (with manual configuration of all the IPv6 parameters and routing).

option	what it does
server-ipv6 2001:db8::/64	sort of a macro - enables IPv6 server mode, sets up local IPv6 addresses for the TUN interface on the server (ifconfig-ipv6 $prefix::1 $prefix::2), sets up ifconfig-ipv6-pool and tun-ipv6 accordingly
ifconfig-ipv6 2001:db8:5::1 2001:db8:5::2	interface configuration for TUN interface, usually setup automatically via ``server-ipv6'' on the server side and via automatic push from the server to the client. The first address given is used for the ``tun'' interface (``ifconfig'' on the operating system side), the second address is used as a route gateway for operating systems that do not know how to setup a route to an interface without an explicit gateway IP address.
ifconfig-ipv6-pool 2001:db8:6::7/64	hand out IPv6 addresses from the specified pool with the specified netbits (/64) to the clients. Do not use IPv6 addresses lower than the one specified (in this example: ::1 to ::6 are reserved for other purposes). Usually setup automatically by ``server-ipv6''. caveat: the implementation is currently tied to ``ifconfig-pool'' - that is, IPv6 addresses are always allocated and released together with IPv4, and if the IPv4 pool is full, no IPv6 address can be allocated either. Needs cleanup when IPv4 is finally dead.
ifconfig-pool-persist file sec	not a new option, but now also used to store ``ifconfig-ipv6-pool'' assignments (for information, not used on reading)
iroute-ipv6 2001:db8:a0::/60	route an IPv6 prefix to a specific client (goes to per-client configuration file, needs ``route-ipv6'' statement to install the route from the OS to the OpenVPN server)
route-ipv6 2001:db8:1000::/60	similar to ``route'' for IPv4 - route this prefix from the operating system to the OpenVPN process, and subsequently across the tunnel. Needed to complement ``iroute-ipv6'' on the server side, and pushed to the client to get packets to the ``internal network'' routed through the tunnel.
push route-ipv6 ...	tell the client to route the specific prefix via the OpenVPN tunnel
ifconfig-ipv6-push 2001:db8:1001::1	Push ``ifconfig-ipv6'' config to client, and route the specified IPv6 address to that client. To be used from ccd/ per-client configuration, analogous to ``ifconfig-push'' for IPv4.
tun-ipv6	enable IPv6 routing on the tunnel. Not strictly a new option, but was only implemented in point-to-point mode so far (with manual configuration of all the IPv6 parameters and routing).

Other Uses

While the patch was primarily built to enable point-to-multipoint tun, it should help other uses as well:

point-to-point tun with the patch, you can now set ``ifconfig-ipv6'' and ``route-ipv6'' in the config file and don't need to run a separate ``up''-script to setup IPv6 on the tun0 interface. Less different files, all configuration in one place. Should work, but yet untested.
point-to-multipoint tap could profit from having a central server that has an ``ifconfig-ipv6-pool'' defined and will hand out IPv6 addresse for interface configuration to the TAP clients. I don't know whether it works, though - some parts of the code might have some assumptions about ``ifconfig-ipv6-pool only works in tun mode'' - needs testing.
point-to-point tap can use ``ifconfig-ivp6'' and ``route-ipv6'' to setup IPv6 addresses and routing from within the OpenVPN config file, without resorting to external scripts.

Test Results

The following table lists operating systems successfully tested in ``server-ipv6'' or ``client vs. IPv6-enabled server'' mode. If a column is empty, I have not tested this myself - it might work, or might not work, please let me know. Those cells marked with a "(*)" are combinations I use for daily production use, so those are very well tested.

OS/variant server-ipv6 client-ipv6 remarks

Linux/iproute2 ok, 09-12-31 ok, 09-12-31 (*) gert

Linux/ifconfig ok, 09-12-31 ok, 09-12-31 gert, berniv6

Linux/ARM (Debian Squeeze) ok, 10-06-18 (*) ok, 10-06-18 gert

FreeBSD 6.3/i386 ok, 10-01-01 (*) gert

FreeBSD 7.3/i386 ok, 10-09-01 (*) gert

MacOS X 10.5 i386 ok, 10-01-02 gert

NetBSD 3.1/Sparc64 no kernel IPv6 support on tun interfaces gert

NetBSD 5.0/Sparc64 ok, 10-01-03 gert

Solaris 10U5/Sparc64 ok, 10-01-04 gert

Windows XP ok, 10-03-07 gert (tap 9.7!)

Windows 7 Home Premium ok, 11-05-20 gert (signed tap from 2.2 release)

OpenWRT 10.03/ar71xx ok, 10-06-10 (*) ok, 10-06-18 gert (ipk here)

OpenBSD 4.7/i386 ok, 10-08-08 gert (in git)

OS/variant	server-ipv6	client-ipv6	remarks
Linux/iproute2	ok, 09-12-31	ok, 09-12-31 (*)	gert
Linux/ifconfig	ok, 09-12-31	ok, 09-12-31	gert, berniv6
Linux/ARM (Debian Squeeze)	ok, 10-06-18 (*)	ok, 10-06-18	gert
FreeBSD 6.3/i386	ok, 10-01-01 (*)		gert
FreeBSD 7.3/i386	ok, 10-09-01 (*)		gert
MacOS X 10.5 i386		ok, 10-01-02	gert
NetBSD 3.1/Sparc64		no kernel IPv6 support on tun interfaces	gert
NetBSD 5.0/Sparc64		ok, 10-01-03	gert
Solaris 10U5/Sparc64		ok, 10-01-04	gert
Windows XP		ok, 10-03-07	gert (tap 9.7!)
Windows 7 Home Premium		ok, 11-05-20	gert (signed tap from 2.2 release)
OpenWRT 10.03/ar71xx	ok, 10-06-10 (*)	ok, 10-06-18	gert (ipk here)
OpenBSD 4.7/i386		ok, 10-08-08	gert (in git)

Other combinations that have been (mostly successfully) tested:

Client Server remarks

unmodified 2.1rc15 IPv6-enabled server warnings about unknown config options (ifconfig-ipv6, route-ipv6), but does not fail

unmodified, various client versions IPv6-enabled server warnings about unknown config options (ifconfig-ipv6, route-ipv6), but does not fail

unmodified, various client versions patched server, but IPv6 not enabled no visible change to the client - works as usual

older clients (debian lenny, 2.0rc11) IPv6-enabled server with lots of ``push'' options configured (long string, needing push-continuation) fails, because IPv4 ifconfig is sent in a 2nd ``push'' packet, which the older client doesn't handle (reduce number of ``push'' options)

Client	Server	remarks
unmodified 2.1rc15	IPv6-enabled server	warnings about unknown config options (ifconfig-ipv6, route-ipv6), but does not fail
unmodified, various client versions	IPv6-enabled server	warnings about unknown config options (ifconfig-ipv6, route-ipv6), but does not fail
unmodified, various client versions	patched server, but IPv6 not enabled	no visible change to the client - works as usual
older clients (debian lenny, 2.0rc11)	IPv6-enabled server with lots of ``push'' options configured (long string, needing push-continuation)	fails, because IPv4 ifconfig is sent in a 2nd ``push'' packet, which the older client doesn't handle (reduce number of ``push'' options)

Tests needed...:

point-to-multipoint tun on the following list of operating systems
- FreeBSD (client side)
- NetBSD (more different versions and platforms)
- Solaris (9, 10, OpenSolaris)
- MacOS X (Darwin) (more versions, server side)
point-to-point tun with IPv6 config in the OpenVPN config files
point-to-multipoint tap with IPv6 config (``ifconfig-ipv6'') and IPv6 pools (``ifconfig-ipv6-pool'')
``ifconfig-pool-persist'' with IPv6

What Does Not Work

Some things have not been implemented yet, to get this out quickly:

Windows support - I have no windows programming environment available, nor ANY clue how win32 programming is done. Patches welcome. This might require implementing a DHCPv6 server on the TAP interface... UPDATE Windows has been implemented and support is there since 20100301-1. There is no packaged installer yet, as the whole ``build software under windows'' thing is a bit tricky if all you know is unix. Since the official TUN/TAP driver does not have IPv6 support yet, you need to patch and replace the driver as well. Instructions to come.
UPDATE the 2.2-beta3 release from openvpn.net contains an IPv6-capable signed(!) TAP driver. Using that with a self-compiled openvpn.exe with the patch will give you IPv6 without having to compile the driver yourself.
UPDATE HERE is a windows installer with GUI (early snapshot version!) and IPv6 and signed TAP driver. Use on your own risk.
UPDATE 2011-05-21 HERE is a new windows installer based on OpenVPN 2.2.0 + IPv6 payload, with GUI (early snapshot version!) and IPv6 and signed TAP driver. This one properly cleans up the TAP interface after session shutdown and is compiled with --enable-saved-passwords. Tested on XP SP3 and Win7.
UPDATE 2011-05-22 HERE is yet another new windows installer with some more IPv6 route cleanups.
IPv6 interface pool is fully dependent on IPv4, that is: you can't run an IPv6 pool without an IPv4 pool. Design decision, re-use of the same code. (You should be able to run this without any IPv4 ``push route'' stuff towards the client, effectively creating v6-only VPN with additional v4 IP addresses on the interfaces).
patches exist to enable OpenVPN over IPv6 transport - and they might interfere with IPv6 payload support in surprising ways (like ``changing IPv6 routes in a way that breaks IPv6 tunnel endpoint reachability''). No provisions have been taken in the code yet to handle these cases.
``--topology subnet'' puts the server tun interface into not-ptp-mode, which causes ICMPv6 neighbor solicitations to be sent - which are ignored by Linux on the client side, and thus communication fails. Don't use --topology subnet togheter with IPv6 (as of today).
management interface - no work has been done yet to figure out how the management interface works, and what is needed to signal IPv6 information there. Mostly a question of available time.

The Patch Sets

Date	Link	ChangeLog
20009-12-31	openvpn-2.1-ipv6-20091231-1.patch.gz	basic client-server p2mp functionality works tested on linux with a single simultaneous client (ping, and ssh). iroute-ipv6 is not working yet.
2010-01-01	openvpn-2.1-ipv6-20100101-1.patch.gz	iroute-ipv6 implemented and tested (Linux and FreeBSD 6), works. tested on FreeBSD 6.3 (server side), works. tested on NetBSD, does not work yet. ChangeLog.IPv6 and README.IPv6 included.
2010-01-03	openvpn-2.1-ipv6-20100103-1.patch.gz	fixed system-dependent stuff for NetBSD and MacOS X (major rework of tunnel open/read/write code for NetBSD, needs to use multi-af mode). fixed setting of gateway IPv6 address for route-ipv6 config options without gateway address. tested on MacOS 10.5 (client side). works. tested on NetBSD 5.0/Sparc64 (client side). works!.
2010-01-04	openvpn-2.1-ipv6-20100104-1.patch.gz	adapted ifconfig/route stuff and system dependent stuff (u_int32_t) for Solaris 10. tested on Solaris 10/Sparc64 (client side) - works!. Use together with the ``new'' tun/tap driver from here. Implement online help (openvpn --help) for new options.
2010-01-14	openvpn-2.1-ipv6-20100114-1.patch.gz	fixed NetBSD-pre-4.0 which has no multi-af tunnels. implement ``ifconfig-ipv6-push'' ccd/ option (for gizmo). add lots of warnings to code to spot common misconfigurations. GIT repository set up (berniv6).
2010-02-16	openvpn-2.1-ipv6-20100216-1.patch.gz	print patch version on --version. fix ``make check'' regression (revert unneeded change). rebase to OpenVPN-Testing GIT tree.
2010-03-07	openvpn-2.1-ipv6-20100307-1.patch.gz	Windows support! (needs new TUN/TAP driver, no easy-to-install binary distribution yet) cleanup MacOS X support (clean deconfiguration of IPv6 address on close) cleanup NetBSD support (destroy/recreate tun, remove ``old'' config)
2011-04-24	openvpn-2.2RC2-ipv6-20110424-2.patch.gz	patch vs OpenVPN 2.2 RC2 Solaris TUN and TAP support OpenBSD support (tested on OpenBSD 4.7) Linux/iproute2 and "topology subnet" + ipv6 fixed various platform cleanups Linux and Solaris: configuring and pushing IPv6 addresses for "TAP" interfaces implemented. Pushing routes doesn't work yet.
2011-05-22	openvpn-2.2.0-ipv6-20110522-1.patch.gz	patch vs. OpenVPN 2.2.0 release Windows IPv6 cleanups (properly deconfigure addresses and routes on disconnected). Windows installer is here, tested on XP SP3 and Win7. This patch does not compile with Microsoft Visual C++ on Windows, but it nicely builds with msys/mingw, read and follow ``domake-win'' in the source.

Acknowledgement

Thanks goes to:

Thomas Glanzmann, for doing the initial work with ``tun-ipv6'' and figuring out how to enable IPv6 on TUN interfaces on various operating systems.
Bernhard Schmidt, for helping with documentation and coordination
Jan Dirnberger, for nagging long enough to get me started
James Yonan (OpenVPN), for helping me to get started with the Windows stuff
Jeroen Massar (Sixxs), for answering questions about AICCU and Windows
Seth Mos and Tony Lim, for helping with Windows netsh.exe corrections, and for testing on Windows.

Binary Packages

Bernhard Schmidt has put up debian/ubuntu binary packages for easy installing of fully IPv6 capable OpenVPN, both with IPv6 transport as well as IPv6 payload.

A (preliminary) Windows package of openvpn-testing/allmerged ("with all the nice goodies") as of September 08, 2010, with the openvpn-gui snapshot 20100827, is HERE

If you use OpenWRT, I have compiled two packages (OpenVPN 2.1.1 plus my IPv6 patch, no other -devel patches) for the platforms I have available and can test. Download with "wget" to your router, install with "opkg install ./openvpn*ipv6*ipk"

OpenWRT 10.03 (Backfire), AR71xx chipset, e.g Buffalo WZR-HP-G300NH or TP-Link TL-WR1043ND(20100307_2 ipk)
OpenWRT 10.03 (Backfire), Broadcom chipset / 2.4 variant, e.g. Cisco/Linksys WRT54GL (20100307_2 ipk)

(Don't send me questions whether this works for your specific OpenWRT hardware - I wouldn't know, I don't know other OpenWRT-supported platforms, and which chipsets are used inside. If your normal opkg packets have names ending in "ar71xx.ipk" or "brcm-2.4.ipk", chances are fairly good that it will work...)

UPDATE: there is an openvpn-devel package available in the official openwrt packages feed now, so you can get your IPv6-enabled binary from THERE (pick the subdirectory according to platform, and then go to the "packages" directoryn in there, e.g. ".../trunk/ar71xx/packages/") and the OpenWRT 10.03.1 release should then have it available for direct installing with "ipk install openvpn-devel".

Whether you trust a binary compiled by someone you don't know is your choice, of course. If you don't, just get the OpenVPN source and the patch set, review the source for backdoors, and build your own binary.

GIT repository

I'm working with Berni's repository, which can be found here:

git://git.birkenwald.de/openvpn.git

and my stuff is in the ``gert-ipv6'' branch.

There is an official OpenVPN testing repository now, to be found at:

git://openvpn.git.sourceforge.net/gitroot/openvpn/openvpn-testing.git

The IPv6 payload and IPv6 transport patch have both been merged into the ``master'' branch. The old ``feat_ipv6_payload'' branch is not maintained anymore, work continues in ``master'', which will be released as v2.3 alpha really soon now.

Feedback

If you test this, and want to report anything back (it works, it does not work, it needed a patch, ...) please contact me at gert<at>greenie.muc.de

You can also comment my blog article (German!) about this project.

Please do not send me questions for precompiled binaries for your architecture of choice. This stuff is in a quite early phase, and you should have some experience in compiling and patching open source software to make use of it (I hope that the IPv6 stuff will be integrated into the main OpenVPN line, and then the distribution vendors will of course pick it up).