Yggdrasil over WiFi Mesh
Warning
This project is on extremely early stage. Something may break even if it's supposed to work. Do it on your own risk.
This project builds a mesh network for cases where normal network infrastructure is unavailable or unreliable.
- Routers connect to each other over 802.11s WiFi mesh.
- Yggdrasil (Yggdrasil-ng, its Rust implementation) runs directly on top of those 802.11s interfaces and provides end-to-end encrypted IPv6 mesh routing.
- All WiFi clients can resolve and access Alfis domains (such as
.yggand other Yggdrasil services) out of the box, thanks to integrated Alfis DNS forwarding. - Every node runs a WiFi hotspot (open by default). Phones and laptops that connect to it get access to Yggdrasil IPv6.
- Access to clearnet (the Internet) websites through the mesh, via YggMesh exit nodes.
You need one of the supported routers below. If your router is not in the list, write me (pick any convenient way to contact me on my website) or open a pull request.
| Device | device_keyname |
Links |
|---|---|---|
| GL.iNet GL-AXT1800 (Slate AX) | axt1800 |
GL.iNet, Amazon |
| GL.iNet GL-MT3000 (Beryl AX) | mt3000 |
GL.iNet, Amazon |
| GL.iNet GL-MT6000 (Flint 2) | mt6000 |
GL.iNet, Amazon |
| Asus RT-AX53U | ax53u |
Amazon, Asus |
| GL.iNet GL-AR300M16 (16 MB) | ar300m16 |
Amazon, GL.iNet |
| TP-Link CPE710 v1 | cpe710 |
Amazon, TP-Link |
| Cudy AP3000 Outdoor V1 | ap3000outdoor |
Cudy |
| Cudy WR3000 V1 | wr3000 |
Cudy |
- Download the firmware for your device from the Releases page, or build it yourself.
- Flash it to your router over stock OpenWrt (or the vendor firmware) without keeping settings: the old settings would conflict with YggMesh.
- Option A: via the bootloader. The exact actions depend on your device, google the instructions for it. Usually it requires a TFTP server or holding the reset button.
- Option B: if OpenWrt and LuCI are installed, go to System β Backup / Flash Firmware β Flash new firmware image and uncheck "Keep settings", or run
sysupgrade -n -v /tmp/openwrt-*-sysupgrade.bin.
- Wait for the router to reboot. The first boot takes 30-60 seconds longer than usual while the node configures itself.
- Repeat for every router you want in the mesh. All nodes are identical, no node-specific configuration is needed.
- Power on your YggMesh node and connect to its WiFi (it is called
YggMesh). - Open http://10.0.0.1 in a browser and log in (default login
root, passwordyggmesh). - First, change the admin password: open System β Administration and set a new one. All nodes ship with the same default password, so do this before anything else.
- Then open the YggMesh page (the first item of the menu). It has every setting of the node and shows its Yggdrasil address, peers and clearnet state. Configure the node as you see fit:
The access point for phones and laptops, on every node.
| Field | Meaning |
|---|---|
| Network name (SSID) | Name of the WiFi network clients see. Up to 32 characters. |
| Encryption | None (open network, default), WPA2/WPA3 (recommended), WPA3 only or WPA2 only. |
| Password | WiFi password, 8-63 characters. Shown for any encryption except None. |
| Field | Meaning |
|---|---|
| Private key | Defines the node's Yggdrasil address. Keep it secret: never share it with anyone, whoever has it can act as your node. Never use the same key on two nodes. Exits know your node by its public key (shown below the private key): give that one to the owners of the exits you use, never the private key. Changing the private key changes the public key too. Use "Generate a new key" to make one. |
| DNS resolvers | IPv6 addresses of DNS resolvers reachable over Yggdrasil. They resolve .ygg and the other Yggdrasil domains. |
A node with internet on WAN connects to the global Yggdrasil network through public peers it picks by itself. A node without WAN gets there through a neighbour that has a path (any number of hops).
| Field | Meaning |
|---|---|
| yggpeers instances | Base URLs of yggpeers instances. A peer is used only if a majority of them report it up; the reported peers are ranked by ping and the fastest are used. Empty: no public peers. |
| Number of peers | How many public peers the node should be connected to in total. Recommended: 2-3. |
| Check interval (minutes) | How often to check that the current peers are alive. If fewer peers are alive than "Number of peers", a new list is requested from yggpeers and the dead ones are replaced. |
| Forced refresh interval (days) | How often to request a new peers list from yggpeers, even if all current peers are alive and working well. |
What the IPv4 traffic of the clients uses. Their IPv6 traffic reaches Yggdrasil only.
| Field | Meaning |
|---|---|
| Mode | WAN: directly through the WAN port of this node (nodes without WAN give no clearnet).Exits: only through the exits, never through WAN, so your IP is never used; if no exit works, clients have no clearnet.WAN, then exits: through WAN while it works, through the exits otherwise (sites see your IP while WAN works).Off: no clearnet, Yggdrasil only. |
| Exits | Public keys (64 hex digits) of YggMesh exit nodes. The fastest working one is used. Switching to another exit restarts Yggdrasil: the mesh links of the node drop for a few seconds, so the node switches only when the active exit stops working or another one is much faster. |
An exit node is a server that is in Yggdrasil and on the Internet at the same time. Deploy YggMesh-exit-node on a VPS, or even at home on your own laptop: that works too. Then put its public key here. Wi-Fi clients (laptops and smartphones connected to the WiFi of your YggMesh node) need nothing: no apps and no settings, they just get the Internet over IPv4. An exit serves only the nodes it knows: give its owner the public key of your node, shown on the YggMesh page.
How it works: Yggdrasil-ng's Crypto-Key Routing carries the clients' IPv4 to the public key of the exit. The node masquerades it to its own address, 100.64.0.0/10 plus the last 22 bits of its public key; the exit derives the same address from the key and accepts the node's traffic from it only.
This project develops quickly and new releases come out often. There is no auto-update yet: when a new release is out, download the firmware for your device from the Releases page and upgrade, keeping the settings. Your node then keeps its settings, including its Yggdrasil key, so its address stays the same. There are two ways:
Via LuCI
- Open System β Backup / Flash Firmware.
- Click "Flash image...", choose the downloaded
sysupgradefile. - Make sure "Keep settings and retain the current configuration" is checked, then continue and confirm.
Via SSH
scp -O openwrt-*-sysupgrade.bin root@10.0.0.1:/tmp/
ssh root@10.0.0.1 'sysupgrade -v /tmp/openwrt-*-sysupgrade.bin'Fork this repository, then go to Actions β Build Firmware β Run workflow. Fill in the inputs and run. The firmware artifact will be available for download when the job completes.
| Input | Description |
|---|---|
device |
Device keyname to build (see supported devices). |
default_root_password |
Initial root password set on first boot. Always change from the default and on the first boot. |
private_ssid |
Client AP SSID shown to end-user devices. |
yggdrasil_dns |
Space-separated DNS resolver IPv6 addresses reachable over Yggdrasil. Leave empty to skip overlay DNS. |
yggpeers_instances |
Space-separated base URLs of yggpeers instances used to auto-discover public Yggdrasil peers. A peer is used only if a majority of the reachable instances report it as up. Leave empty to disable public peers discovery and rely only on multicast discovery. |
yggpeers_count |
Target number (1-10, default 3) of global Yggdrasil peers per node with internet on WAN. |
yggpeers_check_interval |
Minutes between checks of the global peers (1-59 or a multiple of 60 up to 1380, default 30). Peers that are down are replaced at the next check. |
yggpeers_rerank_interval |
Days between forced refreshes of the global peers list (1-90, default 7), even if all current peers are alive. |
clearnet_exits |
Space-separated public keys of clearnet exits; the fastest working one is used. |
clearnet_mode |
What clients' IPv4 traffic uses: wan (directly), exit (only the exits, never WAN), wan_exit (WAN while it works, the exits otherwise) or off. Default wan_exit. |
The inputs are only the default settings of a freshly installed node; every node can change them later on its YggMesh page in LuCI.
To trigger a release build for all devices at once, push a git tag (e.g. v1.0.0). Firmware for all supported devices will be built and attached to a GitHub Release automatically.
If you edit the code: the 802.11s mesh ID (MESH_ID) and the Yggdrasil peering port (YGG_PORT, 17000) are constants in yggmesh-apply, not settings β all YggMesh nodes share the same mesh network and can peer with each other. Keep them at their default values so all forks can peer with one another.
Requires either:
- Linux with
wget,zstd,make, andpython3 - This repository opened in the devcontainer (works on ARM Macs)
All variables below are required. The script will fail immediately if any are missing.
PRIVATE_SSID="YggMesh" \
DEFAULT_ROOT_PASSWORD="yggmesh" \
YGGDRASIL_DNS="308:c8:48:45:: 300:7c75:d590:c5d8::100" \
YGGPEERS_INSTANCES="https://yggpeers.fsky.io" \
YGGPEERS_COUNT="3" \
YGGPEERS_CHECK_INTERVAL="30" \
YGGPEERS_RERANK_INTERVAL="7" \
CLEARNET_EXITS="" \
CLEARNET_MODE="wan_exit" \
./scripts/build_router.sh axt1800The script downloads the OpenWrt Image Builder on first run (~1.5 GB per target). Output lands in output/.
| Variable | Description |
|---|---|
PRIVATE_SSID |
Client AP SSID shown to end-user devices. |
DEFAULT_ROOT_PASSWORD |
Initial root password set on first boot. Always change on first boot. |
YGGDRASIL_DNS |
Space-separated DNS resolver IPv6 addresses reachable over Yggdrasil. Can be empty to skip overlay DNS. |
YGGPEERS_INSTANCES |
Space-separated base URLs of yggpeers instances used to auto-discover public peers. Can be empty to disable auto-discovery. |
YGGPEERS_COUNT |
Target number (1-10) of global Yggdrasil peers per node with internet on WAN. |
YGGPEERS_CHECK_INTERVAL |
Minutes between checks of the global peers (1-59 or a multiple of 60 up to 1380). |
YGGPEERS_RERANK_INTERVAL |
Days between forced refreshes of the global peers list (1-90), even if all current peers are alive. |
CLEARNET_EXITS |
Space-separated public keys of clearnet exits; the fastest working one is used. Can be empty. |
CLEARNET_MODE |
What clients' IPv4 traffic uses: wan, exit, wan_exit or off. |
To see the mesh working, set up a 3-node linear test (A β B β C).
- Flash the firmware to three devices and power them on. Make sure none of them is plugged into your home network or internet router.
- Place Node A at one end of your house, Node B in the middle and Node C at the other end. The distance should be large enough that a phone near Node A cannot see the WiFi of Node C. Wait about 3 minutes for the first-boot configuration and the mesh forming.
- Turn off mobile data on your phone, stand near Node A and connect to the
YggMeshWiFi hotspot. - Open a browser on the phone and load a public Yggdrasil website, e.g. from https://yggdrasil-network.github.io/services.html.
If the site loads, your mesh is formed and routes Yggdrasil traffic end-to-end across multiple hops.
You can find the next items planned to add to YggMesh here.
You can find various tests, field notes, and experiment data in the experiments/ folder.