nixos/modules/services/networking/yggdrasil.xml

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