diff --git a/about.md b/about.md index a92ea41..74a1334 100644 --- a/about.md +++ b/about.md @@ -46,7 +46,8 @@ The result is that each node has a set of [coordinates in a greedy metric space] These coordinates are used as a distance label. Given the coordinates of any two nodes, it is possible to calculate the length of some real path through the network between the two nodes. Traffic is forwarded using a [greedy routing](https://en.wikipedia.org/wiki/Small-world_routing#Greedy_routing) scheme, where each node forwards the packet to a one-hop neighbor that is closer to the destination (according to this distance metric) than the current node. -In particular, nodes try to maximize: ` / `, where the denominator is equal to 1 (from the link from the current node to the next hop) + the expected distance from the next hop to the destination (from the [metric space](https://en.wikipedia.org/wiki/Metric_space)). +In particular, nodes try to minimize: ` + `, where the first term based on the distance in the greedy [metric space](https://en.wikipedia.org/wiki/Metric_space) used by the network, and must be strictly less than the distance from the current node to the destination. +The second term acts as a kind of (local) backpressure to route around congestion in some scenarios, particularly when there are multiple interfaces through which the same neighbor can be reached (e.g. ad-hoc wifi and a physical ethernet cable). ### Spanning Tree @@ -64,7 +65,8 @@ The implementation chooses to set the sequence number equal to the unix time on Other than the root node, every other node in the network must select one of its neighbors to use as their parent. This selection is done by maximizing: ` / `. -The `uptime` in this definition is equal to the time that a neighbor has been advertising *the same* coords for a node. +Here, `uptime` is the time between when we first and last received a message from the node, and timeout is the time we wait before dropping a root due to inactivity. +This essentially means the numerator is at least as long as the amount of time between when the neighbor was first seen and when the advertisement from the neighbor becomes invalid due to root timeout. The distance metric between nodes is simply the distance between the nodes if they routed on the spanning tree. This is equal to the sum of the distance from each node to the last common ancestor of the two nodes being compared. @@ -79,13 +81,13 @@ The DHT is Kademlia-like in that it uses the `xor` metric and structures the has It differs from kademlia in that there are no values in the key:value store--it only stores information about DHT peers. Furthermore, the network bootstraps by adding one-hop neighbors to the DHT, and (for subtle reasons) this strategy does not behave the same as bootstrapping off of a dedicated node. To bootstrap successfully, when a bucket is full, old nodes (the least recently pinged) are removed to make room for new nodes. -For a combination of performance and testing reasons, the usual iterative-parallel lookups are not used for searches in the DHT, and a recursive-serial approach is taken instead (similar to e.g. some implementations of [Chord](https://en.wikipedia.org/wiki/Chord_(DHT))). To summarize the entire procedure, given only a node's IP address, the goal is to find a route to the destination. That happens through 3 steps: 1. The address is unpacked into the known bits of a NodeID and a bitmask to signal which bits of the NodeID are known (the unknown bits are ignored). -2. A DHT search is performed, which normally results in a response from the node closest in the DHT keyspace to the target NodeID. The response contains the node's curve25519 key, which is checked to match the NodeID (and therefore the address), as well as the node's coordinates. Incorrect responses are ignored. +2. A DHT search is performed, which normally results in a response from the node closest in the DHT keyspace to the target NodeID. The response contains the node's curve25519 key, which is checked to match the NodeID (and therefore the address), as well as the node's coordinates. +The NodeID is checked to make sure it matches the target IPv6 address. 3. Using the keys and coords from the above step, an ephemeral key exchange occurs between the source and destination nodes. These ephemeral session keys are used to encrypt any ordinary IPv6 traffic that may be encapsulated and sent between the nodes. ## Project Status and Plans diff --git a/configuration.md b/configuration.md index 016930e..6148b55 100644 --- a/configuration.md +++ b/configuration.md @@ -21,7 +21,7 @@ A new configuration file may be generated with `yggdrasil --genconf > path/to/co # List of connection strings for static peers (i.e. tcp://a.b.c.d:e) Peers: [] - # List of peer BoxPubs to allow UDP incoming TCP connections from + # List of peer BoxPubs to allow incoming connections from # (if left empty/undefined then connections will be allowed by default) AllowedBoxPubs: [] @@ -81,7 +81,7 @@ Note that any field not specified in the configuration will use its default valu ## Configuration Options - `Listen` - - A string, in the form of `"ip:port"`, on which to listen for connections from peers (both TCP and UDP). + - A string, in the form of `"ip:port"`, on which to listen for (TCP) connections from peers. - Note that, due to Go language design choices, `[::]` listens on IPv4 and IPv6 on most platforms, while an empty IP or `0.0.0.0` listens only to IPv4. - The default is to listen on all addresses (`[::]`) with a random port. - `AdminListen` @@ -91,11 +91,11 @@ Note that any field not specified in the configuration will use its default valu - `Peers` - A list of strings in the form `["peerAddress:peerPort", "peerAddress:peerPort", ...]` of peers to connect to. - Peer hostnames can be specified either using IPv4 addresses, IPv6 addresses or DNS names. - - Each entry may optionally begin with `tcp://`, `udp://` or `socks://proxyAddress:proxyPort/` to manually force a connection over a specific protocol. + - Each entry may optionally begin with `tcp://` or `socks://proxyAddress:proxyPort/` to manually force a connection over a specific protocol. - If unspecified, the default is to connect over TCP. - `AllowedBoxPubs` - A list of strings in the form `["boxpub", "boxpub", ...]`, where `boxpub` is each node's `BoxPub` key which you would like to allow connections from. - - This option allows you to restrict which other nodes can connect to your Yggdrasil node as a peer. It applies to incoming TCP connections and both incoming and outgoing UDP connections. + - This option allows you to restrict which other nodes can connect to your Yggdrasil node as a peer. It applies to incoming TCP connections. - If the list is left empty, or the option is not specified, then Yggdrasil will automatically accept connections from any other node. - Note that multicast link-local peerings (see below) will always override this option if enabled. - `BoxPub` @@ -138,11 +138,6 @@ Note that any field not specified in the configuration will use its default valu - The MTU of the `tun`/`tap` interface. - Defaults to the maximum value supported on each platform, up to `65535` on Linux/macOS/Windows, `32767` on FreeBSD, `16384` on OpenBSD, `9000` on NetBSD, etc. - Yggdrasil automatically assists in Path MTU Discovery (PMTU) and will limit the MTU of a given connection between two hosts to the lower of the MTUs used by each endpoint. The operating system is made aware of these MTUs using ICMP. - - If traffic is routed over UDP links, PMTU may be further reduced to prevent unnecessary packet fragmentation. -- `Net` - - Additional configuration options for overlay networks (Tor, I2P). - - Still under development. - - Note that a `socks` connection should be sufficient to use any network which is reachable over a SOCKS proxy. # Use Cases @@ -150,13 +145,11 @@ Note that any field not specified in the configuration will use its default valu By default, only link-local auto-peering is enabled. This connects devices that are connected directly to each other at layer 2, including devices on the same LAN, directly connected by ethernet or configured to use the same ad-hoc wireless network. -As the network uses ordinary TCP and UDP, it is possible to connect over other networks, such as the Internet or WAN links, provided that the connecting node knows the address and port to connect to and that the connection is not blocked by a NAT or firewall. If the node resides behind a NAT, then port forwarding may be required in order to accept incoming connections. +As the network uses ordinary TCP, it is possible to connect over other networks, such as the Internet or WAN links, provided that the connecting node knows the address and port to connect to and that the connection is not blocked by a NAT or firewall. If the node resides behind a NAT, then port forwarding may be required in order to accept incoming connections. -By default, connections to peers are made over TCP. This tends to have lower CPU usage than connecting over UDP, which leads to higher bandwidth on CPU-constrained single-board computers (i.e. Raspberry Pi). UDP connections can be made by specifying `udp://` in the connection string. These tend to require more CPU, due to lower PMTU, but otherwise mostly works the same. - -If two nodes that want to connect are both stuck behind NATs, then it should generally be possible to punch a hole through the NAT if each node specifies a `udp://` connection to the other. - -As a last resort, it is possible to route through a `socks://proxyAddr:proxyPort:/` connection. This uses TCP over the specified SOCKS proxy, and can be used to tunnel out from a network with a particularly restrictive firewall, for example, using SSH tunnelling. This can also be used to connect over Tor, particularly for `.onion` hidden service addresses. +By default, connections to peers are made over TCP. It is possible to route through a `socks://proxyAddr:proxyPort/` connection. +This uses TCP over the specified SOCKS proxy, and can be used to tunnel out from a network with a particularly restrictive firewall, for example, using SSH tunneling. +This can also be used to [connect over Tor](https://github.com/yggdrasil-network/public-peers/blob/master/other/tor.md), particularly for `.onion` hidden service addresses. If you are unable to find nodes in the nearby area, a best effort is made to maintain a list of [Public Peers](https://github.com/yggdrasil-network/public-peers) for new users looking to join or test the network. @@ -204,9 +197,9 @@ This can partially mitigate the fact that IPv6 addresses are only 128 bits long, In short, if you plan to advertise a prefix, or if you want your address to be exceptionally difficult to collide with, then it is strongly advised that you burn some CPU cycles generating a harder-to-collide set of keys, using the following tool: ``` -GOPATH=$PWD go run misc/genkeys.go +GOPATH=$PWD go run -tags debug misc/genkeys.go ``` This continually generates new keys and prints them out each time a new best set of keys is discovered. -These keys must then be manually added to the configuration file. +These keys may then be manually added to the configuration file. diff --git a/platform-edgerouter.md b/platform-edgerouter.md index 019490a..e39e3b5 100644 --- a/platform-edgerouter.md +++ b/platform-edgerouter.md @@ -31,7 +31,7 @@ At this point, Yggdrasil will start running using default configuration, which i ## Add peers -Add additional peers to your configuration (using `tcp://` or `udp://`): +Add additional peers to your configuration (using `tcp://` or `socks://`): ``` configure set interfaces yggdrasil tunX peers tcp://hostname.com:12345