[docs] Added zerotier setup tutorial

index.rst

@@ -15,6 +15,7 @@ Contents:
    user/configuration-variables
    user/vpn
    user/wireguard
+   user/zerotier
    user/configure-push-updates
    user/send-commands
    user/subnet-division-rules

user/monitoring.rst

@@ -88,9 +88,9 @@ This is the most common scenario:
 
 In this scenario, the OpenWISP application will not be able to reach the
 devices **unless a management tunnel** is used, for that reason having
-a management VPN like OpenVPN, Wireguard or any other tunneling solution
-is paramount, not only to allow OpenWISP to work properly, but also to
-be able to perform debugging and troubleshooting when needed.
+a management VPN like OpenVPN, Wireguard, ZeroTier or any other tunneling
+solution is paramount, not only to allow OpenWISP to work properly, but
+also to be able to perform debugging and troubleshooting when needed.
 
 In this scenario, the following requirements are needed:
 

user/network-topology.rst

@@ -122,6 +122,103 @@ Sending data for topology with RECEIVE strategy
    or, alternatively, a non-admin visualizer page is also available at
    the URL ``/topology/topology/<TOPOLOGY-UUID>/``.
 
+Sending data for ZeroTier topology with RECEIVE strategy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Follow the procedure described below to
+setup **ZeroTier** topology with **RECEIVE** strategy.
+
+**Note:** In this example, the **Shared
+systemwide (no organization)** option is used
+for the ZeroTier topology organization. You are free
+to opt for any organization, as long as both the topology
+and the device share the same organization, assuming the
+`OpenWISP controller integration <https://github.com/openwisp/
+openwisp-network-topology/ #integration-with-openwisp-controller
+-and-openwisp-monitoring>`_ feature is enabled.
+
+1. Create topology for ZeroTier
+###############################
+
+1. Visit ``admin/topology/topology/add`` to add a new topology.
+
+2. We will set the **Label** of this topology to ``ZeroTier`` and
+   select the topology **Format** from the dropdown as ``ZeroTier``.
+
+3. Select the strategy as ``RECEIVE`` from the dropdown.
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-network-topology/docs/docs/zerotier-tutorial/topology-1.png
+   :alt: ZeroTier topology configuration example 1
+
+4. Let use default **Expiration time** ``0``
+   and make sure **Published** option is checked.
+
+5. After clicking on the **Save and continue editing** button,
+   a topology receive URL is generated. Make sure you copy
+   that URL for later use in the topology script.
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-network-topology/docs/docs/zerotier-tutorial/topology-2.png
+   :alt: ZeroTier topology configuration example 2
+
+2. Create a script for sending ZeroTier topology data
+#####################################################
+
+1. Now, create a script on your server where
+   the ZeroTier controller is hosted (e.g: ``/opt/send-zt-topology.sh``)
+   that sends the ZeroTier topology data using a POST request.
+   In the example script below, we are sending the peers data
+   from the self-hosted ZeroTier controller to OpenWISP:
+
+.. code-block:: shell
+
+ #!/bin/bash
+ # command to fetch zerotier controller peers data in json format
+ COMMAND="zerotier-cli peers -j"
+ UUID="<TOPOLOGY-UUID-HERE>"
+ KEY="<TOPOLOGY-KEY-HERE>"
+ OPENWISP_URL="https://<OPENWISP_DOMAIN_HERE>"
+ $COMMAND |
+     # Upload the topology data to OpenWISP
+     curl -X POST \
+         --data-binary @- \
+         --header "Content-Type: text/plain" \
+         $OPENWISP_URL/api/v1/network-topology/topology/$UUID/receive/?key=$KEY
+
+2. Add the ``/opt/send-zt-topology.sh`` script
+   created in the previous step to the root crontab,
+   here's an example which sends the topology data every **5 minutes**:
+
+.. code-block:: shell
+
+    # flag script as executable
+    chmod +x /opt/send-zt-topology.sh
+
+.. code-block:: shell
+
+    # open rootcrontab
+    sudo crontab -e
+
+    ## Add the following line and save
+
+    echo */5 * * * * /opt/send-zt-topology.sh
+
+**Note:** When using the **ZeroTier** topology,
+ensure that you use ``sudo crontab -e`` to edit
+the **root crontab**. This step is essential because
+the ``zerotier-cli peers -j`` command requires
+**root privileges** for kernel interaction, without
+which the command **WILL NOT** function correctly.
+
+3. Once the steps above are completed, you should see nodes and links
+   being created automatically, you can see the network topology graph
+   from the admin page of the topology change page (you have to click on
+   the **View topology graph** button in the upper right part of the page)
+   or, alternatively, a non-admin visualizer page is also available at
+   the URL ``/topology/topology/<TOPOLOGY-UUID>/``.
+
+   .. image:: https://raw.githubusercontent.com/openwisp/openwisp-network-topology/docs/docs/zerotier-tutorial/topology-graph.png
+    :alt: ZeroTier topology graph example 1
+
 Find out more about OpenWISP Network Topology
 ---------------------------------------------
 

user/zerotier.rst

