nixpkgs/nixos/modules/services/networking/yggdrasil.xml

<!-- Do not edit this file directly, edit its companion .md instead
     and regenerate this file using nixos/doc/manual/md-to-db.sh -->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-networking-yggdrasil">
  <title>Yggdrasil</title>
  <para>
    <emphasis>Source:</emphasis>
    <filename>modules/services/networking/yggdrasil/default.nix</filename>
  </para>
  <para>
    <emphasis>Upstream documentation:</emphasis>
    <link xlink:href="https://yggdrasil-network.github.io/">https://yggdrasil-network.github.io/</link>
  </para>
  <para>
    Yggdrasil is an early-stage implementation of a fully end-to-end
    encrypted, self-arranging IPv6 network.
  </para>
  <section xml:id="module-services-networking-yggdrasil-configuration">
    <title>Configuration</title>
    <section xml:id="module-services-networking-yggdrasil-configuration-simple">
      <title>Simple ephemeral node</title>
      <para>
        An annotated example of a simple configuration:
      </para>
      <programlisting>
{
  services.yggdrasil = {
    enable = true;
    persistentKeys = false;
      # The NixOS module will generate new keys and a new IPv6 address each time
      # it is started if persistentKeys is not enabled.

    settings = {
      Peers = [
        # Yggdrasil will automatically connect and &quot;peer&quot; with other nodes it
        # discovers via link-local multicast announcements. Unless this is the
        # case (it probably isn't) a node needs peers within the existing
        # network that it can tunnel to.
        &quot;tcp://1.2.3.4:1024&quot;
        &quot;tcp://1.2.3.5:1024&quot;
        # Public peers can be found at
        # https://github.com/yggdrasil-network/public-peers
      ];
    };
  };
}
</programlisting>
    </section>
    <section xml:id="module-services-networking-yggdrasil-configuration-prefix">
      <title>Persistent node with prefix</title>
      <para>
        A node with a fixed address that announces a prefix:
      </para>
      <programlisting>
let
  address = &quot;210:5217:69c0:9afc:1b95:b9f:8718:c3d2&quot;;
  prefix = &quot;310:5217:69c0:9afc&quot;;
  # taken from the output of &quot;yggdrasilctl getself&quot;.
in {

  services.yggdrasil = {
    enable = true;
    persistentKeys = true; # Maintain a fixed public key and IPv6 address.
    settings = {
      Peers = [ &quot;tcp://1.2.3.4:1024&quot; &quot;tcp://1.2.3.5:1024&quot; ];
      NodeInfo = {
        # This information is visible to the network.
        name = config.networking.hostName;
        location = &quot;The North Pole&quot;;
      };
    };
  };

  boot.kernel.sysctl.&quot;net.ipv6.conf.all.forwarding&quot; = 1;
    # Forward traffic under the prefix.

  networking.interfaces.${eth0}.ipv6.addresses = [{
    # Set a 300::/8 address on the local physical device.
    address = prefix + &quot;::1&quot;;
    prefixLength = 64;
  }];

  services.radvd = {
    # Announce the 300::/8 prefix to eth0.
    enable = true;
    config = ''
      interface eth0
      {
        AdvSendAdvert on;
        prefix ${prefix}::/64 {
          AdvOnLink on;
          AdvAutonomous on;
        };
        route 200::/8 {};
      };
    '';
  };
}
</programlisting>
    </section>
    <section xml:id="module-services-networking-yggdrasil-configuration-container">
      <title>Yggdrasil attached Container</title>
      <para>
        A NixOS container attached to the Yggdrasil network via a node
        running on the host:
      </para>
      <programlisting>
let
  yggPrefix64 = &quot;310:5217:69c0:9afc&quot;;
    # Again, taken from the output of &quot;yggdrasilctl getself&quot;.
in
{
  boot.kernel.sysctl.&quot;net.ipv6.conf.all.forwarding&quot; = 1;
  # Enable IPv6 forwarding.

  networking = {
    bridges.br0.interfaces = [ ];
    # A bridge only to containers…

    interfaces.br0 = {
      # … configured with a prefix address.
      ipv6.addresses = [{
        address = &quot;${yggPrefix64}::1&quot;;
        prefixLength = 64;
      }];
    };
  };

  containers.foo = {
    autoStart = true;
    privateNetwork = true;
    hostBridge = &quot;br0&quot;;
    # Attach the container to the bridge only.
    config = { config, pkgs, ... }: {
      networking.interfaces.eth0.ipv6 = {
        addresses = [{
          # Configure a prefix address.
          address = &quot;${yggPrefix64}::2&quot;;
          prefixLength = 64;
        }];
        routes = [{
          # Configure the prefix route.
          address = &quot;200::&quot;;
          prefixLength = 7;
          via = &quot;${yggPrefix64}::1&quot;;
        }];
      };

      services.httpd.enable = true;
      networking.firewall.allowedTCPPorts = [ 80 ];
    };
  };

}
</programlisting>
    </section>
  </section>
</chapter>