yggdrasil

Yggdrasil encrypted IPv6 routing overlay network

This module sets up yggdrasil across your clan.

Yggdrasil is designed to be a future-proof and decentralised alternative to the structured routing protocols commonly used today on the internet. Inside your clan, it will allow you to reach all of your machines.

If you have other services in your inventory which export peers (e.g. the internet or the VPN services) as service exports, they will be added as yggdrasil peers automatically. This allows using the stable yggdrasil IPv6 address to refer to other hosts and letting yggdrasil decide on the best routing based on available connections.

The yggdrasil IPv6-address will be added to /etc/hosts using the meta.domain settings, allowing you to reach each host in the clan via <hostname>.<meta.domain>.

Yggdrasil also does auto-discovery of local peers per default.

Basic Usage Example

The simplest set-up is deploying yggdrasil on its own:

inventory = {

  machines = {
    peer1 = { };
    peer2 = { };
  };

  instances = {
    # Deploy yggdraisl on all machines
    yggdrasil = {
      roles.default.tags.all = { };
    };
  };
};

Complex Usage Example

This example demonstrates a more sophisticated setup that combines yggdrasil with multiple network clan services. By setting meta.domain = "ccc", you can access any machine in your clan using <hostname>.ccc (e.g., peer1.ccc or peer2.ccc). Yggdrasil will automatically choose the best available routing path between machines, whether that's via direct internet connection (internet service_, the mycelium mesh network, or through Tor hidden services. This provides resilient connectivity with automatic failover between different network transports.

inventory = {

  machines = {
    peer1 = { };
    peer2 = { };
  };

  meta.domain = "ccc";

  instances = {

    # Deploy yggdraisl on all machines
    yggdrasil = {
      roles.default.tags.all = [ "all" ];
    };

    internet = {
      roles.default.machines = {
        peer1.settings.host = "85.139.10.1";
        peer2.settings.host = "85.139.10.2";
      };
    };

    mycelium = {
      roles.peer.tags.all = { };
    };

    tor = {

      roles.client.tags = [ "all" ];
      roles.server.tags = [ "all" ];

      roles.server.settings = {

        secretHostname = false;

        # yggdrasil ports need to be mapped
        portMapping = [
          {
            port = 6443;
            target.port = 6443;
          }
          {
            port = 6446;
            target.port = 6446;
          }
        ];
      };
    };
  };
};

Security and Privacy

This module sets Yggdrasil's AllowedEncryptionPublicKeys to limit the connections to the public keys of all machines with the default role.

According to the yggdrasil documentation:

This is not a firewall and does not control who can send you traffic over the Yggdrasil Network or reach open ports and services on your machine. For that you need an IPv6 firewall.

This service therefore also sets up firewall rules, such that the ygg network interface only accepts traffic from clan member IPs.

By default, multicast peer discovery is enabled on all network interfaces, allowing automatic discovery of local peers. Since Yggdrasil provides end-to-end encryption, this is safe even on untrusted networks.

If you want to restrict multicast to specific interfaces (e.g., only VPN interfaces), you can configure settings.multicastInterfaces with a list of interface patterns. For example, to only announce on VPN interfaces:

settings.multicastInterfaces = [
  {
    Regex = "(wg|zt|tailscale|mycelium|tinc|tun|tap).*";
    Beacon = true;
    Listen = true;
    Port = 5400;
    Priority = 0;
  }
];

Roles

The yggdrasil service has the following roles:

• default

Options for the default role

extraPeers

Additional static peers to configure for this host. If you use a VPN clan service, it will automatically be added as peers to other hosts. Local peers are also auto-discovered and don't need to be added.

Type: list of string

Default:

[ ]

[
  "tcp://192.168.1.1:6443"
  "quic://192.168.1.1:6444"
  "tls://192.168.1.1:6445"
  "ws://192.168.1.1:6446"
]

Declared in: clanServices/yggdrasil/default.nix

multicastInterfaces

Interfaces to use for Yggdrasil multicast peer discovery. By default, multicast is enabled on all interfaces (empty list). To restrict multicast to specific interfaces, add them to this list. See https://yggdrasil-network.github.io/configurationref.html#multicastinterfaces

Type: list of (attribute set)

Default:

[ ]

[
  {
    Beacon = true;
    Listen = true;
    Port = 5400;
    Priority = 0;
    Regex = "(wg|zt|tailscale|mycelium|tinc|tun|tap).*";
  }
  {
    Beacon = true;
    Listen = true;
    Port = 5400;
    Priority = 1024;
    Regex = "(eth|en).*";
  }
  {
    Beacon = true;
    Listen = true;
    Port = 5400;
    Priority = 1025;
    Regex = "(wl).*";
  }
]

Declared in: clanServices/yggdrasil/default.nix

ports

Port configuration for Yggdrasil listeners.

Type: submodule

Default:

{ }

Declared in: clanServices/yggdrasil/default.nix

ports.quic

QUIC port, used for the quic:// yggdrasil listener

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

6444

Declared in: clanServices/yggdrasil/default.nix

ports.tcp

TCP port, used for the tcp:// yggdrasil listener

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

6443

Declared in: clanServices/yggdrasil/default.nix

ports.tls

TLS port, used for the tls:// yggdrasil listener

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

6446

Declared in: clanServices/yggdrasil/default.nix

ports.ws

Websocket port, used for the ws:// yggdrasil listener

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

6445

Declared in: clanServices/yggdrasil/default.nix