Yggdrasil Mesh Network — Complete Setup Guide (TTY / Linux / Arch Friendly)

This guide explains how to install, configure, debug, and verify a working Yggdrasil node from scratch.

Goal: join the IPv6 mesh network reliably using outbound peers + listeners.

What Yggdrasil is

Yggdrasil is a decentralized encrypted IPv6 mesh overlay network.

Features:

• automatic routing
• no central servers
• end-to-end encryption
• stable node identity via keypair
• works over TCP / TLS / QUIC
• multicast discovery on LAN

Install Yggdrasil

Arch Linux

sudo pacman -S yggdrasil

Enable service:

sudo systemctl enable yggdrasil

Generate configuration

Create default config:

sudo yggdrasil -genconf > ~/yggdrasil.conf

Move into place:

sudo mv ~/yggdrasil.conf /etc/yggdrasil.conf

Important: PrivateKey

Example:

PrivateKey: YOUR_PRIVATE_KEY

Never regenerate unless you want a new node identity.

Add peers (recommended inline format)

Find:

Peers: []

Replace with:

Peers: [
  "tcp://ygg-1.okade.pro:20000",
  "tcp://ygg.nadeko.net:44441",
  "tls://ygg.nadeko.net:44442",
  "quic://ip6.casa2.mywire.org:44443?key=000000003cb1cc50e05147fc548f6d1f78e7ffcdc67b456f9bb0db6f0a5e4723",
  "tcp://Yggdrasil.UnderEu.Net:37001",
  "quic://Yggdrasil.UnderEu.Net:37003",
  "tls://ygg.jjolly.dev:3443",
  "tcp://mo.us.ygg.triplebit.org:9000",
  "tls://mo.us.ygg.triplebit.org:993"
]

Why inline format?

Because YAML indentation errors break configs easily.

This avoids them.

Enable incoming connections (important)

Find:

Listen: []

Replace with:

Listen: ["tls://0.0.0.0:0","tls://[::]:0"]

This allows:

• better mesh participation
• faster routing convergence
• more peers connecting to you

Multicast discovery (LAN auto-peering)

Keep enabled:

MulticastInterfaces:
  - Regex: .*
    Beacon: true
    Listen: true

This lets nearby nodes auto-connect.

Restart service

sudo systemctl restart yggdrasil

Verify connection

Check peers:

yggdrasilctl getpeers

Working example output:

URI                State
tcp://peer...      Established
tls://peer...      Established

Empty table means:

node is not connected yet.

Confirm interface exists

Run:

ip addr | grep ygg

Expected:

ygg0

Test connectivity

Ping internal mesh DNS node:

ping6 inv.nadeko.ygg

Success = working mesh connection

Validate configuration syntax

Before restarting service:

sudo yggdrasil -useconffile /etc/yggdrasil.conf -normaliseconf

If config is broken:

command prints exact error line.

Debug connection failures

Check service logs

journalctl -u yggdrasil -n 50

Check active peers

yggdrasilctl getpeers

Columns:

Most common config errors

1 — YAML indentation

Wrong:

  Peers:

Correct:

Peers:

2 — Tabs instead of spaces

Fix inside vim:

:set expandtab
:retab

3 — Missing commas in inline format

Wrong:

Peers: ["tcp://peer1" "tcp://peer2"]

Correct:

Peers: ["tcp://peer1","tcp://peer2"]

4 — trailing comma

Wrong:

Peers: ["tcp://peer1",]

Confirm node identity

Check IPv6 address:

yggdrasilctl getself

Example:

Address: 200:xxxx:xxxx:xxxx::xxxx

This is your mesh address.

Permanent until PrivateKey changes.

Optional: allow firewall traffic

If using firewall:

sudo ufw allow 0:65535/tcp
sudo ufw allow 0:65535/udp

Verify routing table

yggdrasilctl getroutes

Shows mesh topology paths.

Quick health checklist

Working node checklist:

