doc/yggdrasil.texi

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