X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=doc%2Fyggdrasil.texi;fp=doc%2Fyggdrasil.texi;h=3d1c73f9dc288e2f386a6813bffcfa3207d08a21;hb=e068d88291cd45a4d6b748e258077dd6c0ffb9c2;hp=0000000000000000000000000000000000000000;hpb=655146e4ee2bde72c9e8daa1361010fefe016df9;p=nncp.git

diff --git a/doc/yggdrasil.texi b/doc/yggdrasil.texi
new file mode 100644
index 0000000..3d1c73f
--- /dev/null
+++ b/doc/yggdrasil.texi
@@ -0,0 +1,122 @@
+@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