OpenWISP Network Topology

The OpenWISP Network Topology module provides tools for managing, visualizing, and monitoring network topologies. Key capabilities include:

• Topology Collection: Supports multiple formats including NetJSON NetworkGraph, OLSR, batman-adv, BMX6, CNML 1.0, OpenVPN, Wireguard, and ZeroTier. You can extend this by writing custom netdiff parsers.
• Visualization: Uses netjsongraph.js for rendering topologies.
• Data Access: Provides a REST API that exposes data in the NetJSON NetworkGraph format.
• Management: An admin interface for managing, auditing, visualizing, and debugging nodes, links, and topology data.
• Data Ingestion: Supports receiving network topology data from multiple nodes.
• Topology History: Enables saving and viewing daily snapshots of topologies in the frontend.
• Monitoring Integration: Integrates with OpenWISP Controller and OpenWISP Monitoring for rapid detection of critical network events.

The RECEIVE strategy allows topology data to be pushed directly from one or more network nodes to the collector via HTTP POST requests.

How it works:

1. The collector waits for a POST request containing a payload.
2. It checks the key parameter in the request against the Topology instance's key.
3. If authorized, the collector updates the topology.

Configuration based on node count:

• Single Node: If only one node sends data, set the expiration_time of the Topology instance to 0 (seconds). This mimics the FETCH strategy behavior where missing links are flagged as "down" immediately.
• Multiple Nodes: If data is sent from multiple nodes, set the expiration_time to a value slightly higher than the interval used by the nodes to send data. This prevents links from being flagged as "down" prematurely due to network splits or timing jitter, though it introduces a delay in detecting offline links.

To set up ZeroTier topology visualization:

1. Create Topology: Visit admin/topology/topology/add. Set Label to ZeroTier, select Format as ZeroTier, and set Strategy to RECEIVE. Ensure Published is checked. Copy the generated receive URL.
2. Create Script: Create a script (e.g., /opt/send-zt-topology.sh) that uses zerotier-cli peers -j to fetch data in JSON format and sends it via curl to the OpenWISP receive URL.
3. Permissions: Because zerotier-cli requires root privileges for kernel interaction, you must add the script to the root crontab using sudo crontab -e.

Note: If using the OpenWISP controller integration, ensure the ZeroTier topology organization matches the device organization.

#!/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

If you have enabled the WiFi Mesh integration, you must schedule the create_mesh_topology task in your CELERY_BEAT_SCHEDULE.

This task generates the mesh topology from monitoring data. It requires two arguments:

1. A list of organization UUIDs: The topology will only be created for devices belonging to these organizations.
2. A lookback period (in seconds): The task will ignore monitoring data reported before this time.

from datetime import timedelta

CELERY_BEAT_SCHEDULE.update(
    {
        "create_mesh_topology": {
            "task": "openwisp_network_topology.integrations.device.tasks.create_mesh_topology",
            "schedule": timedelta(minutes=5),
            "args": (
                [
                    "4e002f97-eb01-4371-a4a8-857faa22fe5c",
                    "be88d4c4-599a-4ca2-a1c0-3839b4fdc315",
                ],
                6 * 60,  # 6 minutes
            ),
        },
    }
)