pyrox.dev
lol
nixos/yggdrasil: convert manual chapter to MD
+178
-36
+141
nixos/modules/services/networking/yggdrasil.md
+141
nixos/modules/services/networking/yggdrasil.md
···
1
+
# Yggdrasil {#module-services-networking-yggdrasil}
2
+
3
+
*Source:* {file}`modules/services/networking/yggdrasil/default.nix`
4
+
5
+
*Upstream documentation:* <https://yggdrasil-network.github.io/>
6
+
7
+
Yggdrasil is an early-stage implementation of a fully end-to-end encrypted,
8
+
self-arranging IPv6 network.
9
+
10
+
## Configuration {#module-services-networking-yggdrasil-configuration}
11
+
12
+
### Simple ephemeral node {#module-services-networking-yggdrasil-configuration-simple}
13
+
14
+
An annotated example of a simple configuration:
15
+
```
16
+
{
17
+
services.yggdrasil = {
18
+
enable = true;
19
+
persistentKeys = false;
20
+
# The NixOS module will generate new keys and a new IPv6 address each time
21
+
# it is started if persistentKeys is not enabled.
22
+
23
+
settings = {
24
+
Peers = [
25
+
# Yggdrasil will automatically connect and "peer" with other nodes it
26
+
# discovers via link-local multicast announcements. Unless this is the
27
+
# case (it probably isn't) a node needs peers within the existing
28
+
# network that it can tunnel to.
29
+
"tcp://1.2.3.4:1024"
30
+
"tcp://1.2.3.5:1024"
31
+
# Public peers can be found at
32
+
# https://github.com/yggdrasil-network/public-peers
33
+
];
34
+
};
35
+
};
36
+
}
37
+
```
38
+
39
+
### Persistent node with prefix {#module-services-networking-yggdrasil-configuration-prefix}
40
+
41
+
A node with a fixed address that announces a prefix:
42
+
```
43
+
let
44
+
address = "210:5217:69c0:9afc:1b95:b9f:8718:c3d2";
45
+
prefix = "310:5217:69c0:9afc";
46
+
# taken from the output of "yggdrasilctl getself".
47
+
in {
48
+
49
+
services.yggdrasil = {
50
+
enable = true;
51
+
persistentKeys = true; # Maintain a fixed public key and IPv6 address.
52
+
settings = {
53
+
Peers = [ "tcp://1.2.3.4:1024" "tcp://1.2.3.5:1024" ];
54
+
NodeInfo = {
55
+
# This information is visible to the network.
56
+
name = config.networking.hostName;
57
+
location = "The North Pole";
58
+
};
59
+
};
60
+
};
61
+
62
+
boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1;
63
+
# Forward traffic under the prefix.
64
+
65
+
networking.interfaces.${eth0}.ipv6.addresses = [{
66
+
# Set a 300::/8 address on the local physical device.
67
+
address = prefix + "::1";
68
+
prefixLength = 64;
69
+
}];
70
+
71
+
services.radvd = {
72
+
# Announce the 300::/8 prefix to eth0.
73
+
enable = true;
74
+
config = ''
75
+
interface eth0
76
+
{
77
+
AdvSendAdvert on;
78
+
prefix ${prefix}::/64 {
79
+
AdvOnLink on;
80
+
AdvAutonomous on;
81
+
};
82
+
route 200::/8 {};
83
+
};
84
+
'';
85
+
};
86
+
}
87
+
```
88
+
89
+
### Yggdrasil attached Container {#module-services-networking-yggdrasil-configuration-container}
90
+
91
+
A NixOS container attached to the Yggdrasil network via a node running on the
92
+
host:
93
+
```
94
+
let
95
+
yggPrefix64 = "310:5217:69c0:9afc";
96
+
# Again, taken from the output of "yggdrasilctl getself".
97
+
in
98
+
{
99
+
boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1;
100
+
# Enable IPv6 forwarding.
101
+
102
+
networking = {
103
+
bridges.br0.interfaces = [ ];
104
+
# A bridge only to containers…
105
+
106
+
interfaces.br0 = {
107
+
# … configured with a prefix address.
108
+
ipv6.addresses = [{
109
+
address = "${yggPrefix64}::1";
110
+
prefixLength = 64;
111
+
}];
112
+
};
113
+
};
114
+
115
+
containers.foo = {
116
+
autoStart = true;
117
+
privateNetwork = true;
118
+
hostBridge = "br0";
119
+
# Attach the container to the bridge only.
120
+
config = { config, pkgs, ... }: {
121
+
networking.interfaces.eth0.ipv6 = {
122
+
addresses = [{
123
+
# Configure a prefix address.
124
+
address = "${yggPrefix64}::2";
125
+
prefixLength = 64;
126
+
}];
127
+
routes = [{
128
+
# Configure the prefix route.
129
+
address = "200::";
130
+
prefixLength = 7;
131
+
via = "${yggPrefix64}::1";
132
+
}];
133
+
};
134
+
135
+
services.httpd.enable = true;
136
+
networking.firewall.allowedTCPPorts = [ 80 ];
137
+
};
138
+
};
139
+
140
+
}
141
+
```
+2
nixos/modules/services/networking/yggdrasil.nix
+2
nixos/modules/services/networking/yggdrasil.nix
···
193
193
environment.systemPackages = [ cfg.package ];
194
194
});
195
195
meta = {
196
+
# Don't edit the docbook xml directly, edit the md and generate it:
197
+
# `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`
196
198
doc = ./yggdrasil.xml;
197
199
maintainers = with lib.maintainers; [ gazally ehmry ];
198
200
};
+35
-36
nixos/modules/services/networking/yggdrasil.xml
+35
-36
nixos/modules/services/networking/yggdrasil.xml
···
1
-
<?xml version="1.0"?>
2
-
<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">
1
+
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-networking-yggdrasil">
3
2
<title>Yggdrasil</title>
4
3
<para>
5
4
<emphasis>Source:</emphasis>
···
7
6
</para>
8
7
<para>
9
8
<emphasis>Upstream documentation:</emphasis>
10
-
<link xlink:href="https://yggdrasil-network.github.io/"/>
9
+
<link xlink:href="https://yggdrasil-network.github.io/" role="uri">https://yggdrasil-network.github.io/</link>
11
10
</para>
12
11
<para>
13
-
Yggdrasil is an early-stage implementation of a fully end-to-end encrypted,
14
-
self-arranging IPv6 network.
15
-
</para>
12
+
Yggdrasil is an early-stage implementation of a fully end-to-end
13
+
encrypted, self-arranging IPv6 network.
14
+
</para>
16
15
<section xml:id="module-services-networking-yggdrasil-configuration">
17
16
<title>Configuration</title>
18
17
<section xml:id="module-services-networking-yggdrasil-configuration-simple">
19
18
<title>Simple ephemeral node</title>
20
19
<para>
21
-
An annotated example of a simple configuration:
22
-
<programlisting>
20
+
An annotated example of a simple configuration:
21
+
</para>
22
+
<programlisting>
23
23
{
24
24
services.yggdrasil = {
25
25
enable = true;
···
29
29
30
30
settings = {
31
31
Peers = [
32
-
# Yggdrasil will automatically connect and "peer" with other nodes it
32
+
# Yggdrasil will automatically connect and "peer" with other nodes it
33
33
# discovers via link-local multicast announcements. Unless this is the
34
34
# case (it probably isn't) a node needs peers within the existing
35
35
# network that it can tunnel to.
36
-
"tcp://1.2.3.4:1024"
37
-
"tcp://1.2.3.5:1024"
36
+
"tcp://1.2.3.4:1024"
37
+
"tcp://1.2.3.5:1024"
38
38
# Public peers can be found at
39
39
# https://github.com/yggdrasil-network/public-peers
40
40
];
···
42
42
};
43
43
}
44
44
</programlisting>
45
-
</para>
46
45
</section>
47
46
<section xml:id="module-services-networking-yggdrasil-configuration-prefix">
48
47
<title>Persistent node with prefix</title>
49
48
<para>
50
-
A node with a fixed address that announces a prefix:
51
-
<programlisting>
49
+
A node with a fixed address that announces a prefix:
50
+
</para>
51
+
<programlisting>
52
52
let
53
-
address = "210:5217:69c0:9afc:1b95:b9f:8718:c3d2";
54
-
prefix = "310:5217:69c0:9afc";
55
-
# taken from the output of "yggdrasilctl getself".
53
+
address = "210:5217:69c0:9afc:1b95:b9f:8718:c3d2";
54
+
prefix = "310:5217:69c0:9afc";
55
+
# taken from the output of "yggdrasilctl getself".
56
56
in {
57
57
58
58
services.yggdrasil = {
59
59
enable = true;
60
60
persistentKeys = true; # Maintain a fixed public key and IPv6 address.
61
61
settings = {
62
-
Peers = [ "tcp://1.2.3.4:1024" "tcp://1.2.3.5:1024" ];
62
+
Peers = [ "tcp://1.2.3.4:1024" "tcp://1.2.3.5:1024" ];
63
63
NodeInfo = {
64
64
# This information is visible to the network.
65
65
name = config.networking.hostName;
66
-
location = "The North Pole";
66
+
location = "The North Pole";
67
67
};
68
68
};
69
69
};
70
70
71
-
boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1;
71
+
boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1;
72
72
# Forward traffic under the prefix.
73
73
74
74
networking.interfaces.${eth0}.ipv6.addresses = [{
75
75
# Set a 300::/8 address on the local physical device.
76
-
address = prefix + "::1";
76
+
address = prefix + "::1";
77
77
prefixLength = 64;
78
78
}];
79
79
···
94
94
};
95
95
}
96
96
</programlisting>
97
-
</para>
98
97
</section>
99
98
<section xml:id="module-services-networking-yggdrasil-configuration-container">
100
99
<title>Yggdrasil attached Container</title>
101
100
<para>
102
-
A NixOS container attached to the Yggdrasil network via a node running on the
103
-
host:
104
-
<programlisting>
101
+
A NixOS container attached to the Yggdrasil network via a node
102
+
running on the host:
103
+
</para>
104
+
<programlisting>
105
105
let
106
-
yggPrefix64 = "310:5217:69c0:9afc";
107
-
# Again, taken from the output of "yggdrasilctl getself".
106
+
yggPrefix64 = "310:5217:69c0:9afc";
107
+
# Again, taken from the output of "yggdrasilctl getself".
108
108
in
109
109
{
110
-
boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1;
110
+
boot.kernel.sysctl."net.ipv6.conf.all.forwarding" = 1;
111
111
# Enable IPv6 forwarding.
112
112
113
113
networking = {
114
114
bridges.br0.interfaces = [ ];
115
-
# A bridge only to containers…
115
+
# A bridge only to containers…
116
116
117
117
interfaces.br0 = {
118
-
# … configured with a prefix address.
118
+
# … configured with a prefix address.
119
119
ipv6.addresses = [{
120
-
address = "${yggPrefix64}::1";
120
+
address = "${yggPrefix64}::1";
121
121
prefixLength = 64;
122
122
}];
123
123
};
···
126
126
containers.foo = {
127
127
autoStart = true;
128
128
privateNetwork = true;
129
-
hostBridge = "br0";
129
+
hostBridge = "br0";
130
130
# Attach the container to the bridge only.
131
131
config = { config, pkgs, ... }: {
132
132
networking.interfaces.eth0.ipv6 = {
133
133
addresses = [{
134
134
# Configure a prefix address.
135
-
address = "${yggPrefix64}::2";
135
+
address = "${yggPrefix64}::2";
136
136
prefixLength = 64;
137
137
}];
138
138
routes = [{
139
139
# Configure the prefix route.
140
-
address = "200::";
140
+
address = "200::";
141
141
prefixLength = 7;
142
-
via = "${yggPrefix64}::1";
142
+
via = "${yggPrefix64}::1";
143
143
}];
144
144
};
145
145
···
150
150
151
151
}
152
152
</programlisting>
153
-
</para>
154
153
</section>
155
154
</section>
156
155
</chapter>