[feature] Added intergration with openwisp-monitoring

.github/workflows/ci.yml

@@ -34,7 +34,18 @@ jobs:
  - name: Install system libraries
  run: |
  sudo apt update
- sudo apt-get -qq -y install xmlsec1 gettext
+ sudo apt-get -qq -y install xmlsec1 gettext \
+ sqlite3 \
+ fping \
+ gdal-bin \
+ libproj-dev \
+ libgeos-dev \
+ libspatialite-dev \
+ spatialite-bin \
+ libsqlite3-mod-spatialite
+
+ - name: Start InfluxDB and Redis container
+ run: docker-compose up -d influxdb redis
 
  - name: Set up Python ${{ matrix.python-version }}
  uses: actions/setup-python@v2
@@ -47,7 +58,7 @@ jobs:
  pip install -U -r requirements-test.txt
 
  - name: Install npm dependencies
- run: sudo npm install -g jslint
+ run: sudo npm install -g jslint stylelint jshint
 
  - name: Install openwisp-radius
  run: |
@@ -61,6 +72,7 @@ jobs:
  - name: Tests
  run: |
  coverage run --source=openwisp_radius runtests.py
+ MONITORING_INTEGRATION=1 coverage run --append --source=openwisp_radius runtests.py
  # SAMPLE tests do not influence coverage, so we can speed up tests with --parallel
  SAMPLE_APP=1 ./runtests.py --parallel --keepdb
 

.jshintrc

@@ -0,0 +1,7 @@
+{
+ "unused": true,
+ "esversion": 6,
+ "curly": true,
+ "strict": "global",
+ "browser": true
+}

docker-compose.yml

@@ -0,0 +1,22 @@
+version: "3"
+
+services:
+ influxdb:
+ image: influxdb:1.8-alpine
+ volumes:
+ - influxdb-data:/var/lib/influxdb
+ ports:
+ - "8086:8086"
+ environment:
+ INFLUXDB_DB: openwisp2
+ INFLUXDB_USER: openwisp
+ INFLUXDB_USER_PASSWORD: openwisp
+
+ redis:
+ image: redis:alpine
+ ports:
+ - "6379:6379"
+ entrypoint: redis-server --appendonly yes
+
+volumes:
+ influxdb-data: {}

docs/source/index.rst

@@ -58,6 +58,7 @@ that are common in WiFi and ISP deployments.
  /user/registration
  /user/social_login
  /user/saml
+ /user/radius_monitoring
  /user/change_of_authorization
  /user/api
  /developer/signals

docs/source/user/radius_monitoring.rst

@@ -0,0 +1,81 @@
+Integration with OpenWISP Monitoring
+------------------------------------
+
+OpenWISP RADIUS includes an optional Django sub-app that adds integration with
+`OpenWISP Monitoring <https://github.com/openwisp/openwisp-monitoring#openwisp-monitoring>`_
+to provide RADIUS metrics.
+
+.. image:: /images/radius-dashboard-charts.png
+ :alt: RADIUS session dashboard charts
+
+RADIUS metrics
+==============
+
+1. User registrations
+~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: /images/user-registration-chart.png
+ :alt: User registration chart
+
+This chart shows number of users signed up using different registration methods.
+
+2. Total user registrations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: /images/total-user-registration-chart.png
+ :alt: Total user registration chart
+
+This chart shows total users registered using different registration methods
+in the system on a given date.
+
+3. Unique RADIUS Sessions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: /images/unique-radius-session-chart.png
+ :alt: Unique RADIUS session chart
+
+This chart shows unique RADIUS sessions. It is helpful to know how many
+unique users has used the system in a given time.
+
+4. RADIUS traffic
+~~~~~~~~~~~~~~~~~
+
+.. image:: /images/radius-traffic-chart.png
+ :alt: RADIUS traffic chart
+
+This chart shows the RADIUS traffic generated by user sessions.
+
+Enabling RADIUS metrics in Django project
+=========================================
+
+You can enable the monitoring integration by including ``openwisp_radius.integrations.monitoring``
+in ``INSTALLED_APPS`` of your Django project's settings as following:
+
+
+.. code-block:: python
+
+ # In your_project/settings.py
+
+ INSTALLED_APPS = [
+ # ...
+ 'openwisp_radius',
+ 'openwisp_radius.integrations.monitoring' # <--- add the app after openwisp_radius
+ # ...
+ ]
+
+.. note::
+
+ Ensure your Django project is correctly configured to utilize OpenWISP Monitoring as
+ outlined in the `OpenWISP Monitoring's documentation <https://github.com/openwisp/openwisp-monitoring#setup-integrate-in-an-existing-django-project>`_.
+ For production environments, it is advisable to deploy OpenWISP using
+ `Ansible OpenWISP2 <https://github.com/openwisp/ansible-openwisp2>`_ or
+ `Docker OpenWISP <https://github.com/openwisp/docker-openwisp>`_, as they simplify
+ the deployment process considerably.
+
+.. important::
+
+ If you are registering a :ref:`"registration method" <register_registration_method>`
+ in any other Django application, then ``openwisp_radius.integrations.monitoring``
+ should come after that app in the ``INSTALLED_APPS``. Otherwise, the
+ registration method would not appear in the chart.
+

docs/source/user/settings.rst

@@ -446,7 +446,7 @@ or Cameroon (``+237``).
 
 OpenWISP RADIUS only allow using mobile phone numbers for user registration.
 This can cause issues in regions where fixed line and mobile phone numbers
- uses the same pattern (e.g. USA). Setting the value to ``True``
+uses the same pattern (e.g. USA). Setting the value to ``True``
 would make phone number type checking less strict.
 
 .. _openwisp_radius_optional_registration_fields:
