Explanation on EdgeVPN

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Introduction

EdgeVPN uses libp2p to establish a decentralized, asymmetrically encrypted gossip network which propagates a (symmetrically encrypted) ledger state between nodes.

The ledger is a hash-linked chain of blocks, and it is deliberately minimal:

There is no proof of work and no consensus protocol. A block is just Index, Timestamp, Storage, Hash and PrevHash, where Hash is a SHA256 over the other four — Index, Timestamp, Storage and PrevHash.
There is no DAG, CARv2 or GraphSync. The chain holds metadata only — service and file names, machine records, DNS entries, IP allocations, heartbeats — never addressable content.

Because there is no consensus round, “blockchain” here means hash-chained gossiped state, not a distributed ledger with agreement guarantees. Nodes converge because every node keeps re-announcing its own entries and merges what it receives; a node that has just joined, or one that has restarted with an empty chain, is refilled by those re-announcements.

The security model

Mon, 01 Jan 0001 00:00:00 +0000

EdgeVPN’s security model is perimeter-only. Anyone holding the network token is a fully trusted member of the network. There is no per-peer authorization on the data plane, and no audit trail of which peer did what. The token is the security boundary.

Everything else on this page — ledger ownership, trust zones, relay ACLs, socket permissions — narrows specific abuses by someone who is already inside, or protects the machine you are running on. None of it changes the sentence above. Read this before you decide who gets a copy of your token, because that decision is the security design.

The ledger

Mon, 01 Jan 0001 00:00:00 +0000

EdgeVPN have a simplified model of a blockchain embedded. The model is actually simplified on purpose as the blockchain is used to store merely network and services metadata and not transaction, or content addressable network.

The only data stored in the blockchain is:

Network Peer IDs, Service IDs, File IDs
Healthchecks, DNS records and IP allocation

However, the ledger is freely accessible via API, allowing for external coordination to use the blockchain mechanism as a shared memory access (which can be optionally persisted on disk).

The authenticated ledger

Mon, 01 Jan 0001 00:00:00 +0000

This is the design document

This is the design note for ledger ownership: why entries are signed, and how the merge, the policy registry and the reaper work. For the operator-facing side — which mode to run, and how to move a live network between modes without splitting it — see Ledger ownership.

Status: implemented. The edgevpn binary defaults to --ownership=enforce; operators opt out with --ownership=off (EDGEVPNOWNERSHIP). The library default (node.New without the option) stays off so embedders opt in deliberately.

Discovery and NAT traversal

Mon, 01 Jan 0001 00:00:00 +0000

This page has not been written. Architecture sketches the three bootstrap phases in a few paragraphs, and relays and hop nodes covers the relay case from the operator’s side. Nothing explains the mechanism as a whole, or what to expect when a given piece of it fails.

What is missing, and where the source is:

The OTP rendezvous. pkg/discovery/dht.go derives the DHT rendezvous string from a TOTP over the token’s OTP key (Rendezvous(): TOTP-SHA256, then MD5), so the point peers meet at rotates on the token’s otp.dht.interval (see network config). A two-entry ring (rendezvousHistory, pkg/discovery/ring.go) keeps the previous rendezvous announced across a rotation so nodes do not lose each other at the boundary. The consequences — clock skew between peers, and what a node sees when it drifts — are undocumented.
DHT versus mDNS. --dht and --mdns are both on by default (cmd/util.go), and they solve different problems: pkg/discovery/mdns.go finds peers on the same LAN and dials them directly, while the DHT (pkg/discovery/dht.go) is the internet-wide path and needs bootstrap peers. What happens with only one of them enabled is not written down.
Hole punching and reachability. --holepunch, --natservice and --natmap (all default on) map onto libp2p’s DCUtR, AutoNAT and UPnP respectively — see the wiring in pkg/config/config.go. Hole punching needs a third party both peers can already reach, which is why it interacts with the relay settings.
Relay fallback. --autorelay, --autorelay-static-peer, --autorelay-static-only, --autorelay-discovery-interval and --relay-service, and the order in which a node tries direct, hole-punched and relayed connections.
Diagnosing it. Which of the above a stuck “0 peers” state actually points at. See troubleshooting for what exists today.

Contributions welcome — see contributing.

When not to use EdgeVPN

Mon, 01 Jan 0001 00:00:00 +0000

Is it for me?

EdgeVPN makes VPN decentralization a first strong requirement.

Its main use is for edge and low-end devices and especially for development.

The decentralized approach has few cons:

The underlying network is chatty. It uses a Gossip protocol for synchronizing the routing table and p2p. Every blockchain message is broadcasted to all peers, while the traffic is to the host only.
Might be not suited for low latency workload.

Keep that in mind before using it for your prod networks!