3 @unnumbered Yggdrasil support
5 NNCP is able to act as a node of
6 @url{https://yggdrasil-network.github.io/, Yggdrasil} overlay network.
7 Current IPv6 adoption for @strong{home} users is relatively bad in many
8 countries. That is why Yggdrasil overlay network uses dynamic spanning
9 tree mesh network for packets routing, making it useful for gaining
10 hosts high reachability without complex manual manipulations. By default
11 it creates 200::/7 IPv6 network, where each host's address is derived
14 NNCP reuses Yggdrasil's source code, but instead of relying on operating
15 system's network stack, that would require use of some kind
16 full-featured TUN network interface, there is pure Go built-in stack,
17 responsible for IPv6 and TCP protocols support. You do not need to think
18 about network interfaces, addressing and firewall setup at all:
19 @command{@ref{nncp-daemon}} acts as Yggdrasil IPv6 reachable host,
20 listening on single TCP port. You can reach it using ordinary
21 non-Yggdrasil capable version of @command{@ref{nncp-call}}, calling
22 corresponding 200::/7 IPv6 address through native Yggdrasil daemon
23 created TUN interface. @command{@ref{nncp-daemon}},
24 @command{@ref{nncp-call}}* can freely peer with Yggdrasil nodes, reusing
25 existing infrastructure.
27 Only minor modifications were done to current NNCP's tools:
31 @cindex yggdrasils schema
32 @item @command{@ref{nncp-daemon}} has @option{-yggdrasil yggdrasils://}
33 option, making it also as a Yggdrasil listener network node. It can
34 automatically connect to other peers and participate in routing. It does
35 not have to answer NNCP's online protocol requests at all and just can
36 be some intermediate routing point in the whole mesh network.
38 @cindex yggdrasilc schema
39 @item @command{@ref{nncp-call}}/@command{@ref{nncp-caller}} commands understand
40 @code{yggdrasilc://} addresses, pointing to the desired Yggdrasil's
41 public key (that also acts as the destination host's address). Yggdrasil
42 background goroutine is automatically started, connecting to the
43 specified Yggdrasil entrypoints, calling remote NNCP node and initiating
44 NNCP's native @ref{Sync, online protocol} handshake on top of that.
46 @item @command{@ref{nncp-cfgnew}} is able to generate ed25519 keypair.
48 @item @ref{CfgYggdrasilAliases, Configuration file} optionally contains
49 @code{yggdrasil-aliases} map.
53 How to start using NNCP through that overlay network?
58 Generate ed25519 keypair, that will be used for identification and
59 authentication of your node in Yggdrasil network:
62 $ nncp-cfgnew -yggdrasil
63 Public: 4fd64130e23cf7abdbc0fabdf2ae12bbc2ab7179861efa296d2beb0181ae07ea
64 Private: 571fb05c81e62a572096566fd48e87ad47e706b1f600dd625ebbf86d310332624fd64130e23cf7abdbc0fabdf2ae12bbc2ab7179861efa296d2beb0181ae07ea
67 You should share that public key with other NNCP peers.
70 Start @command{@ref{nncp-daemon}} listening on Yggdrasil's incoming connections.
77 Your private key (generated above). Yggdrasil's @code{PrivateKey} analogue.
80 Optional non-default port you will listen on Yggdrasil's IPv6 address.
84 Optional list of bind addresses, used for peering between the nodes.
85 Yggdrasil's @code{Listen} analogue.
89 Optional list of peer addresses you should connect to.
90 Yggdrasil's @code{Peers} analogue.
92 @vindex AllowedPublicKeys
94 Optional list of allowed peer public keys, allowed for incoming peering
95 connections from. Yggdrasil's @code{AllowedPublicKeys} analogue.
98 Optional list of multicast-related regular expressions to match desired
99 network interfaces where Yggdrasil multicasting must be enabled. Beacon
100 and listening are always enabled on them, but optionally you can specify
101 port you forcefully want to listen on.
106 $ nncp-daemon -yggdrasil "yggdrasils://571f...07ea:6789"\
107 "?bind=tcp://[::1]:1234"\
108 "&bind=tcp://[2001::1]:1234"\
111 "&peer=tcp://example.com:2345"\
112 "&peer=tcp://another.peer:3456%3Fkey=f879...2e9b"\
117 That @code{yggdrasils://} is transformed to following Yggdrasil's
118 configuration analogue:
122 PrivateKey: 571f...07ea
123 Listen: ["tcp://[::1]:1234", "tcp://[2001::1]:1234"]
124 AllowedPublicKeys: ["c6b7...9469", "eb2d...ca07"]
126 tcp://some.peer.be:2345
127 tcp://some.peer.ru:3456?key=f879...2e9b
129 MulticastInterfaces: [
145 Basically you have to specify only private key and either @code{bind} or
146 @code{peer} address. Look for Yggdrasil's documentation for more
147 description of each option and related behaviour.
149 As you can see, private key is in command line arguments, that could be
150 treated as a security issue. That is why it is preferred to specify them
151 in @ref{CfgYggdrasilAliases, configuration}'s @code{yggdrasil-aliases}
152 section, where you can alias all of entities and reference them in
153 @option{-yggdrasil} or @code{yggdrasilc://}-addresses:
158 bindPublic: tcp://[2001::1]:1234
159 bindLocalhost: tcp://[::1]:2345
160 peerBE: tcp://some.peer.be:2345
161 peerRU: tcp://some.peer.ru:3456?key=f879...2e9b
162 somePeerPub1: c6b7...9469
163 somePeerPub2: eb2d...ca07
164 remoteAlicePub: 52be...3c14
169 And now you can more conveniently and safely specify:
172 $ nncp-daemon -yggdrasil "yggdrasils://myprv:6789"\
173 "?bind=bindPublic&bind=bindLocalhost"\
174 "&peer=peerBE&peer=peerRU"\
175 "&pub=somePeerPub1&pub=somePeerPub2"\
176 "&mcast=mcastAll&mcast=lo0"
180 Make calls to that node from another ones, by using
181 @code{yggdrasilc://}-address, similarly:
184 yggdrasilc://PUB[:PORT]?prv=PRV[&peer=PEER][&mcast=REGEX[:PORT]]
187 where @code{PUB} is remote node's public key.
190 $ nncp-call alice "yggdrasilc://remoteAlicePub?prv=myprv&mcast=mcastAll"
195 Per private key Yggdrasil core goroutine is started when first call is
196 initiated and stays until program is finished. You can have multiple
197 Yggdrasil-related private keys and multiple (Yggdrasil) cores will work
198 simultaneously. But running multiple cores for one private key with
199 varying configuration (except for destination public key of course) is