From 269474ba826ac8ce782429938281f5836cebd04f Mon Sep 17 00:00:00 2001 From: Neil Alexander Date: Mon, 17 Feb 2020 20:15:50 +0000 Subject: [PATCH 1/4] Update for Windows documentation --- index.md | 2 +- installation-windows.md | 96 ++++++++++++++++++++++------------------- installation.md | 2 +- platform-windows.md | 19 -------- platforms.md | 4 -- 5 files changed, 53 insertions(+), 70 deletions(-) delete mode 100644 platform-windows.md diff --git a/index.md b/index.md index c79e38c..9a82b36 100644 --- a/index.md +++ b/index.md @@ -11,7 +11,7 @@ Although Yggdrasil shares many similarities with [cjdns](https://github.com/cjde ## Project Status -The project is currently in early stages but it is being actively developed. We have recently released [version 0.3.12](changelog.md) and are still regularly working on updates. +The project is currently in early stages but it is being actively developed. We have recently released [version 0.3.13](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 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. diff --git a/installation-windows.md b/installation-windows.md index 0aa0a57..b3de26e 100644 --- a/installation-windows.md +++ b/installation-windows.md @@ -3,61 +3,67 @@ tags: dontlink sitemap: true --- -# Installing manually on Windows +# Installing using the Windows installer -Yggdrasil is supported on Windows. You can either [download the latest binary from CircleCI](builds.md). +Yggdrasil is supported on Windows. You can [download the latest installer from +GitHub](https://github.com/yggdrasil-network/yggdrasil-go/releases). -## TAP Driver +## TUN driver -Yggdrasil depends on the OpenVPN TAP driver to work on Windows. There are two flavours of this driver: +Starting with version 0.3.13, Yggdrasil on Windows uses the Wireguard TUN +driver. If this is not installed on the system already, it will be installed +automatically by the Yggdrasil installer. -- [NDIS 5](https://swupdate.openvpn.org/community/releases/tap-windows-9.9.2_3.exe) (`tap-windows-9.9.2_3`) - recommended -- [NDIS 6](https://swupdate.openvpn.org/community/releases/tap-windows-9.21.2.exe) (`tap-windows-9.21.2`) - functional +For this reason, it is important that you use the correct installer for your +architecture - make sure to use the `x64` installer on 64-bit Windows and the +`x86` installer on 32-bit Windows. -Yggdrasil works with either driver, although the performance is remarkably better with the older NDIS 5 driver, therefore it is recommended to use that instead of the NDIS 6 driver. +Please note that the OpenVPN TAP driver is **no longer supported**. -Please note that if you already have OpenVPN for Windows, you likely have one of the two drivers installed already and should not install it again. +Once Yggdrasil is started, a new virtual network adapter will be created called +`Yggdrasil` by default, although this can be renamed using the `IfName` option +in the configuration file (below). The virtual network adapter will *not* be +visible on the system when Yggdrasil is not running. -## Installation +## Configuration -Start by [downloading the latest Yggdrasil binary](builds.md) and use Windows Explorer to copy it into a sensible location and rename it to `yggdrasil.exe`. +The Yggdrasil installer will automatically generate an `yggdrasil.conf` +configuration file, if one does not exist, in the following locations: -The below examples assume that you placed `yggdrasil.exe` into `C:\Program Files\Yggdrasil`. +- 64-bit Windows: `C:\Program Files\Yggdrasil` +- 32-bit Windows: `C:\Program Files (x86)\Yggdrasil` -## Generate configuration +## Windows Service -Before starting Yggdrasil, you should generate configuration. Open a Command Prompt as Administrator: +Yggdrasil is installed as a Windows service that starts automatically with +Windows. You can start, stop and restart Yggdrasil using the Services MMC +snap-in (`services.msc`) or, in more recent versions of Windows, the "Services" +tab in Task Manager. + +You will need to restart the Yggdrasil service after each change to the +configuration file. + +## Windows Firewall + +Windows Firewall may prompt for the Yggdrasil process to allow incoming or +outgoing connections. If so, you should allow this or Yggdrasil may not be able +to establish peerings correctly. + +Note that Yggdrasil, by default, does allow incoming traffic over the +`Yggdrasil` virtual adapter, therefore you may wish to designate the `Yggdrasil` +virtual network adapter as a public network in the Windows Firewall so that +unexpected incoming connections are blocked automatically. + +If you do, pay particular attention to ensure that file sharing (SMB), remote +procedure call (RPC) or remote desktop (RDP) services are not allowed on public +networks unless you explicitly need them to be accessible from remote Yggdrasil +hosts. + +## yggdrasilctl + +The `yggdrasilctl` utility is also installed into the same location above. You +can query Yggdrasil's runtime state using this tool using a Command Prompt or +PowerShell command line, e.g. ``` -"C:\Program Files\Yggdrasil\yggdrasil.exe" -genconf > "C:\Program Files\Yggdrasil\yggdrasil.conf" +"C:\Program Files\Yggdrasil\yggdrasilctl.exe" getPeers ``` - -## Run Yggdrasil - -### Run once - -Open a Command Prompt as Administrator and start Yggdrasil using your generated configuration: -``` -"C:\Program Files\Yggdrasil\yggdrasil.exe" -useconffile "C:\Program Files\Yggdrasil\yggdrasil.conf" -``` -Alternatively, start Yggdrasil in auto-configuration mode: -``` -"C:\Program Files\Yggdrasil\yggdrasil.exe" -autoconf -``` - -### Run as a background service - -Running as a background system service means that Yggdrasil will automatically start up in the background when Windows boots. - -Assuming that Yggdrasil is installed into `C:\Program Files\Yggdrasil` and your configuration *already exists* in `C:\Program Files\Yggdrasil\yggdrasil.conf`, as above, then you can install Yggdrasil as a Windows service. Open a Command Prompt as Administrator: -``` -sc create yggdrasil binpath= "\"C:\Program Files\Yggdrasil\yggdrasil.exe\" -useconffile \"C:\Program Files\Yggdrasil\yggdrasil.conf\"" -sc config yggdrasil displayname= "Yggdrasil Service" -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" -``` - -The Yggdrasil service can then be stopped and started using `services.msc`, or in more recent versions of Windows, the Task Manager. diff --git a/installation.md b/installation.md index cced1eb..d1abc02 100644 --- a/installation.md +++ b/installation.md @@ -24,4 +24,4 @@ Installation guides are available for the following platforms/distributions. ## Windows -- [Manual install as a Windows service](installation-windows.md) +- [Windows `.msi` installer](installation-windows.md) diff --git a/platform-windows.md b/platform-windows.md deleted file mode 100644 index 626fc2e..0000000 --- a/platform-windows.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -tags: dontlink -sitemap: true ---- - -# Windows - -Yggdrasil has been tested and is working on the following versions of Windows: - -- Windows 7 -- Windows 8.1 -- Windows 10 -- Windows Server 2016 - -It may work on other versions of Windows too, although these are untested. - -## Notes - -- TUN mode is not supported on Windows, and attempts to configure TUN mode will default to TAP mode automatically. diff --git a/platforms.md b/platforms.md index eed9c31..9b97067 100644 --- a/platforms.md +++ b/platforms.md @@ -16,10 +16,6 @@ sitemap: true - See the [iOS platform page](platform-ios.md). -## Windows - -- See the [Windows platform page](platform-windows.md). - ## EdgeRouter - See the [EdgeRouter platform page](platform-edgerouter.md). From 30bbb91cbfcf31d2c12e62d2982b481ed1739d68 Mon Sep 17 00:00:00 2001 From: Neil Alexander Date: Mon, 17 Feb 2020 20:17:04 +0000 Subject: [PATCH 2/4] Update gems --- Gemfile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Gemfile b/Gemfile index f419341..51cbf65 100644 --- a/Gemfile +++ b/Gemfile @@ -7,3 +7,5 @@ gem "jekyll-feed", "~> 0.11.0" gem "jekyll-sitemap", "~> 1.2" gem "github-pages", group: :jekyll_plugins + +gem "nokogiri", ">= 1.10.4" From 30b08f6eb2757607c87f10744a2f116ff11dbdc8 Mon Sep 17 00:00:00 2001 From: Neil Alexander Date: Mon, 17 Feb 2020 22:55:25 +0000 Subject: [PATCH 3/4] Add blog post --- _posts/2020-02-21-release-v0-3-13.md | 121 +++++++++++++++++++++++++++ index.md | 2 +- 2 files changed, 122 insertions(+), 1 deletion(-) create mode 100644 _posts/2020-02-21-release-v0-3-13.md diff --git a/_posts/2020-02-21-release-v0-3-13.md b/_posts/2020-02-21-release-v0-3-13.md new file mode 100644 index 0000000..623a808 --- /dev/null +++ b/_posts/2020-02-21-release-v0-3-13.md @@ -0,0 +1,121 @@ +--- +layout: post +title: "Release v0.3.11" +date: 2020-02-21 09:00:00 +0000 +author: Neil Alexander +--- + +### Release time! + +Our last Yggdrasil release, v0.3.12, was merged a couple of months ago at the +end of November. For the most part we have seen good stability with the v0.3.12 +builds, not to mention good adoption (with the crawler showing over 500 nodes +running it). Today we are releasing our next version, v0.3.13. + +Many of our releases tend not to warrant blog post entries, especially given +that the changelog documents the changes. However, there's some fairly big news +points associated with this version therefore this post aims to discuss them in +a bit more detail. + +#### TUN adapter changes + +The first big talking point is that this is the first Yggdrasil release that +departs entirely from the Water library and replaces it with the Wireguard TUN +library. There are a few reasons why we decided to switch from Water to the +Wireguard library, but one of the most prominent is that it gives us better TUN +support across all platforms and allows us to finally remove TAP support +altogether. + +At a high-level, TUN interfaces are effectively emulating "Layer 3" interfaces - +they deal only in IP packets - whereas TAP interfaces are emulating "Layer 2" +full-fat Ethernet interfaces. + +To run in TAP mode, Yggdrasil not only had to add and remove Ethernet headers +for each packet, but it also has to implement an entire NDP implementation and +track MAC addresses in order to trick the host operating system into believing +that there was a real Ethernet domain on the other end of the adapter. Needless +to say, the amount of boilerplate code in order to make TAP mode work correctly +was significant and much of that code was very fragile. + +Although we implemented NDP, we did not ever get around to implementing ARP, +which also meant that sending tunnel-routed IPv4 traffic over TAP interfaces +invariably did not work either. We have now been able to remove much of this +code and simplify the TUN code massively, closing the gaps between some of our +supported platforms. + +There is one platform that is negatively impacted by this change and that's +NetBSD. The Wireguard TUN package that we are using currently has **no support +for NetBSD**, so we are also removing NetBSD as a supported target until the +necessary code appears upstream. To our knowledge, we don't have a base of +NetBSD users anyway, but we will aim to re-add this soon. + +The `IfTAPMode` configuration option has now been removed from Yggdrasil +entirely and it will be ignored if specified. **If you are using TAP mode today, +then this will affect you**. Please make sure to check your Yggdrasil +configuration since this may result in interface naming changes and you may have +to update network settings in your host operating system. + +Initially we added TAP support into Yggdrasil as it was the only way to support +Windows, since the OpenVPN driver that we used at the time only supported TAP +mode. Thankfully, this is no longer a problem, as the Wireguard project have +also released [Wintun](https://wintun.net), which is supported by the Wireguard +TUN library. The net result is that we gain TUN support on Windows and the +performance is *far* better than the buggy OpenVPN driver, which is a nice segue +into... + +#### Windows installer and performance + +We have spent a lot of time trying to improve the installation and setup +experience on Windows. This mostly falls into two areas. + +The first is that using the Wintun driver has *massively* improved performance, +in some cases by hundreds of MB/s, and starting the Yggdrasil process is now +much more reliable too - it should no longer be necessary to restart Yggdrasil +due to cases of the TAP adapter not being set up or configured correctly. + +The second is that we now automatically generate Windows `.msi` installers using +Appveyor, which means that installing or upgrading Yggdrasil is now simpler than +ever. It is no longer necessary to create directories, copy files and register +Windows services by hand - a marked improvement! + +The installer also bundles the Wintun driver and it is installed automatically +if required, therefore there is no longer a need to hunt down and install the +OpenVPN TAP driver separately. We hope that these changes will help to encourage +adoption of Yggdrasil on Windows platforms by significantly reducing the barrier +to entry. + +As in the previous section, Yggdrasil on Windows has gone from supporting TAP +mode only to now supporting TUN mode only. **This may mean that you need to +review your configuration**. If you no longer need the OpenVPN TAP driver on +your system, it is best to entirely uninstall it. It is also important to make +sure that the `IfName` configuration option in your `yggdrasil.conf` does not +specify the same name as an existing OpenVPN TAP interface or Yggdrasil may fail +to start. + +#### End of the v0.3 release cycle + +Generally we try, where possible, to avoid make any changes which would damage +backward compatibility with previous versions. The last version that had +breaking changes was v0.2.1 - over a year and a half ago. However, maintaining +backward compatibility so tightly also prevents us from improving the Yggdrasil +design in various ways. + +Therefore, unless any serious bugs or security vulnerabilities appear, it is +very likely that this version will be the last in the v0.3 release cycle. +Instead, we will start working on the v0.4 release, which is likely to include a +number of breaking protocol changes and will be incompatible with v0.3 releases +as a result. + +More information will be announced on the types of changes in v0.4 as they +happen - expect to see more blog posts and chatter in the Matrix channel on this +subject - but we will aim to give as much notice as possible before releases +occur that contain breaking changes. + +#### Final mentions + +In addition to the release notes above, I'd like to relay the message that +[@mwarning](https://github.com/mwarning) has a proposal open for a Google Summer +of Code (GSoC) project under the Freifunk umbrella, comparing a number of mesh +routing protocols including Yggdrasil. More information about the proposal is +available [here](https://projects.freifunk.net/#/projects?project=freifunk_meshnet_protocol_evaluation&lang=en). +If you are interested, please reach out! diff --git a/index.md b/index.md index 9a82b36..d8c06e7 100644 --- a/index.md +++ b/index.md @@ -21,7 +21,7 @@ Binaries are [automatically built](https://circleci.com/gh/yggdrasil-network/ygg ## Implementation -Yggdrasil is written in Go. The codebase is fairly small and easy to navigate. It has been tested on a number of platforms (including [Linux](platform-linux.md), [Windows](platform-windows.md), [macOS](platform-macos.md), NetBSD, FreeBSD, OpenBSD and [Ubiquiti EdgeOS](platform-edgerouter.md)) although with various minor caveats. See the [Platforms](platforms.md) page for more information. +Yggdrasil is written in Go. The codebase is fairly small and easy to navigate. It has been tested on a number of platforms (including [Linux](platform-linux.md), [Windows](platform-windows.md), [macOS](platform-macos.md), FreeBSD, OpenBSD and [Ubiquiti EdgeOS](platform-edgerouter.md)) although with various minor caveats. See the [Platforms](platforms.md) page for more information. ## Get Involved From 0f132952ba27f7a3e974d5ae06e60303af1b6819 Mon Sep 17 00:00:00 2001 From: Neil Alexander Date: Tue, 18 Feb 2020 18:47:41 +0000 Subject: [PATCH 4/4] Update 2020-02-21-release-v0-3-13.md --- _posts/2020-02-21-release-v0-3-13.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_posts/2020-02-21-release-v0-3-13.md b/_posts/2020-02-21-release-v0-3-13.md index 623a808..e4f2fac 100644 --- a/_posts/2020-02-21-release-v0-3-13.md +++ b/_posts/2020-02-21-release-v0-3-13.md @@ -1,6 +1,6 @@ --- layout: post -title: "Release v0.3.11" +title: "Release v0.3.13" date: 2020-02-21 09:00:00 +0000 author: Neil Alexander ---