Yggdrasil Encrypted IPv6 Mesh Network on AWS User Guide

Overview

This guide covers the deployment and configuration of Yggdrasil on AWS using cloudimg AWS Marketplace images. Yggdrasil is an early stage implementation of a fully end to end encrypted IPv6 mesh network. It is decentralised and self arranging: every node derives a permanent, cryptographic IPv6 address in the 0200::/7 range from its own key, and nodes automatically build a spanning tree between their peers so that any node can reach any other over the encrypted overlay, without a central server and without you having to plan an address scheme. The result is a flat private IPv6 network that follows your machines across NAT, changing IP addresses and different clouds, so services keep the same address wherever they run.

The image installs Yggdrasil as a single static Go binary (yggdrasil plus the yggdrasilctl admin CLI), run under systemd as the yggdrasil.service overlay node. The node is administered with yggdrasilctl over a local Unix domain socket, so the management interface is never exposed to the network. The peering transport listens on port 9001 over TCP with TLS, which is the only network facing surface the image opens besides SSH. There is no web interface and no database: the flat /etc/yggdrasil/yggdrasil.conf is the whole node state.

Secure by default - no known key. A node's key is its identity on the network, so a shared or baked in key would let anyone impersonate your node and would give every instance the same address. This image avoids that: on the first boot of every instance a one shot service generates a unique node key for this instance alone, writes the configuration with strict permissions, derives this node's overlay IPv6 address, subnet and public key, records them in a root only file, and only then starts the node. The admin socket is a local Unix socket so it can never be reached from the network.

What is included:

• Yggdrasil installed from the official pinned, checksum verified release, run under systemd as yggdrasil.service

• A self arranging, end to end encrypted IPv6 overlay with a stable cryptographic address per node in the 0200::/7 range

• The peering transport on 0.0.0.0:9001 (TCP, TLS) - the only network facing port besides SSH

• A local Unix admin socket (/var/run/yggdrasil/yggdrasil.sock) that yggdrasilctl uses, never reachable from the network

• A unique per instance node key generated on first boot, with this node's overlay address, subnet and public key written to /root/yggdrasil-credentials.txt (root only)

Prerequisites

• An AWS account subscribed to the Yggdrasil listing on AWS Marketplace

• An EC2 key pair for SSH access, and a VPC + subnet in your target region

• A security group allowing TCP 22 (administration) and TCP 9001 (the peering transport) from the peers that will connect to this node

Recommended instance type: m5.large (2 vCPU, 8 GB RAM) is ample for an overlay node or a small to medium network. Yggdrasil is a lightweight Go daemon; larger types are only needed for very high throughput routing.

Step 1: Launch from AWS Marketplace

Subscribe to the Yggdrasil listing, then launch an instance from the AMI. In the launch wizard select your key pair and a security group that opens TCP 22 for administration and TCP 9001 from the peers that will connect to this node. The peering transport must be reachable for other nodes to dial in and form an encrypted link; if you only ever peer outbound from this node you can leave 9001 closed inbound.

Step 2: Connecting to your instance

Connect over SSH as the default login user for your operating system variant.

ssh -i your-key.pem ubuntu@<public-ip>

Step 3: First boot - retrieve your node identity

On first boot the image generates a unique node key for this instance, renders /etc/yggdrasil/yggdrasil.conf with a peering listener and the local admin socket, derives this node's overlay IPv6 address, subnet and public key from the key, resolves this instance's public address for the peer endpoint, writes the root only credentials file, and starts yggdrasil. This completes within seconds. SSH in as ubuntu and read your node identity:

sudo cat /root/yggdrasil-credentials.txt

The file records this node's ipv6_address (its address inside the overlay), its ipv6_subnet (a /64 you can route to other machines), its public_key, and a peer_endpoint your other machines connect to. The public_key and ipv6_address are safe to share - they identify your node to peers. The node's private key stays in /etc/yggdrasil/yggdrasil.conf (root only) and is never shown.

Step 4: Confirm the node is running

yggdrasil.service is active, yggdrasil -version reports the shipped version, and yggdrasilctl getSelf shows this node's overlay IPv6 address (in the 0200::/7 range), its subnet and its public key - all derived from the node's own key.

systemctl is-active yggdrasil.service
yggdrasil -version
sudo yggdrasilctl getSelf

Expected output resembles:

active
Build version: 0.5.14
IPv6 address:  201:eb1a:2e29:53c:3172:1184:2463:ef74
IPv6 subnet:   301:eb1a:2e29:53c::/64
Public key:    45397475beb0f3a37b9ef6e70422df85992bca0969311fe12dcc844ce5bbc5e8

