Release v0.3.13

21 February 2020 by 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, 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 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. If you are interested, please reach out!