Architecture, Modules, Technologies

OpenWISP Architecture Overview

The diagram above provides an overview of the OpenWISP architecture. It highlights the key technologies used, the structure of the OpenWISP modules, their major dependencies, and their interactions.

Important

For an enhanced viewing experience, open the image in a new browser tab.

Table of Contents:

OpenWISP Modules

Note

For more insights into the motivations and philosophy behind the modular architecture of OpenWISP, refer to Applying the Unix Philosophy to Django projects: a report from the real world.

Deployment

Server Side

  • OpenWISP Users: Manages user authentication, multi-tenancy, and provides REST API utilities and classes for implementing multi-tenancy.

  • OpenWISP Controller: Handles configuration management, VPN provisioning (OpenVPN, Wireguard, Wireguard over VXLAN), shell commands, SSH connections, x509 PKI management, geographic maps, floor plans, programmable IP address management, and subnet provisioning.

    This module depends on several Django apps and Python libraries developed or maintained by OpenWISP:

  • OpenWISP Monitoring: Monitors and tracks device metrics like ping success rate, packet loss, round trip time, traffic, WiFi clients, memory, CPU load, flash space, ARP/neighbor information, DHCP leases, and provides charts and configurable alerts. It also allows custom checks and tolerance threshold configurations.

  • OpenWISP Network Topology: Collects and visualizes network topology data from dynamic mesh routing protocols and other popular networking software like OpenVPN. It can visualize network graphs and save daily snapshots for future viewing.

    This module relies on two libraries developed and maintained by OpenWISP:

  • OpenWISP Firmware Upgrader: Provides a firmware upgrade solution for OpenWrt and potentially other embedded OSes. Features include automatic retry for network failures, mass upgrades, a REST API, and more.

  • OpenWISP RADIUS: Offers a web interface to a FreeRADIUS database, a rich REST HTTP API, and features like user self-registration, SMS verification, user import from CSV files, event-based user generation, Captive Portal Social Login, and Captive Portal SAML login.

  • OpenWISP Notifications: Provides email and web notifications for OpenWISP, enabling modules to notify users about significant events in their network.

  • OpenWISP Utils: Common utilities and classes shared by all OpenWISP Python modules. Includes many utilities for QA checks and automated testing, heavily used in continuous integration builds of most OpenWISP GitHub repositories.

  • OpenWISP WiFi Login Pages: A configurable login page and self registration app for WiFi Hotspot services, offering features like login, sign up, social login, SMS verification, password reset and more. It is a frontend for the OpenWISP RADIUS REST API, designed for end users of a WiFi Hotspot service.

Network Device Side

Website and Documentation

Main Technologies Used

Python

Python is the primary programming language used for the server-side application (web admin, API, controller, workers).

Originally, OpenWISP was built on Ruby On Rails, but we later switched to Python due to its suitability for networking and a larger pool of potential contributors.

Find out more on why OpenWISP chose Python as its main language.

Django

Django is one of the most popular web frameworks for Python.

It is used extensively in our modules, allowing rapid development and access to a rich ecosystem.

It's the base framework used in most of the server-side modules of OpenWISP.

Find out more on why OpenWISP chose Django as its main web framework.

Django REST Framework

Django REST framework is a powerful and flexible toolkit for building Web APIs based on Django, widely used in most of the Django and web-based OpenWISP modules.

Find out more on why OpenWISP chose Django REST Framework to build its REST API.

Celery

Celery is a Python implementation of a distributed task queue. It is heavily used in OpenWISP to execute background tasks, perform network operations like monitoring checks, configuration updates, firmware upgrades, and more.

OpenWrt

OpenWrt is a Linux distribution designed for embedded systems, routers, and networking in general.

It has a very skilled community and is used as a base by many hardware vendors (Technicolor, Ubiquiti Networks, Linksys, Teltonika, and many others).

Lua

Lua is a lightweight, multi-paradigm programming language designed primarily for embedded systems and clients.

Lua is cross-platform, since the interpreter is written in ANSI C, and has a relatively simple C API.

It is the official scripting language of OpenWrt and is used heavily in the OpenWrt packages of OpenWISP: openwisp-config and openwisp-monitoring.

Node.js and React JS

NodeJS is a JavaScript runtime for building JS-based applications.

In OpenWISP, it's used as a base for frontend applications along with React, like the WiFi Login Pages module.

Ansible

Ansible is a popular software automation tool written in Python, generally used for automating software provisioning, configuration management, and application deployment.

We use Ansible to provide automated procedures to deploy OpenWISP, to compile custom OpenWrt images for different organizations, to deploy OpenWISP WiFi Login Pages, and to deploy the Wireguard integration for OpenWISP Controller.

Docker

We use Docker in docker-openwisp, which aims to ease the deployment of OpenWISP in a containerized infrastructure.

NetJSON

NetJSON is a data interchange format based on JSON designed to ease the development of software tools for computer networks.

RADIUS

RADIUS (Remote Authentication Dial-In User Service) is a networking protocol used for centralized Authentication, Authorization, and Accounting management of network services.

FreeRADIUS

FreeRADIUS is the most popular open-source implementation of the RADIUS protocol and is extensively relied upon in OpenWISP RADIUS.

Mesh Networking

A mesh network is a local network topology where infrastructure nodes connect directly, dynamically, and non-hierarchically to as many other nodes as possible. They cooperate to efficiently route data to and from clients.

OpenWrt supports the standard mesh mode (802.11s), which OpenWISP supports out of the box. Additionally, OpenWrt can support other popular dynamic open-source routing protocols such as OLSRd2, BATMAN-advanced, Babel, BMX, etc.

For more information on how to set up a mesh network with OpenWISP, refer to: How to Set Up a Wireless Mesh Network.

InfluxDB

InfluxDB is the default open-source time-series database used in OpenWISP Monitoring.

Elasticsearch

Elasticsearch is an alternative option that can be used in OpenWISP Monitoring as a time-series database. It excels in storing and retrieving data quickly and efficiently.

Networkx

Networkx is a network graph analysis library written in Python and used under the hood by netdiff and the OpenWISP Network Topology module.

Relational Databases

Django supports several Relational Database Management Systems.

The most notable ones are:

For production usage, we recommend PostgreSQL.

For development, we recommend SQLite for its simplicity.

Other Notable Dependencies