A toolkit for embedding VPN capabilities in your application
OCaml Groff Shell Makefile
Latest commit 767ab11 Jan 23, 2017 @djs55 djs55 committed on GitHub Merge pull request #176 from djs55/add-mtu
Increase the MTU on the virtual ethernet link

README.md

VPN-friendly networking devices for HyperKit

Build Status (OSX)

Binary artefacts are built by CI:

VPNKit diagram

VPNKit is a set of tools and services for helping HyperKit VMs interoperate with host VPN configurations.

Building on Unix

First install wget, opam using your package manager of choice. Build all the dependencies and the program itself with:

opam pin add vpnkit .

This will add the binary com.docker.slirp to your $PATH.

Running with hyperkit

First ask com.docker.slirp to listen for ethernet connections on a local Unix domain socket:

com.docker.slirp --ethernet /tmp/ethernet --debug

Next ask com.docker.hyperkit to connect a NIC to this socket by adding a command-line option like -s 2:0,virtio-vpnkit,path=/tmp/ethernet. Note: you may need to change the slot 2:0 to a free slot in your VM configuration.

Why is this needed?

Running a VM usually involves modifying the network configuration on the host, for example by activating Ethernet bridges, new routing table entries, DNS and firewall/NAT configurations. Activating a VPN involves modifying the same routing tables, DNS and firewall/NAT configurations and therefore there can be a clash -- this often results in the network connection to the VM being disconnected.

VPNKit, part of HyperKit attempts to work nicely with VPN software by intercepting the VM traffic at the Ethernet level, parsing and understanding protocols like NTP, DNS, UDP, TCP and doing the "right thing" with respect to the host's VPN configuration.

VPNKit operates by reconstructing Ethernet traffic from the VM and translating it into the relevant socket API calls on OSX or Windows. This allows the host application to generate traffic without requiring low-level Ethernet bridging support.

Design

  • ethernet: describes the flow of ethernet traffic to/from the VM
  • DNS: describes the DNS forwarder implementation