✔ service running ✔ ygg0 exists ✔ peers connected ✔ IPv6 assigned ✔ ping works ✔ routes visible

Next steps after connection

Once connected you can run:

• yggdrasil SSH tunnels
• mesh HTTP services
• distributed DNS
• IPFS over Yggdrasil
• Gemini capsules
• TTY-native mesh tools
• offline-first knowledge systems

DNS for .ygg domains

Yggdrasil no tiene DNS oficial. Usá un servidor DNS público de la comunidad.

Why you need DNS

Without DNS, you can’t resolve .ygg domains like inv.nadeko.ygg.

Finding a working DNS server

Search online:

yggdrasil DNS server public list

Official list: https://yggdrasil-network.github.io/services.md

Common public DNS servers

Testing which DNS is reachable

Not all DNS servers are accessible from every node. It depends on your mesh topology (who you’re peered with).

Test each one:

ping -c 2 324:71e:281a:9ed3::53
ping -c 2 302:db60::53
ping -c 2 300:6223::53
ping -c 2 302:7991::53

The one that responds = your DNS server.

Why this specific DNS?

In my case:

• My routing table was small (only 13 nodes)
• Most DNS servers were unreachable
• Only 324:71e:281a:9ed3::53 responded to ping
• That’s why I used this one

Your reachable DNS may be different. Test all of them.

Configure systemd-resolved

sudo mkdir -p /etc/systemd/resolved.conf.d

Create config:

echo '[Resolve]
DNS=324:71e:281a:9ed3::53
Domains=~ygg' | sudo tee /etc/systemd/resolved.conf.d/yggdrasil.conf

What this does:

• DNS= → Your Yggdrasil DNS server IP
• Domains=~ygg → Route all .ygg domains to this DNS

Restart:

sudo systemctl restart systemd-resolved

Verify DNS works

resolvectl query inv.nadeko.ygg

Should return an IPv6 address like:

inv.nadeko.ygg: 200:28fa:d807:e104:5a13:e2c4:eaf:445f

Accessing .ygg websites

From nadeko.net

Other Yggdrasil services

Full directory

There’s a full directory with 157+ sites at:

http://[21e:a51c:885b:7db0:166e:927:98cd:d186]/

Check there for more services!

HTTP vs HTTPS

• HTTP → works perfectly
• HTTPS → may have certificate errors (cert is for clearnet domain, not .ygg)

For HTTPS services on .ygg, you may need to:

• Use https://inv-ygg.nadeko.net (clearnet alternative)
• Or ignore certificate errors in curl:

  curl -kL https://inv.nadeko.ygg
  

Useful commands

# Check peers
sudo yggdrasilctl getpeers

# Check routing table
sudo yggdrasilctl gettree

# See your address
sudo yggdrasilctl getself

# See sessions
sudo yggdrasilctl getsessions

# Restart Yggdrasil
sudo systemctl restart yggdrasil

# View logs
sudo journalctl -u yggdrasil -f

# Test DNS resolution
resolvectl query inv.nadeko.ygg

# Test connectivity
curl -sL http://inv.nadeko.ygg/

Complete Setup — New PC from Scratch

This section has everything you need to set up Yggdrasil on a fresh system.

Step 1: Install Yggdrasil

Arch Linux

sudo pacman -S yggdrasil

Debian/Ubuntu

# Download from GitHub
wget https://github.com/yggdrasil-network/yggdrasil/releases/latest/download/yggdrasil-linux-amd64
mv yggdrasil-linux-amd64 /usr/local/bin/yggdrasil
chmod +x /usr/local/bin/yggdrasil

# Or build from source (requires Go)
git clone https://github.com/yggdrasil-network/yggdrasil
cd yggdrasil
go build -o yggdrasil .
sudo mv yggdrasil /usr/local/bin/

Fedora/RHEL

sudo dnf install yggdrasil
# Or use COPR
sudo dnf copr enable @yggdrasil/yggdrasil
sudo dnf install yggdrasil

Void Linux

