--- /dev/null
+@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{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;[::]:1234,[::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: [::]:1234
+ bindLocalhost: [::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