Tunfish Sandbox

About

A SDN proof-of-concept for approaching convenient VXLAN Layer 2/3 convergence on top of secure WireGuard tunnels.

This runbook will guide you through the process of setting up an appropriate testbed environment. It will provision a number of Vagrant machines and configure them to talk to each other over a software-defined secure private network.

After that, you will easily be able to conduct connectivity tests and continue with further experiments.

Details

While the effective network transport is based on IP/UDP, the virtual circuit offers Data Link Layer (Layer 2) connectivity on a multi-tenant basis through VXLAN.

As this unlocks the capability to send Ethernet frames across IP networks, it will eventually become possible to use protocols and technologies reserved for local networks (LANs) so far.

It opens the door to countless applications requiring Data Link Layer connectivity like Zeroconf, Multicast DNS (mDNS) or DNS Service Discovery (DNS-SD) and their popular implementations and applications like Bonjour, Avahi and .local.

Other candidates are Universal Plug and Play (UPnP), the Service Location Protocol (SLP) and Web Services Dynamic Discovery (WS-Discovery).

Setup

This section will guide you through setting up a development/testing sandbox on your machine.

Acquire source repository:

git clone https://github.com/tunfish/tunfish-sandbox
cd tunfish-sandbox/environment/quickstart

Install requirements on Mac OS X using Homebrew:

./requirements-macosx.sh

Make Vagrant provision and spin up all machines configured in this environment:

vagrant up

Network layout

There are two machines "tf-alice" and "tf-bob", completely provisioned by Vagrant.

As they are running different networks (IP transport, WireGuard tunnel, VXLAN), here is a short overview as an introduction. Please read this section carefully.

192.168.50.1        The hypervisor host on its "vboxnet0" interface
192.168.50.51       The guest host "tf-alice" on its "eth1" interface
192.168.50.52       The guest host "tf-bob"   on its "eth1" interface

10.10.10.51         The host "tf-alice"
10.10.10.52         The host "tf-bob"

10.10.20.51         The host "tf-alice"
10.10.20.52         The host "tf-bob"

Usage

vagrant ssh tf-alice
vagrant ssh tf-bob

systemctl start wg-quick@wg0-server

# Login to alice
vagrant ssh tf-alice

# Ping bob
vagrant@tf-alice:~$ ping 10.10.10.52
64 bytes from 10.10.10.52: icmp_seq=1 ttl=64 time=0.650 ms

# Login to bob
vagrant ssh tf-bob

# Ping alice
vagrant@tf-bob:/tmp$ ping 10.10.10.51
64 bytes from 10.10.10.51: icmp_seq=1 ttl=64 time=0.497 ms

vagrant ssh tf-alice
sudo /opt/quickstart-dev/tunfish-client/tunfish-join.sh

vagrant ssh tf-bob
sudo /opt/quickstart-dev/tunfish-client/tunfish-join.sh

# Login to alice
vagrant ssh tf-alice

# Ping bob
vagrant@tf-alice:~$ ping 10.10.20.52
64 bytes from 10.10.20.52: icmp_seq=1 ttl=64 time=0.672 ms

# Login to bob
vagrant ssh tf-bob

# Ping alice
vagrant@tf-bob:/tmp$ ping 10.10.20.51
64 bytes from 10.10.20.51: icmp_seq=1 ttl=64 time=0.484 ms

brctl showmacs tb-quickstart | grep no

bridge fdb show | grep -v permanent | grep master

nmap -sP 10.10.20.0/24

Development

To repeat the virtual machine provisioning, run:

vagrant up --provision

To reprovision just a single host, use:

vagrant up --provision tf-alice

The source code directory ./src will be mounted into each virtual machine at /opt/quickstart-dev for convenient live editing.

Project information

Acknowledgements

Tunfish would not have been possible without these awesome people:

• Jason Donenfeld for conceiving and building WireGuard. After reading the introduction [RFC] WireGuard: next generation secure network tunnel in late 2016 and quickly scanning his paper about WireGuard, nobody wondered that WireGuard rapidly gained attraction.
• M. Mahalingam, D. Dutt, K. Duda, P. Agarwal, L. Kreeger, T. Sridhar, M. Bursell and C. Wright for conceiving the [RFC 7348] Virtual eXtensible Local Area Network (VXLAN) standard, a framework for overlaying virtualized layer 2 networks over layer 3 networks.
• J. Gross, T. Sridhar, P. Garg, C. Wright, I. Ganga, P. Agarwal, K. Duda, D. Dutt and J. Hudson for their work on the VXLAN successor Geneve per [draft-ietf-nvo3-geneve-06] Geneve: GEneric NEtwork Virtualization Encapsulation.
• The many authors of Open vSwitch.
• Aaron Brady for his journal article Making your own private Internet, which strongly inspired the central idea behind this PoC. The tunfish-join.sh prototype is derived from his wg-config.bash gist.
• Scott S. Lowe for his collection of tools and files for learning new technologies. To be able to easily spin up development and testing environments, we used his Vagrant+Ansible recipe "Open Virtual Network (OVN)" setup. He writes about it at Learning Environments for OVN and you might also enjoy reading his many other articles about Open vSwitch.
• Martin Eskdale Moen for his Ansible role to deploy a wireguard server. We forked this Ansible role to tunfish.wireguard and added some slight improvements.
• Mitchell Hashimoto, Chris Roberts and the countless other contributors to Vagrant for conceiving and maintaining Vagrant.
• Michael DeHaan, James Cammarata, Toshio Kuratomi, Brian Coca, Matt Clay, Dag Wieers and the countless other contributors to Ansible for conceiving and maintaining Ansible.

Thank you so much for providing such great infrastructure components and resources to the community! You know who you are.

Troubleshooting

If you encounter any problems during setup, we may humbly refer you to the doc/troubleshooting.rst documentation.

Have fun!