Yggdrasil on Ubuntu 24.04 on Azure User Guide

Overview

This guide covers the deployment and configuration of Yggdrasil on Ubuntu 24.04 on Azure using cloudimg Azure 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 0.5.14 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 VM a one shot service generates a unique node key for this VM 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 0.5.14 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

• Active Azure subscription, SSH public key, VNet + subnet in target region

• Subscription to the Yggdrasil listing on Azure Marketplace

• Network Security Group rules allowing TCP 22 (admin) and TCP 9001 (the peering transport) from the peers that will connect to this node

Recommended virtual machine size: Standard_B2s (2 vCPU, 4 GB RAM) is ample for an overlay node or a small to medium network. Yggdrasil is a lightweight Go daemon; larger sizes are only needed for very high throughput routing.

Step 1: Deploy from the Azure Portal

Search Yggdrasil in Marketplace, select the cloudimg publisher, and click Create. Configure the Network Security Group to allow TCP 9001 from the peers that will connect to this node, and TCP 22 for administration.

Step 2: Deploy from the Azure CLI

RG="overlay-prod"; LOCATION="eastus"; VM_NAME="yggdrasil1"
GALLERY_IMAGE_ID="/subscriptions/<sub-id>/resourceGroups/azure-cloudimg/providers/Microsoft.Compute/galleries/cloudimgGallery/images/yggdrasil-ubuntu-24-04/versions/<version>"
SSH_KEY="$(cat ~/.ssh/id_rsa.pub)"
az group create --name "$RG" --location "$LOCATION"
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$GALLERY_IMAGE_ID" \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values "$SSH_KEY" \
  --public-ip-sku Standard
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 9001 --priority 1001
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 22 --priority 1002

Step 3: First boot — retrieve your node identity

On first boot the image generates a unique node key for this VM, 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 VM's address for the peer endpoint, writes the root only credentials file, and starts yggdrasil. This completes within seconds. SSH in as azureuser 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. If your VM sits behind a Standard SKU public IP that the platform metadata does not expose, the recorded peer_endpoint may show the VM's private address — substitute your VM's public IP when peering to it from outside Azure.

Step 4: Confirm the node is running

yggdrasil.service is active, yggdrasil -version reports 0.5.14, 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:

yggdrasil.service: active
Build version: 0.5.14
IPv6 address:  202:2049:f8df:d093:85d7:be11:c005:fb3c
IPv6 subnet:   302:2049:f8df:d093::/64
Public key:    3bf6c0e405ed8f45083dc7ff4098749b48225a96c7986071ef93e3ecf993b0d2

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, and the node answers on its own overlay address.

ip -6 addr show tun0
ADDR=$(sudo yggdrasilctl -json getSelf | python3 -c 'import sys,json;print(json.load(sys.stdin)["address"])')
ping -6 -c 3 "$ADDR"

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: Confirm the network surface and the local admin socket

The only network facing surface besides SSH is the peering transport on :9001/tcp. The admin API that yggdrasilctl uses is a local Unix socket, never a TCP port, so it can never be reached from the network. The peer table is empty until you peer another machine in.

sudo ss -tlnH | grep 9001
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 here):

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 — for example ping6 202:2049:f8df:d093:85d7:be11:c005:fb3c from the second machine to this node. 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 VM 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.

ls -l /etc/yggdrasil/yggdrasil.conf
sudo cat /root/yggdrasil-credentials.txt

The config is -rw------- (root only) and AdminListen is a unix:// socket. The credentials file holds only your node's public identity (address, subnet, public key) — never the private key.

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.

Troubleshooting

• A peer will not connect. Confirm the NSG 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 and sudo journalctl -u yggdrasil show service logs.

• 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 NSG 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.