Architecture, Modules, Technologies
The following SVG image summarizes the architecture of OpenWISP, the main technologies used, the structure of the OpenWISP modules and their most important dependencies and the way they interact with one another.
For the best experience it is recommended to open the image in a new tab of your browser, from there you can also click on the different elements to open the README or website of each module or technology used.
The Inkscape source file of the architecture diagram is
also available for download.
Inkscape is an open source vector editing software which has been used to produce this diagram.
If you want to know more about the motivations and philosophy that have shaped the modular architecture of OpenWISP, please see Applying the Unix Philosophy to Django projects: a report from the real world.
Ansible OpenWISP2: Recommended way to deploy OpenWISP on virtual machines.
Docker OpenWISP (alpha): allows to deploy OpenWISP on dockerized cloud infrastructure. It’s still being improved but the basic features of OpenWISP are working.
Ansible OpenWISP WiFi Login Pages: ansible role that allows to deploy OpenWISP WiFi Login Pages.
Ansible OpenWISP2 Image Generator: useful to generate many OpenWrt firmware images for different organizations with the OpenWISP packages preinstalled.
Ansible Wireguard OpenWISP.: ansible role that allows to deploy the Wireguard integration for OpenWISP Controller.
OpenWISP Users: User management, multi-tenancy, authentication backend, REST API utilities and classes to implement multi-tenancy.
OpenWISP Controller: Configuration management and templating, automatic provisioning of VPN tunnels like OpenVPN, Wireguard, Wireguard over VXLAN, shell commands, SSH connections, x509 PKI management, geographic maps and floorplans, programmable IP address management and subnet provisioning.
This module depends on several django apps or python libraries developed or maintained by OpenWISP:
netjsonconfig: configuration generation, validation and parsing.
django-x509: Public Key Infrastructure (management of certification authorities and x509 certificates).
django-loci: Geographic and indoor mapping features.
openwisp-ipam: IP and Subnet administration.
django-rest-framework-gis: GIS addons for Django REST Framework.
OpenWISP Monitoring: Monitors and tracks device information like uptime, packet loss, round trip time, traffic, WiFi clients,memory, CPU load, flash space, ARP/neighbor information, DHCP leases, provides charts and configurable alerts, allows to write custom checks or reconfigure tolerance thresholds and charts.
OpenWISP Network Topology: Network topology collector and visualizer. Collects network topology datafrom dynamic mesh routing protocols or other popular networking software like OpenVPN, allows to visualize the network graph and save daily snapshots that can be viewed in the future.
This module depends on a couple of libraries developed and maintained by OpenWISP:
netdiff: network topology parsing.
OpenWISP Firmware Upgrader: Firmware upgrade solution for OpenWRT with possibility to add support for other embedded OSes. Provides features like automatic retry for network failures, mass upgrades, REST API and more.
OpenWISP RADIUS: provides a web interface to a freeradius database, a rich REST HTTP API and features like user self registration, SMS verification, import of users from CSV files, generation of new users for events, Captive Portal Social Login, Captive Portal SAML login and more.
OpenWISP Notifications: provides email and web notifications to OpenWISP. Its main goal is to allow any OpenWISP module to notify users about meaningful events that happen in their network.
OpenWISP Utils: common utilities and classes shared by all the OpenWISP python modules, it includes a lot of utilities for QA checks and automated testing which are heavily used in the continous integration builds of most if not all the OpenWISP github repositories.
OpenWISP WiFi Login Pages: Configurable captive page for public/private WiFi services providing login, sign up, social login, SMS verification, change password, reset password, change phone number and more. It is a frontend of the OpenWISP RADIUS REST API and it’s designed to be used by end users of a public WiFi network.
Network Device Side
OpenWISP Config: OpenWrt package which integrates with OpenWISP Controller.
OpenWISP Monitoring: OpenWrt package which integrates with OpenWISP Monitoring.
Website and Documentation
openwisp2-docs: repository for the documentation of OpenWISP, hosted on openwisp.io/docs.
OpenWISP-Website: repository of the OpenWISP website, hosted on openwisp.org.
Main Technologies Used
Python it’s the main programming language used by the server side application (web admin, API, controller, workers).
In the past OpenWISP was built in Ruby On Rails, but we later switched to Python because it’s much more suited to networking and it has a wider pool of potential contributors.
Find out more on why OpenWISP chose Python as its main language.
Django is one of the most popular web frameworks for Python language.
It is used extensively in our modules. Django allows rapid development and has a very 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 and it’s widely used in most of the Django and web based based OpenWISP modules.
Find out more on why OpenWISP chose Django REST Framework to build its REST API.
Celery is a python implementation of a distributed task queue and is heavily used in OpenWISP to execute background tasks, perform network operations like monitoring checks, configuration updates, firmware upgrades and so on.
OpenWrt is an linux distribution designed for embedded systems, routers and networking in general.
It has a very skilled community and it is used as a base by many hardware vendors (Technicolor, Ubiquiti Networks, Linksys, Teltonika and many others).
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 it’s used heavily in the OpenWrt packages of OpenWISP: openwisp-config and openwisp-monitoring.
Node.js and React JS
In OpenWISP it’s used as a base for frontend applications along with React, like openwisp-wifi-login-pages.
Ansible is a very popular software automation tool written in python that is 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.
We use docker in docker-openwisp, which aims to ease the deployment of OpenWISP in a containerized infrastructure.
NetJSON is a data interchange format based on JSON designed to ease the development of software tools for computer networks.
RADIUS (Remote Authentication Dial-In User Service) is a networking protocol that used for centralized Authentication, Authorization, and Accounting management of network services.
Freeradius is the most popular open source implementation of the RADIUS protocol and is heavily relied on in OpenWISP RADIUS.
A mesh nework is a local network topology in which the infrastructure nodes connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients.
OpenWrt supports the standard mesh mode (802.11s) and OpenWISP supports this mode out of the box.
It is also possible to support other popular dynamic open source routing protocols available on OpenWrt like OLSRd2, BATMAN-advanced, Babel, BMX, etc.
InfluxDB is the deafult open source timeseries DB used in OpenWISP Monitoring.
Elasticsearch is an alternative option which can be used in OpenWISP Monitoring as timeseries DB, although it was designed with different purposes related to storing and retrieving data in a fast and efficient way.
Networkx is a network graph analysis library written in Python and used under the hood by netdiff and the OpenWISP Network Topology module.
Django supports several Relational Database Management Systems.
The most notable ones are:
For production usage we recommend PostgreSQL.
For development we recommend SQLite for it simplicity.
Other notable dependencies
paramiko (used in OpenWISP Controller and Firmware Upgrader)
django-allauth (used in OpenWISP Users)
django-organizations (used in OpenWISP Users)
django-swappable-models (used in all the major Django modules)
django-private-storage (used in OpenWISP RADIUS and Firmware Upgrader)
dj-rest-auth (used in OpenWISP RADIUS)
django-sendsms (used in OpenWISP RADIUS)
django-saml2 (used in OpenWISP RADIUS)