znhdocker/chaoslayer repository overview

This joins the docker network chaoslayer to a defined layer 2 network with other peers. Effectively plugging an ethernet cable into a virtual network switch. Thanks to Yggdrasil used as underlay, the transport operates without inbound port forwarding. The layer 2 switch is created using Linux native bridge feature. Connections between peers is created with Linux native gretap feature. You can join a chaoslayer network without foreign software, what this docker provides is the automatic connecting and indexing peers.

Clients retrieve an list of peers from the CHAOS_MASTER and setup their connections. native spanning tree feature is enabled to avoid network loops

One can setup their own layer 2 switch or join an existing one. The CHAOS_MASTER collects IP addresses and serves a list. Which is a tcpdump listening for ping of 12+8 bytes and matches are written to a file and served with python3 -m http.server

Peers connect independently using the previously mentioned list with other peers. there is redundancy when multiple paths exists. Paths are however not speed measured so links have to be fast. This is a mixture of how the STP operates and how the Yggdrasil underlay is designed peer-wise.

Similar like a LAN network clients should use end-to-end encryption and firewall their services, there is no predefined NAT which acts as a firewall. The container does not expose services and the network should be isolated within.

A public chaoslayer is on the Yggdrasil address 200:3535:d12b:a2c:c877:3229:3a83:d2c3 - There are no security measurements in place, bad actors such as malicious DHCP servers or ARP poisoning may occur. You can however setup a VLAN or whatever you come up with.

⁠Setting up

Place the following files in a directory. The only required change is to modify YGG_PEERS in .env which you can obtain from https://github.com/yggdrasil-network/yggdrasil-go`⁠ or the remote address of another chaoslayer container on port 9123.

An example docker-compose.yml:

services:
  chaoslayer:
    build: chaoslayer
    image: znhdocker/chaoslayer
    ports:
      - "9123:9123"
    volumes:
      - source: storage
        target: /storage
        type: volume
        read_only: false
    environment:
      - YGG_PEERS=${YGG_PEERS}
      - YGG_LISTEN=${YGG_LISTEN}
      - IS_MASTER=${IS_MASTER}
      - CHAOS_MASTER=${CHAOS_MASTER}
    cap_add:
      - NET_ADMIN
    networks:
      chaoslayer:
      default:
        gw_priority: 10
volumes:
  storage:
  dnsmasqstorage:
networks:
  chaoslayer:
    driver: bridge
    ipam:
     config:
       - subnet: 10.10.0.0/16
         gateway: 10.10.0.1

And the .env:

YGG_PEERS=["tls://some-yggdrasil-peer:port"]
YGG_LISTEN=["tls://0.0.0.0:9123"]
CHAOS_MASTER="200:3535:d12b:a2c:c877:3229:3a83:d2c3"
IS_MASTER=0

Finally docker-compose up -d will startup the container and connect.

Inside the container with docker exec -it chaoslayer-chaoslayer-1 sh you will find a network bridge chaoslayer which is connected to other peers. One can optionally retrieve an IP with udhcpc -i chaoslayer and a DHCP server should reply.

The docker network chaoslayer is now running. containers such as dockerznh/webtop integrate this network.

⁠Notes

The network 10.10.0.0/16 in the docker-compose.yml is required as docker needs a pool and must set an IP as per their API. It is however unset after the container is up.