sudo xbps-install yggdrasil

Gentoo

# Add to /etc/portage/package.accept_keywords
echo "=net-p2p/yggdrasil-9999 **" | sudo tee /etc/portage/package.accept_keywords/yggdrasil
sudo emerge --ask net-p2p/yggdrasil

macOS

brew install yggdrasil
# Or
sudo brew install --cask yggdrasil

Step 2: Enable and start service

systemd (Linux)

sudo systemctl enable yggdrasil
sudo systemctl start yggdrasil

OpenRC (Void, Gentoo)

sudo rc-update add yggdrasil default
sudo service yggdrasil start

macOS (launchd)

sudo launchctl load /Library/LaunchDaemons/com.yggdrasil.plist

Manual run (no service)

sudo yggdrasil -useconffile /etc/yggdrasil.conf

Step 3: Generate configuration

sudo yggdrasil -genconf | sudo tee /etc/yggdrasil.conf

This creates a fresh config with:

• New random PrivateKey (new node identity)
• Empty peers list
• Default settings

Step 4: Add public peers

Peers are required to join the network. Without peers, you can’t connect.

Option A: Use recommended peers from this guide

sudo yggdrasil -genconf > /tmp/yggdrasil-new.conf

# Edit the file and add peers to the Peers: [] section
nano /tmp/yggdrasil-new.conf

Recommended peers:

Peers: [
  "tcp://ygg-1.okade.pro:20000",
  "tcp://ygg.nadeko.net:44441",
  "tls://ygg.nadeko.net:44442",
  "tls://ygg.jjolly.dev:3443",
  "tcp://mo.us.ygg.triplebit.org:9000",
  "tls://mo.us.ygg.triplebit.org:993"
]

Option B: Find public peers online

Official public peers list:

• https://github.com/yggdrasil-network/public-peers
• https://yggdrasil-network.github.io/services.html

Look for peers close to your geographic location for best latency.

Option C: Use peer discovery on LAN

If other Yggdrasil nodes are on your LAN, multicast discovery will find them automatically:

MulticastInterfaces:
  - Regex: .*
    Beacon: true
    Listen: true

Step 5: Configure listeners (recommended)

Allow incoming connections for better connectivity:

Listen: ["tls://0.0.0.0:0","tls://[::]:0"]

This lets other nodes connect to you and improves network participation.

Step 6: Apply configuration

sudo cp /tmp/yggdrasil-new.conf /etc/yggdrasil.conf
sudo systemctl restart yggdrasil

Wait 10-30 seconds for connections to establish.

Step 7: Verify connection

Check if service is running

sudo systemctl status yggdrasil
# Or
ps aux | grep yggdrasil

Check your address

sudo yggdrasilctl getself

Should show an address like 202:xxxx:xxxx:xxxx::xxxx

Check peers

sudo yggdrasilctl getpeers

You should see peers with State: Established

Check routing table

sudo yggdrasilctl gettree

Shows known nodes (should grow over time)

Test connectivity

ping -c 3 200:415c:2061:a9c0:9dbc:b95d:66ec:1347

This is nadeko’s Yggdrasil address.

Step 8: Set up DNS (for .ygg domains)

This lets you resolve domains like inv.nadeko.ygg

Configure systemd-resolved

sudo mkdir -p /etc/systemd/resolved.conf.d

echo '[Resolve]
DNS=324:71e:281a:9ed3::53
Domains=~ygg' | sudo tee /etc/systemd/resolved.conf.d/yggdrasil.conf

sudo systemctl restart systemd-resolved

Test DNS resolution

resolvectl query inv.nadeko.ygg

Should return an IPv6 address.

Alternative: Use /etc/hosts

# Find the IP first
resolvectl query inv.nadeko.ygg

# Add to /etc/hosts
echo "200:28fa:d807:e104:5a13:e2c4:eaf:445f inv.nadeko.ygg" | sudo tee -a /etc/hosts

Step 9: Configure firewall (if needed)

ufw

