Automatic Management of ZeroTier Tunnels through OpenWISP

7 min readAug 20, 2023
Google Summer Of Code 2023 @OpenWISP

This summer has been incredibly productive. I had the privilege of working on “Adding Support For Automatic Management of ZeroTier Tunnels” in collaboration with OpenWISP, guided by my supportive mentors: Federico Capaono (nemesifier), Gagan Deep (pandafy), and Ajay Tripathi (atb00ker).

Let’s take a closer look at what we have achieved this summer ☀

Before GSoC

Last year, I was fortunate to be selected as a GSoC contributor, where I added an Iperf3 check to OpenWISP Monitoring. If you haven’t had a chance to check out that project, you can find my project report here.

Following my participation in GSoC, I immediately continued my contributions to various OpenWISP modules, including OpenWISP Controller, OpenWISP Network Topology, Netjsonconfig, and OpenWISP OpenWRT packages. This allowed me to gain a deeper understanding of how these modules are interconnected. During this exploration, I found the controller and topology modules particularly intriguing.

I started by familiarizing myself with their existing features, which included VPN automation with OpenVPN and WireGuard, configuration templates, variables, device groups, and network topologies. One day, while troubleshooting Docker OpenWISP installation issues, I needed to test changes on my remotely located router. To do this, I began searching for remote access solutions.

That’s when I came across ZeroTier, often described as:

A global Ethernet switch that allows you to build modern, secure multi-point virtualized networks of almost any type — docs

On that day, I relied on ngrok tunnels for testing, which turned out to be a lifesaver. In the following days, I delved deeper into the capabilities of ZeroTier.

ZeroTier has gained popularity for various useful applications, including:

  • Windows Remote Desktop
  • Secure device connections via SSH
  • Creating private gaming LANs
  • Accessing web interfaces of home lab devices
  • Establishing personal VPNs
  • Routing to remote subnets
  • Connecting to Docker networks
  • Adding DNS to your network

I was aware of a GSoC project introduced last year to integrate ZeroTier with OpenWISP, offering learning opportunities in VPN automation for contributors. Upon reviewing the project’s expected outcomes, I noticed its dependency on three core OpenWISP modules: netjsonconfig, controller, and topology. Consequently, I committed myself to enhancing my understanding of and contributing to these essential modules.

After Selection

Surprisingly, I was the only GSoC contributor selected with OpenWISP this year. Following my selection, I was invited to attend a community meeting with the mentors. During this meeting, we discussed my motivation for the project and reviewed my proposal. Additionally, I was tasked with creating all the necessary issues for my project, aligning with the plan outlined in the project proposal, just as I did last year.

About Project

What is Netjsonconfig?

A python library that converts NetJSON DeviceConfiguration objects into real router configurations that can be installed on systems like OpenWRT, LEDE or OpenWISP Firmware — docs

The goal of my project was to implement support for the automatic management of ZeroTier tunnels through OpenWISP. To achieve this, my initial task was to integrate a VPN backend into the netjsonconfig library, responsible for generating configurations — in our case, ZeroTier network configurations.

Adding Support for ZeroTier VPN backend

ZeroTier VPN Network Configuration

At the outset, we already had support for two popular open-source VPN backends: OpenVPN and WireGuard. In a similar manner, I implemented a ZeroTier VPN backend class. During the initial implementation phase, I had some doubts about the format of the ZeroTier network configuration. However, I later discovered that it uses a straightforward JSON format, which we could use to automate network management through the ZeroTier Service API in OpenWISP Controller.

Furthermore, in the netjsonconfig library, every configuration is validated against its defined JSON schema. For the ZeroTier schema, I utilized their OpenAPI schema from both the self-hosted controller and central controllers.

Pull Requests 🔃

Adding Support of ZeroTier to OpenWRT backend

ZeroTier VPN Client Template Configuration

In the second part, I added support for a ZeroTier converter to the existing OpenWRT backend. This addition allows us to generate ZeroTier UCI configurations, which are utilized by the VPN client templates in the OpenWISP controller. With this support, users can effortlessly generate a wide range of ZeroTier OpenWRT configurations, whether it involves configuring custom ZeroTier interface name, managing multiple ZeroTier networks, or handling configurations for multiple ZeroTier services.

Pull Requests 🔃

What is OpenWISP Controller?

