vpnkit

A toolkit for embedding VPN capabilities in your application.

VPN-friendly networking devices for HyperKit.

Binary artefacts are built by CI:

• MacOS
• Windows

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

Building on Unix (including Mac)

First install wget, opam and pkg-config using your package manager of choice.

If you are an existing opam user then you can either build against your existing opam package universe, or the custom universe contained in this repo. To use the custom universe, ensure that you unset your OPAMROOT environment variable:

unset OPAMROOT

To build, type

make

The first build will take a little longer as it will build all the package dependencies first.

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

Building on Windows

First install the OCaml environment with Cygwin. Note that although the Cygwin tools are needed for the build scripts, Cygwin itself will not be linked to the final executable.

Inside the OCaml64 (Cygwin) shell, unset the OPAMROOT environment and build by:

unset OPAMROOT
make

The first build will take a little longer as it will build all the package dependencies first.

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

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

• Using vpnkit as a default gateway: describes the flow of ethernet traffic to/from the VM
• Port forwarding: describes how ports are forwarded from the host into the VM
• Experimental transparent HTTP proxy: describes the experimental support for transparent HTTP(S) proxying

from  https://github.com/moby/vpnkit

-----

A toolkit for embedding hypervisor capabilities in your application.

HyperKit is a toolkit for embedding hypervisor capabilities in your application. It includes a complete hypervisor, based on xhyve/bhyve, which is optimized for lightweight virtual machines and container deployment. It is designed to be interfaced with higher-level components such as the VPNKit and DataKit.

HyperKit currently only supports macOS using the Hypervisor.framework. It is a core component of Docker Desktop for Mac.

Requirements

• OS X 10.10.3 Yosemite or later
• a 2010 or later Mac (i.e. a CPU that supports EPT)

Reporting Bugs

If you are using a version of Hyperkit which is embedded into a higher level application (e.g. Docker Desktop for Mac) then please report any issues against that higher level application in the first instance. That way the relevant team can triage and determine if the issue lies in Hyperkit and assign as necessary.

If you are using Hyperkit directly then please report issues against this repository.

Usage

$ hyperkit -h

Building

$ git clone https://github.com/moby/hyperkit
$ cd hyperkit
$ make

The resulting binary will be in build/hyperkit

To enable qcow support in the block backend an OCaml OPAM development environment is required with the qcow module available. A suitable environment can be setup by installing opam and libev via brew and using opam to install the appropriate libraries:

$ brew install opam libev
$ opam init
$ eval `opam env`
$ opam pin add qcow.0.11.0 git://github.com/mirage/ocaml-qcow -n
$ opam pin add qcow-tool.0.11.0 git://github.com/mirage/ocaml-qcow -n
$ opam install uri qcow.0.11.0 conduit.2.1.0 lwt.5.3.0 qcow-tool mirage-block-unix.2.12.0 conf-libev logs fmt mirage-unix prometheus-app

Notes:

• opam config env must be evaluated each time prior to building hyperkit so the build will find the ocaml environment.

• Any previous pin of mirage-block-unix or qcow should be removed with the commands:

  $ opam update
  $ opam pin remove mirage-block-unix
  $ opam pin remove qcow

Tracing

HyperKit defines a number of static DTrace probes to simplify investigation of performance problems. To list the probes supported by your version of HyperKit, type the following command while HyperKit VM is running:

 $ sudo dtrace -l -P 'hyperkit$target' -p $(pgrep hyperkit)

Refer to scripts in dtrace/ directory for examples of possible usage and available probes.

Relationship to xhyve and bhyve

HyperKit includes a hypervisor derived from xhyve, which in turn was derived from bhyve. See the original xhyve README which incorporates the bhyve README.

We try to avoid deviating from these upstreams unnecessarily in order to more easily share code, for example the various device models/emulations should be easily shareable.

Reporting security issues

The maintainers take security seriously. If you discover a security issue, please bring it to their attention right away!

Please DO NOT file a public issue, instead send your report privately to security@docker.com.

Security reports are greatly appreciated and we will publicly thank you for it. We also like to send gifts—if you're into Docker schwag, make sure to let us know. We currently do not offer a paid security bounty program, but are not ruling it out in the future.

from  https://github.com/moby/hyperkit