Yggdrasil is an early-stage implementation of a fully end-to-end encrypted IPv6 network. It is lightweight, self-arranging, supported on multiple platforms and allows pretty much any IPv6-capable application to communicate securely with other Yggdrasil nodes. Yggdrasil does not require you to have IPv6 Internet connectivity - it also works over IPv4.
Mainline Yggdrasil implementation uses virtual network interface (TUN) to deliver traffic. While this setup is very powerful and flexible, several use cases are not covered:
- Systems without TUN adapter support
- System without root / administrator access
- Web browser access
Yggstack fills the gap by providing SOCKS5 proxy server and TCP port forwarder functionality similar to TOR router. It also can serve as a standalone network node to connect network segments.
Yggdrasil works on a number of platforms, including Linux, macOS, Ubiquiti EdgeRouter, VyOS, Windows, FreeBSD, OpenBSD and OpenWrt.
Please see our Installation
page for more information. You may also find other platform-specific wrappers, scripts
or tools in the contrib folder.
Bleeding-edge binaries can be downloaded via trunk release
Tagged releases provide packages similar to Yggdrasil.
If you want to build from source, as opposed to installing one of the pre-built packages:
- Install Go (requires Go 1.22 or later)
- Clone this repository
- Run
./build
Note that you can cross-compile for other platforms and architectures by
specifying the GOOS and GOARCH environment variables, e.g. GOOS=windows ./build or GOOS=linux GOARCH=mipsle ./build.
To generate static configuration, either generate a HJSON file (human-friendly, complete with comments):
./yggstack -genconf > /path/to/yggdrasil.conf
... or generate a plain JSON file (which is easy to manipulate programmatically):
./yggstack -genconf -json > /path/to/yggdrasil.conf
You will need to edit the yggdrasil.conf file to add or remove peers, modify
other configuration such as listen addresses or multicast addresses, etc.
To run SOCKS proxy server listening on local port 1080 using generated
configuration (like ssh -D):
./yggstack -useconffile /path/to/yggdrasil.conf -socks 127.0.0.1:1080
To run SOCKS proxy server listening on UNIX socket file /tmp/yggstack.sock:
./yggstack -useconffile /path/to/yggdrasil.conf -socks /tmp/yggstack.sock
To expose network services (like a Web server) listening on local port 8080
to Yggdrasil network address at port 80 (like ssh -R):
TCP:
./yggstack -useconffile /path/to/yggdrasil.conf -remote-tcp 80:127.0.0.1:8080
UDP:
./yggstack -useconffile /path/to/yggdrasil.conf -remote-udp 53:127.0.0.1:53
To forward remote port on some other Yggdrasil node to local machine (like ssh -L):
TCP:
./yggstack -useconffile /path/to/yggdrasil.conf -local-tcp 127.0.0.1:8080:<remote-yggdrasil-ipv6>:8080
./yggstack -useconffile /path/to/yggdrasil.conf -local-tcp [::1]:8080:<remote-yggdrasil-ipv6>:8080
UDP:
./yggstack -useconffile /path/to/yggdrasil.conf -local-udp 127.0.0.1:5353:<remote-yggdrasil-ipv6>:53
./yggstack -useconffile /path/to/yggdrasil.conf -local-udp [::1]:5353:<remote-yggdrasil-ipv6>:53
To run as a standalone node without SOCKS server or TCP port forwarding:
./yggstack -useconffile /path/to/yggdrasil.conf
To run in auto-configuration mode (which will use sane defaults and random keys at each startup, instead of using a static configuration file):
./yggstack -autoconf -socks 127.0.0.1:1080
Unlike mainline Yggdrasil, Yggstack does NOT require privileged access. You can even run several Yggstack instances with different configurations on the same OS and user!
If a client tool like curl fails to resolve .ygg domain, and yggstack prints
the following warning on start-up:
2024/08/06 03:27:20 DNS nameserver is not set!
2024/08/06 03:27:20 SOCKS server will not be able to resolve hostnames other than .pk.ygg !
start yggstack pointing to a DNS server, for example:
yggstack -useconffile /path/to/yggdrasil.conf -nameserver '[324:71e:281a:9ed3::53]:53' -socks 127.0.0.1:1080
and test if resolver works:
curl -x socks5h://127.0.0.1:1080 http://web.mc.ygg
One unique feature of Yggstack is built-in DNS resolver functionality using
<publickey>.pk.ygg format without the need for external DNS nameservers.
For example, HowToYgg website (whose public key is d40d4a7153cf288ea28f1865f6cfe95143a478b5c8c9e7cb002a0633d10a53eb)
can be accessed by any Web browser supporting SOCKS servers
via http://d40d4a7153cf288ea28f1865f6cfe95143a478b5c8c9e7cb002a0633d10a53eb.pk.ygg
You can even use cURL with Yggstack:
curl -x socks5h://127.0.0.1:1080 http://d40d4a7153cf288ea28f1865f6cfe95143a478b5c8c9e7cb002a0633d10a53eb.pk.ygg
Documentation is available on our website.
Feel free to join us on our Matrix
channel at #yggdrasil:matrix.org
or in the #yggdrasil IRC channel on libera.chat.
This code is released under the terms of the LGPLv3, but with an added exception that was shamelessly taken from godeb. Under certain circumstances, this exception permits distribution of binaries that are (statically or dynamically) linked with this code, without requiring the distribution of Minimal Corresponding Source or Minimal Application Code. For more details, see: LICENSE.