nixos/yggdrasil: convert manual chapter to MD

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 &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.
-        "tcp://1.2.3.4:1024"
-        "tcp://1.2.3.5:1024"
+        &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
       ];
@@ -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 = &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 = [ "tcp://1.2.3.4:1024" "tcp://1.2.3.5:1024" ];
+      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 = "The North Pole";
+        location = &quot;The North Pole&quot;;
       };
     };
   };
 
-  boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1;
+  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 + "::1";
+    address = prefix + &quot;::1&quot;;
     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 = &quot;310:5217:69c0:9afc&quot;;
+    # Again, taken from the output of &quot;yggdrasilctl getself&quot;.
 in
 {
-  boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1;
+  boot.kernel.sysctl.&quot;net.ipv6.conf.all.forwarding&quot; = 1;
   # Enable IPv6 forwarding.
 
   networking = {
     bridges.br0.interfaces = [ ];
-    # A bridge only to containers&#x2026;
+    # A bridge only to containers…
 
     interfaces.br0 = {
-      # &#x2026; configured with a prefix address.
+      # … configured with a prefix address.
       ipv6.addresses = [{
-        address = "${yggPrefix64}::1";
+        address = &quot;${yggPrefix64}::1&quot;;
         prefixLength = 64;
       }];
     };
@@ -126,20 +126,20 @@ in
   containers.foo = {
     autoStart = true;
     privateNetwork = true;
-    hostBridge = "br0";
+    hostBridge = &quot;br0&quot;;
     # Attach the container to the bridge only.
     config = { config, pkgs, ... }: {
       networking.interfaces.eth0.ipv6 = {
         addresses = [{
           # Configure a prefix address.
-          address = "${yggPrefix64}::2";
+          address = &quot;${yggPrefix64}::2&quot;;
           prefixLength = 64;
         }];
         routes = [{
           # Configure the prefix route.
-          address = "200::";
+          address = &quot;200::&quot;;
           prefixLength = 7;
-          via = "${yggPrefix64}::1";
+          via = &quot;${yggPrefix64}::1&quot;;
         }];
       };
 
@@ -150,7 +150,6 @@ in
 
 }
 </programlisting>
-      </para>
     </section>
   </section>
 </chapter>