vpnkit

VPN-friendly networking devices for HyperKit
README

Binary artefacts are built by CI:

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:

cd [path to vpnkit source]
opam remote add vpnkit ./repo/darwin
opam install --deps-only vpnkit
make

When the build succeeds the vpnkit binary should be available in the current path.

Running with hyperkit

First ask vpnkit to listen for ethernet connections on a local Unix domain socket:

vpnkit --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

Licensing

VPNKit is licensed under the Apache License, Version 2.0. See
LICENSE for the full
license text.

Contributions are welcome under the terms of this license. You may wish to browse
the weekly reports to read about overall activity in the repository.