nixos/modules/services/networking/yggdrasil.md

   1 # Yggdrasil {#module-services-networking-yggdrasil}
   2
   3 *Source:* {file}`modules/services/networking/yggdrasil/default.nix`
   4
   5 *Upstream documentation:* <https://yggdrasil-network.github.io/>
   6
   7 Yggdrasil is an early-stage implementation of a fully end-to-end encrypted,
   8 self-arranging IPv6 network.
   9
  10 ## Configuration {#module-services-networking-yggdrasil-configuration}
  11
  12 ### Simple ephemeral node {#module-services-networking-yggdrasil-configuration-simple}
  13
  14 An annotated example of a simple configuration:
  15 ```nix
  16 {
  17   services.yggdrasil = {
  18     enable = true;
  19     persistentKeys = false;
  20       # The NixOS module will generate new keys and a new IPv6 address each time
  21       # it is started if persistentKeys is not enabled.
  22
  23     settings = {
  24       Peers = [
  25         # Yggdrasil will automatically connect and "peer" with other nodes it
  26         # discovers via link-local multicast announcements. Unless this is the
  27         # case (it probably isn't) a node needs peers within the existing
  28         # network that it can tunnel to.
  29         "tcp://1.2.3.4:1024"
  30         "tcp://1.2.3.5:1024"
  31         # Public peers can be found at
  32         # https://github.com/yggdrasil-network/public-peers
  33       ];
  34     };
  35   };
  36 }
  37 ```
  38
  39 ### Persistent node with prefix {#module-services-networking-yggdrasil-configuration-prefix}
  40
  41 A node with a fixed address that announces a prefix:
  42 ```nix
  43 let
  44   address = "210:5217:69c0:9afc:1b95:b9f:8718:c3d2";
  45   prefix = "310:5217:69c0:9afc";
  46   # taken from the output of "yggdrasilctl getself".
  47 in {
  48
  49   services.yggdrasil = {
  50     enable = true;
  51     persistentKeys = true; # Maintain a fixed public key and IPv6 address.
  52     settings = {
  53       Peers = [ "tcp://1.2.3.4:1024" "tcp://1.2.3.5:1024" ];
  54       NodeInfo = {
  55         # This information is visible to the network.
  56         name = config.networking.hostName;
  57         location = "The North Pole";
  58       };
  59     };
  60   };
  61
  62   boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1;
  63     # Forward traffic under the prefix.
  64
  65   networking.interfaces.${eth0}.ipv6.addresses = [{
  66     # Set a 300::/8 address on the local physical device.
  67     address = prefix + "::1";
  68     prefixLength = 64;
  69   }];
  70
  71   services.radvd = {
  72     # Announce the 300::/8 prefix to eth0.
  73     enable = true;
  74     config = ''
  75       interface eth0
  76       {
  77         AdvSendAdvert on;
  78         prefix ${prefix}::/64 {
  79           AdvOnLink on;
  80           AdvAutonomous on;
  81         };
  82         route 200::/8 {};
  83       };
  84     '';
  85   };
  86 }
  87 ```
  88
  89 ### Yggdrasil attached Container {#module-services-networking-yggdrasil-configuration-container}
  90
  91 A NixOS container attached to the Yggdrasil network via a node running on the
  92 host:
  93 ```nix
  94 let
  95   yggPrefix64 = "310:5217:69c0:9afc";
  96     # Again, taken from the output of "yggdrasilctl getself".
  97 in
  98 {
  99   boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1;
 100   # Enable IPv6 forwarding.
 101
 102   networking = {
 103     bridges.br0.interfaces = [ ];
 104     # A bridge only to containers…
 105
 106     interfaces.br0 = {
 107       # … configured with a prefix address.
 108       ipv6.addresses = [{
 109         address = "${yggPrefix64}::1";
 110         prefixLength = 64;
 111       }];
 112     };
 113   };
 114
 115   containers.foo = {
 116     autoStart = true;
 117     privateNetwork = true;
 118     hostBridge = "br0";
 119     # Attach the container to the bridge only.
 120     config = { config, pkgs, ... }: {
 121       networking.interfaces.eth0.ipv6 = {
 122         addresses = [{
 123           # Configure a prefix address.
 124           address = "${yggPrefix64}::2";
 125           prefixLength = 64;
 126         }];
 127         routes = [{
 128           # Configure the prefix route.
 129           address = "200::";
 130           prefixLength = 7;
 131           via = "${yggPrefix64}::1";
 132         }];
 133       };
 134
 135       services.httpd.enable = true;
 136       networking.firewall.allowedTCPPorts = [ 80 ];
 137     };
 138   };
 139
 140 }
 141 ```