Network and WiFi controller: provisioning, configuration management and updates, (pull via openwisp-config or push via SSH), x509 PKI management and more. Mainly OpenWRT, but designed to work also on other systems — docs

ZeroTier Tunnel Setup with OpenWISP

I already had experience with the connection app of the OpenWISP controller due to my last year’s GSoC project. However, for this project, I needed to primarily work with the config app of the OpenWISP controller. So, before adding support for the ZeroTier VPN backend, I explored some of the features offered by this module. These features include configuration templates, variables, VPN servers, and more. Once I familiarized myself with these aspects, I began working on integrating the ZeroTier Service API to completely manage ZeroTier self-hosted controllers networks through OpenWISP.

ZeroTier Service Class

I began working on the implementation of the ZeroTier Service class within the config app. This class includes various methods for managing ZeroTier service operations, such as CRUD operations on networks and network members (OpenWRT devices in our case), with robust error handling. The implementation of this class was done with extensibility in mind, making it adaptable whenever the need arises.

ZeroTier Background API Tasks

ZeroTier Background API Tasks Notifications For Unrecoverable Failures

Most of the ZeroTier network management operations are executed in the background via Celery workers. These operations include updates, deletions, IP assignments, and authorizations of network members. However, the creation of a ZeroTier network is synchronous to provide a better user experience. The background API tasks also feature a retry mechanism, which is enabled for recoverable failures based on HTTP status codes such as 429, 500, 502, 503, and 504. This feature ensures that ZeroTier Service API calls are resilient to recoverable failures, thereby enhancing the system’s overall reliability. Additionally, we’ve leveraged the OpenWISP notification module to send alerts to users in case of unrecoverable failures during the execution of background API tasks.

ZeroTier VPN Client Templates

These templates allow users to effortlessly manage ZeroTier OpenWRT configurations through OpenWISP. Creating ZeroTier templates is straightforward, you only need to follow these steps:

  1. Go to ‘Configuration’ > ‘Templates’ > ‘Add Template’.
  2. Set the name of your template and select your organization.
  3. Select the template type as ‘VPN Client’.
  4. Ensure that ‘Automatic tunnel provisioning’ is enabled (this allows OpenWISP to automatically generate secrets, IP addresses, etc)
  5. Choose your ZeroTier Server (Network) from the dropdown menu.

Voila! OpenWISP will automatically create your ZeroTier configuration, ready to be applied to an OpenWRT device. If you wish to customize certain properties of the configuration, you can easily do so using the OpenWISP template UI or by using the advanced mode editor of the template.

Pull Requests 🔃

What is Netdiff?

A Python library for parsing network topology data (eg: dynamic routing protocols, OpenVPN, NetJSON, CNML, WireGuard) and detect changes — docs

What is OpenWISP Network Topology?

A Network topology collector and visualizer. Collects network topology data from dynamic mesh routing protocols or other popular networking software like OpenVPN, allows to visualize the network graph, save daily snapshots that can be viewed in the future and more — docs

ZeroTier Topology Setup with OpenWISP

This marks the final phase of my project, which focused on enhancing the visualization and monitoring capabilities of the ZeroTier self-hosted controller’s topology. To achieve this, I developed a parser responsible for converting ZeroTier controller peer information into the NetJSON Network Graph format. This format is essential for the topology module, enabling it to visualize data related to ZeroTier peers seamlessly.

Luckily, the ZeroTier CLI simplifies the process by providing an option to generate ZeroTier controller peer information in JSON format. This can be done using the command zerotier-cli listpeers -j

The final task involved integrating this parser into the topology module while also ensuring compatibility and support for integration with the OpenWISP controller. This integration brings significant benefits, allowing each network peer node in the topology graph to be represented by a registered device within the OpenWISP ecosystem.

Pull Requests 🔃


This summer has been an extraordinary journey for me, filled with learning, development, and valuable networking experiences. Working under the guidance of my mentors: Federico Capaono (nemesifier), Gagan Deep (pandafy), and Ajay Tripathi (atb00ker), has been an absolute pleasure. I want to express my heartfelt gratitude to my mentors, as without their support, my project would not have been possible.

What’s Next?

With a solid grasp of the OpenWISP codebase, my journey doesn’t end here. I plan to continue contributing to OpenWISP and assisting newcomers in making their initial contributions to the project. Moreover, I’m excited to keep maintaining my GSoC projects.




Code is poetry • SDE Intern @Atlan • GSoC’23 & GSoC'22 @OpenWISP