Merge pull request #28 from yggdrasil-network/v0.3.0

Documentation for Version 0.3

_posts/2018-12-12-announcing-v0-3.md

@@ -0,0 +1,135 @@
+---
+layout: post
+title:  "Announcing Yggdrasil Network v0.3"
+date:   2018-12-12 00:00:00 -0000
+author: Neil Alexander, Arceliar
+---
+
+### It's finally here
+
+At the end of 2017, Yggdrasil's first commit was uploaded to GitHub - a project
+to explore whether it was possible to build a decentralised, end-to-end
+encrypted and scalable compact routing scheme modelled around the concept of a
+global spanning tree. Many concept routing schemes that we have seen to date
+seem to have problems with scalability - after the network exceeds a certain
+size, they either fail to perform or they start to rely on centralised points in
+order to consolidate routing information. We want to figure out how to build
+something that would not be subject to these limitations, and to maintain
+decentralisation as far as possible, and the best way to test our ideas is to
+build that network. To our knowledge, this hasn't quite been achieved before.
+
+Throughout the course of 2018, Yggdrasil has gone from being a very early-stage
+project supporting only a single platform to a feature-strong and relatively
+stable project which now runs on many supported platforms. Although we currently
+still haven't advanced from the "alpha" label, our network has grown to exceed
+70 nodes across the world (and growing slowly but steadily), with a good portion
+of these users coming on-board and contributing their own
+[services](services.md) to the network and using the network for their own
+purposes. We've even had a small amount of publicity - [Toronto
+Mesh](https://tomesh.net) have been exploring using Yggdrasil on their city-wide
+mesh net, and even [presented some Yggdrasil
+fundamentals](https://www.nuug.no/aktiviteter/20181009-mesh/) to the Norwegian
+Unix User Group (NUUG) back in October.
+
+So far, we believe that Yggdrasil is well on track to delivering on its promises
+to build a fully end-to-end encrypted, self-arranging IPv6 network. We also
+believe that Yggdrasil should be scalable on paper; we have somewhat proven
+this in simulations, but the real proof will come in how the Yggdrasil Network
+scales up in the real world, on real hardware, across real links. Having users
+helping us to test brings us closer to our goal and enhances our understanding
+of how our software will behave on large-scale network graphs.
+
+Version 0.3 has been quite some time coming - we released version 0.2.7 on the
+13th October and we have been working since then on what will make it into this
+release. Even though it feels in some ways that version 0.3 is a relatively
+small evolutionary release, it's actually by far our biggest release yet. We've
+included quite a large list of fixes, changes and even new features and over
+2000 lines of code changed. We've taken a lot of feedback from our users about
+their use-cases and pain points, and we've collected topographical data from
+various contributor nodes to try and get a good view of what the network looks
+like. We've even experienced some rather large topology changes and enjoyed
+relatively good network stability throughout.
+
+For much of the time that we were developing v0.3, we had thought that there
+would end up being protocol-breaking changes and that this would render v0.3
+incompatible with nodes running previous versions. I am happy to announce that
+we have **not** needed to introduce breaking changes at this stage and currently
+the network has been running a mix of both older and newer developmental nodes
+without any particular issues.
+
+### Features
+
+You can see the full list of modifications that have been made in our
+[changelog](changelog.md).
+
+Perhaps the largest user-visible change is the introduction of Crypto-Key
+Routing for traffic tunnelling, allowing you to effectively use Yggdrasil as a
+VPN for both IPv4 and IPv6 traffic between any two given points on the network.
+This tunnelled traffic enjoys the same benefits as regular Yggdrasil IPv6
+traffic in that it is end-to-end encrypted and our many optimisations assist in
+preventing TCP-over-TCP anomalies that often arise in other solutions. I wrote
+an introductory [blog post](_posts/2018-11-06-crypto-key-routing.md) back at the
+beginning of November about CKR, which explains some more about how to configure
+it and how it works.
+
+In the background, we've made a substantial change from using a Kademlia-based
+DHT to a Chord-based DHT. The Chord-based approach allows us to do lookups with
+`O(1)` (constant) state, and only depends on additional (`O(logn)`) state as a
+performance optimisation, which allows us to bootstrap more quickly after
+changes. We also believe that using Chord can help us to reduce some idle DHT
+chatter on the network in the future, which will save a little bandwidth, and
+may be helpful on battery-powered devices.
+
+The spanning tree is now constructed a little differently. Previously, in a
+stable network, each node would select a new parent only if this reduced the
+length of the path to the root of the tree, measured by the number of other
+Yggdrasil nodes in the path. This has the virtue of simplicity, but it sometimes
+leads to poor performance when a node replaces a few low-latency/high-bandwidth
+local links with a comparatively high-latency/low-bandwidth link over the
+internet (or an anonymous overlay like [Tor](https://github.com/yggdrasil-network/public-peers/blob/master/other/tor.md)
+or [I2P](https://github.com/yggdrasil-network/public-peers/blob/master/other/i2p.md)).
+Starting with this release, nodes will switch to a new parent if it provides a
+consistency lower latency path to the root, and its less eager to immediately
+switch again after having just changed parents. This should lead to lower
+latency in stable networks, and better reliability in unstable ones.
+
+We've fixed a reasonable number of bugs and crashes, including in the DHT,
+switch and ICMPv6 code, and have made a number of additions to the admin socket
+in order to support new functionality and to make parameter naming more
+consistent throughout.
+
+### Upgrading
+
+Our CI pipeline automatically produces builds for all supported platforms and
+these will become available on our [Builds page](builds.md). In addition, our S3
+repository for Debian and RPM-based distributions will also be updated with the
+new package releases.
+
+New macOS .pkg installers are now available as a part of the v0.3 release too,
+so installing and upgrading on macOS is now significantly easier than before.
+You can find these installers on the [Builds page](builds.md) also.
+
+On other platforms, simply download the latest binary for your platform and drop
+it into place. Remember to take a backup of your configuration and normalise it,
+which will add any new options for features in v0.3:
+```
+cp /path/to/yggdrasil.conf /var/backups/yggdrasil.conf
+yggdrasil -useconffile /var/backups/yggdrasil.conf -normaliseconf > /path/to/yggdrasil.conf
+```
+
+### What's next?
+
+Our work is far from over. We still have a list of things that can potentially
+be rolled into future releases and we will be looking to see what we should
+prioritise for our next version.
+
+As always, we'll be hanging around in our Matrix/IRC channel too, so please feel
+free to join and chat to us:
+
+- `#yggdrasil:matrix.org` on Matrix
+- `chat.freenode.net` channel `#yggdrasil` on IRC
+
+A big thanks to our contributors, particularly those who have worked on creating
+packages for Yggdrasil and bringing it to their distributions of choice, and to
+all of the users who use Yggdrasil, contributing services and providing feedback
+to us on a regular basis!

admin.md

@@ -10,7 +10,7 @@ The admin socket provides an interface to query and configure Yggdrasil during r
 
 The `yggdrasilctl` utility provides a human-friendly CLI interface to the Yggdrasil admin socket. It can connect to both local and remote Yggdrasil instances, and accepts the same verbs as below. Every field is specified in the `field=value` format.
 
-Examples:
+Examples include:
 ```
 yggdrasilctl getDHT
 yggdrasilctl addPeer uri=tcp://a.b.c.d:e
@@ -19,6 +19,11 @@ yggdrasilctl removePeer port=4
 yggdrasilctl setTunTap name=auto mtu=65535 tap_mode=false
 ````
 
+To get a list of supported commands:
+```
+yggdrasilctl list
+```
+
 To perform an action on a remote Yggdrasil node, specify the `-endpoint` parameter:
 ```
 yggdrasilctl -endpoint=tcp://10.0.0.1:9001 getPeers
@@ -97,10 +102,9 @@ The `"request"` field contains a verb that describes which request to perform.
 Expects no additional request fields.
 
 Returns known nodes in the DHT.
-- `last_seen` (`uint32`) contains the number of seconds since the DHT record was last updated
+- `box_pub_key` (`string`) contains the `EncryptionPublicKey` of the remote node
-- `bucket` (`uint8`) contains the ID of the bucket that the DHT record is stored in
 - `coords` (`string`) contains the coordinates of the node on the spanning tree
-- `peer_only` (`bool`) shows if the node is a peer
+- `last_seen` (`uint32`) contains the number of seconds since the DHT record was last updated
 
 #### `getPeers`
 
@@ -109,8 +113,10 @@ Expects no additional request fields.
 Returns one or more records containing information about active peer sessions. The first record typically refers to the current node.
 
 For each IPv6 address:
+- `box_pub_key` (`string`) contains the `EncryptionPublicKey` of the remote node
 - `bytes_sent` (`uint64`) contains the number of bytes sent to that peer
 - `bytes_recvd` (`uint64`) contains the number of bytes received from that peer
+- `endpoint` (`string`) contains the connected IPv4/IPv6 address and port of the peering
 - `port` (`uint8`) contains the local switch port number for that peer
 - `uptime` (`uint32`) contains the number of seconds since the peer connection was established
 
@@ -143,8 +149,12 @@ Expects no additional request fields.
 Returns zero or more records containing information about switch peers.
 
 For each port number:
+- `box_pub_key` (`string`) contains the `EncryptionPublicKey` of the remote node
+- `bytes_sent` (`uint64`) contains the number of bytes sent to the remote node
+- `bytes_recvd` (`uint64`) contains the number of bytes received from the remote node
 - `coords` (`string`) contains the coordinates of the node on the spanning tree
-- `ip` (`string`) contains the IPv6 address of the node
+- `endpoint` (`string`) contains the connected IPv4/IPv6 address and port of the peering
+- `ip` (`string`) contains the IPv6 address of the remote node
 
 #### `getSelf`
 
@@ -153,7 +163,11 @@ Expects no additional request fields.
 Returns exactly one record containing information about the current Yggdrasil node.
 
 For the current IPv6 address:
+- `box_pub_key` (`string`) contains the `EncryptionPublicKey` of the current node
+- `build_name` (`string`) contains the build name, if available (e.g. `yggdrasil`, `yggdrasil-develop`)
+- `build_version` (`string`) contains the build version, if available (e.g. `0.3.0`, `0.2.7-0091`)
 - `coords` (`string`) contains the coordinates of the node on the spanning tree
+- `subnet` (`string`) contains the routed IPv6 subnet for this host
 
 #### `getSessions`
 
@@ -162,6 +176,7 @@ Expects no additional request fields.
 Returns zero or more records containing information about open sessions between the current Yggdrasil node and other nodes. Open sessions indicate that traffic has been exchanged with the remote node recently.
 
 For each IPv6 address:
+- `box_pub_key` (`string`) contains the `EncryptionPublicKey` of the remote node
 - `bytes_sent` (`uint64`) contains the number of bytes sent across that session
 - `bytes_recvd` (`uint64`) contains the number of bytes received across that session
 - `coords` (`string`) contains the coordinates of the remote node on the spanning tree
@@ -207,3 +222,84 @@ Removes an existing box pub key.
 Returns:
 - Zero or more successful `string` box pub keys in the `"removed"` section
 - Zero or more failed `string` box pub keys in the `"not_removed"` section
+
+#### `getMulticastInterfaces`
+
+Expects no additional request fields.
+
+Returns zero or more strings containing the enabled multicast peering interfaces.
+
+If zero strings are returned then it is implied that multicast peering is not allowed on any interface.
+
+#### `getRoutes`
+
+Expects no additional request fields.
+
+Returns zero or more records where the subnet (`string`) is mapped to the public key (`string`).
+
+#### `addRoute`
+
+Expects:
+- `subnet=` `string` for the subnet to route
+- `box_pub_key=` `string` for the public key to route to
+
+Adds a new crypto-key route.
+
+Returns:
+- Zero or more successful `string` routes in the `"added"` section
+- Zero or more failed `string` routes in the `"not_added"` section
+
+#### `removeRoute`
+
+Expects:
+- `subnet=` `string` for the subnet to remove the route route for
+- `box_pub_key=` `string` for the public key that is routed to
+
+Removes an existing crypto-key route.
+
+Returns:
+- Zero or more successful `string` routes in the `"removed"` section
+- Zero or more failed `string` routes in the `"not_removed"` section
+
+#### `getSourceSubnets`
+
+Expects no additional request fields.
+
+Returns zero or more records for allowed crypto-key routing source subnets (`string`).
+
+#### `addSourceSubnet`
+
+Expects:
+- `subnet=` `string` for the subnet to allow traffic from
+
+Adds a new crypto-key source subnet.
+
+Returns:
+- Zero or more successful `string` source subnets in the `"added"` section
+- Zero or more failed `string` source subnets in the `"not_added"` section
+
+#### `removeSourceSubnet`
+
+Expects:
+- `subnet=` `string` for the subnet to remove
+
+Removes an existing crypto-key source subnet.
+
+Returns:
+- Zero or more successful `string` source subnets in the `"removed"` section
+- Zero or more failed `string` source subnets in the `"not_removed"` section
+
+#### `dhtPing`
+
+Expects:
+- `box_pub_key=` `string`, hex-encoded public key of the remote node to ping, in the same format as e.g. verbose output from a `getDHT` response
+- `coords=` `string`, location of the remote node in the network, in the same format as e.g. a `getDHT` response
+- `target=` `string`, hex-encoded 512-bit NodeID to ask about, affects what the response from the remote node will be, optional
+
+Asks a remote node to respond with information from the DHT
+
+Returns a `nodes` section with information about each node included in the DHT lookup response, indexed by IPv6.
+
+For each IPv6 address, this includes:
+- `box_pub_key` (`string`) contains the `EncryptionPublicKey` of the remote node
+- `coords` (`string`) contains the coordinates of the node on the spanning tree

changelog.md

@@ -25,6 +25,33 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - in case of vulnerabilities.
 -->
 
+## [0.3.0] - 2018-12-12
+### Added
+- Crypto-key routing support for tunnelling both IPv4 and IPv6 over Yggdrasil
+- Add advanced `SwitchOptions` in configuration file for tuning the switch
+- Add `dhtPing` to the admin socket to aid in crawling the network
+- New macOS .pkgs built automatically by CircleCI
+- Add Dockerfile to repository for Docker support
+- Add `-json` command line flag for generating and normalising configuration in plain JSON instead of HJSON
+- Build name and version numbers are now imprinted onto the build, accessible through `yggdrasil -version` and `yggdrasilctl getSelf`
+- Add ability to disable admin socket by setting `AdminListen` to `"none"`
+- `yggdrasilctl` now tries to look for the default configuration file to find `AdminListen` if `-endpoint` is not specified
+- `yggdrasilctl` now returns more useful logging in the event of a fatal error
+
+### Changed
+- Switched to Chord DHT (instead of Kademlia, although still compatible at the protocol level)
+- The `AdminListen` option and `yggdrasilctl` now default to `unix:///var/run/yggdrasil.sock` on BSDs, macOS and Linux
+- Cleaned up some of the parameter naming in the admin socket
+- Latency-based parent selection for the switch instead of uptime-based (should help to avoid high latency links somewhat)
+- Real peering endpoints now shown in the admin socket `getPeers` call to help identify peerings
+- Reuse the multicast port on supported platforms so that multiple Yggdrasil processes can run
+- `yggdrasilctl` now has more useful help text (with `-help` or when no arguments passed)
+
+### Fixed
+- Memory leaks in the DHT fixed
+- Crash fixed where the ICMPv6 NDP goroutine would incorrectly start in TUN mode
+- Removing peers from the switch table if they stop sending switch messages but keep the TCP connection alive
+
 ## [0.2.7] - 2018-10-13
 ### Added
 - Session firewall, which makes it possible to control who can open sessions with your node

configuration.md

@@ -8,27 +8,54 @@ Yggdrasil can be run with a dynamically generated configuration, using sane-ish
 
 In most cases, a static configuration simplifies most setups - it allows you to maintain the same IP address, configure static peers and various other options that will persist across restarts.
 
-Configuration can be provided to Yggdrasil in HJSON format either through `stdin` (using `yggdrasil --useconf < path/to/yggdrasil.conf`) or through a path to a configuration file (using `yggdrasil --useconffile path/to/yggdrasil.conf`).
+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.
 
-A new configuration file may be generated with `yggdrasil --genconf > path/to/yggdrasil.conf`, which looks something like:
+## Generating Configuration
+
+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`.
+
+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 Configuration
+
+Yggdrasil can accept a configuration file either through `stdin` or by being given a path on the filesystem to a configuration file:
+
+- **Using stdin**: `yggdrasilctl --useconf < /etc/yggdrasil.conf`
+- **Using file:** `yggdrasilctl --useconffile /etc/yggdrasil.conf`
+
+## Normalising Configuration
+
+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.
+
+- **Convert from HJSON to JSON**: `yggdrasilctl -normaliseconf -useconffile /etc/yggdrasil.conf -json`
+- **Convert from JSON to HJSON**: `yggdrasilctl -normaliseconf -useconffile /etc/yggdrasil.conf`
+
+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.
+
+## Configuration Layout
+
+A new configuration file has the following format. Please note that some of the default values will vary from platform to platform.
 
 ```
 {
   # Listen address for peer connections. Default is to listen for all
   # TCP connections over IPv4 and IPv6 with a random port.
-  Listen: "[::]:52072"
+  Listen: "[::]:xxxxx"
 
   # Listen address for admin connections Default is to listen for local
   # connections either on TCP/9001 or a UNIX socket depending on your
   # platform. Use this value for yggdrasilctl -endpoint=X.
   AdminListen: tcp://localhost:9001
 
-  # List of connection strings for static peers in URI format, i.e.
+  # List of connection strings for static peers in URI format, e.g.
   # tcp://a.b.c.d:e or socks://a.b.c.d:e/f.g.h.i:j.
   Peers: []
 
   # List of connection strings for static peers in URI format, arranged
-  # by source interface, i.e. { "eth0": [ tcp://a.b.c.d:e ] }. Note that
+  # by source interface, e.g. { "eth0": [ tcp://a.b.c.d:e ] }. Note that
   # SOCKS peerings will NOT be affected by this option and should go in
   # the "Peers" section instead.
   InterfacePeers: {}
@@ -109,6 +136,43 @@ A new configuration file may be generated with `yggdrasil --genconf > path/to/yg
     # regardless of the whitelist, AllowFromDirect or AllowFromRemote.
     BlacklistEncryptionPublicKeys: []
   }
+
+  # Allow tunneling non-Yggdrasil traffic over Yggdrasil. This effectively
+  # allows you to use Yggdrasil to route to, or to bridge other networks,
+  # similar to a VPN tunnel. Tunnelling works between any two nodes and
+  # does not require them to be directly peered.
+  TunnelRouting:
+  {
+    # Enable or disable tunnel routing.
+    Enable: false
+
+    # IPv6 CIDR subnets, mapped to the EncryptionPublicKey to which they  
+    # should be routed, e.g. { "aaaa:bbbb:cccc::/e": "boxpubkey", ... }
+    IPv6Destinations: {}
+
+    # Optional IPv6 source subnets which are allowed to be tunnelled in  
+    # addition to this node's Yggdrasil address/subnet. If not  
+    # specified, only traffic originating from this node's Yggdrasil  
+    # address or subnet will be tunnelled.
+    IPv6Sources: []
+
+    # IPv4 CIDR subnets, mapped to the EncryptionPublicKey to which they  
+    # should be routed, e.g. { "a.b.c.d/e": "boxpubkey", ... }
+    IPv4Destinations: {}
+
+    # IPv4 source subnets which are allowed to be tunnelled. Unlike for  
+    # IPv6, this option is required for bridging IPv4 traffic. Only  
+    # traffic with a source matching these subnets will be tunnelled.
+    IPv4Sources: []
+  }
+
+  # Advanced options for tuning the switch. Normally you will not need
+  # to edit these options.
+  SwitchOptions:
+  {
+    # Maximum size of all switch queues combined (in bytes).
+    MaxTotalQueueSize: 4194304
+  }
 }
 ```
 
@@ -124,7 +188,7 @@ Note that any field not specified in the configuration will use its default valu
     - Port to listen on for the admin socket, specified in URI format, i.e. `tcp://localhost:9001`.
     - On supported platforms, the admin socket can listen on a UNIX domain socket instead, i.e. `unix:///var/run/yggdrasil.sock`.
     - The default is to listen on the loopback interface (`tcp://localhost:9001`) which ensures that only local connections to the admin socket are allowed.
-    - Note that if you change the listen address to a non-loopback address, this will allow other hosts on the network to manage the Yggdrasil process. This probably isn't desirable.
+    - Note that if you change the listen address to a non-loopback address, this may allow other hosts on the network to manage the Yggdrasil process. This probably isn't desirable.
 - `Peers`
     - A list of strings in the form `[ "tcp://peerAddress:peerPort", "socks://proxyAddress:proxyPort/peerAddress:peerPort", ... ]` of peers to connect to.
     - Peer hostnames can be specified either using IPv4 addresses, IPv6 addresses or DNS names.
@@ -142,13 +206,13 @@ Note that any field not specified in the configuration will use its default valu
     - A node's IP address is derived from the ID.
 - `EncryptionPrivateKey`
     - A hexadecimal string representing the node's private Curve25519 key.
-    - This is a private key, don't share it.
+    - This is a private key, **don't share it with anyone**.
 - `SigningPublicKey`
     - A hexadecimal string representing a node's public Ed25519 key.
     - Used primarily for signatures in the greedy routing scheme.
 - `SigningPrivateKey`
     - A hexadecimal string representing the node's private Ed25519 key.
-    - This is a private key, don't share it.
+    - This is a private key, **don't share it with anyone**.
 - `MulticastInterfaces`
     - A list of regex strings for matching which interfaces to enable multicast peer discovery on. Interfaces that don't match any of the provided regexes are ignored.
     - The default value (`.*`) matches all interfaces.
@@ -160,13 +224,14 @@ Note that any field not specified in the configuration will use its default valu
     - The behaviour of this option is different on different operating systems. Some quick notes:
         - On Linux, any suitable interface name can be specified.
         - On FreeBSD, OpenBSD and NetBSD, a full path to the TAP interface should be specified, i.e. `"/dev/tap0"`.
-        - On macOS, a utun device is automatically assigned by the operating system, therefore you cannot specify a name.
+        - On macOS, a `utun` device is automatically assigned by the operating system, therefore you cannot specify a name.
         - On Windows, a network adapter friendly name (like `"Local Area Connection 2"`) can be specified to choose a specific adapter. Use "Network Adapters" in Control Panel to see and/or rename adapters.
 - `IfTAPMode`
     - If true, then the interface will be a `tap` device (Layer 2) instead of a `tun` (Layer 3) device.
     - Default value is platform specific, and some platforms support only `tun` or `tap` mode.
     - Note that the network only transports IPv6 packets, so frames sent to or received from a `tap` are decapsulated or encapsulated at the end points of a connection.
     - In TAP mode, Yggdrasil automatically answers Neighbor Discovery Packet (NDP) requests on behalf of Yggdrasil IPv6 addresses.
+    - In TAP mode, it may be possible to bridge with the Yggdrasil `tap` adapter, e.g. to allow container bridging.
 - `IfMTU`
     - The MTU of the `tun`/`tap` interface.
     - Defaults to the maximum value supported on each platform, up to `65535` on Linux/macOS/Windows, `32767` on FreeBSD, `16384` on OpenBSD, `9000` on NetBSD, etc.
@@ -178,17 +243,42 @@ Note that any field not specified in the configuration will use its default valu
             - Disables or enables the session firewall.
             - If enabled, the rules from the below options apply. If disabled, all traffic is allowed.
         - `AllowFromDirect`
-            - Allows traffic from nodes that are direct peers.
+            - Decides whether or not traffic should be allowed from nodes that are directly peered to you.
         - `AllowFromRemote`
-            - Allows traffic from nodes that are not direct peers.
+            - Decides whether or not traffic should be allowed from nodes that are elsewhere on the network and *not* directly peered to you.
         - `AlwaysAllowOutbound`
-            - Allows traffic to a node only when outbound traffic is sent to that node.
+            - Decides whether to allow traffic to be sent to any node on the network, as long the connection is initiated from your node.
+            - Note that once you open a session with a remote node, they *can* send traffic back to you for the lifetime of the session.
         - `WhitelistEncryptionPublicKeys`
-            - A list of node's `EncryptionPublicKey` keys that are always allowed to send traffic to this host.
+            - A list of node's `EncryptionPublicKey` keys that are always allowed to exchange traffic with this host, both incoming or outgoing.
             - Takes priority over the above options, but is overridden by the blacklist below.
         - `BlacklistEncryptionPublicKeys`
-            - A list of node's `EncryptionPublicKey` keys that are never allowed to communicate with this node under any circumstances.
+            - A list of node's `EncryptionPublicKey` keys that are never allowed to communicate with this node under any circumstances, both incoming or outgoing.
             - Takes priority over all other options.
+- `TunnelRouting`
+    - Crypto-key tunnel routing allows you to tunnel either IPv4 or IPv6 traffic to remote nodes over Yggdrasil. This is similar to using a VPN.
+    - Contains the following configuration options:
+        - `Enable`
+            - Enables crypto-key routing.
+            - If enabled, the following crypto-key routes will be used by Yggdrasil. If disabled, the below options have no effect.
+        - `IPv6Destinations`
+            - A list of routes in the form `{ "aaaa:bbbb:cccc::/e": "EncryptionPublicKey", ... }`
+            - For each entry, an IPv6 route entry will be created that sends traffic destined for `aaaa:bbbb:cccc::/e` to the node with the specified `EncryptionPublicKey` (effectively your "remote" ranges).
+        - `IPv6Sources`
+            - A list of allowed source subnets in the form `[ "aaaa:bbbb:cccc::/e" ]`
+            - Specifies a list of source IPv6 addresses which are allowed to be sent over the tunnel (essentially your "local" ranges).
+            - Traffic from the Yggdrasil node's IPv6 address and routed subnet are always allowed.
+        - `IPv4Destinations`
+            - A list of routes in the form `{ "a.b.c.d/e": "EncryptionPublicKey", ... }`
+            - For each entry, an IPv4 route entry will be created that sends traffic destined for `a.b.c.d/e` to the node with the specified `EncryptionPublicKey` (effectively your "remote" ranges).
+        - `IPv4Sources`
+            - A list of allowed source subnets in the form `[ "a.b.c.d/e" ]`
+            - Specifies a list of source IPv4 addresses which are allowed to be sent over the tunnel (essentially your "local" ranges).
+- `SwitchOptions`
+    - Switch options are advanced tuning settings. Ordinarily you should not attempt to change these from their defaults.
+    - Contains the following configuration options:
+        - `MaxTotalQueueSize`
+            - The maximum allowed size, in bytes, of all local switch queues combined. Default is `4194304` (or 4MB).
 
 # Use Cases
 
@@ -200,7 +290,7 @@ As the network uses ordinary TCP, it is possible to connect over other networks,
 
 By default, connections to peers are made over TCP. It is possible to route through a `socks://proxyAddr:proxyPort/` connection.
 This uses TCP over the specified SOCKS proxy, and can be used to tunnel out from a network with a particularly restrictive firewall, for example, using SSH tunneling.
-This can also be used to [connect over Tor](https://github.com/yggdrasil-network/public-peers/blob/master/other/tor.md), particularly for `.onion` hidden service addresses.
+This can also be used to [connect over Tor](https://github.com/yggdrasil-network/public-peers/blob/master/other/tor.md), particularly for `.onion` hidden service addresses, although this does have a number of performance issues and is not generally recommended.
 
 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.
 

index.md

@@ -7,13 +7,13 @@ sitemap: true
 
 Yggdrasil is an early-stage implementation of a fully end-to-end encrypted IPv6 network. It is lightweight, self-arranging, supported on multiple platforms and allows pretty much any IPv6-capable application to communicate securely with other Yggdrasil nodes. Yggdrasil does not require you to have IPv6 Internet connectivity - it also works over IPv4.
 
-Although Yggdrasil shares many similarities with [cjdns](https://github.com/cjdelisle/cjdns), it employs a different routing algorithm based on a globally-agreed spanning tree and greedy routing in a metric space, and aims to implement some novel local backpressure routing techniques. In theory, an Yggdrasil network should scale well on networks with internet-like topologies. Take a look at the [About](about.md) page for a detailed overview.
+Although Yggdrasil shares many similarities with [cjdns](https://github.com/cjdelisle/cjdns), it employs a different routing algorithm based on a globally-agreed spanning tree and greedy routing in a metric space, and aims to implement some novel local backpressure routing techniques. In theory, Yggdrasil should scale well on networks with internet-like topologies. Take a look at the [About](about.md) page for a detailed overview.
 
 ## Project Status
 
-The project is currently in very early stages but it is being actively developed. We have already passed our first [alpha release](https://github.com/yggdrasil-network/yggdrasil-go/milestone/1) and are now regularly releasing updates.
+The project is currently in early stages but it is being actively developed. We have recently made our biggest release yet - [version 0.3.0](changelog.md) - and are still regularly working on updates.
 
-A small number of users have been using and stress-testing Yggdrasil quite heavily for a number of purposes, including but not limited to secure remote access (SSH and VNC), access to Matrix, Jabber and IRC servers (including a Matrix-IRC bridge that runs solely over Yggdrasil) and even some video streams, large file transfers and performance tests.
+A small number of users have been using and stress-testing Yggdrasil quite heavily for a number of purposes, including but not limited to secure remote access (SSH and VNC), access to Matrix, Jabber and IRC servers and even some video streams, large file transfers and performance tests. We have a number of [internal services](services.md) available, contributed and operated by the community.
 
 It is entirely possible that occasional breaking changes may still happen in future versions but generally Yggdrasil works well and has proven to be reasonably stable so far, with recent builds reaching weeks of uptime without crashes or failures.
 

platform-linux.md

@@ -155,9 +155,9 @@ journalctl -u yggdrasil
 ## Build instructions
 
 Linux has most of the tools needed to build Yggdrasil from source - you just
-need to install Go 1.9 or later.
+need to install Go 1.11 or later.
 
-1. Install Go 1.9 or later, [godeb](https://github.com/niemeyer/godeb) is
+1. Install Go 1.11 or later, [godeb](https://github.com/niemeyer/godeb) is
 recommended for Debian-based distributions).
 1. Open a shell, clone the repository and build:
 ```

platform-macos.md

@@ -16,6 +16,16 @@ Yggdrasil is well supported on macOS out of the box, thanks to the inclusion of
 
 ## Installation
 
+### Using the macOS installer
+
+Visit the [Builds](builds.md) page and download the relevant `-macos-amd64.pkg` (64-bit) or `-macos-i386.pkg` (32-bit) package file.
+
+Once downloaded, open the Downloads folder in Finder, right-click the package and click "Open".
+
+(Alternatively, double-click and then use System Preferences > Security to "Open Anyway" after the developer prompt.)
+
+### Manual installation
+
 System Integrity Protection in macOS prevents you from copying files into `/usr/bin`, therefore you should install into `/usr/local/bin` instead. This may not exist by default so create it if it doesn't exist:
 ```
 sudo mkdir -p /usr/local/bin
@@ -77,7 +87,7 @@ sudo launchctl unload /Library/LaunchDaemons/yggdrasil.plist
 
 ## Build instructions
 
-macOS has most of the tools needed to build Yggdrasil from source - you just need to install Go 1.9 or later.
+macOS has most of the tools needed to build Yggdrasil from source - you just need to install Go 1.11 or later.
 
 1. Download the latest [Go .pkg installer for macOS](https://golang.org/dl/)
 1. Run the installer to install Go on your system

platform-windows.md

@@ -67,8 +67,8 @@ sc config yggdrasil start= "auto"
 sc start yggdrasil
 ```
 Alternatively, if you want the service to autoconfigure instead of using an `yggdrasil.conf`, replace the `sc create` line from above with:
-  ```
+```
-  sc create yggdrasil binpath= "\"C:\Program Files\Yggdrasil\yggdrasil.exe\" -autoconf"
+sc create yggdrasil binpath= "\"C:\Program Files\Yggdrasil\yggdrasil.exe\" -autoconf"
-  ```
+```
 
 The Yggdrasil service can then be stopped and started using `services.msc`, or in more recent versions of Windows, the Task Manager.