[feature] Added intergration with openwisp-monitoring

.github/workflows/ci.yml

@@ -43,12 +43,23 @@ jobs:
         id: deps
         run: |
           sudo apt update -qq
-          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
+          sudo npm install -g jslint stylelint jshint
           pip install -U pip wheel setuptools
           pip install -U -r requirements-test.txt
           pip install -e .[saml,openvpn_status]
           pip install ${{ matrix.django-version }}
-          sudo npm install -g jslint
+
+      - name: Start InfluxDB and Redis container
+        run: docker compose up -d influxdb redis
 
       - name: QA checks
         run: |
@@ -57,10 +68,11 @@ jobs:
       - name: Tests
         if: ${{ !cancelled() && steps.deps.conclusion == 'success' }}
         run: |
-          coverage run runtests.py --parallel || ./runtests.py
+          coverage run --parallel-mode runtests.py --parallel || ./runtests.py
           # SAMPLE tests do not influence coverage, so we can speed up tests with --parallel
-          SAMPLE_APP=1 coverage run ./runtests.py --parallel > /dev/null 2>&1 || SAMPLE_APP=1 ./runtests.py
+          SAMPLE_APP=1 coverage run --parallel-mode ./runtests.py --parallel > /dev/null 2>&1 || SAMPLE_APP=1 ./runtests.py
           coverage combine
+          MONITORING_INTEGRATION=1 coverage run --append runtests.py
           coverage xml
 
       - name: Upload Coverage

.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/index.rst

@@ -40,6 +40,7 @@ OpenWISP architecture.
     user/saml.rst
     user/enforcing_limits.rst
     user/change_of_authorization.rst
+    user/radius_monitoring
     user/management_commands.rst
     user/rest-api.rst
     user/settings.rst

docs/user/radius_monitoring.rst

@@ -0,0 +1,80 @@
+.. _integration_with_openwisp_monitoring:
+
+Integration with OpenWISP Monitoring
+====================================
+
+OpenWISP RADIUS includes an optional Django sub-app that adds integration
+with :doc:`OpenWISP Monitoring </monitoring/index>` 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
+-----------------------------------------
+
+.. include:: /partials/settings-note.rst
+
+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.append("openwisp_radius.integrations.monitoring")
+
+.. note::
+
+    Ensure your Django project is correctly configured to utilize OpenWISP
+    Monitoring. For production environments, it is advisable to deploy
+    OpenWISP using :doc:`Ansible OpenWISP </ansible/index>` or
+    :doc:`Docker OpenWISP </docker/index>`, as they simplify the
+    deployment process considerably.
+
+.. important::
+
+    If you are registering a :ref:`"registration method"
+    <openwisp_radius_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/user/settings.rst

@@ -667,8 +667,8 @@ If this is enabled, each registered user should be verified using a
 verification method. 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``: :doc:`social login feature <social_login>`
@@ -690,6 +690,8 @@ verification method. 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.
 
+.. _openwisp_radius_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)