@@ -643,8 +643,8 @@ If this is enabled, each registered user should be verified using a verification
 The following choices are available by default:
 
 - ``''`` (empty string): unspecified
-- ``manual``: manually created
-- ``email``: Email (No Identity Verification)
+- ``manual``: Manually created
+- ``email``: Email
 - ``mobile_phone``: Mobile phone number
  :ref:`verification via SMS <openwisp_radius_sms_verification_enabled>`
 - ``social_login``: :ref:`social login feature <social_login>`
@@ -665,6 +665,8 @@ The following choices are available by default:
  **Disclaimer:** these are just suggestions on possible configurations
  of OpenWISP RADIUS and must not be considered as legal advice.
 
+.. _register_registration_method:
+
 Adding support for more registration/verification methods
 #########################################################
 

openwisp_radius/api/urls.py

@@ -83,6 +83,11 @@ def get_api_urls(api_views=None):
  api_views.download_rad_batch_pdf,
  name='download_rad_batch_pdf',
  ),
+ path(
+ 'radius/sessions/',
+ api_views.radius_accounting,
+ name='radius_accounting_list',
+ ),
  ]
  else:
  return []

openwisp_radius/api/views.py

@@ -11,14 +11,15 @@
 from django.contrib.sites.shortcuts import get_current_site
 from django.core.cache import cache
 from django.core.exceptions import ValidationError
+from django.db.models import Q
 from django.db.utils import IntegrityError
 from django.http import Http404, HttpResponse
 from django.utils import timezone
 from django.utils.decorators import method_decorator
 from django.utils.translation import gettext_lazy as _
 from django.utils.translation.trans_real import get_language_from_request
 from django.views.decorators.csrf import csrf_exempt
-from django_filters.rest_framework import DjangoFilterBackend
+from django_filters.rest_framework import CharFilter, DjangoFilterBackend
 from drf_yasg.utils import no_body, swagger_auto_schema
 from rest_framework import serializers, status
 from rest_framework.authentication import SessionAuthentication
@@ -41,6 +42,7 @@
 
 from openwisp_radius.api.serializers import RadiusUserSerializer
 from openwisp_users.api.authentication import BearerAuthentication, SesameAuthentication
+from openwisp_users.api.mixins import FilterByOrganizationManaged, ProtectedAPIMixin
 from openwisp_users.api.permissions import IsOrganizationManager
 from openwisp_users.api.views import ChangePasswordView as BasePasswordChangeView
 from openwisp_users.backends import UsersAuthenticationBackend
@@ -801,3 +803,46 @@ def create_phone_token(self, *args, **kwargs):
 
 
 change_phone_number = ChangePhoneNumberView.as_view()
+
+
+class RadiusAccountingFilter(AccountingFilter):
+ called_station_id = CharFilter(
+ field_name='called_station_id', method='filter_mac_address'
+ )
+ calling_station_id = CharFilter(
+ field_name='calling_station_id', method='filter_mac_address'
+ )
+
+ def filter_mac_address(self, queryset, name, value):
+ """
+ The input MAC address in any of these two formats:
+ - AA-BB-CC-DD-EE-FF (quadrants separated by hyphen)
+ - AA:BB:CC:DD:EE:FF (quadrants separated by colon)
+ The below lookup ensures that the filtering is
+ case-insensitive and works across different formats.
+ """
+ lookup = f'{name}__iexact'
+ return queryset.filter(
+ Q(**{lookup: value.replace(':', '-')})
+ | Q(**{lookup: value.replace('-', ':')})
+ )
+
+
+@method_decorator(
+ name='get',
+ decorator=swagger_auto_schema(
+ operation_description="""
+ Returns all RADIUS sessions of user managed organizations.
+ """,
+ ),
+)
+class RadiusAccountingView(ProtectedAPIMixin, FilterByOrganizationManaged, ListAPIView):
+ throttle_scrope = 'radius_accounting_list'
+ serializer_class = RadiusAccountingSerializer
+ pagination_class = AccountingViewPagination
+ filter_backends = (DjangoFilterBackend,)
+ filterset_class = RadiusAccountingFilter
+ queryset = RadiusAccounting.objects.all().order_by('-start_time')
+
+
+radius_accounting = RadiusAccountingView.as_view()

openwisp_radius/integrations/monitoring/admin.py

@@ -0,0 +1,40 @@
+from django.contrib import admin
+from django.urls import reverse
+from swapper import load_model
+
+Device = load_model('config', 'Device')
+RadiusAccounting = load_model('openwisp_radius', 'RadiusAccounting')
+
+BaseDeviceAdmin = admin.site._registry[Device].__class__
+
+
+class DeviceAdmin(BaseDeviceAdmin):
+ change_form_template = 'admin/config/radius-monitoring/device/change_form.html'
+
+ class Media:
+ js = tuple(BaseDeviceAdmin.Media.js) + (
+ 'radius-monitoring/js/device-change.js',
+ )
+ css = {
+ 'all': ('radius-monitoring/css/device-change.css',)
+ + BaseDeviceAdmin.Media.css['all']
+ }
+
+ def get_extra_context(self, pk=None):
+ ctx = super().get_extra_context(pk)
+ ctx.update(
+ {
+ 'radius_accounting_api_endpoint': reverse(
+ 'radius:radius_accounting_list'
+ ),
+ 'radius_accounting': reverse(
+ f'admin:{RadiusAccounting._meta.app_label}'
+ f'_{RadiusAccounting._meta.model_name}_changelist'
+ ),
+ }
+ )
+ return ctx
+
+
+admin.site.unregister(Device)
+admin.site.register(Device, DeviceAdmin)