doc/yggdrasil.texi

   1 @node Yggdrasil
   2 @cindex yggdrasil
   3 @unnumbered Yggdrasil support
   4
   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
  12 from its public key.
  13
  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.
  26
  27 Only minor modifications were done to current NNCP's tools:
  28
  29 @itemize
  30
  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.
  37
  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.
  45
  46 @item @command{@ref{nncp-cfgnew}} is able to generate ed25519 keypair.
  47
  48 @item @ref{CfgYggdrasilAliases, Configuration file} optionally contains
  49 @code{yggdrasil-aliases} map.
  50
  51 @end itemize
  52
  53 How to start using NNCP through that overlay network?
  54
  55 @enumerate
  56
  57 @item
  58 Generate ed25519 keypair, that will be used for identification and
  59 authentication of your node in Yggdrasil network:
  60
  61 @example
  62 $ nncp-cfgnew -yggdrasil
  63 Public: 4fd64130e23cf7abdbc0fabdf2ae12bbc2ab7179861efa296d2beb0181ae07ea
  64 Private: 571fb05c81e62a572096566fd48e87ad47e706b1f600dd625ebbf86d310332624fd64130e23cf7abdbc0fabdf2ae12bbc2ab7179861efa296d2beb0181ae07ea
  65 @end example
  66
  67 You should share that public key with other NNCP peers.
  68
  69 @item
  70 Start @command{@ref{nncp-daemon}} listening on Yggdrasil's incoming connections.
  71 You have to specify:
  72
  73 @itemize
  74
  75 @vindex PrivateKey
  76 @item
  77 Your private key (generated above). Yggdrasil's @code{PrivateKey} analogue.
  78
  79 @item
  80 Optional non-default port you will listen on Yggdrasil's IPv6 address.
  81
  82 @vindex Listen
  83 @item
  84 Optional list of bind addresses, used for peering between the nodes.
  85 Yggdrasil's @code{Listen} analogue.
  86
  87 @vindex Peers
  88 @item
  89 Optional list of peer addresses you should connect to.
  90 Yggdrasil's @code{Peers} analogue.
  91
  92 @vindex AllowedPublicKeys
  93 @item
  94 Optional list of allowed peer public keys, allowed for incoming peering
  95 connections from. Yggdrasil's @code{AllowedPublicKeys} analogue.
  96
  97 @item
  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.
 102
 103 @end itemize
 104
 105 @example
 106 $ nncp-daemon -yggdrasil "yggdrasils://571f...07ea:6789"\
 107 "?bind=tcp://[::1]:1234"\
 108 "&bind=tcp://[2001::1]:1234"\
 109 "&pub=c6b7...9469"\
 110 "&pub=eb2d...ca07"\
 111 "&peer=tcp://example.com:2345"\
 112 "&peer=tcp://another.peer:3456%3Fkey=f879...2e9b"
 113 "&mcast=.*:5400"
 114 "&mcast=lo0"
 115 @end example
 116
 117 That @code{yggdrasils://} is transformed to following Yggdrasil's
 118 configuration analogue:
 119
 120 @verbatim
 121 {
 122   PrivateKey: 571f...07ea
 123   Listen: ["tcp://[::1]:1234", "tcp://[2001::1]:1234"]
 124   AllowedPublicKeys: ["c6b7...9469", "eb2d...ca07"]
 125   Peers: [
 126     tcp://some.peer.be:2345
 127     tcp://some.peer.ru:3456?key=f879...2e9b
 128   ]
 129   MulticastInterfaces: [
 130     {
 131         Regex: .*
 132         Beacon: true
 133         Listen: true
 134         Port: 5400
 135     }, {
 136         Regex: lo0
 137         Beacon: true
 138         Listen: true
 139         Port: 0
 140     }
 141   ]
 142 }
 143 @end verbatim
 144
 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.
 148
 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:
 154
 155 @verbatim
 156 yggdrasil-aliases: {
 157   myprv: 571f...07ea
 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
 165   mcastAll: .*:5400
 166 }
 167 @end verbatim
 168
 169 And now you can more conveniently and safely specify:
 170
 171 @example
 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"
 177 @end example
 178
 179 @item
 180 Make calls to that node from another ones, by using
 181 @code{yggdrasilc://}-address, similarly:
 182
 183 @example
 184 yggdrasilc://PUB[:PORT]?prv=PRV[&peer=PEER][&mcast=REGEX[:PORT]]
 185 @end example
 186
 187 where @code{PUB} is remote node's public key.
 188
 189 @example
 190 $ nncp-call alice "yggdrasilc://remoteAlicePub?prv=myprv&mcast=mcastAll"
 191 @end example
 192
 193 @end enumerate
 194
 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
 200 not supported.