doc/yggdrasil.texi

   1 @node Yggdrasil
   2 @unnumbered Yggdrasil support
   3
   4 NNCP is able to act itself as a client to
   5 @url{https://yggdrasil-network.github.io/, Yggdrasil} overlay network.
   6 Current IPv6 adoption for @strong{home} users is relatively bad in many
   7 countries. That is why Yggdrasil overlay network uses dynamic spanning
   8 tree mesh network for packets routing, making it useful for gaining
   9 hosts high availability reachability without complex manual manipulations.
  10 By default it creates 200::/7 IPv6 network, where each host's address is
  11 derived from the corresponding public key.
  12
  13 NNCP's Yggdrasil support is fully based on and resembles the idea taken
  14 from @url{https://github.com/neilalexander/yggmail, yggmail} software,
  15 that does not use Yggdrasil's full-featured IP tunnelling capabilities,
  16 but rather uses it only as a generic packet transmission network,
  17 greatly simplifying the whole setup, without necessity to setup separate
  18 networking interface and operating system's routing tables with firewall.
  19 @url{http://bittorrent.org/beps/bep_0029.html, μTP} transport protocol
  20 is used over Yggdrasil's packet interface -- it is relatively simple and
  21 efficient enough.
  22
  23 No separate explicit Yggdrasil daemon installation is necessary, however
  24 you should be able to interoperate with it too, using for example as an
  25 entry point to the global Yggdrasil network. You can reuse already
  26 existing Yggdrasil network, without colliding with its IP tunnelling
  27 features.
  28
  29 Only minor modifications were done to current NNCP's tools:
  30
  31 @itemize
  32
  33 @item @ref{nncp-daemon} has @option{-yggdrasil} option, making it acting
  34 as a Yggdrasil listener network node. It can automatically connect to
  35 other peers and participate in routing. It does not have to answer
  36 NNCP's online protocol requests at all and just can be some intermediate
  37 routing point in the whole mesh network.
  38
  39 @item @ref{nncp-call}/@ref{nncp-caller} commands understand
  40 @code{yggdrasil:} addresses, pointing to the desired Yggdrasil's public
  41 key (that also acts as the destination host's address). Yggdrasil
  42 background goroutine is automatically started, connecting to the
  43 specified Yggdrasil entrypoints and making μTP connection with the hosts
  44 and initiating NNCP's native @ref{Sync, online protocol} handshake on
  45 top of that.
  46
  47 @item @ref{nncp-cfgnew} is able to generate ed25519 keypair.
  48
  49 @item @ref{CfgYggdrasilAliases, Configuration file} optionally contains
  50 @code{yggdrasil-aliases} map.
  51
  52 @end itemize
  53
  54 How to start using NNCP through that overlay network?
  55
  56 @enumerate
  57
  58 @item
  59 Generate ed25519 keypair, that will be used for identification and
  60 authentication of your node in Yggdrasil network:
  61
  62 @example
  63 $ nncp-cfgnew -yggdrasil
  64 Public: 4fd64130e23cf7abdbc0fabdf2ae12bbc2ab7179861efa296d2beb0181ae07ea
  65 Private: 571fb05c81e62a572096566fd48e87ad47e706b1f600dd625ebbf86d310332624fd64130e23cf7abdbc0fabdf2ae12bbc2ab7179861efa296d2beb0181ae07ea
  66 @end example
  67
  68 You should share your public key with other NNCP peers.
  69
  70 @item
  71 Start @ref{nncp-daemon} listening on Yggdrasil's incoming connections.
  72 You have to specify the private key (generated above), list of bind
  73 addresses for incoming Yggdrasil's TCP connections, optional list of
  74 allowed incoming connections, identified by a public key, and optionally
  75 a list of another similar listening peers, through which you can route
  76 and discover packets to the other nodes. @option{-yggdrasil} option
  77 takes that information in form of:
  78 @code{PRV;BIND[,...];[PUB,...];[PEER,...]}, where
  79 @code{BIND}/@code{PEER} is in Yggdrasil's URL format, like
  80 @code{tcp://HOST:PORT} or @code{tcp://HOST:PORT?key=PUBKEY}.
  81
  82 @example
  83 $ nncp-daemon -yggdrasil "571f...07ea;tcp://[::]:1234,tcp://[::1]:2345;;tcp://some.peer?key=ITSPUBKEY"
  84 @end example
  85
  86 Here we did not specify any allowable public key -- anyone can connect
  87 to us and route packets through. As you can see, private key is in
  88 command line arguments, that could be treated as a security issue. That
  89 is why it is preferred to specify them in
  90 @ref{CfgYggdrasilAliases, configuration}'s @code{yggdrasil-aliases}
  91 section, where you can alias all of entities and reference them in
  92 @option{-yggdrasil} or @code{yggdrasil:}-addresses:
  93
  94 @verbatim
  95 yggdrasil-aliases: {
  96   myprv: 571f...07ea
  97   bindPublic: tcp://[::]:1234
  98   bindLocalhost: tcp://[::1]:2345
  99   peerBE: tcp://some.peer.be?key=BEPUBKEY
 100   peerRU: tcp://some.peer.ru?key=RUPUBKEY
 101   defPeers: peerBE,peerRU
 102   remoteAlicePub: 52be...3c14
 103 }
 104 @end verbatim
 105
 106 And now you can more conveniently and safely specify:
 107
 108 @example
 109 $ nncp-daemon -yggdrasil "myprv;bindPublic,bindLocalhost;;defPeers"
 110 @end example
 111
 112 @item
 113 Make calls to that node from another ones, by using
 114 @code{yggdrasil:}-address, that takes remote host's public key, our
 115 host's private key and list of Yggdrasil peers entrypoints. Similarly to
 116 @option{-yggdrasil} option, it is ";"-separated list too:
 117
 118 @example
 119 $ nncp-call alice "yggdrasil:remoteAlicePub;myprv;bindLocalhost,tcp://some.other.entrypoint"
 120 @end example
 121
 122 @end enumerate