From 764a9252a36dc828f2a4f5de123679992353dd9c Mon Sep 17 00:00:00 2001 From: Emery Hemingway Date: Sat, 30 May 2020 15:35:48 +0530 Subject: [PATCH] nixos/yggdrasil: add manual section --- .../modules/services/networking/yggdrasil.nix | 5 +- .../modules/services/networking/yggdrasil.xml | 167 ++++++++++++++++++ 2 files changed, 171 insertions(+), 1 deletion(-) create mode 100644 nixos/modules/services/networking/yggdrasil.xml 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 @@ + + + Yggdrasil + + Source: + modules/services/networking/yggdrasil/default.nix + + + Upstream documentation: + + + +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. + + +When enabled the Yggdrasil service creates a tun device with a unique IPv6 in +the 200::/8 address space. This device and address can be +used to communicate with all other connected nodes in the +200::/7 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 300::/8 space. This +prefix may be announced to locally attached networks. + + +Despite the normal distribution of nodes within the 200::/8 +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. + +
+ Configuration +
+ Simple ephemeral node + +An annotated example of a simple configuration: + +{ + 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" + ]; + }; + }; +} + + +
+
+ Persistent node with prefix + +A node with a fixed address that announces a prefix: + +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 {}; + }; + ''; + }; +} + + +
+
+ Yggdrasil attached Container + +A NixOS container attached to the Yggdrasil network via a node running on the +host: + +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 ]; + }; + }; + +} + + +
+
+