sudo ufw allow 0:65535/tcp
sudo ufw allow 0:65535/udp
# Or more specific
sudo ufw allow 9001/tcp
sudo ufw allow 9001/udp

iptables

sudo iptables -A INPUT -p tcp --dport 9001 -j ACCEPT
sudo iptables -A OUTPUT -p tcp --sport 9001 -j ACCEPT
sudo ip6tables -A INPUT -p tcp --dport 9001 -j ACCEPT
sudo ip6tables -A OUTPUT -p tcp --sport 9001 -j ACCEPT

firewalld

sudo firewall-cmd --permanent --add-port=9001/tcp
sudo firewall-cmd --reload

Step 10: Troubleshooting

No peers connected

1. Check service status:

   sudo systemctl status yggdrasil
   

2. Check logs:

   sudo journalctl -u yggdrasil -n 50
   

3. Check firewall:

   sudo ufw status
   sudo iptables -L -n
   

4. Try different peers (some may be down)

5. Check your internet connection

Service won’t start

1. Check configuration syntax:

   sudo yggdrasil -useconffile /etc/yggdrasil.conf -normaliseconf
   

2. Check logs:

   sudo journalctl -u yggdrasil -xe
   

3. Check port availability:

   sudo netstat -tlnp | grep yggdrasil
   

DNS not working

1. Check systemd-resolved:

   sudo systemd-resolve --status
   # Or
   resolvectl status
   

2. Test DNS server directly:

   dig @324:71e:281a:9ed3::53 inv.nadeko.ygg
   

3. Check /etc/resolv.conf:

   cat /etc/resolv.conf
   

4. Try different DNS server

Can’t reach .ygg websites

1. Verify your Yggdrasil address:

   sudo yggdrasilctl getself
   

2. Test connectivity to a known node:

   ping -c 3 200:415c:2061:a9c0:9dbc:b95d:66ec:1347
   

3. Check your routing table:

   sudo yggdrasilctl gettree
   

4. Check peer connections:

   sudo yggdrasilctl getpeers
   

Quick verification checklist

• Service running: sudo systemctl status yggdrasil
• Have address: sudo yggdrasilctl getself
• Peers connected: sudo yggdrasilctl getpeers
• Can ping another node: ping -c 3 200:415c:2061:a9c0:9dbc:b95d:66ec:1347
• DNS resolves: resolvectl query inv.nadeko.ygg
• Can load website: curl -sL http://inv.nadeko.ygg/

Keeping your identity

Your Yggdrasil address is tied to your PrivateKey.

Backup your key:

sudo yggdrasilctl getself | grep "Private key"
# Or extract from config
grep PrivateKey /etc/yggdrasil.conf

Store this key securely. If you lose it, you get a new address.

Restoring on a new PC:

# Copy the PrivateKey to the new config
nano /etc/yggdrasil.conf
# Edit the PrivateKey line with your backed-up key
sudo systemctl restart yggdrasil

Quick reference commands

# Service management
sudo systemctl start yggdrasil
sudo systemctl stop yggdrasil
sudo systemctl restart yggdrasil
sudo systemctl status yggdrasil

# Get info
sudo yggdrasilctl getself      # Your address and keys
sudo yggdrasilctl getpeers     # Connected peers
sudo yggdrasilctl gettree    # Routing table
sudo yggdrasilctl getsessions  # Active sessions

# Debug
sudo journalctl -u yggdrasil -f    # Follow logs
sudo yggdrasilctl list           # All available commands

# Network
ip addr show tun0               # Check interface
ping -c 3 200:415c:2061:a9c0:9dbc:b95d:66ec:1347

# DNS
resolvectl query inv.nadeko.ygg
resolvectl query nadeko.net

Sources

• https://yggdrasil-network.github.io/
• https://yggdrasil-network.github.io/services.html
• https://github.com/yggdrasil-network/public-peers
• https://nadeko.net/announcements/invidious-yggdrasil/
• https://github.com/Revertron/wyrd