@node Yggdrasil
@unnumbered Yggdrasil support

NNCP is able to act itself as a client to
@url{https://yggdrasil-network.github.io/, Yggdrasil} overlay network.
Current IPv6 adoption for @strong{home} users is relatively bad in many
countries. That is why Yggdrasil overlay network uses dynamic spanning
tree mesh network for packets routing, making it useful for gaining
hosts high availability reachability without complex manual manipulations.
By default it creates 200::/7 IPv6 network, where each host's address is
derived from the corresponding public key.

NNCP's Yggdrasil support is fully based on and resembles the idea taken
from @url{https://github.com/neilalexander/yggmail, yggmail} software,
that does not use Yggdrasil's full-featured IP tunnelling capabilities,
but rather uses it only as a generic packet transmission network,
greatly simplifying the whole setup, without necessity to setup separate
networking interface and operating system's routing tables with firewall.
@url{http://bittorrent.org/beps/bep_0029.html, μTP} transport protocol
is used over Yggdrasil's packet interface -- it is relatively simple and
efficient enough.

No separate explicit Yggdrasil daemon installation is necessary, however
you should be able to interoperate with it too, using for example as an
entry point to the global Yggdrasil network. You can reuse already
existing Yggdrasil network, without colliding with its IP tunnelling
features.

Only minor modifications were done to current NNCP's tools:

@itemize

@item @ref{nncp-daemon} has @option{-yggdrasil} option, making it acting
as a Yggdrasil listener network node. It can automatically connect to
other peers and participate in routing. It does not have to answer
NNCP's online protocol requests at all and just can be some intermediate
routing point in the whole mesh network.

@item @ref{nncp-call}/@ref{nncp-caller} commands understand
@code{yggdrasil:} addresses, pointing to the desired Yggdrasil's public
key (that also acts as the destination host's address). Yggdrasil
background goroutine is automatically started, connecting to the
specified Yggdrasil entrypoints and making μTP connection with the hosts
and initiating NNCP's native @ref{Sync, online protocol} handshake on
top of that.

@item @ref{nncp-cfgnew} is able to generate ed25519 keypair.

@item @ref{CfgYggdrasilAliases, Configuration file} optionally contains
@code{yggdrasil-aliases} map.

@end itemize

How to start using NNCP through that overlay network?

@enumerate

@item
Generate ed25519 keypair, that will be used for identification and
authentication of your node in Yggdrasil network:

@example
$ nncp-cfgnew -yggdrasil
Public: 4fd64130e23cf7abdbc0fabdf2ae12bbc2ab7179861efa296d2beb0181ae07ea
Private: 571fb05c81e62a572096566fd48e87ad47e706b1f600dd625ebbf86d310332624fd64130e23cf7abdbc0fabdf2ae12bbc2ab7179861efa296d2beb0181ae07ea
@end example

You should share your public key with other NNCP peers.

@item
Start @ref{nncp-daemon} listening on Yggdrasil's incoming connections.
You have to specify the private key (generated above), list of bind
addresses for incoming Yggdrasil's TCP connections, optional list of
allowed incoming connections, identified by a public key, and optionally
a list of another similar listening peers, through which you can route
and discover packets to the other nodes. @option{-yggdrasil} option
takes that information in form of:
@code{PRV;BIND[,...];[PUB,...];[PEER,...]}, where
@code{BIND}/@code{PEER} is in Yggdrasil's URL format, like
@code{tcp://HOST:PORT} or @code{tcp://HOST:PORT?key=PUBKEY}.

@example
$ nncp-daemon -yggdrasil "571f...07ea;tcp://[::]:1234,tcp://[::1]:2345;;tcp://some.peer?key=ITSPUBKEY"
@end example

Here we did not specify any allowable public key -- anyone can connect
to us and route packets through. As you can see, private key is in
command line arguments, that could be treated as a security issue. That
is why it is preferred to specify them in
@ref{CfgYggdrasilAliases, configuration}'s @code{yggdrasil-aliases}
section, where you can alias all of entities and reference them in
@option{-yggdrasil} or @code{yggdrasil:}-addresses:

@verbatim
yggdrasil-aliases: {
  myprv: 571f...07ea
  bindPublic: tcp://[::]:1234
  bindLocalhost: tcp://[::1]:2345
  peerBE: tcp://some.peer.be?key=BEPUBKEY
  peerRU: tcp://some.peer.ru?key=RUPUBKEY
  defPeers: peerBE,peerRU
  remoteAlicePub: 52be...3c14
}
@end verbatim

And now you can more conveniently and safely specify:

@example
$ nncp-daemon -yggdrasil "myprv;bindPublic,bindLocalhost;;defPeers"
@end example

@item
Make calls to that node from another ones, by using
@code{yggdrasil:}-address, that takes remote host's public key, our
host's private key and list of Yggdrasil peers entrypoints. Similarly to
@option{-yggdrasil} option, it is ";"-separated list too:

@example
$ nncp-call alice "yggdrasil:remoteAlicePub;myprv;bindLocalhost,tcp://some.other.entrypoint"
@end example

@end enumerate