Network Topology ================ .. image:: https://github.com/openwisp/openwisp-network-topology/raw/docs/docs/demo_network_topology.gif :alt: Features Highlights `OpenWISP Network Topology `_ is a network topology collector and visualizer web application and API, it allows to collect network topology data from different networking software (dynamic mesh routing protocols, OpenVPN), store it, visualize it, edit its details, it also provides hooks (a.k.a `Django signals `_) to execute code when the status of a link changes. When used in conjunction with `OpenWISP Controller `_ and `OpenWISP Monitoring `_, it `makes the monitoring system faster in detecting change to the network `_. .. contents:: **Table of Contents**: :backlinks: none :depth: 3 Deploy instructions ------------------- See `Enabling the network topology module on the OpenWISP 22.05 ansible role documentation `_. This module is also available in `docker-openwisp `_ although its usage is not recommended for production usage yet, unless the reader is willing to invest effort in adapting the docker images and configurations to overcome any roadblocks encountered. Quickstart Guide ---------------- This module works by periodically collecting the network topology graph data of the `supported networking software or formats `_. The data has to be either fetched by the application or received in POST API requests, therefore after deploying the application, additional steps are required to make the data collection and visualization work, read on to find out how. Creating a topology ^^^^^^^^^^^^^^^^^^^ .. image:: https://github.com/openwisp/openwisp-network-topology/raw/docs/docs/quickstart-topology.gif 1. Create a topology object by going to *Network Topology* > *Topologies* > *Add topology*. 2. Give an appropriate label to the topology. 3. Select the *topology format* from the dropdown menu. The *topology format* determines which parser should be used to process topology data. 4. Select the *Strategy* for updating this topology. - If you are using `FETCH strategy `_, then enter the URL for fetching topology data in the *Url* field. - If you are using `RECEIVE strategy `_, you will get the *URL* for sending topology data. The *RECEIVE* strategy provides an additional field *expiration time*. This can be used to add delay in marking missing links as down. Sending data for topology with RECEIVE strategy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. image:: https://github.com/openwisp/openwisp-network-topology/raw/docs/docs/quickstart-receive.gif 1. Copy the *URL* generated by OpenWISP for sending the topology data. E.g., in our case the URL is ``http://127.0.0.1:8000/api/v1/network-topology/topology/d17e539a-1793-4be2-80a4-c305eca64fd8/receive/?key=cMGsvio8q0L0BGLd5twiFHQOqIEKI423``. 2. Create a script (eg: ``/opt/send-topology.sh``) which sends the topology data using ``POST``, in the example script below we are sending the status log data of OpenVPN but the same code can be applied to other formats by replacing ``cat /var/log/openvpn/tun0.stats`` with the actual command which returns the network topology output: .. code-block:: shell #!/bin/bash # Get OpenVPN topology data from OpenVPN management interface cat /var/log/openvpn/tun0.stats | # Upload the topology data to OpenWISP curl -s -X POST \ --data-binary @- \ --header "Content-Type: text/plain" \ http://127.0.0.1:8000/api/v1/network-topology/topology/d17e539a-1793-4be2-80a4-c305eca64fd8/receive/?key=cMGsvio8q0L0BGLd5twiFHQOqIEKI423 3. Add the ``/opt/send-topology.sh`` script created in the previous step to the crontab, here's an example which sends the topology data every 5 minutes: .. code-block:: shell # flag script as executable chmod +x /opt/send-topology.sh # open crontab crontab -e ## Add the following line and save echo */5 * * * * /opt/send-topology.sh 4. 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//``. 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 `_ 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="" KEY="" OPENWISP_URL="https://" $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//``. .. 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 --------------------------------------------- For more information about the features offered by OpenWISP Network Topology we refer to the following sections of its documentation: - `List of the available features `_ - `Collection Strategies `_ - `Integration with OpenWISP Controller and OpenWISP Monitoring `_ - `Rest API `_ - `Django Settings `_