Yggdrasil

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

RG="overlay-prod"; LOCATION="eastus"; VM_NAME="yggdrasil1" IMAGE_URN="sac1647283583153:yggdrasil-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION"
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:yggdrasil-ubuntu-24-04:default:latest
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$IMAGE_URN" \
  --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

On first boot, the image generates a unique node key for this VM and renders /etc/yggdrasil/yggdrasil.conf with a peering listener and the local admin socket. It derives this node's overlay IPv6 address, subnet and public key from the key, and resolves this VM's address for the peer endpoint. It then 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 that your other machines connect to. The public_key and ipv6_address are safe to share, because 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. In that case, substitute your VM's public IP when you peer to it from outside Azure.

Confirm that yggdrasil.service is active and that yggdrasil -version reports 0.5.14. Then check that yggdrasilctl getSelf shows this node's overlay IPv6 address (in the 0200::/7 range), its subnet and its public key. All three are 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

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. To inspect it, run:

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. This is normal for a point-to-point TUN device. Any other machine you peer into the overlay reaches this node on this same address.

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

To grow the overlay, install the free Yggdrasil client on another machine (or launch another of these images). 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, run ping6 202:2049:f8df:d093:85d7:be11:c005:fb3c from the second machine to reach this node.

Every link is authenticated and encrypted with the node keys, so 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.

This image ships with no known key. The node key is the only thing that determines this node's overlay identity. The image generates it uniquely per VM at first boot and stores it 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. 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.

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 not empty, only listed keys may peer in. This is a 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 setting governs peering only. It is not a firewall for services you run over the overlay.

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.

Other nodes can dial in and form an encrypted link only if the peering transport is reachable. If you only ever peer outbound from this node, you can leave 9001 closed inbound.

Connect over SSH. This image is Ubuntu 24.04, and the default login user is ubuntu:

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

On first boot, the image generates a unique node key for this instance and renders /etc/yggdrasil/yggdrasil.conf with a peering listener and the local admin socket. It derives this node's overlay IPv6 address, subnet and public key from the key, and resolves this instance's public address for the peer endpoint. It then 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 that your other machines connect to. The public_key and ipv6_address are safe to share, because they identify your node to peers. The node's private key stays in /etc/yggdrasil/yggdrasil.conf (root only) and is never shown.

Confirm that yggdrasil.service is active and that yggdrasil -version reports the shipped version. Then check that yggdrasilctl getSelf shows this node's overlay IPv6 address (in the 0200::/7 range), its subnet and its public key. All three are 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

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. To inspect both, run:

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. This is normal for a point-to-point TUN device. Any other machine you peer into the overlay reaches this node on this same address.

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

To grow the overlay, install the free Yggdrasil client on another machine (or launch another of these images). 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.

Every link is authenticated and encrypted with the node keys, so 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.

This image ships with no known key. The node key is the only thing that determines this node's overlay identity. The image generates it uniquely per instance at first boot and stores it 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. 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.

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 not empty, only listed keys may peer in. This is a 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 setting governs peering only. It is not a firewall for services you run over the overlay.

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 you edit the configuration. Use sudo systemctl stop yggdrasil to take the node off the overlay. Use sudo journalctl -u yggdrasil to read its logs.