diff --git a/about.md b/about.md
index 608f6ec..f0cc16f 100644
--- a/about.md
+++ b/about.md
@@ -4,65 +4,46 @@ sitemap: true
# About
-Yggdrasil is a new and experimental compact routing scheme designed for mesh or even Internet-like networks. It is predominanently a shortest-path scheme, whereby the network will attempt to find the most direct path to the destination.
+Yggdrasil is an experimental compact routing scheme that is **fully decentralised** and only requires a small amount of state to work. It is predominanently a shortest-path scheme, whereby the network will attempt to find the most direct path to the destination.
-Compared to the structured and typically hierarchial routing schemes in use today on many networks, Yggdrasil is strongly decentralised, largely self-arranging and mostly self-healing. The network topology is adaptive, aiming to make use of whichever links are available in order to provide full routability between all network participants. All nodes in Yggdrasil with multiple peers act as routers and will forward traffic on behalf of other nodes.
+
-Each node on the network is identified by a cryptographic public key and, in our [current experimental implementation](implementation.md), stable IPv6 addresses are generated from this key. This allows all IPv6-supporting applications to operate over Yggdrasil largely without modification. The address is fully mobile and stays with the node as it moves around the network.
+Nodes are equal participants and connect to each other using **peering connections** which carry network traffic. Peerings can be set up over any IP network — whether that's a direct wired or wireless link, a local area network or even the Internet. In some cases, peerings can also be set up automatically by nearby devices on the same network using multicast discovery.
-Yggdrasil's design means that it is well suited towards truly ad-hoc wireless mesh networks which many other existing routing protocols struggle with.
+All nodes on an Yggdrasil network are routers and will automatically pass traffic to help it get closer to its destination where possible. This means that, even in a network that is only sparsely connected, **all nodes will be reachable** by all other nodes on that network. It doesn't even matter if a node is behind a NAT — once a peering is established, traffic flows in both directions over that peering.
-### What are the problems today?
+Yggdrasil is also designed to tolerate changes in the network. For example, if a link fails, the network will self-heal and use other links to route traffic where available. This makes it **suitable for use in mesh networks**, where the network topolopy can and often will change.
-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:
+Each node on the network has a location-independent **cryptographic identity** and, in our [current experimental implementation](implementation.md), stable IPv6 addresses are generated from this key. This allows IPv6-supporting applications to work over Yggdrasil largely without modification. The address is fully mobile and stays with the node as it moves around the network.
-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
+### Why Yggdrasil?
-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.
+Many networks that exist today are hierarchical in nature, require extensive manual configuration and often rely on a certain degree of centralisation in order to scale. This often makes it difficult or impractical to set up networks quickly on an ad-hoc basis and so most people are heavily reliant on their Internet Service Providers (ISPs).
-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.
+On the other hand, Yggdrasil requires **very little configuration** in order to work and full multi-hop networks can be built up very quickly and easily using Yggdrasil.
-### What does Yggdrasil do differently?
+Nodes do not need to be assigned an address from a centralised authority; they can **generate their own cryptographic identity** and, more importantly, they can keep this address as they roam. Once peering connections are established, routing information is propagated quickly and automatically throughout the network.
-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 distributed global network topology.
+This ability to provide full end-to-end routability between all network nodes means that Yggdrasil is potentially an enabling technology for true edge computing scenarios, as well as real-world mesh networks, as it **does not rely on the Internet** to function.
-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 exchange bloom filters which contain information about which keyspace neighbours are reachable through each node. Intermediate nodes then populate their routing tables with these paths, enabling nodes to forward packets closer to their destination public key.
-
-In addition, nodes can pathfind using the spanning tree routing to establish a path that is likely shorter than the path through keyspace. 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 tree-routed path breaks.
-
-Cryptographic signatures are used to secure protocol messages against tampering or forgery.
+### How does Yggdrasil compare to other projects?
-### What are the benefits?
+Yggdrasil is often compared to other projects attempting to create anonymous overlays, such as Tor, I2P, Lokinet and others. These projects are very different to Yggdrasil, in part because they try to guarantee anonymity. Yggdrasil does not aim to provide and **does not guarantee anonymity**. These projects are also intentionally overlay-by-design rather than by convenience, whereas Yggdrasil only exists as an overlay network today because it is an easy way to test the design.
-There are a number of benefits to a routing scheme such as this:
+Yggdrasil is frequently compared with VPN projects such as Wireguard, Tailscale, Nebula and Zerotier. Although it is possible to use Yggdrasil to build up private networks and/or point-to-point VPN links, this isn't explicitly our primary goal. It's also important to understand that connecting any single node of a private network to another network (such as a public peer) will result in **both networks being bridged together**.
-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, which allows building true wireless mesh networks
-1. Sparse routing knowledge and only small amounts of protocol traffic should mean that Yggdrasil is able to efficiently scale to very large networks
+Finally, Yggdrasil has **no native exit nodes**, nor does it have any concept of exit nodes, for providing access to the public Internet or to other networks. This can be achieved using proxies or other tunnelling solutions on top of Yggdrasil but this is not something we explicitly aim to provide.
### 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-level research project**, with on-going 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 and we are doing so with our [overlay network implementation](implementation.md). We need 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 true goal of this project is to test the scalability of the Yggdrasil routing scheme and we are doing so with our [overlay network implementation](implementation.md). Studying the behaviour of the network in the real world is most easily achieved with a large number of participants running the software and joining the public test network. 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 **recommend against running any mission-critical workloads** over Yggdrasil and it may be dangerous to rely solely on Yggdrasil for any life-or-death situation. There may be failure modes that we don't yet know about yet!
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 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
-
-### How does Yggdrasil compare to other projects?
-
-The Yggdrasil Network often attract comparisons with other projects attempting to create anonymous overlays, such as Tor, I2P, Lokinet and others. These projects are very different to Yggdrasil, in part because they are attempting to provide anonymity, which Yggdrasil does not, and in part because they are intentionally overlay-by-design rather than by convenience. Any anonymity or pseudonymity that can occur with the Yggdrasil testbed network is purely coincidental and should not be relied upon.
-
-Yggdrasil is frequently compared with VPN projects such as Wireguard, Tailscale, Nebula and Zerotier. Although the Yggdrasil Network can be used as a kind of point-to-point VPN if appropriately configured, it is not a primary goal of ours to provide VPN tunnelling.
-
-We do not see Yggdrasil as being in competition with these projects as they are attempting to solve a different set of problems.
-
-The Yggdrasil Network does not natively provide access to the public Internet or to other networks, although it can be achieved with proxies or other tunnelling solutions.
diff --git a/assets/images/about/first.svg b/assets/images/about/first.svg
new file mode 100644
index 0000000..62d932a
--- /dev/null
+++ b/assets/images/about/first.svg
@@ -0,0 +1,10 @@
+
\ No newline at end of file
diff --git a/configuration.md b/configuration.md
index 7a050e8..6c340e3 100644
--- a/configuration.md
+++ b/configuration.md
@@ -7,31 +7,35 @@ tags: dontlink
Yggdrasil can run in one of two modes: with a configuration file, or in autoconfigure mode.
-A static configuration file simplifies most setups as it allows you to keep the same keypair (and therefore IP address), maintain a list of peers and so on. For most users this will be the recommended configuration. Most Yggdrasil distribution packages will generate a configuration file automatically.
+A static configuration file simplifies most setups as it allows you to keep the same keypair (and therefore IP address), maintain a list of peers and so on. For most users this will be the recommended configuration. Most Yggdrasil distribution packages will generate an `yggdrasil.conf` configuration file automatically.
-However, autoconfigure mode allows you to quickly start Yggdrasil using sane-ish default settings, with `yggdrasil --autoconf`. In this mode, Yggdrasil will automatically attempt to peer with other nodes on the same subnet, but it also generates a random set of keys each time it is started, and therefore a random IP address.
+However, autoconfigure mode allows you to quickly start Yggdrasil using sane-ish default settings, with `yggdrasil -autoconf`. In this mode, Yggdrasil will automatically attempt to peer with other nodes on the same subnet, but it also generates a random set of keys each time it is started, and therefore a random IP address.
Yggdrasil supports configuration in either HJSON or JSON format. HJSON is the default preferred format, as it has comments, although JSON support is available due to ease of manipulation.
-## Generating a new config file
+### Configuration reference
-If you installed Yggdrasil through one of the platform packages (i.e. macOS, Debian, RPM) then a default configuration file may already exist in `/etc/yggdrasil.conf`.
+Information about the various options in the configuration file [can be found here](configurationref.md).
-On some systems, configuration file could be located at `/etc/yggdrasil/yggdrasil.conf`.
+### Generating a new config file
+
+If you installed Yggdrasil through one of the platform packages (i.e. macOS, Debian, RPM) then a default configuration file may already exist.
+
+It is likely located in either `/etc/yggdrasil.conf` or `/etc/yggdrasil/yggdrasil.conf` depending on your platform.
Otherwise, you can generate a configuration file in the following ways:
| **Generate HJSON**: | `yggdrasil -genconf > /etc/yggdrasil.conf` |
| **Generate JSON**: | `yggdrasil -genconf -json > /etc/yggdrasil.conf` |
-## Using a config file
+### Using a config file
Yggdrasil can accept a configuration file either through `stdin` or by being given a path on the filesystem to a configuration file:
| **Using stdin**: | `yggdrasil -useconf < /etc/yggdrasil.conf` |
| **Using file:** | `yggdrasil -useconffile /etc/yggdrasil.conf` |
-## Normalising a config file
+### Normalising a config file
If you want to see the original format of the configuration file, or convert between HJSON and JSON formats, you can use the `-normaliseconf` option, e.g.
@@ -40,9 +44,9 @@ If you want to see the original format of the configuration file, or convert bet
Normalising the configuration also adds any missing configuration items with their default values. This can be useful when upgrading to a newer version of Yggdrasil that adds new configuration options. Many of our distribution packages normalise the configuration automatically during upgrade.
-## Manually Connecting to Peers
+### Manually Connecting to Peers
-Yggdrasil can be configured to connect to other peers by adding entries into the `Peers` configuration section. At startup, Yggdrasil will attempt to open a connection to these peers.
+Yggdrasil can be configured to connect to other peers by adding entries into the `Peers` configuration section. At startup, Yggdrasil will attempt to open a connection to these peers.
A peering URI will look similar to one of the following:
@@ -57,7 +61,7 @@ As the network uses ordinary TCP, it is possible to connect over other networks,
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.
-## Advertising a Prefix
+### Advertising a Prefix
While it is generally encouraged that nodes run the software locally, to provide end-to-end cryptographic sessions and participate in routing, this is not always practical. The device may not have the resources to run the software or may not be able to run user code. To that end, Yggdrasil also provides each node with a routed `/64` subnet in addition to their IPv6 address. A node running Yggdrasil that acts as a router may advertise this prefix to other devices just as they would any other ordinary IPv6 network.
@@ -74,6 +78,7 @@ On Linux, something like the following should be sufficient to advertise a prefi
2. `ip addr add 300:1111:2222:3333::1/64 dev eth0` or similar — replacing `300:1111:2222:3333::` with your routed subnet from `yggdrasilctl getSelf` — to assign an address for the router to use in that prefix, where the LAN is reachable through `eth0`
3. Install/run `radvd` with something like the following in `/etc/radvd.conf` — again, replacing the `300:1111:2222:3333::` with your routed subnet:
+
```
interface eth0
{
@@ -88,7 +93,7 @@ interface eth0
Note that a `/64` prefix has fewer bits of address space available to check against the node's ID, which in turn means hash collisions are more likely. As such, it is unwise to rely on addresses as a form of identity verification for the `300::/8` address range.
-## Generating Stronger Addresses (and Prefixes)
+### Generating Stronger Addresses (and Prefixes)
While 128 bits is long enough to make collisions technically impractical, if not outright impossible, it's not unreasonable to think that 64 bits may be attackable at some point if not now.
Without going too far into the details, addresses are a truncated hash of a node's public key, with leading `1` bits accumulated and suppressed (along with the inevitable first `0` bit).
diff --git a/configurationref.md b/configurationref.md
new file mode 100644
index 0000000..1f8f257
--- /dev/null
+++ b/configurationref.md
@@ -0,0 +1,78 @@
+---
+sitemap: true
+tags: dontlink
+---
+
+# Configuration Reference
+
+The configuration file contains the following options:
+
+### `Peers`
+
+A list of outbound peering connections to make. Peers are specified in URL format. The following types of peers are supported:
+
+* `tcp://1.1.1.1:1234` (TCP)
+* `tls://1.1.1.1:1234` (TCP+TLS)
+* `quic://1.1.1.1:1234` (QUIC+TLS)
+* `socks://2.2.2.2:2345/1.1.1.1:1234` (TCP via the SOCKS proxy at `2.2.2.2:2345`)
+* `sockstls://2.2.2.2:2345/1.1.1.1:1234` (TLS via the SOCKS proxy at `2.2.2.2:2345`)
+* `unix:///path/to/sock.sock` (UNIX)
+* `ws://1.1.1.1:1234` or `ws://1.1.1.1:1234/path` (WebSockets, Yggdrasil 0.5.7 or later only)
+* `wss://1.1.1.1:1234` or `wss://1.1.1.1:1234/path` (WebSockets+TLS, Yggdrasil 0.5.7 or later only)
+
+Additional settings can optionally be added as query-string parameters to the end of the URL:
+
+* `password=PASSWORD` — set this only for peers that require a shared secret/password to connect
+* `key=PUBLICKEY` — pin the specified public key for this peer, this will cause the connection to fail if the remote side's key does not match
+* `maxbackoff=DURATION` — control what the maximum backoff/retry time will be if the peering goes down, format like `30s` for seconds or `1m` for minutes
+
+### `InterfacePeers`
+
+Like `Peers` above, but sorted into sections representing the outbound network interface used to establish the peering connection. This is only useful on hosts that require a special multi-homed configuration, otherwise you should use `Peers` instead.
+
+### `Listen`
+
+A list of listeners to open for accepting incoming connections. Instead of supplying the remote address, you should instead supply a bind address. This would either be `0.0.0.0` for IPv4, `::` for IPv4+IPv6 or the IP address of a network interface on your machine. The following listener types are supported:
+
+* `tcp://[::]:1234` (TCP)
+* `tls://[::]:1234` (TCP+TLS)
+* `quic://[::]:1234` (QUIC+TLS)
+* `unix:///path/to/sock.sock` (UNIX)
+* `ws://[::]:444` (WebSockets, Yggdrasil 0.5.7 or later only)
+
+### `MulticastInterfaces`
+
+Controls which interfaces to enable or disable multicast peer discovery on. The default varies by platform.
+
+Each multicast interface block has the following options:
+
+* `Regex` — match the names of specific interfaces, i.e. `eth.*` for matching all network interfaces starting with `eth`
+* `Beacon` — controls whether this node should advertise its presence to nearby devices
+* `Listen` — controls whether this node should attempt to connect to other nearby nodes that are advertising their presence
+* `Port` — sets the port number for the TLS listener that is automatically opened for each matched interface, or `0` for a random port
+* `Password` — optionally sets a password, only other nodes that have the same password configured will discover and connect to each other automatically
+* `Priority` — controls whether peerings made to a node over this interface should take predecence over peerings made *to the same node* over other interfaces, lower numbers are higher priority, i.e. for preferring ethernet over Wi-Fi
+
+### `AllowedPublicKeys`
+
+A list of public keys that will be allowed to connect to this node.
+
+If no public keys are specified in this section then all nodes will be able to connect based on the `Listen` and/or `MulticastInterfaces` configuration. If public keys are specified, whitelisting is enabled and only nodes with those public keys will be able to connect.
+
+### `IfName`
+
+Determines which TUN interface to use. The default is set to `auto` which will try to set up a TUN automatically. If set to `none`, TUN will be disabled and the node will run in headless router-only mode.
+
+On Linux, you can use this setting to give your Yggdrasil TUN interface a unique/persistent name, i.e. `ygg0`, if desired.
+
+### `IfMTU`
+
+The MTU of the interface.
+
+### `NodeInfoPrivacy`
+
+Whether or not the node info should automatically include build information, i.e. the operating system and architecture and the Yggdrasil build version. If privacy is enabled, the node info will not contain this information.
+
+### `NodeInfo`
+
+A free-form section that the node operator can use to put JSON-formatted metadata that may be made available to other nodes.
diff --git a/documentation.md b/documentation.md
new file mode 100644
index 0000000..2c79217
--- /dev/null
+++ b/documentation.md
@@ -0,0 +1,14 @@
+---
+sitemap: true
+---
+
+# Documentation
+
+The following pages will help to get started with Yggdrasil:
+
+1. [Install the router software](installation.md)
+2. [Generating and editing a configuration file](configuration.md)
+3. [Configuration file reference](configurationref.md)
+3. [Find public peers](https://publicpeers.neilalexander.dev) and [try public services](services.md)
+
+(TODO: this page/section needs further work!)
diff --git a/implementation.md b/implementation.md
index b3b3ea6..ac87ca0 100644
--- a/implementation.md
+++ b/implementation.md
@@ -1,5 +1,6 @@
---
sitemap: true
+tags: dontlink
---
# Implementation
@@ -10,13 +11,13 @@ All network nodes are userspace software routers that run under a single process
Implementing Yggdrasil as an overlay network allows us to test the protocol and routing scheme at scale relatively easily, as the user-space router can easily run on most computers. Users also do not need to be physically close to one another in order to join or test the network. Users can just download the software and establish some peerings over the Internet or other over networks. However, the Yggdrasil design does not constrain it to only being implemented as an overlay network — it could also be implemented as a native routing protocol with physical links instead.
-### Security
+### How is Yggdrasil secured?
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 will be encrypted using the destination node's public key, ensuring that intermediate nodes cannot snoop on the contents of traffic being forwarded through the network.
It is possible for anyone to join the public Yggdrasil Network and it should therefore be considered as an untrusted network, similar to a public Wi-Fi network or a direct Internet connection. An IPv6-capable firewall that blocks unexpected incoming traffic is highly recommended in order to prevent services on your machine from being accidentally exposed to all users of the Yggdrasil Network.
-### Peerings
+### How do nodes peer with each other?
Network nodes establish peerings either in one of two ways:
@@ -27,13 +28,46 @@ It is important to note that Yggdrasil nodes **never** establish new peerings wi
This is because it is the goal of the Yggdrasil protocol to find the best possible paths using only the set of links that are already available. It is therefore essential that we strictly do not make any assumptions about the network topology underneath the peerings, nor do we assume that any two nodes would be able to establish a direct link on demand. In real-world networks with physical links, automatic establishment of new peering links between arbitrary pairs of nodes would simply not be possible.
-### Node identities
+### How are nodes identified?
In the Yggdrasil design, a node's true identity is its public key. The current overlay implementation generates an IPv6 address based on the truncated public key. Translation between IPv6 addresses and partial public keys, as well as searching the network based on those keys, is performed transparently by the Yggdrasil router, therefore all you need to know in order to communicate with a remote node is the IPv6 address it has generated.
Domain Name System (DNS) and other name/service lookup mechanisms are specifically out of scope for the project and there is no "official" DNS system that is endorsed for use on the Yggdrasil Network, although some third-party projects attempting to solve this problem are indeed available.
-### Link metrics
+### Which problems exist today?
+
+The Internet 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. This gives us some unavoidable problems:
+
+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 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.
+
+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 to sharing routing knowledge. Rather than distributing address ranges as paths through centrally assigned autonomous systems, Yggdrasil instead builds up a single distributed global network topology.
+
+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 exchange bloom filters which contain information about which keyspace neighbours are reachable through each node. Intermediate nodes then populate their routing tables with these paths, enabling nodes to forward packets closer to their destination public key.
+
+In addition, nodes can pathfind using the spanning tree routing to establish a path that is likely shorter than the path through keyspace. 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 tree-routed path breaks.
+
+Cryptographic signatures are used to secure protocol messages against tampering or forgery.
+
+### What are the benefits?
+
+There are a number of benefits to a routing scheme such as this:
+
+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, which allows building true wireless mesh networks
+1. Sparse routing knowledge and only small amounts of protocol traffic should mean that Yggdrasil is able to efficiently scale to very large networks
+
+### Does Yggdrasil have link metrics?
As a decentralised routing protocol design, we believe it is important that routing decisions are only ever made using information that can be securely and independently verified by any given node in a low-cost fashion. We therefore consider most interactive link quality metrics to be out-of-scope at this time, although this will likely change in the future as the protocol becomes more mature.
diff --git a/installation.md b/installation.md
index 5d033d3..7edb507 100644
--- a/installation.md
+++ b/installation.md
@@ -1,17 +1,12 @@
---
sitemap: true
+tags: dontlink
---
# Installation
Yggdrasil can be downloaded for major platforms from our [GitHub Releases](https://github.com/yggdrasil-network/yggdrasil-go/releases) page. Additionally, installation guides are available for the following platforms/distributions.
-Once you have installed Yggdrasil, take a look at:
-
-- [Configuration](configuration.md) — information about configuring Yggdrasil
-- [Public Peers](https://github.com/yggdrasil-network/public-peers) — public nodes to connect to
-- [Public Services](services.md) — services running inside the Yggdrasil Network
-
---
🚨 **Please remember to check for Yggdrasil updates regularly.** 🚨 Yggdrasil does not have a built-in method of notifying you when new versions are available. You may want to subscribe to the [GitHub Releases Atom feed](https://github.com/yggdrasil-network/yggdrasil-go/releases.atom) or consider [watching the GitHub repository](https://github.com/yggdrasil-network/yggdrasil-go) (a "Custom" watch can be used to subscribe to release notifications only). Release notifications are also sent in our [Matrix room](https://matrix.to/#/#yggdrasil:matrix.org).
@@ -43,14 +38,13 @@ Yggdrasil works on Windows and [an MSI installer is available](installation-wind
Yggdrasil is supported on iOS with the following applications:
-- [Yggdrasil for iOS on TestFlight](https://testflight.apple.com/join/jZNsIkRr), reference client based on the [v0.4 release candidate](https://yggdrasil-network.github.io/2021/06/19/preparing-for-v0-4.html) ([source code](https://github.com/yggdrasil-network/yggdrasil-ios))
+- [Yggdrasil for iOS on TestFlight](https://testflight.apple.com/join/jZNsIkRr) ([source code](https://github.com/yggdrasil-network/yggdrasil-ios))
### Android
Yggdrasil is supported on Android with the following applications:
-- [Yggdrasil for Android](https://github.com/yggdrasil-network/yggdrasil-android/releases), reference client based on the [v0.4 release candidate](https://yggdrasil-network.github.io/2021/06/19/preparing-for-v0-4.html)
-- [Crispa for Android](https://github.com/yggdrasil-network/crispa-android/releases), contributed by the community
+- [Yggdrasil for Android](https://github.com/yggdrasil-network/yggdrasil-android/releases) ([source code](https://github.com/yggdrasil-network/yggdrasil-android))
### FreeBSD
-Each node on the network is identified by a cryptographic public key and, in our [current experimental implementation](implementation.md), stable IPv6 addresses are generated from this key. This allows all IPv6-supporting applications to operate over Yggdrasil largely without modification. The address is fully mobile and stays with the node as it moves around the network.
+Nodes are equal participants and connect to each other using **peering connections** which carry network traffic. Peerings can be set up over any IP network — whether that's a direct wired or wireless link, a local area network or even the Internet. In some cases, peerings can also be set up automatically by nearby devices on the same network using multicast discovery.
-Yggdrasil's design means that it is well suited towards truly ad-hoc wireless mesh networks which many other existing routing protocols struggle with.
+All nodes on an Yggdrasil network are routers and will automatically pass traffic to help it get closer to its destination where possible. This means that, even in a network that is only sparsely connected, **all nodes will be reachable** by all other nodes on that network. It doesn't even matter if a node is behind a NAT — once a peering is established, traffic flows in both directions over that peering.
-### What are the problems today?
+Yggdrasil is also designed to tolerate changes in the network. For example, if a link fails, the network will self-heal and use other links to route traffic where available. This makes it **suitable for use in mesh networks**, where the network topolopy can and often will change.
-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:
+Each node on the network has a location-independent **cryptographic identity** and, in our [current experimental implementation](implementation.md), stable IPv6 addresses are generated from this key. This allows IPv6-supporting applications to work over Yggdrasil largely without modification. The address is fully mobile and stays with the node as it moves around the network.
-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
+### Why Yggdrasil?
-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.
+Many networks that exist today are hierarchical in nature, require extensive manual configuration and often rely on a certain degree of centralisation in order to scale. This often makes it difficult or impractical to set up networks quickly on an ad-hoc basis and so most people are heavily reliant on their Internet Service Providers (ISPs).
-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.
+On the other hand, Yggdrasil requires **very little configuration** in order to work and full multi-hop networks can be built up very quickly and easily using Yggdrasil.
-### What does Yggdrasil do differently?
+Nodes do not need to be assigned an address from a centralised authority; they can **generate their own cryptographic identity** and, more importantly, they can keep this address as they roam. Once peering connections are established, routing information is propagated quickly and automatically throughout the network.
-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 distributed global network topology.
+This ability to provide full end-to-end routability between all network nodes means that Yggdrasil is potentially an enabling technology for true edge computing scenarios, as well as real-world mesh networks, as it **does not rely on the Internet** to function.
-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 exchange bloom filters which contain information about which keyspace neighbours are reachable through each node. Intermediate nodes then populate their routing tables with these paths, enabling nodes to forward packets closer to their destination public key.
-
-In addition, nodes can pathfind using the spanning tree routing to establish a path that is likely shorter than the path through keyspace. 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 tree-routed path breaks.
-
-Cryptographic signatures are used to secure protocol messages against tampering or forgery.
+### How does Yggdrasil compare to other projects?
-### What are the benefits?
+Yggdrasil is often compared to other projects attempting to create anonymous overlays, such as Tor, I2P, Lokinet and others. These projects are very different to Yggdrasil, in part because they try to guarantee anonymity. Yggdrasil does not aim to provide and **does not guarantee anonymity**. These projects are also intentionally overlay-by-design rather than by convenience, whereas Yggdrasil only exists as an overlay network today because it is an easy way to test the design.
-There are a number of benefits to a routing scheme such as this:
+Yggdrasil is frequently compared with VPN projects such as Wireguard, Tailscale, Nebula and Zerotier. Although it is possible to use Yggdrasil to build up private networks and/or point-to-point VPN links, this isn't explicitly our primary goal. It's also important to understand that connecting any single node of a private network to another network (such as a public peer) will result in **both networks being bridged together**.
-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, which allows building true wireless mesh networks
-1. Sparse routing knowledge and only small amounts of protocol traffic should mean that Yggdrasil is able to efficiently scale to very large networks
+Finally, Yggdrasil has **no native exit nodes**, nor does it have any concept of exit nodes, for providing access to the public Internet or to other networks. This can be achieved using proxies or other tunnelling solutions on top of Yggdrasil but this is not something we explicitly aim to provide.
### 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-level research project**, with on-going 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 and we are doing so with our [overlay network implementation](implementation.md). We need 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 true goal of this project is to test the scalability of the Yggdrasil routing scheme and we are doing so with our [overlay network implementation](implementation.md). Studying the behaviour of the network in the real world is most easily achieved with a large number of participants running the software and joining the public test network. 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 **recommend against running any mission-critical workloads** over Yggdrasil and it may be dangerous to rely solely on Yggdrasil for any life-or-death situation. There may be failure modes that we don't yet know about yet!
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 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
-
-### How does Yggdrasil compare to other projects?
-
-The Yggdrasil Network often attract comparisons with other projects attempting to create anonymous overlays, such as Tor, I2P, Lokinet and others. These projects are very different to Yggdrasil, in part because they are attempting to provide anonymity, which Yggdrasil does not, and in part because they are intentionally overlay-by-design rather than by convenience. Any anonymity or pseudonymity that can occur with the Yggdrasil testbed network is purely coincidental and should not be relied upon.
-
-Yggdrasil is frequently compared with VPN projects such as Wireguard, Tailscale, Nebula and Zerotier. Although the Yggdrasil Network can be used as a kind of point-to-point VPN if appropriately configured, it is not a primary goal of ours to provide VPN tunnelling.
-
-We do not see Yggdrasil as being in competition with these projects as they are attempting to solve a different set of problems.
-
-The Yggdrasil Network does not natively provide access to the public Internet or to other networks, although it can be achieved with proxies or other tunnelling solutions.
diff --git a/assets/images/about/first.svg b/assets/images/about/first.svg
new file mode 100644
index 0000000..62d932a
--- /dev/null
+++ b/assets/images/about/first.svg
@@ -0,0 +1,10 @@
+
\ No newline at end of file
diff --git a/configuration.md b/configuration.md
index 7a050e8..6c340e3 100644
--- a/configuration.md
+++ b/configuration.md
@@ -7,31 +7,35 @@ tags: dontlink
Yggdrasil can run in one of two modes: with a configuration file, or in autoconfigure mode.
-A static configuration file simplifies most setups as it allows you to keep the same keypair (and therefore IP address), maintain a list of peers and so on. For most users this will be the recommended configuration. Most Yggdrasil distribution packages will generate a configuration file automatically.
+A static configuration file simplifies most setups as it allows you to keep the same keypair (and therefore IP address), maintain a list of peers and so on. For most users this will be the recommended configuration. Most Yggdrasil distribution packages will generate an `yggdrasil.conf` configuration file automatically.
-However, autoconfigure mode allows you to quickly start Yggdrasil using sane-ish default settings, with `yggdrasil --autoconf`. In this mode, Yggdrasil will automatically attempt to peer with other nodes on the same subnet, but it also generates a random set of keys each time it is started, and therefore a random IP address.
+However, autoconfigure mode allows you to quickly start Yggdrasil using sane-ish default settings, with `yggdrasil -autoconf`. In this mode, Yggdrasil will automatically attempt to peer with other nodes on the same subnet, but it also generates a random set of keys each time it is started, and therefore a random IP address.
Yggdrasil supports configuration in either HJSON or JSON format. HJSON is the default preferred format, as it has comments, although JSON support is available due to ease of manipulation.
-## Generating a new config file
+### Configuration reference
-If you installed Yggdrasil through one of the platform packages (i.e. macOS, Debian, RPM) then a default configuration file may already exist in `/etc/yggdrasil.conf`.
+Information about the various options in the configuration file [can be found here](configurationref.md).
-On some systems, configuration file could be located at `/etc/yggdrasil/yggdrasil.conf`.
+### Generating a new config file
+
+If you installed Yggdrasil through one of the platform packages (i.e. macOS, Debian, RPM) then a default configuration file may already exist.
+
+It is likely located in either `/etc/yggdrasil.conf` or `/etc/yggdrasil/yggdrasil.conf` depending on your platform.
Otherwise, you can generate a configuration file in the following ways:
| **Generate HJSON**: | `yggdrasil -genconf > /etc/yggdrasil.conf` |
| **Generate JSON**: | `yggdrasil -genconf -json > /etc/yggdrasil.conf` |
-## Using a config file
+### Using a config file
Yggdrasil can accept a configuration file either through `stdin` or by being given a path on the filesystem to a configuration file:
| **Using stdin**: | `yggdrasil -useconf < /etc/yggdrasil.conf` |
| **Using file:** | `yggdrasil -useconffile /etc/yggdrasil.conf` |
-## Normalising a config file
+### Normalising a config file
If you want to see the original format of the configuration file, or convert between HJSON and JSON formats, you can use the `-normaliseconf` option, e.g.
@@ -40,9 +44,9 @@ If you want to see the original format of the configuration file, or convert bet
Normalising the configuration also adds any missing configuration items with their default values. This can be useful when upgrading to a newer version of Yggdrasil that adds new configuration options. Many of our distribution packages normalise the configuration automatically during upgrade.
-## Manually Connecting to Peers
+### Manually Connecting to Peers
-Yggdrasil can be configured to connect to other peers by adding entries into the `Peers` configuration section. At startup, Yggdrasil will attempt to open a connection to these peers.
+Yggdrasil can be configured to connect to other peers by adding entries into the `Peers` configuration section. At startup, Yggdrasil will attempt to open a connection to these peers.
A peering URI will look similar to one of the following:
@@ -57,7 +61,7 @@ As the network uses ordinary TCP, it is possible to connect over other networks,
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.
-## Advertising a Prefix
+### Advertising a Prefix
While it is generally encouraged that nodes run the software locally, to provide end-to-end cryptographic sessions and participate in routing, this is not always practical. The device may not have the resources to run the software or may not be able to run user code. To that end, Yggdrasil also provides each node with a routed `/64` subnet in addition to their IPv6 address. A node running Yggdrasil that acts as a router may advertise this prefix to other devices just as they would any other ordinary IPv6 network.
@@ -74,6 +78,7 @@ On Linux, something like the following should be sufficient to advertise a prefi
2. `ip addr add 300:1111:2222:3333::1/64 dev eth0` or similar — replacing `300:1111:2222:3333::` with your routed subnet from `yggdrasilctl getSelf` — to assign an address for the router to use in that prefix, where the LAN is reachable through `eth0`
3. Install/run `radvd` with something like the following in `/etc/radvd.conf` — again, replacing the `300:1111:2222:3333::` with your routed subnet:
+
```
interface eth0
{
@@ -88,7 +93,7 @@ interface eth0
Note that a `/64` prefix has fewer bits of address space available to check against the node's ID, which in turn means hash collisions are more likely. As such, it is unwise to rely on addresses as a form of identity verification for the `300::/8` address range.
-## Generating Stronger Addresses (and Prefixes)
+### Generating Stronger Addresses (and Prefixes)
While 128 bits is long enough to make collisions technically impractical, if not outright impossible, it's not unreasonable to think that 64 bits may be attackable at some point if not now.
Without going too far into the details, addresses are a truncated hash of a node's public key, with leading `1` bits accumulated and suppressed (along with the inevitable first `0` bit).
diff --git a/configurationref.md b/configurationref.md
new file mode 100644
index 0000000..1f8f257
--- /dev/null
+++ b/configurationref.md
@@ -0,0 +1,78 @@
+---
+sitemap: true
+tags: dontlink
+---
+
+# Configuration Reference
+
+The configuration file contains the following options:
+
+### `Peers`
+
+A list of outbound peering connections to make. Peers are specified in URL format. The following types of peers are supported:
+
+* `tcp://1.1.1.1:1234` (TCP)
+* `tls://1.1.1.1:1234` (TCP+TLS)
+* `quic://1.1.1.1:1234` (QUIC+TLS)
+* `socks://2.2.2.2:2345/1.1.1.1:1234` (TCP via the SOCKS proxy at `2.2.2.2:2345`)
+* `sockstls://2.2.2.2:2345/1.1.1.1:1234` (TLS via the SOCKS proxy at `2.2.2.2:2345`)
+* `unix:///path/to/sock.sock` (UNIX)
+* `ws://1.1.1.1:1234` or `ws://1.1.1.1:1234/path` (WebSockets, Yggdrasil 0.5.7 or later only)
+* `wss://1.1.1.1:1234` or `wss://1.1.1.1:1234/path` (WebSockets+TLS, Yggdrasil 0.5.7 or later only)
+
+Additional settings can optionally be added as query-string parameters to the end of the URL:
+
+* `password=PASSWORD` — set this only for peers that require a shared secret/password to connect
+* `key=PUBLICKEY` — pin the specified public key for this peer, this will cause the connection to fail if the remote side's key does not match
+* `maxbackoff=DURATION` — control what the maximum backoff/retry time will be if the peering goes down, format like `30s` for seconds or `1m` for minutes
+
+### `InterfacePeers`
+
+Like `Peers` above, but sorted into sections representing the outbound network interface used to establish the peering connection. This is only useful on hosts that require a special multi-homed configuration, otherwise you should use `Peers` instead.
+
+### `Listen`
+
+A list of listeners to open for accepting incoming connections. Instead of supplying the remote address, you should instead supply a bind address. This would either be `0.0.0.0` for IPv4, `::` for IPv4+IPv6 or the IP address of a network interface on your machine. The following listener types are supported:
+
+* `tcp://[::]:1234` (TCP)
+* `tls://[::]:1234` (TCP+TLS)
+* `quic://[::]:1234` (QUIC+TLS)
+* `unix:///path/to/sock.sock` (UNIX)
+* `ws://[::]:444` (WebSockets, Yggdrasil 0.5.7 or later only)
+
+### `MulticastInterfaces`
+
+Controls which interfaces to enable or disable multicast peer discovery on. The default varies by platform.
+
+Each multicast interface block has the following options:
+
+* `Regex` — match the names of specific interfaces, i.e. `eth.*` for matching all network interfaces starting with `eth`
+* `Beacon` — controls whether this node should advertise its presence to nearby devices
+* `Listen` — controls whether this node should attempt to connect to other nearby nodes that are advertising their presence
+* `Port` — sets the port number for the TLS listener that is automatically opened for each matched interface, or `0` for a random port
+* `Password` — optionally sets a password, only other nodes that have the same password configured will discover and connect to each other automatically
+* `Priority` — controls whether peerings made to a node over this interface should take predecence over peerings made *to the same node* over other interfaces, lower numbers are higher priority, i.e. for preferring ethernet over Wi-Fi
+
+### `AllowedPublicKeys`
+
+A list of public keys that will be allowed to connect to this node.
+
+If no public keys are specified in this section then all nodes will be able to connect based on the `Listen` and/or `MulticastInterfaces` configuration. If public keys are specified, whitelisting is enabled and only nodes with those public keys will be able to connect.
+
+### `IfName`
+
+Determines which TUN interface to use. The default is set to `auto` which will try to set up a TUN automatically. If set to `none`, TUN will be disabled and the node will run in headless router-only mode.
+
+On Linux, you can use this setting to give your Yggdrasil TUN interface a unique/persistent name, i.e. `ygg0`, if desired.
+
+### `IfMTU`
+
+The MTU of the interface.
+
+### `NodeInfoPrivacy`
+
+Whether or not the node info should automatically include build information, i.e. the operating system and architecture and the Yggdrasil build version. If privacy is enabled, the node info will not contain this information.
+
+### `NodeInfo`
+
+A free-form section that the node operator can use to put JSON-formatted metadata that may be made available to other nodes.
diff --git a/documentation.md b/documentation.md
new file mode 100644
index 0000000..2c79217
--- /dev/null
+++ b/documentation.md
@@ -0,0 +1,14 @@
+---
+sitemap: true
+---
+
+# Documentation
+
+The following pages will help to get started with Yggdrasil:
+
+1. [Install the router software](installation.md)
+2. [Generating and editing a configuration file](configuration.md)
+3. [Configuration file reference](configurationref.md)
+3. [Find public peers](https://publicpeers.neilalexander.dev) and [try public services](services.md)
+
+(TODO: this page/section needs further work!)
diff --git a/implementation.md b/implementation.md
index b3b3ea6..ac87ca0 100644
--- a/implementation.md
+++ b/implementation.md
@@ -1,5 +1,6 @@
---
sitemap: true
+tags: dontlink
---
# Implementation
@@ -10,13 +11,13 @@ All network nodes are userspace software routers that run under a single process
Implementing Yggdrasil as an overlay network allows us to test the protocol and routing scheme at scale relatively easily, as the user-space router can easily run on most computers. Users also do not need to be physically close to one another in order to join or test the network. Users can just download the software and establish some peerings over the Internet or other over networks. However, the Yggdrasil design does not constrain it to only being implemented as an overlay network — it could also be implemented as a native routing protocol with physical links instead.
-### Security
+### How is Yggdrasil secured?
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 will be encrypted using the destination node's public key, ensuring that intermediate nodes cannot snoop on the contents of traffic being forwarded through the network.
It is possible for anyone to join the public Yggdrasil Network and it should therefore be considered as an untrusted network, similar to a public Wi-Fi network or a direct Internet connection. An IPv6-capable firewall that blocks unexpected incoming traffic is highly recommended in order to prevent services on your machine from being accidentally exposed to all users of the Yggdrasil Network.
-### Peerings
+### How do nodes peer with each other?
Network nodes establish peerings either in one of two ways:
@@ -27,13 +28,46 @@ It is important to note that Yggdrasil nodes **never** establish new peerings wi
This is because it is the goal of the Yggdrasil protocol to find the best possible paths using only the set of links that are already available. It is therefore essential that we strictly do not make any assumptions about the network topology underneath the peerings, nor do we assume that any two nodes would be able to establish a direct link on demand. In real-world networks with physical links, automatic establishment of new peering links between arbitrary pairs of nodes would simply not be possible.
-### Node identities
+### How are nodes identified?
In the Yggdrasil design, a node's true identity is its public key. The current overlay implementation generates an IPv6 address based on the truncated public key. Translation between IPv6 addresses and partial public keys, as well as searching the network based on those keys, is performed transparently by the Yggdrasil router, therefore all you need to know in order to communicate with a remote node is the IPv6 address it has generated.
Domain Name System (DNS) and other name/service lookup mechanisms are specifically out of scope for the project and there is no "official" DNS system that is endorsed for use on the Yggdrasil Network, although some third-party projects attempting to solve this problem are indeed available.
-### Link metrics
+### Which problems exist today?
+
+The Internet 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. This gives us some unavoidable problems:
+
+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 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.
+
+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 to sharing routing knowledge. Rather than distributing address ranges as paths through centrally assigned autonomous systems, Yggdrasil instead builds up a single distributed global network topology.
+
+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 exchange bloom filters which contain information about which keyspace neighbours are reachable through each node. Intermediate nodes then populate their routing tables with these paths, enabling nodes to forward packets closer to their destination public key.
+
+In addition, nodes can pathfind using the spanning tree routing to establish a path that is likely shorter than the path through keyspace. 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 tree-routed path breaks.
+
+Cryptographic signatures are used to secure protocol messages against tampering or forgery.
+
+### What are the benefits?
+
+There are a number of benefits to a routing scheme such as this:
+
+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, which allows building true wireless mesh networks
+1. Sparse routing knowledge and only small amounts of protocol traffic should mean that Yggdrasil is able to efficiently scale to very large networks
+
+### Does Yggdrasil have link metrics?
As a decentralised routing protocol design, we believe it is important that routing decisions are only ever made using information that can be securely and independently verified by any given node in a low-cost fashion. We therefore consider most interactive link quality metrics to be out-of-scope at this time, although this will likely change in the future as the protocol becomes more mature.
diff --git a/installation.md b/installation.md
index 5d033d3..7edb507 100644
--- a/installation.md
+++ b/installation.md
@@ -1,17 +1,12 @@
---
sitemap: true
+tags: dontlink
---
# Installation
Yggdrasil can be downloaded for major platforms from our [GitHub Releases](https://github.com/yggdrasil-network/yggdrasil-go/releases) page. Additionally, installation guides are available for the following platforms/distributions.
-Once you have installed Yggdrasil, take a look at:
-
-- [Configuration](configuration.md) — information about configuring Yggdrasil
-- [Public Peers](https://github.com/yggdrasil-network/public-peers) — public nodes to connect to
-- [Public Services](services.md) — services running inside the Yggdrasil Network
-
---
🚨 **Please remember to check for Yggdrasil updates regularly.** 🚨 Yggdrasil does not have a built-in method of notifying you when new versions are available. You may want to subscribe to the [GitHub Releases Atom feed](https://github.com/yggdrasil-network/yggdrasil-go/releases.atom) or consider [watching the GitHub repository](https://github.com/yggdrasil-network/yggdrasil-go) (a "Custom" watch can be used to subscribe to release notifications only). Release notifications are also sent in our [Matrix room](https://matrix.to/#/#yggdrasil:matrix.org).
@@ -43,14 +38,13 @@ Yggdrasil works on Windows and [an MSI installer is available](installation-wind
Yggdrasil is supported on iOS with the following applications:
-- [Yggdrasil for iOS on TestFlight](https://testflight.apple.com/join/jZNsIkRr), reference client based on the [v0.4 release candidate](https://yggdrasil-network.github.io/2021/06/19/preparing-for-v0-4.html) ([source code](https://github.com/yggdrasil-network/yggdrasil-ios))
+- [Yggdrasil for iOS on TestFlight](https://testflight.apple.com/join/jZNsIkRr) ([source code](https://github.com/yggdrasil-network/yggdrasil-ios))
### Android
Yggdrasil is supported on Android with the following applications:
-- [Yggdrasil for Android](https://github.com/yggdrasil-network/yggdrasil-android/releases), reference client based on the [v0.4 release candidate](https://yggdrasil-network.github.io/2021/06/19/preparing-for-v0-4.html)
-- [Crispa for Android](https://github.com/yggdrasil-network/crispa-android/releases), contributed by the community
+- [Yggdrasil for Android](https://github.com/yggdrasil-network/yggdrasil-android/releases) ([source code](https://github.com/yggdrasil-network/yggdrasil-android))
### FreeBSD