yggdrasil

Yggdrasil is an experimental, end-to-end encrypted IPv6 overlay network and compact routing scheme.

It is designed as a decentralised alternative to the structured routing protocols commonly used on today’s Internet, and as a possible foundation for large-scale mesh networks.

This package contains

• yggdrasil — the network daemon
• yggdrasilctl — the administration utility
• a systemd service for Sailfish OS

Configuration

During installation, the package creates a unique configuration file:

/etc/yggdrasil.conf

The configuration contains the private key that determines your Yggdrasil IPv6 address. Keep this file private and back it up if you want to preserve the same Yggdrasil identity and address.

The package does not overwrite an existing non-empty configuration file during upgrades.

Connecting to the network

Yggdrasil may discover nearby nodes through multicast on a local network.

To connect through the Internet, add one or more public or private peers to the Peers section of:

/etc/yggdrasil.conf

After changing the configuration, restart the service:

devel-su systemctl restart yggdrasil

To enable Yggdrasil automatically at boot and start it immediately:

devel-su systemctl enable --now yggdrasil

Check the service status with:

systemctl status yggdrasil

You can inspect the local Yggdrasil node with:

yggdrasilctl getSelf

The Yggdrasil interface will usually appear as tun0 and receive an IPv6 address from the 200::/7 range. The interface name can be changed in the Yggdrasil configuration.

You can find the active interface with:

ip -6 route show 200::/7

For example:

200::/7 dev tun0 proto kernel metric 256 pref medium

Sailfish OS firewall

Sailfish OS uses a ConnMan-managed firewall which blocks unsolicited incoming IPv6 traffic by default.

This does not normally prevent Yggdrasil from starting, connecting to peers, or making outgoing connections. However, other Yggdrasil nodes may be unable to ping the phone or connect to services running on it.

To allow incoming traffic through the Yggdrasil interface, first determine its name:

ip -6 route show 200::/7

The examples below assume that the interface is named tun0. Replace tun0 if your configuration uses another name, such as rat0.

Become root:

devel-su

Create a persistent ConnMan firewall rule:

cat > /etc/connman/firewall.d/01-allow-yggdrasil-firewall.conf <<'EOF'
[General]
IPv6.INPUT.RULES = -i tun0 -j ACCEPT
EOF

Restart ConnMan to apply the rule:

systemctl restart connman

Restarting ConnMan may briefly interrupt Wi-Fi or mobile-data connectivity.

The rule persists across reboots and allows incoming IPv6 traffic only through the Yggdrasil interface. The normal Sailfish firewall remains active on Wi-Fi, mobile-data and other interfaces.

To verify that the rule was installed:

ip6tables-save | grep tun0

To remove the rule and restore the default Sailfish firewall behaviour:

devel-su rm /etc/connman/firewall.d/01-allow-yggdrasil-firewall.conf
devel-su systemctl restart connman

Security note

Allowing all incoming traffic on the Yggdrasil interface makes services listening on IPv6 reachable from other Yggdrasil nodes.

Only run services that you intend to expose, and configure their own authentication and access controls appropriately.

Important

Yggdrasil is experimental software. Routing behaviour, configuration formats and interoperability may change between releases.

The generated configuration and private key must not be shared publicly.