diff options
author | pennae <github@quasiparticle.net> | 2023-01-03 06:32:09 +0100 |
---|---|---|
committer | pennae <github@quasiparticle.net> | 2023-01-10 10:31:57 +0100 |
commit | e4897cdf1605e8c30e79402b5bb054085d5f8a06 (patch) | |
tree | 6024cd30a66cb244935dd71d287aa26eb6861d69 /nixos | |
parent | 963c6f54aa14cb040ee3ef38626cadf445dcd732 (diff) |
nixos/yggdrasil: convert manual chapter to MD
Diffstat (limited to 'nixos')
-rw-r--r-- | nixos/modules/services/networking/yggdrasil.md | 141 | ||||
-rw-r--r-- | nixos/modules/services/networking/yggdrasil.nix | 2 | ||||
-rw-r--r-- | nixos/modules/services/networking/yggdrasil.xml | 71 |
3 files changed, 178 insertions, 36 deletions
diff --git a/nixos/modules/services/networking/yggdrasil.md b/nixos/modules/services/networking/yggdrasil.md new file mode 100644 index 0000000000000..bbaea5bc74aaf --- /dev/null +++ b/nixos/modules/services/networking/yggdrasil.md @@ -0,0 +1,141 @@ +# Yggdrasil {#module-services-networking-yggdrasil} + +*Source:* {file}`modules/services/networking/yggdrasil/default.nix` + +*Upstream documentation:* <https://yggdrasil-network.github.io/> + +Yggdrasil is an early-stage implementation of a fully end-to-end encrypted, +self-arranging IPv6 network. + +## Configuration {#module-services-networking-yggdrasil-configuration} + +### Simple ephemeral node {#module-services-networking-yggdrasil-configuration-simple} + +An annotated example of a simple configuration: +``` +{ + 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 "peer" 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. + "tcp://1.2.3.4:1024" + "tcp://1.2.3.5:1024" + # Public peers can be found at + # https://github.com/yggdrasil-network/public-peers + ]; + }; + }; +} +``` + +### Persistent node with prefix {#module-services-networking-yggdrasil-configuration-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. + settings = { + 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 = { + # Announce the 300::/8 prefix to eth0. + enable = true; + config = '' + interface eth0 + { + AdvSendAdvert on; + prefix ${prefix}::/64 { + AdvOnLink on; + AdvAutonomous on; + }; + route 200::/8 {}; + }; + ''; + }; +} +``` + +### Yggdrasil attached Container {#module-services-networking-yggdrasil-configuration-container} + +A NixOS container attached to the Yggdrasil network via a node running on the +host: +``` +let + yggPrefix64 = "310:5217:69c0:9afc"; + # Again, taken from the output of "yggdrasilctl getself". +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 ]; + }; + }; + +} +``` diff --git a/nixos/modules/services/networking/yggdrasil.nix b/nixos/modules/services/networking/yggdrasil.nix index 3d5cbdd2dc3ed..88ab728fc51cc 100644 --- a/nixos/modules/services/networking/yggdrasil.nix +++ b/nixos/modules/services/networking/yggdrasil.nix @@ -193,6 +193,8 @@ in { environment.systemPackages = [ cfg.package ]; }); meta = { + # Don't edit the docbook xml directly, edit the md and generate it: + # `pandoc yggdrasil.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > yggdrasil.xml` 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 index a7b8c469529a0..5b6f63b3ae064 100644 --- a/nixos/modules/services/networking/yggdrasil.xml +++ b/nixos/modules/services/networking/yggdrasil.xml @@ -1,5 +1,4 @@ -<?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"> +<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> @@ -7,19 +6,20 @@ </para> <para> <emphasis>Upstream documentation:</emphasis> - <link xlink:href="https://yggdrasil-network.github.io/"/> + <link xlink:href="https://yggdrasil-network.github.io/" role="uri">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> + 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: -<programlisting> + An annotated example of a simple configuration: + </para> + <programlisting> { services.yggdrasil = { enable = true; @@ -29,12 +29,12 @@ An annotated example of a simple configuration: settings = { Peers = [ - # Yggdrasil will automatically connect and "peer" with other nodes it + # Yggdrasil will automatically connect and "peer" 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. - "tcp://1.2.3.4:1024" - "tcp://1.2.3.5:1024" + "tcp://1.2.3.4:1024" + "tcp://1.2.3.5:1024" # Public peers can be found at # https://github.com/yggdrasil-network/public-peers ]; @@ -42,38 +42,38 @@ An annotated example of a simple configuration: }; } </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> + A node with a fixed address that announces a prefix: + </para> + <programlisting> let - address = "210:5217:69c0:9afc:1b95:b9f:8718:c3d2"; - prefix = "310:5217:69c0:9afc"; - # taken from the output of "yggdrasilctl getself". + 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. settings = { - Peers = [ "tcp://1.2.3.4:1024" "tcp://1.2.3.5:1024" ]; + 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"; + location = "The North Pole"; }; }; }; - boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1; + 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"; + address = prefix + "::1"; prefixLength = 64; }]; @@ -94,30 +94,30 @@ in { }; } </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> + A NixOS container attached to the Yggdrasil network via a node + running on the host: + </para> + <programlisting> let - yggPrefix64 = "310:5217:69c0:9afc"; - # Again, taken from the output of "yggdrasilctl getself". + yggPrefix64 = "310:5217:69c0:9afc"; + # Again, taken from the output of "yggdrasilctl getself". in { - boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1; + boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1; # Enable IPv6 forwarding. networking = { bridges.br0.interfaces = [ ]; - # A bridge only to containers… + # A bridge only to containers… interfaces.br0 = { - # … configured with a prefix address. + # … configured with a prefix address. ipv6.addresses = [{ - address = "${yggPrefix64}::1"; + address = "${yggPrefix64}::1"; prefixLength = 64; }]; }; @@ -126,20 +126,20 @@ in containers.foo = { autoStart = true; privateNetwork = true; - hostBridge = "br0"; + hostBridge = "br0"; # Attach the container to the bridge only. config = { config, pkgs, ... }: { networking.interfaces.eth0.ipv6 = { addresses = [{ # Configure a prefix address. - address = "${yggPrefix64}::2"; + address = "${yggPrefix64}::2"; prefixLength = 64; }]; routes = [{ # Configure the prefix route. - address = "200::"; + address = "200::"; prefixLength = 7; - via = "${yggPrefix64}::1"; + via = "${yggPrefix64}::1"; }]; }; @@ -150,7 +150,6 @@ in } </programlisting> - </para> </section> </section> </chapter> |