Step 5: Inspect the overlay interface

Yggdrasil brings up a TUN interface (tun0) and assigns this node's overlay IPv6 address to it. The interface is up the moment the service starts. The only network facing surface besides SSH is the peering transport listening on :9001/tcp.

ip -6 addr show tun0
sudo ss -tlnp | grep 9001

tun0 shows the node's 0200::/7 address with a state UNKNOWN line and the UP flag - that is normal for a point to point TUN device. Any other machine you peer into the overlay reaches this node on this same address.

Step 6: The admin API is local only

The admin API that yggdrasilctl uses is a local Unix socket, never a TCP port, so it can never be reached from the network. Use it to read this node's own identity and its peer table. The peer table is empty until you peer another machine in.

ls -l /var/run/yggdrasil/yggdrasil.sock
sudo yggdrasilctl getPeers

Step 7: Peer another machine into the overlay

To grow the overlay, install the free Yggdrasil client on another machine (or launch another of these images) and add this node's peer endpoint to that machine's Peers list. Read this node's peer_endpoint from /root/yggdrasil-credentials.txt (Step 3) - it looks like tls://<public-ip>:9001. On the other machine, edit its /etc/yggdrasil/yggdrasil.conf and add the endpoint to Peers (this is a configuration snippet for the other machine, not a command to run on this node):

Peers: [
  tls://<peer-public-ip>:9001
]

Then restart Yggdrasil on that machine. Once the link forms, each node can reach the other over its overlay IPv6 address. Because every link is authenticated and encrypted with the node keys, all traffic between the machines is end to end encrypted. You can add peers in either direction: point this node at a remote endpoint, or point remote nodes at this one. Yggdrasil has no bootstrap nodes - traffic transits your peer links, so peer with nearby, well connected nodes.

Step 8: Secure by default

This image ships with no known key. The node key - the sole thing that determines this node's overlay identity - is generated uniquely per instance at first boot and stored in a root only 0600 config file. The admin API is bound to a local Unix socket, so it can never be reached from the network, and every overlay link is encrypted with the node keys. The only network facing surface besides SSH is the peering transport on port 9001.

sudo ls -l /root/yggdrasil-credentials.txt /etc/yggdrasil/yggdrasil.conf
sudo ss -tlnH | grep 9001

The config and credentials files are -rw------- (root only), and there is no admin TCP port - AdminListen is a unix:// socket. Two instances launched from this image get different node keys and therefore different overlay addresses, so no two instances ever share an identity.

Step 9: Restrict who may peer

By default a Yggdrasil node accepts incoming peerings from any node (all overlay traffic is still encrypted by node keys). To restrict who may form an inbound peering with this node, add the allowed peers' public keys to AllowedPublicKeys in /etc/yggdrasil/yggdrasil.conf and restart the service. When the list is non empty, only listed keys may peer in (configuration snippet, not a command to run here):

AllowedPublicKeys: [
  <peer-public-key>
]

Collect each peer's public key from its own yggdrasilctl getSelf output. This governs peering only; it is not a firewall for services you run over the overlay.

Step 10: Managing the service

systemctl is-active yggdrasil.service

Yggdrasil runs under systemd, so it restarts automatically on failure and starts on boot. Use sudo systemctl restart yggdrasil after editing the configuration, sudo systemctl stop yggdrasil to take the node off the overlay, and sudo journalctl -u yggdrasil to read its logs.

Troubleshooting

• A peer will not connect. Confirm the security group allows TCP 9001 from the peer, and that the peer's Peers list uses this node's reachable endpoint (tls://<public-ip>:9001). Check sudo yggdrasilctl getPeers on both sides.

• Check node health. sudo yggdrasilctl getSelf dumps this node's own overlay identity; sudo yggdrasilctl getPeers lists connected peers with latency; sudo systemctl status yggdrasil shows service state.

• The overlay address is stable. A node's address is derived from its key, so it never changes for the life of the key - that is the point. To change a node's address, generate a new key.

Support

cloudimg provides 24/7 technical support for this Yggdrasil image. Our engineers help with peering design, restricting who may connect with allowed public keys, exposing and reaching services over the encrypted overlay, firewall and security group rules, monitoring node and peer health with yggdrasilctl, and Yggdrasil version upgrades. Critical issues receive a one hour average response time. Contact support@cloudimg.co.uk.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.