dev/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

nixos/yggdrasil: convert manual chapter to MD

Browse Source
This commit is contained in:
pennae 2023-01-03 06:32:09 +01:00
parent 963c6f54aa
commit e4897cdf16
3 changed files with 178 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
nixos/modules/services/networking/yggdrasil.md Normal file
View File

@ -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 ];
};
};
}
```

2
nixos/modules/services/networking/yggdrasil.nix
View File

@ -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 ];
};

71
nixos/modules/services/networking/yggdrasil.xml
View File

@ -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>