@@ -0,0 +1,135 @@
+ZeroTier tunnel automation
+--------------------------
+
+In this guide we will explore how to set up the automatic management
+of `ZeroTier tunnels. <https://www.zerotier.com/>`_
+
+.. contents:: **Table of Contents**:
+   :backlinks: none
+   :depth: 3
+
+How to setup ZeroTier Tunnels
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Follow the procedure described below to setup
+ZeroTier tunnels on your devices.
+
+**Note:** This example uses **Shared systemwide (no organization)**
+option as the organization for VPN server and VPN client template.
+You can use any organization as long as VPN server, VPN client
+template and Device has same organization.
+
+1. Configure Self-Hosted ZeroTier Network Controller
+####################################################
+
+Currently, OpenWISP doesn't support the management
+of `ZeroTier Central Controllers <https://my.zerotier.com/>`_
+and only supports `self-hosted ZeroTier controllers
+<https://docs.zerotier.com/self-hosting/introduction/>`_.
+If you haven't already set up a self-hosted ZeroTier network controller
+on your server, now is a good time to do so. You can
+start by simply installing ZeroTier package on your server
+from the `official website <https://www.zerotier.com/download/>`_.
+
+2. Create VPN server configuration for ZeroTier
+###############################################
+
+1. Visit ``/admin/config/vpn/add/`` to add a new VPN server.
+2. We will set **Name** of this VPN server ``ZeroTier``
+   and **Host** as ``my-zerotier-server.mydomain.com:9993``
+   (update this to point to your ZeroTier VPN server).
+3. Select ``ZeroTier`` from the dropdown as **VPN Backend**.
+4. When using ZeroTier, OpenWISP takes care of managing IP addresses
+   (assigning an IP address to each VPN clients (Zerotier network 
+   members). You can create a new subnet or select an existing one from
+   the dropdown menu.You can also assign an **Internal IP** to the
+   Zerotier controller or leave it empty for OpenWISP to configure.
+   This IP address will be used to assign it to the Zerotier controller
+   running on the server.
+5. Set the **Webhook AuthToken**, this will be ZeroTier authorization
+   token which you can obtain by running the following command on
+   the ZeroTier controller:
+
+   .. code-block:: shell
+
+        sudo cat /var/lib/zerotier-one/authtoken.secret
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/zerotier-tutorial/vpn-server-1.png
+   :alt: ZeroTier VPN server configuration example 1
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/zerotier-tutorial/vpn-server-2.png
+   :alt: ZeroTier VPN server configuration example 2
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/zerotier-tutorial/vpn-server-3.png
+   :alt: ZeroTier VPN server configuration example 3
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/zerotier-tutorial/vpn-server-4.png
+   :alt: ZeroTier VPN server configuration example 4
+
+6. After clicking on **Save and continue editing**, OpenWISP
+   automatically detects the node address of the Zerotier controller
+   and creates a Zerotier network. The **network_id**  of this network
+   can be viewed in the **System Defined Variables** section, where it
+   also provides internal IP address information.
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/zerotier-tutorial/vpn-server-5.png
+   :alt: ZeroTier VPN server configuration example 5
+
+3. Create VPN client template for ZeroTier VPN Server
+#####################################################
+
+1. Visit ``/admin/config/template/add/`` to add a new template.
+2. Set ``ZeroTier Client`` as **Name** (you can set whatever you want)
+   and select ``VPN-client`` as **type** from the dropdown list.
+3. The **Backend** field refers to the backend of the device this
+   template can be applied to. For this example, we will leave
+   it to ``OpenWRT``.
+4. Select the correct VPN server from the dropdown for the
+   **VPN** field. Here it is ``ZeroTier``.
+5. Ensure that the **Automatic tunnel provisioning** option
+   is checked. This will enable OpenWISP to automatically provision
+   an IP address and ZeroTier identity secrets (used for assigning
+   member IDs) for each ZeroTier VPN client.
+6. After clicking on **Save and continue editing** button, you will
+   see details of *ZeroTier* VPN server in **System Defined Variables**.
+   The template configuration will be automatically generated which you
+   can tweak accordingly. We will use the automatically generated VPN
+   client configuration for this example.
+
+**Note:** OpenWISP uses `zerotier-idtool
+<https://github.com/zerotier/ZeroTierOne/blob/dev/doc/zerotier-idtool.1.md>`_
+to manage **ZeroTier identity secrets**. Please make sure that you have
+`ZeroTier package installed <https://www.zerotier.com/download/>`_ on the server.
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/zerotier-tutorial/template.png
+    :alt: ZeroTier VPN client template example
+
+4. Apply ZeroTier VPN template to devices
+#########################################
+
+**Note**: This step assumes that you already have a
+device registered on OpenWISP. Register or create a
+device before proceeding.
+
+1. Open the **Configuration** tab of the concerned device.
+2. Select the *ZeroTier Client* template.
+3. Upon clicking the **Save and Continue Editing** button,
+   you will see entries in the **System Defined Variables** section.
+   These entries will include **member_id**, **identity_secret**, and
+   the internal **IP address** of the ZeroTier client (network member)
+   on the device, along with details of the VPN server.
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/zerotier-tutorial/device-configuration-1.png
+   :alt: ZeroTier VPN device configuration example 1
+
+4. Once the configuration is successfully applied
+   to the device, you will notice a new ZeroTier interface
+   that is up and running. This interface will have the
+   name ``owzt89f498`` (where ``owzt`` is followed by the
+   last six hexadecimal characters of the ZeroTier **network ID**).
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/zerotier-tutorial/device-configuration-2.png
+   :alt: ZeroTier VPN device configuration example 2
+
+**Voila!** You have successfully configured OpenWISP
+to manage ZeroTier tunnels for your devices.