diff options
author | Emery Hemingway <ehmry@posteo.net> | 2020-05-30 15:35:48 +0530 |
---|---|---|
committer | ehmry <ehmry@posteo.net> | 2020-07-25 16:34:20 +0200 |
commit | 764a9252a36dc828f2a4f5de123679992353dd9c (patch) | |
tree | 320f3e064cef188ca2dbd8c50b9e4a5d855e5fbb /nixos/modules | |
parent | 39deb82e4bb0106ba76a44a956a3a493c6436ae9 (diff) |
nixos/yggdrasil: add manual section
Diffstat (limited to 'nixos/modules')
-rw-r--r-- | nixos/modules/services/networking/yggdrasil.nix | 5 | ||||
-rw-r--r-- | nixos/modules/services/networking/yggdrasil.xml | 167 |
2 files changed, 171 insertions, 1 deletions
diff --git a/nixos/modules/services/networking/yggdrasil.nix b/nixos/modules/services/networking/yggdrasil.nix index 0fe9a200a1b60..a71c635c9f6ef 100644 --- a/nixos/modules/services/networking/yggdrasil.nix +++ b/nixos/modules/services/networking/yggdrasil.nix @@ -195,5 +195,8 @@ in { # Make yggdrasilctl available on the command line. environment.systemPackages = [ cfg.package ]; }); - meta.maintainers = with lib.maintainers; [ gazally ehmry ]; + meta = { + doc = ./yggdrasil.xml; + maintainers = with lib.maintainers; [ gazally ehmry ]; + }; } diff --git a/nixos/modules/services/networking/yggdrasil.xml b/nixos/modules/services/networking/yggdrasil.xml new file mode 100644 index 0000000000000..5d7de4c58ceed --- /dev/null +++ b/nixos/modules/services/networking/yggdrasil.xml @@ -0,0 +1,167 @@ +<?xml version="1.0"?> +<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"> + <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/"/> + </para> + <para> +Yggdrasil is an early-stage implementation of a fully end-to-end encrypted +IPv6 network. It is lightweight, self-arranging, supported on multiple +platforms and allows pretty much any IPv6-capable application to communicate +securely with other Yggdrasil nodes. +</para> + <para> +When enabled the Yggdrasil service creates a tun device with a unique IPv6 in +the <literal>200::/8</literal> address space. This device and address can be +used to communicate with all other connected nodes in the +<literal>200::/7</literal> Yggdrasil network. Each Yggdrasil node can also +route a subnet using the first half of its address with the eighth bit masked +as a prefix, that is to say, within the <literal>300::/8</literal> space. This +prefix may be announced to locally attached networks. +</para> + <para> +Despite the normal distribution of nodes within the <literal>200::/8</literal> +space, the addresses of connected nodes can be readily enumerated, unlike the +the traditional global IPv6 network. For this reason, all open services on a +node should be considered public, or the system firewall should be enabled. +</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: +<programlisting> +{ + services.yggdrasil = { + enable = true; + config = { + Peers = [ + # Yggdrasil will automatically connect and "peer" with other nodes it + # discovers via link-local multicast annoucements. Unless this is the + # case (it probably isn't) a node needs peers within the existing + # network that it can tunnel to. + "tcp://1.2.3.4:1024" + "tcp://1.2.3.5:1024" + ]; + }; + }; +} +</programlisting> + </para> + </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: +<programlisting> +let + address = "210:5217:69c0:9afc:1b95:b9f:8718:c3d2"; + prefix = "310:5217:69c0:9afc"; + # taken from the output of "yggdrasilctl getself". +in { + + services.yggdrasil = { + enable = true; + persistentKeys = true; # Maintain a fixed public key and IPv6 address. + config = { + Peers = [ "tcp://1.2.3.4:1024" "tcp://1.2.3.5:1024" ]; + NodeInfo = { + # This information is visible to the network. + name = config.networking.hostName; + location = "The North Pole"; + }; + }; + }; + + boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1; + # Forward traffic under the prefix. + + networking.interfaces.${eth0}.ipv6.addresses = [{ + # Set a 300::/8 address on the local physical device. + address = prefix + "::1"; + prefixLength = 64; + }]; + + services.radvd = { + # Annouce the 300::/8 prefix to eth0. + enable = true; + config = '' + interface eth0 + { + AdvSendAdvert on; + AdvDefaultLifetime 0; + prefix ${prefix}::/64 { + AdvOnLink on; + AdvAutonomous on; + }; + route 200::/8 {}; + }; + ''; + }; +} +</programlisting> + </para> + </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: + <programlisting> +let + yggPrefix64 = "…"; +in +{ + boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1; + # Enable IPv6 forwarding. + + networking = { + bridges.br0.interfaces = [ ]; + # A bridge only to containers… + + interfaces.br0 = { + # … configured with a prefix address. + ipv6.addresses = [{ + address = "${yggPrefix64}::1"; + prefixLength = 64; + }]; + }; + }; + + containers.foo = { + autoStart = true; + privateNetwork = true; + hostBridge = "br0"; + # Attach the container to the bridge only. + config = { config, pkgs, ... }: { + networking.interfaces.eth0.ipv6 = { + addresses = [{ + # Configure a prefix address. + address = "${yggPrefix64}::2"; + prefixLength = 64; + }]; + routes = [{ + # Configure the prefix route. + address = "200::"; + prefixLength = 7; + via = "${yggPrefix64}::1"; + }]; + }; + + services.httpd.enable = true; + networking.firewall.allowedTCPPorts = [ 80 ]; + }; + }; + +} +</programlisting> + </para> + </section> + </section> +</chapter> |