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 @ref{nncp-daemon} acts as Yggdrasil IPv6 reachable host, listening on
  20 single TCP port. You can reach it using ordinary non-Yggdrasil capable
  21 version of @ref{nncp-call}, calling corresponding 200::/7 IPv6 address
  22 through native Yggdrasil daemon created TUN interface.
  23 @ref{nncp-daemon}, @ref{nncp-call}* can freely peer with Yggdrasil
  24 nodes, reusing existing infrastructure.
  25
  26 Only minor modifications were done to current NNCP's tools:
  27
  28 @itemize
  29
  30 @cindex yggdrasils schema
  31 making it also as a Yggdrasil listener network node. It can
  32 automatically connect to other peers and participate in routing. It does
  33 not have to answer NNCP's online protocol requests at all and just can
  34 be some intermediate routing point in the whole mesh network.
  35
  36 @cindex yggdrasilc schema
  37 @code{yggdrasilc://} addresses, pointing to the desired Yggdrasil's
  38 public key (that also acts as the destination host's address). Yggdrasil
  39 background goroutine is automatically started, connecting to the
  40 specified Yggdrasil entrypoints, calling remote NNCP node and initiating
  41 NNCP's native @ref{Sync, online protocol} handshake on top of that.
  42
  43 @item @ref{nncp-cfgnew} is able to generate ed25519 keypair.
  44
  45 @item @ref{CfgYggdrasilAliases, Configuration file} optionally contains
  46 @code{yggdrasil-aliases} map.
  47
  48 @end itemize
  49
  50 How to start using NNCP through that overlay network?
  51
  52 @enumerate
  53
  54 @item
  55 Generate ed25519 keypair, that will be used for identification and
  56 authentication of your node in Yggdrasil network:
  57
  58 @example
  59 $ nncp-cfgnew -yggdrasil
  60 Public: 4fd64130e23cf7abdbc0fabdf2ae12bbc2ab7179861efa296d2beb0181ae07ea
  61 Private: 571fb05c81e62a572096566fd48e87ad47e706b1f600dd625ebbf86d310332624fd64130e23cf7abdbc0fabdf2ae12bbc2ab7179861efa296d2beb0181ae07ea
  62 @end example
  63
  64 You should share that public key with other NNCP peers.
  65
  66 @item
  67 Start @ref{nncp-daemon} listening on Yggdrasil's incoming connections.
  68 You have to specify:
  69
  70 @itemize
  71
  72 @vindex PrivateKey
  73 @item
  74 Your private key (generated above). Yggdrasil's @code{PrivateKey} analogue.
  75
  76 @item
  77 Optional non-default port you will listen on Yggdrasil's IPv6 address.
  78
  79 @vindex Listen
  80 @item
  81 Optional list of bind addresses, used for peering between the nodes.
  82 Yggdrasil's @code{Listen} analogue.
  83
  84 @vindex Peers
  85 @item
  86 Optional list of peer addresses you should connect to.
  87 Yggdrasil's @code{Peers} analogue.
  88
  89 @vindex AllowedPublicKeys
  90 @item
  91 Optional list of allowed peer public keys, allowed for incoming peering
  92 connections from. Yggdrasil's @code{AllowedPublicKeys} analogue.
  93
  94 @item
  95 Optional list of multicast-related regular expressions to match desired
  96 network interfaces where Yggdrasil multicasting must be enabled. Beacon
  97 and listening are always enabled on them, but optionally you can specify
  98 port you forcefully want to listen on.
  99
 100 @end itemize
 101
 102 @example
 103 $ nncp-daemon -yggdrasil "yggdrasils://571f...07ea:6789"\
 104 "?bind=tcp://[::1]:1234"\
 105 "&bind=tcp://[2001::1]:1234"\
 106 "&pub=c6b7...9469"\
 107 "&pub=eb2d...ca07"\
 108 "&peer=tcp://example.com:2345"\
 109 "&peer=tcp://another.peer:3456%3Fkey=f879...2e9b"
 110 "&mcast=.*:5400"
 111 "&mcast=lo0"
 112 @end example
 113
 114 That @code{yggdrasils://} is transformed to following Yggdrasil's
 115 configuration analogue:
 116
 117 @verbatim
 118 {
 119   PrivateKey: 571f...07ea
 120   Listen: ["tcp://[::1]:1234", "tcp://[2001::1]:1234"]
 121   AllowedPublicKeys: ["c6b7...9469", "eb2d...ca07"]
 122   Peers: [
 123     tcp://some.peer.be:2345
 124     tcp://some.peer.ru:3456?key=f879...2e9b
 125   ]
 126   MulticastInterfaces: [
 127     {
 128         Regex: .*
 129         Beacon: true
 130         Listen: true
 131         Port: 5400
 132     }, {
 133         Regex: lo0
 134         Beacon: true
 135         Listen: true
 136         Port: 0
 137     }
 138   ]
 139 }
 140 @end verbatim
 141
 142 Basically you have to specify only private key and either @code{bind} or
 143 @code{peer} address. Look for Yggdrasil's documentation for more
 144 description of each option and related behaviour.
 145
 146 As you can see, private key is in command line arguments, that could be
 147 treated as a security issue. That is why it is preferred to specify them
 148 in @ref{CfgYggdrasilAliases, configuration}'s @code{yggdrasil-aliases}
 149 section, where you can alias all of entities and reference them in
 150 @option{-yggdrasil} or @code{yggdrasilc://}-addresses:
 151
 152 @verbatim
 153 yggdrasil-aliases: {
 154   myprv: 571f...07ea
 155   bindPublic: tcp://[2001::1]:1234
 156   bindLocalhost: tcp://[::1]:2345
 157   peerBE: tcp://some.peer.be:2345
 158   peerRU: tcp://some.peer.ru:3456?key=f879...2e9b
 159   somePeerPub1: c6b7...9469
 160   somePeerPub2: eb2d...ca07
 161   remoteAlicePub: 52be...3c14
 162   mcastAll: .*:5400
 163 }
 164 @end verbatim
 165
 166 And now you can more conveniently and safely specify:
 167
 168 @example
 169 $ nncp-daemon -yggdrasil "yggdrasils://myprv:6789"\
 170 "?bind=bindPublic&bind=bindLocalhost"\
 171 "&peer=peerBE&peer=peerRU"\
 172 "&pub=somePeerPub1&pub=somePeerPub2"\
 173 "&mcast=mcastAll&mcast=lo0"
 174 @end example
 175
 176 @item
 177 Make calls to that node from another ones, by using
 178 @code{yggdrasilc://}-address, similarly:
 179
 180 @example
 181 yggdrasilc://PUB[:PORT]?prv=PRV[&peer=PEER][&mcast=REGEX[:PORT]]
 182 @end example
 183
 184 where @code{PUB} is remote node's public key.
 185
 186 @example
 187 $ nncp-call alice "yggdrasilc://remoteAlicePub?prv=myprv&mcast=mcastAll"
 188 @end example
 189
 190 @end enumerate
 191
 192 Per private key Yggdrasil core goroutine is started when first call is
 193 initiated and stays until program is finished. You can have multiple
 194 Yggdrasil-related private keys and multiple (Yggdrasil) cores will work
 195 simultaneously. But running multiple cores for one private key with
 196 varying configuration (except for destination public key of course) is
 197 not supported.