cwinfo/yggdrasil-network.github.io
5
0
Fork 0
mirror of https://github.com/cwinfo/yggdrasil-network.github.io.git synced 2024-09-08 00:24:33 +00:00
Code Releases Activity

Website updates (#202)

Browse Source 
* Start rewriting about page

* Various further updates

* Update index.md

* Mention source routing, remove other section
This commit is contained in:
Neil Alexander 2022-02-08 09:05:55 +00:00 committed by GitHub
parent 14083e131a
commit ba84341fa5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 77 additions and 150 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
about.md
View File

@ -4,137 +4,65 @@ sitemap: true
# About
Yggdrasil is a proof-of-concept to explore a wholly different approach to
network routing. Whereas current computer networks depend heavily on very
centralised design and configuration, Yggdrasil breaks this mould by making use
of a global spanning tree to form a scalable IPv6 encrypted mesh network.
Yggdrasil is an experimental implementation of a new routing scheme designed for mesh or even Internet-like networks. The current implementation is built as an overlay network, where network nodes are userspace software routers, connected together using virtual peerings over local area networks, point-to-point links or the Internet.
The following table illustrates high-level differences between traditional
networks like the internet, and the Yggdrasil network:
Compared to the structured and typically hierarchial routing schemes in use today on many networks, Yggdrasil is strongly decentralised and largely self-arranging. Each node on the network is identified by a cryptographic public key and IPv6 addresses are generated from this key. The network topology is adaptive, aiming to make use of whichever links are available in order to provide full routability between all network participants. This is made possible by the fact that all Yggdrasil nodes are routers, sharing routing knowledge and forwarding traffic on behalf of other network participants.
In order to ensure that traffic is private as it is routed across other network nodes, all traffic is end-to-end encrypted at all times. Even plain-text application traffic is encrypted in transit, ensuring that intermediate nodes cannot read traffic as it is forwarded through the network.
The following table illustrates high-level differences between traditional networks like the Internet, and the Yggdrasil Network:
| | Traditional | Yggdrasil |
| --------------------------------------------------------------- | ----------- | --------- |
| End-to-end encryption for all traffic across the network | No | Yes |
| Decentralised routing information shared using a DHT | No | Yes |
| Cryptographically-bound IPv6 addresses | No | Yes |
| Cryptographically-bound addressing with no central authority | No | Yes |
| Node is aware of its relative location to other nodes | No | Yes |
| IPv6 address remains with the device even if moved | No | Yes |
| Mobile addressing that stays with the device as it moves around | No | Yes |
| Topology extends gracefully across different mediums, i.e. mesh | No | Yes |
### What are the problems today?
The internet as we know it today doesn't conform to a well-defined topology.
This has largely happened over time - as the internet has grown, more and more
networks have been "bolted together". The lack of defined topology gives us some
unavoidable problems:
The internet as we know it today doesn't conform to a well-defined topology. This has largely happened over time - as the internet has grown, more and more networks have been "bolted together" with peering arrangements between service providers. The lack of defined topology gives us some unavoidable problems:
1. The routing tables that hold a "map" of the internet are huge and inefficient
1. There isn't really any way for a computer to know where it is located on the
internet relative to anything else
1. It's difficult to examine where a packet will go on its journey from source
to destination without actually sending it
1. It's very difficult to install reliable networks into locations that change
often or are non-static, i.e. wireless mesh networks
1. The routing tables that hold a "map" of the internet are huge and inefficient, as every provider has to relay information about IP prefixes belonging to all other providers
1. There isn't really any way for a computer to know where it is located on the internet relative to anything else — most machines are only aware of a "default gateway"
1. It's difficult to examine where a packet will go on its journey from source to destination without actually sending it
These problems have been partially mitigated (but not really
solved) through centralisation - rather than your computers at home holding a
copy of the global routing table, your ISP does it for you. Your computers and
network devices are configured just to "send it upstream" and to let your ISP
decide where it goes from there, but this does leave you entirely at the mercy
of your ISP who can redirect your traffic anywhere they like and to inspect,
manipulate or intercept it.
These problems have been somewhat mitigated (but not really solved) through centralisation - rather than your computers at home holding a copy of the global routing table, your service provider does so on your behalf. Your computers and network devices are configured just to "send traffic upstream" and to let your provider decide where it goes from there. This leaves you entirely at the mercy of your ISP who can redirect your traffic anywhere they like and to inspect, manipulate or intercept it.
In addition, wireless meshing requires you to know a lot about the network
around you, which would not typically be the case when you have outsourced this
knowledge to your ISP. Many existing wireless mesh routing schemes are not
scalable or efficient, and do not bridge well with existing networks.
ISP networks are also typically structured in design and often hierarchical in nature, and as a result, many existing routing protocols have been designed with this in mind. Some optimisations such as prefix aggregation are used to try and reduce the number of routing entries that a provider must send out into the world. These protocols are usually not suitable for use in a network where the topology is not well defined or changes frequently — a wireless mesh network, for example, therefore it has been very difficult in the past for communities to build their own wireless mesh infrastructure on an ad-hoc basis.
### What does Yggdrasil do differently?
Yggdrasil takes a very different approach. Rather than just accepting that the
internet is a sprawling conglomeration of unstructured networks connected
together in an unstructured fashion, we instead arrange the routing scheme of
the entire network into a global spanning tree.
Yggdrasil takes a very different approach to sharing routing knowledge. Rather than distributing address ranges as paths through centrally assigned autonomous systems, Yggdrasil instead builds up a single global network topology.
A spanning tree has the following properties:
A spanning tree is used to provide synchronisation and to allow nodes to allocate themselves a set of tree coordinates, which are used to exchange and establish bootstrap and path setup messages. Nodes then set up paths through the network to their keyspace neighbours, effectively arranging the network into a virtual line, ordered by public keys. Intermediate nodes then populate their routing tables with these paths, enabling nodes to forward packets closer to their destination public key.
1. There is always a single "root" node at the "top" of the tree
1. Every other node in the spanning tree has:
- Exactly one parent
- One or more children
1. Every node is connected to at least one other node
In addition, nodes can pathfind using the spanning tree routing to establish a path that is likely shorter than the path through keyspace and then switch a traffic session over to source routing. The typically more direct source route will continue to be used for as long as it is available and will fall back to keyspace routing if the source routed path breaks.
By arranging every device in such a way that they all agree on the same global
spanning tree, we can do some things that we previously couldn't do before:
1. We can assign a "locator" to a device, effectively a path from the root of
the tree downwards
1. We can determine where our destination is on the tree up front relative to
the source
1. We always have a single worst-case-scenario path to every node by
"walking the tree"
1. We have the ability to infer a number of possible routes (both direct and
indirect) from the structure of the tree, and even take "shortcuts"
1. We can spread out information about the tree itself across nodes and not need
to store it all centrally
By using a distributed hash table (DHT) to share routing information, this
allows any single device on the network to find out enough information to route
to another node, without depending on centralised infrastructure.
Cryptographic signatures are used when exchanging routing information between
peers, such that the network can agree on the same candidate to be the global
root and to lay out the coordinates of each node beneath it.
Cryptographic signatures are used to secure tree announcements, bootstrap and path messages against tampering or forgery.
### What are the benefits?
It should be efficient for the following reasons:
There are a number of benefits to a routing scheme such as this:
1. It lets every device on the network make the same assumptions about the
topology of the network
1. The use of locators for sending traffic across the network simplifies the
switching layer, as forwarding does not require nodes to maintain state tables
of anything beyond their own peers
1. All route determination is automatic - no manual configuration of routes is
required
1. Devices don't need to store lots of information about the topology of the
network - in fact, storing information about only a small number of nodes is
usually enough to reach the entire network
1. We can bridge reliable/static networks very easily with dynamic/non-static
networks without flooding large amounts of routing information between different
areas (i.e. point-to-point or mesh wireless networks)
1. The network responds gracefully to changes in topology without intervention,
and networks can even join and split without interrupting connectivity between
local nodes
We believe that Yggdrasil should be able to scale to very large networks as a
result.
1. Devices need to only maintain a comparatively small amount of state in order to function and to be able to forward packets — there is no need for any Yggdrasil node to maintain "full routing tables" like in BGP, and most nodes only have a handful of routing table entries in total
1. Paths are discovered and built through the network automatically, so manual configuration of routing entries is not required — the only configuration needed is the peering connections between nodes themselves
1. The network can setup and tear down paths quickly without needing to discard all routing state, which helps significantly in handling node mobility events without dropping many packets if at all
1. We can bridge reliable/static networks very easily with dynamic/non-static networks without needing to flood large amounts of state
1. Networks automatically form when any two or more Yggdrasil nodes are connected to each other, even if those connections are entirely ad-hoc in nature
1. Sparse routing knowledge and only small amounts of protocol traffic should mean that Yggdrasil is able to efficiently scale to very large networks
### What is the status of the project?
Yggdrasil is currently an alpha project, early in development but actively
maintained. Our expectation is that a future “beta” quality release should know
enough to be compatible in the face of wire format changes, and reasonably
feature complete. A “stable” 1.0 release, if it ever happens, would probably be
feature complete, with no expectation of future wire format changes, and free of
known critical bugs.
Yggdrasil is currently an alpha project, early in development but actively maintained. Our expectation is that a future “beta” quality release should know enough to be compatible in the face of wire format changes, and reasonably feature complete. A “stable” 1.0 release, if it ever happens, would probably be feature complete, with no expectation of future wire format changes, and free of known critical bugs.
The true goal of this project is to test the scalability of the Yggdrasil
routing scheme, therefore it needs as many participants to run and test the
software as possible so that we can study the behaviour of the network as it
grows. We've done our best to support [as many platforms as possible](installation.md)
and have a number of [public peers](https://github.com/yggdrasil-network/public-peers)
that you can connect to in order to join the network, so please feel free to
experiment.
The true goal of this project is to test the scalability of the Yggdrasil routing scheme, therefore it needs as many participants to run and test the software as possible so that we can study the behaviour of the network as it grows. We've done our best to support [as many platforms as possible](installation.md) and have a number of [public peers](https://github.com/yggdrasil-network/public-peers) that you can connect to in order to join the network, so please feel free to experiment. That said, we don't recommend running mission critical or life-or-death workloads over Yggdrasil yet — there may be failure modes that we don't yet know about.
The project is likely to reach a number of possible outcomes:
1. The project may reach a reasonably stable state but never attract a large
enough number of users
1. The project may attract a large enough number of users but reveal inherent
design flaws in the process (a learning exercise for a future project perhaps)
1. The project may end up working perfectly even as the network grows, in which
case it will become worthwhile to look at writing better-optimised
implementations and/or moving the important parts into other projects (like
[cjdns](https://github.com/cjdelisle/cjdns))
1. The project may reach a reasonably stable state but never attract a large enough number of users
1. The project may attract a large enough number of users but reveal inherent design flaws in the process (a learning exercise for a future project or protocol version perhaps)
1. The project may end up working perfectly even as the network grows, in which case it will become worthwhile to look at writing better-optimised implementations and/or moving the important parts into other projects

91
faq.md
View File

@ -16,34 +16,62 @@ Our official stance is that it is still alpha software. Expect things to not be
It is not a goal of the Yggdrasil project to provide anonymity. Your direct peers may be able to determine your location if, for example, you are peering over the Internet.
### Will my machine be exposed to other users of the network?
Typically yes, you will be routable from other nodes on the network. If you want to restrict incoming connections to your machine, you should use an IPv6 firewall. The steps for this will vary from platform to platform.
#### Linux (with `ip6tables`)
Assuming your TUN/TAP adapter is named `tun0`:
```
ip6tables -A INPUT -i tun0 -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
ip6tables -A INPUT -i tun0 -m conntrack --ctstate INVALID -j DROP
ip6tables -A INPUT -i tun0 -j DROP
```
#### Windows (with Windows Firewall)
Windows, by default, should classify the TAP adapter as a "Public Network". Configure Windows Firewall to prevent incoming connections on Public networks.
#### macOS (with built-in firewall)
macOS has an application firewall, therefore any firewall policies applied on other interfaces will also apply to the Yggdrasil interface.
### Can I run an Yggdrasil router without a TUN interface?
Yes, you can set the `IfName` configuration setting to `"none"`. This will prevent Yggdrasil from creating a TUN interface.
You will be able to create and accept peering connections and will continue to route traffic on behalf of your peers, but you will not be reachable from within the Yggdrasil Network, nor will you be able to send traffic into the network either. In this mode, other users on the network will receive no response if they try to reach or ping your node addresses.
### Does Yggdrasil require IPv6?
Your system must be IPv6-capable, which just about all modern operating systems are.
Your system must be IPv6-enabled in order to send or receive traffic to/from the Yggdrasil Network, which just about all modern operating systems are.
While Yggdrasil does transport only IPv6 traffic internally, you do not need an IPv6 internet connection to peer with other Yggdrasil users. You can peer with other Yggdrasil nodes over either IPv4 or IPv6.
### Will my node route traffic on behalf of other nodes?
If you have peerings to more than one node, your node can potentially route traffic on behalf of other network users. If you have only peerings to a single node, you will typically not route traffic, although you may still handle some occasional protocol messages. Keep this in mind if you are restricted by data usage caps.
### Will Yggdrasil conflict with my network routing?
Yggdrasil uses the `0200::/7` range, which is a range deprecated by the IETF. It has been deprecated since 2004, pending changes to an RFC which simply never materialised 14 years later. It was decided to use this range instead of `fc00::/7` (which is more typically allocated to private networks) in order to prevent conflicts with existing ULA ranges.
Yggdrasil uses the `0200::/7` range, which is a range deprecated by the IETF. It has been deprecated since 2004, pending changes to an RFC which simply never materialised all these years later. It was decided to use this range instead of `fc00::/7` (which is more typically allocated to private networks) in order to prevent conflicts with existing ULA ranges.
As long as you are not using this deprecated address range on your network, you will not experience any routing conflicts.
### Can the network be crawled?
Currently it is possible to crawl the network to reveal the spanning tree relationships by querying nodes in the DHT. This is how the [network map](http://51.15.204.214) and popularity contest are generated today. However, it is considered a design weakness that this is even possible currently and will hopefully be fixed in the future.
### Can I run a crawler?
Please don't run your own network crawler. Crawlers generate a lot of network-wide protocol traffic and effect is amplified by each additional crawler. If you really really *really* want information about the network today, use an [existing data source within the network](http://[301:4541:2f84:1188:216:3eff:feb6:65a3]:3001/nodeinfo.json) instead of crawling yourself.
Currently it is possible to crawl the network by querying the debug query handlers of remote nodes. This is how the [network map](http://51.15.204.214) and popularity contest are generated today, allowing us to observe how the network scales. However, these endpoints are not required for the network to operate and will definitely be removed in a future version — certainly before a potential version 1.0 release.
### I've just installed Yggdrasil and I can't ping anyone. What have I missed?
Yggdrasil requires that you configure either a static peer to another Yggdrasil node, or that you discover another Yggdrasil node *on the same subnet* using multicast discovery (which is enabled by default). If you have not added or discovered any peers, you will not be able to reach beyond your own node.
Yggdrasil requires that you configure either a static peer to another Yggdrasil node, or that you discover another Yggdrasil node *on the same subnet* using multicast discovery (which is enabled by default). Without peers, you will be isolated from the rest of the network. If you have not added or discovered any peers, you will not be able to reach beyond your own node.
You can check if you have any peers by running `yggdrasilctl getPeers` - peer on port 0 is your own node, ports 1 and above are your active peers.
Stuck for peers? Try adding a [public peer](https://github.com/yggdrasil-network/public-peers).
### Does Yggdrasil add or remove peerings automatically?
Peerings may be automatically established to nodes on the same subnet if multicast peering is enabled on both nodes, however, Yggdrasil will never add or remove remote peerings automatically over other networks like the Internet.
### I've installed the Yggdrasil Debian package and now I can't find the logs.
The Debian package installs the Yggdrasil service into systemd, therefore you can query systemd for the logs:
@ -52,17 +80,15 @@ The Debian package installs the Yggdrasil service into systemd, therefore you ca
### I've modified the configuration file but nothing has changed.
Yggdrasil only loads the configuration at startup. Restart the Yggdrasil process or service to load the new configuration.
Yggdrasil only loads the configuration at startup. Restart the Yggdrasil process or service to load the new configuration. If you are troubleshooting peering connections, check the logging output and/or examine the output of `yggdrasilctl getPeers` to see if any peers are connected.
### I'm running Yggdrasil on a machine that is directly reachable from the Internet. Does this mean anyone can peer with me?
Without any further configuration, yes.
The default Yggdrasil configuration does not listen on any external ports for incoming peering connections. In order to accept peering connections from other nodes, you must add a listener entry to the `Listen` section of the configuration file. You can bind to any TCP port of your choosing in either plain TCP (e.g. `tcp://[::]:12345`) or in TLS (e.g. `tls://[::]:54321`) mode.
However, you can either limit incoming connections to your host using a firewall by limiting or denying connections to the port specified in your `Listen` configuration option. This is useful if you want to limit peerings from certain IP ranges or on certain interfaces.
You can either limit incoming connections to your host using a firewall by limiting or denying connections to the port specified in your `Listen` configuration option. This is useful if you want to limit peerings from certain IP ranges or on certain interfaces.
Alternatively, you can limit who can peer with you by modifying the `AllowedEncryptionPublicKeys` option in your Yggdrasil configuration. When this list is empty, any remote node is allowed to peer with you.
To restrict incoming peerings to certain nodes, you should first ask the operators of those nodes for their `EncryptionPublicKey` and then add those public keys into your own `AllowedEncryptionPublicKeys` list. From that point forward, only nodes with those public keys will be allowed to peer with you.
Alternatively, you can limit who can peer with you by modifying the `AllowedPublicKeys` option in your Yggdrasil configuration. When this list is populated, only the nodes with the specified public keys will be able to establish a peering connection with your node. This is useful if you want to ensure that you can only peer from your own devices or to allow peerings from certain users. When this list is empty, any remote node is allowed to peer with you.
### I am running Yggdrasil from behind a NAT. Will this affect my connectivity?
@ -70,50 +96,23 @@ To accept incoming peerings, you will probably need to configure port forwarding
To use outbound peerings, that is, static peers that have been configured in your `Peers` setting, you will likely not need to change anything.
Regardless of whether your peering connections are inbound or outbound, you will be able to accept incoming connections on your Yggdrasil IPv6 addresses. This makes Yggdrasil an effective way to accept incoming connections when you reside behind NATs that you do not control, i.e. carrier-grade NATs (CGNAT).
### Why does my Yggdrasil adapter have an unusually high MTU?
Yggdrasil peerings are typically stream-based and therefore don't suffer from fragmentation issues when pushing large amounts of data. By using the largest possible MTU supported by a platform, we can send much more data in each write, and the TCP connection will take care of the rest. This also helps somewhat in the reduction of TCP-over-TCP amplification, as there are less control messages to be amplified.
Yggdrasil peerings are typically stream-based and therefore don't suffer from fragmentation issues when pushing large amounts of data. By using the largest possible MTU supported by a platform, we can send much more data in each write and the TCP connection will take care of the rest. This also helps somewhat in the reduction of TCP-over-TCP amplification, as there are less control messages to be amplified.
This also uses less CPU, as we can send more data for every system call on the TUN/TAP adapter or network socket. System calls often result in context switches by the operating system and are expensive operations, therefore by using an MTU of up to 65535, we can save as many as 42 context switches for each packet - a substantial performance improvement!
### I've changed my `AdminListen` port and now `yggdrasilctl` doesn't work.
`yggdrasilctl` will assume that your admin port is on `localhost:9001`. If you have changed it, simply pass your configured endpoint through to `yggdrasilctl`, i.e.
```
yggdrasilctl -endpoint=127.0.0.1:12345
```
### I want to run an Yggdrasil router to provide connectivity for other people, but I don't want them to be able to reach my own machine.
You can set the `IfName` configuration setting to `"none"`. This will load Yggdrasil, but will not create a TUN/TAP adapter, meaning that your host will not be exposed to the Yggdrasil network. This does of course mean that you won't be able to send any traffic from that node to Yggdrasil either!
### Does Yggdrasil work alongside an existing VPN?
Yes, Yggdrasil should not interfere with existing VPNs. VPN traffic can be sent while using Yggdrasil.
Yes, Yggdrasil should not interfere with existing VPNs on many platforms. VPN traffic can be sent while using Yggdrasil.
### Does Yggdrasil work with networks like Tor or I2P?
Yggdrasil can peer over Tor or I2P. See [/public-peers/tree/master/other](https://github.com/yggdrasil-network/public-peers/tree/master/other) for public peers.
### I want to allow outgoing connections from my machine but prevent unwanted incoming connections.
Generally this requires you to use a firewall. The steps for this will vary from platform to platform.
#### Linux (with `ip6tables`)
Assuming your TUN/TAP adapter is `tun0`:
```
ip6tables -A INPUT -i tun0 -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
ip6tables -A INPUT -i tun0 -m conntrack --ctstate INVALID -j DROP
ip6tables -A INPUT -i tun0 -j DROP
```
#### Windows (with Windows Firewall)
Windows, by default, will classify the TAP adapter as a "Public Network". Configure Windows Firewall to prevent incoming connections on Public networks.
#### macOS (with built-in firewall)
macOS has an application firewall, therefore any firewall policies applied on other interfaces will also apply to the Yggdrasil interface.
### Is there any benefit to being the "root node" of the network?
### Is there any benefit to being the "root node" of the network spanning tree?
No. At worst, the root node may be used in worst-case-scenario paths between
other nodes in the absence of being able to determine better routes, but this

4
index.md
View File

@ -3,9 +3,9 @@ tags: dontlink
sitemap: true
---
Yggdrasil is an implementation of a new name-independent routing scheme and functions as an end-to-end encrypted IPv6 network.
Yggdrasil is an overlay network implementation of a new routing scheme for mesh networks. It is designed to be a scalable, resilient and decentralised alternative to the structured routing protocols commonly used today on the Internet and other networks.
It is lightweight, easy to configure, supported on multiple platforms, and allows pretty much any IPv6-capable application to communicate securely with other Yggdrasil nodes. You do not need to have IPv6 Internet connectivity from your ISP — it also works just fine over IPv4.
The current implementation of Yggdrasil is a lightweight userspace software router which is easy to configure and supported on a wide range of platforms. It provides fully end-to-end encrypted IPv6 routability between all network participants. Peerings between nodes can be configured using TCP/TLS connections over local area networks, point-to-point links or the Internet. Even though the Yggdrasil Network provides IPv6 routing between nodes, peering connections can be set up over either IPv4 or IPv6.
The highlights of Yggdrasil are that it is: