diff --git a/README.rst b/README.rst index 46886541..a60c841d 100644 --- a/README.rst +++ b/README.rst @@ -29,6 +29,8 @@ openwisp-radius :target: https://pypi.org/project/black/ :alt: code style: black +--- + **Need a quick overview?** `Try the OpenWISP Demo `_. **OpenWISP RADIUS** provides a web interface to a `freeradius `_ database, @@ -45,11 +47,35 @@ It can be used as a standalone application or integrated with the rest of `OpenW It can also be used as a `base system or framework on top of which custom tailored solutions can be built `_. -- `Documentation `_ -- `Change log `_ -- `Support `_ -- `Issue Tracker `_ -- `License `_ +Documentation +------------- + +- `Usage documentation `_ +- `Developer documentation + `_ + +Contributing +------------ + +Please refer to the `OpenWISP contributing guidelines +`_. + +Changelog +--------- + +See `CHANGES +`_. + +License +------- + +See `LICENSE +`_. + +Support +------- + +See `OpenWISP Support Channels `_. .. image:: https://raw.githubusercontent.com/openwisp/openwisp2-docs/master/assets/design/openwisp-logo-black.svg :target: http://openwisp.org diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 69f001ec..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = python -msphinx -SPHINXPROJ = openwisp-radius -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/source/developer/freeradius.rst b/docs/deploy/freeradius.rst similarity index 93% rename from docs/source/developer/freeradius.rst rename to docs/deploy/freeradius.rst index 86cada66..b71f4a53 100644 --- a/docs/source/developer/freeradius.rst +++ b/docs/deploy/freeradius.rst @@ -1,12 +1,9 @@ -.. _freeradius_setup_for_captive_portal: - Freeradius Setup for Captive Portal authentication ================================================== This guide explains how to install and configure `freeradius 3 -`_ in order to make it work with `OpenWISP RADIUS -`_ for Captive Portal -authentication. +`_ in order to make it work with OpenWISP RADIUS +for Captive Portal authentication. The guide is written for debian based systems, other linux distributions can work as well but the name of packages and files may be different. @@ -21,15 +18,14 @@ Coova-Chilli, but other solutions can be used as well. need to perform social login or some other kind of Single Sign On (SSO). - The `openwisp-wifi-login-pages - `_ web app is - an open source solution which integrates with OpenWISP RADIUS to + The :doc:`OpenWISP WiFi Login Pages ` web app + is an open source solution which integrates with OpenWISP RADIUS to provide features like self user registration, social login, SSO/SAML login, SMS verification, simple username & password login using the :ref:`radius_user_token` method. - For more information see: `openwisp-wifi-login-pages - `_. + For more information see: :doc:`OpenWISP WiFi Login Pages + ` How to install freeradius 3 --------------------------- @@ -111,7 +107,7 @@ First of all enable the ``rest`` and optionally the ``sql`` module: # optional ln -s /etc/freeradius/mods-available/sql /etc/freeradius/mods-enabled/sql -.. _configure-rest-module: +.. _radius_configure_rest_module: Configure the REST module ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -206,16 +202,16 @@ Example configuration using the PostgreSQL database: password = "" radius_db = "radius" -.. _freeradius_site: +.. _radius_freeradius_site: Configure the site ~~~~~~~~~~~~~~~~~~ This section explains how to configure the FreeRADIUS site. -Please refer to :ref:`freeradius_api_authentication` to understand the -different possibilities with which FreeRADIUS can authenticate requests -going to OpenWISP RADIUS so that OpenWISP RADIUS knows to which +Please refer to :ref:`radius_freeradius_api_authentication` to understand +the different possibilities with which FreeRADIUS can authenticate +requests going to OpenWISP RADIUS so that OpenWISP RADIUS knows to which organization each request belongs. If you are **not** using the method described in :ref:`radius_user_token`, @@ -225,8 +221,8 @@ you have to do the following: - uncomment the line which starts with ``# api_token_header`` - substitute the occurrences of ```` and ```` with the UUID & RADIUS API token of each - organization, refer to the section :ref:`organization_uuid_token` for - finding these values. + organization, refer to the section :ref:`radius_organization_uuid_token` + for finding these values. If you are deploying a captive portal setup and can use the RADIUS User Token method, you can get away with having only one freeradius site for @@ -281,7 +277,7 @@ Please also ensure that ``acct_unique`` is present in the # ... } -.. _restart_freeradius: +.. _radius_restart_freeradius: Restart freeradius to make the configuration effective ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -300,8 +296,8 @@ In case of errors you can run `freeradius in debug mode **A common problem, especially during development and testing, is that the openwisp-radius application may not be running**, in that case you can -find out how to run the django development server in the :ref:`Install for -development ` section. +find out how to run the django development server in the +:doc:`../developer/installation` section. Also make sure that this server runs on the port specified in ``/etc/freeradius/mods-enabled/rest``. @@ -349,8 +345,8 @@ OpenWISP RADIUS instead uses the FreeRADIUS `rlm_rest `_ module in order to take advantage of the built in user management and authentication capabilities of Django (for more information about these -topics see :ref:`configure-rest-module` and `User authentication in Django -`_). +topics see :ref:`radius_configure_rest_module` and `User authentication in +Django `_). When migrating from existing FreeRADIUS deployments or in cases where it is preferred to use the FreeRADIUS *radcheck* table for storing user @@ -383,7 +379,7 @@ ensure the ``authorize`` section of your site as follows contains the # ... } -.. _debugging: +.. _radius_debugging: Debugging --------- @@ -417,7 +413,7 @@ You can do this with ``radtest``: A successful authentication will return similar output: -:: +.. code-block:: text Sent Access-Request Id 215 from 0.0.0.0:34869 to 127.0.0.1:1812 length 75 User-Name = "admin" @@ -430,7 +426,7 @@ A successful authentication will return similar output: While an unsuccessful one will look like the following: -:: +.. code-block:: text Sent Access-Request Id 85 from 0.0.0.0:51665 to 127.0.0.1:1812 length 73 User-Name = "foo" @@ -461,7 +457,7 @@ Testing accounting You can do this with ``radclient``, but first of all you will have to create a text file like the following one: -:: +.. code-block:: text # /tmp/accounting.txt @@ -490,7 +486,7 @@ Then you can call ``radclient``: You should get the following output: -:: +.. code-block:: text Sent Accounting-Request Id 83 from 0.0.0.0:51698 to 127.0.0.1:1813 length 154 Acct-Session-Id = "35000006" diff --git a/docs/source/developer/freeradius_wpa_enterprise.rst b/docs/deploy/freeradius_wpa_enterprise.rst similarity index 87% rename from docs/source/developer/freeradius_wpa_enterprise.rst rename to docs/deploy/freeradius_wpa_enterprise.rst index 879f0acb..2bde4aaf 100644 --- a/docs/source/developer/freeradius_wpa_enterprise.rst +++ b/docs/deploy/freeradius_wpa_enterprise.rst @@ -2,25 +2,22 @@ Freeradius Setup for WPA Enterprise (EAP-TTLS-PAP) authentication ================================================================= This guide explains how to install and configure `freeradius 3 -`_ in order to make it work with `OpenWISP RADIUS -`_ for WPA Enterprise -EAP-TTLS-PAP authentication. +`_ in order to make it work with OpenWISP RADIUS +for WPA Enterprise EAP-TTLS-PAP authentication. The setup will allow users to authenticate via WiFi WPA Enterprise networks using their personal username and password of their django user accounts. Users can either be created manually via the admin interface, -:ref:`generated `, :ref:`imported from CSV -`, or can self register through a web page which makes -use of the :ref:`registration REST API ` (like -`openwisp-wifi-login-pages -`_). +:doc:`generated <../user/generating_users>`, :doc:`imported from CSV +<../user/importing_users>`, or can self register through a web page which +makes use of the :ref:`registration REST API ` +(like :doc:`OpenWISP WiFi Login Pages `). Prerequisites ------------- Execute the steps explained in the following sections of the -:ref:`freeradius guide for captive portal authentication -`: +:doc:`freeradius guide for captive portal authentication `: - How to install freeradius 3 - Enable the configured modules @@ -31,7 +28,7 @@ Then proceed with the rest of the document. Freeradius configuration ------------------------ -.. _freeradius_site_wpa_enterprise: +.. _radius_freeradius_site_wpa_enterprise: Configure the sites ~~~~~~~~~~~~~~~~~~~ @@ -48,8 +45,8 @@ Let's create the site for an hypotethical organization called org-A. Don't forget to substitute the occurrences of ```` and ```` with the UUID & Radius API token of each -organization, refer to the section :ref:`organization_uuid_token` for -finding these values. +organization, refer to the section :ref:`radius_organization_uuid_token` +for finding these values. .. code-block:: ini @@ -132,7 +129,7 @@ Inner tunnels You will need to set up one inner tunnel for each organization too. -Following the example for a hypotetical organization named org-A: +Following the example for a hypothetical organization named org-A: .. code-block:: ini @@ -258,8 +255,8 @@ Final steps ----------- Once the configurations are ready, you should :ref:`restart freeradius -` and :ref:`then test/troubleshoot/debug your setup -`. +` and :ref:`then test/troubleshoot/debug your +setup `. Implementing other EAP scenarios -------------------------------- @@ -273,5 +270,5 @@ the `django-x509 `_ module into OpenWISP RADIUS and then implement mechanisms for the users to securely download their certificates. -If you're interested in this feature, let us know via the :ref:`support -channels `. +If you're interested in this feature, let us know via the `support +channels `_. diff --git a/docs/source/developer/how_to_extend.rst b/docs/developer/extending.rst similarity index 80% rename from docs/source/developer/how_to_extend.rst rename to docs/developer/extending.rst index 60ed4757..cc10ad7f 100644 --- a/docs/source/developer/how_to_extend.rst +++ b/docs/developer/extending.rst @@ -1,6 +1,8 @@ -Extending openwisp-radius +Extending OpenWISP RADIUS ========================= +.. include:: ../partials/developer-docs.rst + One of the core values of the OpenWISP project is `Software Reusability `_, for this reason *openwisp-radius* provides a set of base classes which can @@ -16,19 +18,17 @@ and the `sample app will serve you as source of truth: just replicate and adapt that code to get a basic derivative of *openwisp-radius* working. -If you want to add new users fields, please follow the `tutorial to extend -the openwisp-users -`_. As -an example, we have extended *openwisp-users* to *sample_users* app and -added a field ``social_security_number`` in the `sample_users/models.py +If you want to add new users fields, please follow the :doc:`tutorial to +extend the openwisp-users `. As an example, we +have extended *openwisp-users* to *sample_users* app and added a field +``social_security_number`` in the `sample_users/models.py `_. -.. note:: +.. important:: - **Premise**: if you plan on using a customized version of this module, - we suggest to start with it since the beginning, because migrating - your data from the default module to your extended version may be time - consuming. + If you plan on using a customized version of this module, we suggest + to start with it since the beginning, because migrating your data from + the default module to your extended version may be time consuming. 1. Initialize your custom module -------------------------------- @@ -41,7 +41,7 @@ A django app is nothing more than a `python package of python scripts), in the following examples we'll call this django app ``myradius``, but you can name it how you want: -:: +.. code-block:: shell django-admin startapp myradius @@ -50,6 +50,18 @@ directory which is available in your `PYTHON_PATH `_ so that you can then import the result into your project. +2. Install ``openwisp-radius`` +------------------------------ + +Install (and add to the requirement of your project) openwisp-radius: + +.. code-block:: + + pip install openwisp-radius + +3. Add your App to ``INSTALLED_APPS`` +------------------------------------- + Now you need to add ``myradius`` to ``INSTALLED_APPS`` in your ``settings.py``, ensuring also that ``openwisp_radius`` has been removed: @@ -96,31 +108,7 @@ Now you need to add ``myradius`` to ``INSTALLED_APPS`` in your "openwisp_radius.saml.backends.OpenwispRadiusSaml2Backend", # optional, can be removed if SAML login is not needed ) -.. important:: - - Remember to include your radius app's name before proceeding. - -.. note:: - - For more information about how to work with django projects and django - apps, please refer to the `django documentation - `_. - -2. Install ``openwisp-radius`` ------------------------------- - -Install (and add to the requirement of your project) openwisp-radius: - -:: - - pip install openwisp-radius - -.. note:: - - Use ``pip install openwisp-radius[saml]`` if you intend to use - :ref:`Single Sign-On (SAML) ` feature. - -3. Add ``EXTENDED_APPS`` +4. Add ``EXTENDED_APPS`` ------------------------ Add the following to your ``settings.py``: @@ -129,7 +117,7 @@ Add the following to your ``settings.py``: EXTENDED_APPS = ("openwisp_radius",) -4. Add ``openwisp_utils.staticfiles.DependencyFinder`` +5. Add ``openwisp_utils.staticfiles.DependencyFinder`` ------------------------------------------------------ Add ``openwisp_utils.staticfiles.DependencyFinder`` to @@ -143,7 +131,7 @@ Add ``openwisp_utils.staticfiles.DependencyFinder`` to "openwisp_utils.staticfiles.DependencyFinder", ] -5. Add ``openwisp_utils.loaders.DependencyLoader`` +6. Add ``openwisp_utils.loaders.DependencyLoader`` -------------------------------------------------- Add ``openwisp_utils.loaders.DependencyLoader`` to ``TEMPLATES`` in your @@ -171,25 +159,20 @@ Add ``openwisp_utils.loaders.DependencyLoader`` to ``TEMPLATES`` in your } ] -6. Inherit the AppConfig class +7. Inherit the AppConfig class ------------------------------ -Please refer to the following files in the sample app of the test project: - -- `sample_radius/__init__.py - `_ -- `sample_radius/apps.py - `_ +Refer to the `sample_radius/apps.py +`_ +file in the sample app of the test project. You have to replicate and adapt that code in your project. -.. note:: - - For more information regarding the concept of ``AppConfig`` please - refer to the `"Applications" section in the django documentation - `_. +For more information regarding the concept of ``AppConfig`` please refer +to the `"Applications" section in the django documentation +`_. -7. Create your custom models +8. Create your custom models ---------------------------- For the purpose of showing an example, we added a simple ``details`` field @@ -198,13 +181,11 @@ to the `models of the sample app in the test project You can add fields in a similar way in your ``models.py`` file. -.. note:: +For doubts regarding how to use, extend or develop models please refer to +the `"Models" section in the django documentation +`_. - For doubts regarding how to use, extend or develop models please refer - to the `"Models" section in the django documentation - `_. - -8. Add swapper configurations +9. Add swapper configurations ----------------------------- Once you have created the models, add the following to your @@ -235,8 +216,8 @@ Once you have created the models, add the following to your Substitute ``myradius`` with the name you chose in step 1. -9. Create database migrations ------------------------------ +10. Create database migrations +------------------------------ Copy the `migration files from the sample_radius's migration folder `_. @@ -244,26 +225,24 @@ Copy the `migration files from the sample_radius's migration folder Now, create database migrations as per your custom application's requirements: -:: +.. code-block:: shell ./manage.py makemigrations If you are starting with a fresh database, you can apply the migrations: -:: +.. code-block:: shell ./manage.py migrate However, if you want :ref:`migrate an existing freeradius database please -read the guide in the setup `. - -.. note:: +read the guide in the setup `. - For more information, refer to the `"Migrations" section in the django - documentation - `_. +For more information, refer to the `"Migrations" section in the django +documentation +`_. -10. Create the admin +11. Create the admin -------------------- Refer to the `admin.py file of the sample app @@ -272,12 +251,10 @@ Refer to the `admin.py file of the sample app To introduce changes to the admin, you can do it in two main ways which are described below. -.. note:: - - For more information regarding how the django admin works, or how it - can be customized, please refer to `"The django admin site" section in - the django documentation - `_. +For more information regarding how the django admin works, or how it can +be customized, please refer to `"The django admin site" section in the +django documentation +`_. 1. Monkey patching ~~~~~~~~~~~~~~~~~~ @@ -414,7 +391,7 @@ resort to monkey patching, you can proceed as follows: pass # add your changes here -11. Setup Freeradius API Allowed Hosts +12. Setup Freeradius API Allowed Hosts -------------------------------------- Add allowed freeradius hosts in ``settings.py``: @@ -423,12 +400,10 @@ Add allowed freeradius hosts in ``settings.py``: OPENWISP_RADIUS_FREERADIUS_ALLOWED_HOSTS = ["127.0.0.1"] -.. note:: +Read more about :ref:`freeradius allowed hosts in settings page +`. - Read more about :ref:`freeradius allowed hosts in settings page - `. - -12. Setup Periodic tasks +13. Setup Periodic tasks ------------------------ Some periodic commands are required in production environments to enable @@ -443,22 +418,20 @@ certain features and facilitate database cleanup: Some celery tasks take an argument, for instance ``365`` is given here for ``delete_old_radacct`` in the example settings. These arguments are passed to their respective management commands. More information about these -parameters can be found at the :ref:`management commands page -`. +parameters can be found at the :doc:`management commands page +<../user/management_commands>`. 3. Add the following in your settings.py file: - :: - - CELERY_IMPORTS = ('openwisp_monitoring.device.tasks',) +.. code-block:: python -.. note:: + CELERY_IMPORTS = ("openwisp_radius.tasks",) - Celery tasks do not start with django server and need to be started - seperately, please read about running :ref:`celery and celery-beat - ` tasks. +For more information about the usage of celery in django, please refer to +the `"First steps with Django" section in the celery documentation +`_. -13. Create root URL configuration +14. Create root URL configuration --------------------------------- The root ``url.py`` file should have the following paths (please read the @@ -479,20 +452,17 @@ comments): # openwisp-radius urls path("accounts/", include("openwisp_users.accounts.urls")), path("api/v1/", include("openwisp_utils.api.urls")), - # Use only when extending views (dicussed below) + # Use only when extending views (discussed below) # path('', include((get_urls(api_views, social_views, saml_views), 'radius'), namespace='radius')), - path( - "", include("openwisp_radius.urls", namespace="radius") - ), # Remove when extending views + # Remove when extending views + path("", include("openwisp_radius.urls", namespace="radius")), ] -.. note:: - - For more information about URL configuration in django, please refer - to the `"URL dispatcher" section in the django documentation - `_. +For more information about URL configuration in django, please refer to +the `"URL dispatcher" section in the django documentation +`_. -14. Import the automated tests +15. Import the automated tests ------------------------------ When developing a custom application based on this module, it's a good @@ -509,7 +479,7 @@ to find out how to do this. You can then run tests with: -:: +.. code-block:: shell # the --parallel flag is optional ./manage.py test --parallel myradius @@ -533,15 +503,13 @@ API views. Create a view file as done in `API views.py `_. -Remember to use these views in root URL configurations in point 11. If you +Remember to use these views in root URL configurations in point 14. If you want only extend the API views and not social views, you can use ``get_urls(api_views, None)`` to get social_views from *openwisp_radius*. -.. note:: - - For more information about django views, please refer to the `views - section in the django documentation - `_. +For more information about django views, please refer to the `views +section in the django documentation +`_. 2. Extending the Social Views ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -554,7 +522,7 @@ social views. Create a view file as done in `social views.py `_. -Remember to use these views in root URL configurations in point 11. If you +Remember to use these views in root URL configurations in point 14. If you want only extend the API views and not social views, you can use ``get_urls(api_views, None)`` to get social_views from *openwisp_radius*. @@ -569,13 +537,11 @@ SAML views. Create a view file as done in `saml views.py `_. -Remember to use these views in root URL configurations in point 11. If you +Remember to use these views in root URL configurations in point 14. If you want only extend the API views and social view but not SAML views, you can use ``get_urls(api_views, social_views, None)`` to get saml_views from *openwisp_radius*. -.. note:: - - For more information about django views, please refer to the `views - section in the django documentation - `_. +For more information about django views, please refer to the `views +section in the django documentation +`_. diff --git a/docs/developer/index.rst b/docs/developer/index.rst new file mode 100644 index 00000000..99915fc9 --- /dev/null +++ b/docs/developer/index.rst @@ -0,0 +1,16 @@ +Developer Docs +============== + +.. include:: ../partials/developer-docs.rst + +.. toctree:: + :maxdepth: 2 + + ./installation.rst + ./utils.rst + ./extending.rst + +Other useful resources: + + - :doc:`../user/rest-api` + - :doc:`../user/settings` diff --git a/docs/developer/installation.rst b/docs/developer/installation.rst new file mode 100644 index 00000000..e8aaf526 --- /dev/null +++ b/docs/developer/installation.rst @@ -0,0 +1,161 @@ +Developer Installation Instructions +=================================== + +.. include:: ../partials/developer-docs.rst + +.. contents:: **Table of Contents**: + :depth: 2 + :local: + +Dependencies +------------ + +- Python >= 3.8 + +Installing for Development +-------------------------- + +Install the system dependencies: + +.. code-block:: shell + + sudo apt update + sudo apt install -y sqlite3 libsqlite3-dev libpq-dev + sudo apt install -y xmlsec1 + sudo apt install -y chromium-browser + +Fork and clone the forked repository: + +.. code-block:: shell + + git clone git://github.com//openwisp-radius + +Navigate into the cloned repository: + +.. code-block:: shell + + cd openwisp-radius/ + +Launch Redis: + +.. code-block:: shell + + docker-compose up -d redis + +Setup and activate a virtual-environment (we'll be using `virtualenv +`_): + +.. code-block:: shell + + python -m virtualenv env + source env/bin/activate + +Make sure that your base python packages are up to date before moving to +the next step: + +.. code-block:: shell + + pip install -U pip wheel setuptools + +Install development dependencies: + +.. code-block:: shell + + pip install -e .[saml,openvpn_status] + pip install -r requirements-test.txt + sudo npm install -g jshint stylelint + +Install WebDriver for Chromium for your browser version from +https://chromedriver.chromium.org/home and Extract ``chromedriver`` to one +of directories from your ``$PATH`` (example: ``~/.local/bin/``). + +Create database: + +.. code-block:: shell + + cd tests/ + ./manage.py migrate + ./manage.py createsuperuser + +Launch celery worker (for background jobs): + +.. code-block:: shell + + celery -A openwisp2 worker -l info + +Launch development server: + +.. code-block:: shell + + ./manage.py runserver + +You can access the admin interface at ``http://127.0.0.1:8000/admin/``. + +Run tests with: + +.. code-block:: shell + + ./runtests.py --parallel + +Run quality assurance tests with: + +.. code-block:: shell + + ./run-qa-checks + +Alternative Sources +------------------- + +Pypi +~~~~ + +To install the latest Pypi: + +.. code-block:: shell + + pip install openwisp-radius + +Github +~~~~~~ + +To install the latest development version tarball via HTTPs: + +.. code-block:: shell + + pip install https://github.com/openwisp/openwisp-radius/tarball/master + +Alternatively you can use the git protocol: + +.. code-block:: shell + + pip install -e git+git://github.com/openwisp/openwisp-radius#egg=openwisp_radius[saml,openvpn_status] + +.. _radius_migrate_existing_freeradius_db: + +Migrating an existing freeradius database +----------------------------------------- + +If you already have a freeradius 3 database with the default schema, you +should be able to use it with openwisp-radius (and extended apps) easily: + +1. first of all, back up your existing database; +2. configure django to connect to your existing database; +3. fake the first migration (which only replicates the default freeradius + schema) and then launch the rest of migrations normally, see the + examples below to see how to do this. + +.. code-block:: shell + + ./manage.py migrate --fake openwisp-radius 0001_initial_freeradius + ./manage.py migrate + +Troubleshooting Steps for Common Installation Issues +---------------------------------------------------- + +If you encounter any issue during installation, run: + +.. code-block:: shell + + pip install -e .[saml] -r requirements-test.txt + +instead of ``pip install -r requirements-test.txt`` diff --git a/docs/developer/utils.rst b/docs/developer/utils.rst new file mode 100644 index 00000000..8fd5de04 --- /dev/null +++ b/docs/developer/utils.rst @@ -0,0 +1,66 @@ +Code Utilities +============== + +.. include:: ../partials/developer-docs.rst + +.. contents:: **Table of Contents**: + :depth: 2 + :local: + +Signals +------- + +``radius_accounting_success`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Path**: ``openwisp_radius.signals.radius_accounting_success`` + +**Arguments**: + +- ``sender`` : ``AccountingView`` +- ``accounting_data`` (``dict``): accounting information +- ``view``: instance of ``AccountingView`` + +This signal is emitted every time the accounting REST API endpoint +completes successfully, just before the response is returned. + +The ``view`` argument can also be used to access the ``request`` object +i.e. ``view.request``. + +Captive portal mock views +------------------------- + +The development environment of openwisp-radius provides two URLs that mock +the behavior of a captive portal, these URLs can be used when testing +frontend applications like :doc:`OpenWISP WiFi Login Pages +` during development. + +.. note:: + + These views are meant to be used just for development and testing. + +Captive Portal Login Mock View +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- **URL**: ``http://localhost:8000/captive-portal-mock/login/``. +- **POST fields**: ``auth_pass`` or ``password``. + +This view handles the captive portal login process by first checking for +either an ``auth_pass`` or ``password`` in the POST request data. It then +attempts to find a corresponding ``RadiusToken`` instance where the key +matches the provided value. If a matching token is found and there are no +active sessions (i.e., no open ``RadiusAccounting`` records), then it +creates a new radius session for the user. If successful, the user is +considered logged in. + +Captive Portal Logout Mock View +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- **URL**: ``http://localhost:8000/captive-portal-mock/logout/``. +- **POST fields**: ``logout_id``. + +This view looks for an entry in the ``radacct`` table where ``session_id`` +matches the value passed in the ``logout_id`` POST field. If such an entry +is found, the view makes a ``POST`` request to the accounting view to mark +the session as terminated, using ``User-Request`` as the termination +cause. diff --git a/docs/source/images/add_users_csv.gif b/docs/images/add_users_csv.gif similarity index 100% rename from docs/source/images/add_users_csv.gif rename to docs/images/add_users_csv.gif diff --git a/docs/source/images/add_users_prefix.gif b/docs/images/add_users_prefix.gif similarity index 100% rename from docs/source/images/add_users_prefix.gif rename to docs/images/add_users_prefix.gif diff --git a/docs/source/images/download_user_credentials_button.png b/docs/images/download_user_credentials_button.png similarity index 100% rename from docs/source/images/download_user_credentials_button.png rename to docs/images/download_user_credentials_button.png diff --git a/docs/source/images/drf_api_interface.png b/docs/images/drf_api_interface.png similarity index 100% rename from docs/source/images/drf_api_interface.png rename to docs/images/drf_api_interface.png diff --git a/docs/source/images/freeradius_allowed_hosts.png b/docs/images/freeradius_allowed_hosts.png similarity index 100% rename from docs/source/images/freeradius_allowed_hosts.png rename to docs/images/freeradius_allowed_hosts.png diff --git a/docs/source/images/mac-address-roaming.png b/docs/images/mac-address-roaming.png similarity index 100% rename from docs/source/images/mac-address-roaming.png rename to docs/images/mac-address-roaming.png diff --git a/docs/source/images/optional_fields.png b/docs/images/optional_fields.png similarity index 100% rename from docs/source/images/optional_fields.png rename to docs/images/optional_fields.png diff --git a/docs/source/images/org_uuid.png b/docs/images/org_uuid.png similarity index 100% rename from docs/source/images/org_uuid.png rename to docs/images/org_uuid.png diff --git a/docs/source/images/organization_coa_enabled.png b/docs/images/organization_coa_enabled.png similarity index 100% rename from docs/source/images/organization_coa_enabled.png rename to docs/images/organization_coa_enabled.png diff --git a/docs/source/images/organization_registration_setting.png b/docs/images/organization_registration_setting.png similarity index 100% rename from docs/source/images/organization_registration_setting.png rename to docs/images/organization_registration_setting.png diff --git a/docs/source/images/organization_saml_setting.png b/docs/images/organization_saml_setting.png similarity index 100% rename from docs/source/images/organization_saml_setting.png rename to docs/images/organization_saml_setting.png diff --git a/docs/source/images/organization_sms_verification_setting.png b/docs/images/organization_sms_verification_setting.png similarity index 100% rename from docs/source/images/organization_sms_verification_setting.png rename to docs/images/organization_sms_verification_setting.png diff --git a/docs/source/images/organization_social_login_setting.png b/docs/images/organization_social_login_setting.png similarity index 100% rename from docs/source/images/organization_social_login_setting.png rename to docs/images/organization_social_login_setting.png diff --git a/docs/source/images/pdf_of_user_list.png b/docs/images/pdf_of_user_list.png similarity index 100% rename from docs/source/images/pdf_of_user_list.png rename to docs/images/pdf_of_user_list.png diff --git a/docs/source/images/swagger_api.png b/docs/images/swagger_api.png similarity index 100% rename from docs/source/images/swagger_api.png rename to docs/images/swagger_api.png diff --git a/docs/source/images/token.png b/docs/images/token.png similarity index 100% rename from docs/source/images/token.png rename to docs/images/token.png diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..73d02ecc --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,70 @@ +RADIUS +====== + +.. seealso:: + + **Source code**: `github.com/openwisp/openwisp-radius + `_. + +OpenWISP RADIUS is available since OpenWISP 22.05 and provides many +features aimed at public WiFi services. + +For a full introduction please refer to :doc:`user/intro`. + +The following diagram illustrates the role of the RADIUS module within the +OpenWISP architecture. + +.. figure:: /images/architecture/v2/architecture-v2-openwisp-radius.png + :target: ../_images/architecture-v2-openwisp-radius.png + :align: center + :alt: OpenWISP Architecture: Radius module + + **OpenWISP Architecture: highlighted radius module** + +.. important:: + + For an enhanced viewing experience, open the image above in a new + browser tab. + + Refer to :doc:`/general/architecture` for more information. + +.. toctree:: + :caption: RADIUS Module Usage Docs + :maxdepth: 1 + + user/intro.rst + user/registration.rst + user/generating_users.rst + user/importing_users.rst + user/social_login.rst + user/saml.rst + user/enforcing_limits.rst + user/change_of_authorization.rst + user/management_commands.rst + user/rest-api.rst + user/settings.rst + +.. toctree:: + :caption: RADIUS Module Developer Docs + :maxdepth: 2 + + Developer Docs Index + +Deploy instructions +------------------- + +See :ref:`Enabling the RADIUS module on the OpenWISP ansible role +documentation `. + +Alternatively you can set it up manually by following these guides: + +.. toctree:: + :maxdepth: 1 + + deploy/freeradius + deploy/freeradius_wpa_enterprise + +This module is also available in :doc:`docker-openwisp ` +although its usage is not recommended for production usage yet, unless the +reader is willing to invest effort in adapting the docker images and +configurations to overcome any roadblocks encountered. diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 7cdf5751..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,36 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=python -msphinx -) -set SOURCEDIR=source -set BUILDDIR=build -set SPHINXPROJ=openwisp-radius - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The Sphinx module was not found. Make sure you have Sphinx installed, - echo.then set the SPHINXBUILD environment variable to point to the full - echo.path of the 'sphinx-build' executable. Alternatively you may add the - echo.Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - -:end -popd diff --git a/docs/partials/developer-docs.rst b/docs/partials/developer-docs.rst new file mode 100644 index 00000000..39d7fc24 --- /dev/null +++ b/docs/partials/developer-docs.rst @@ -0,0 +1,9 @@ +.. note:: + + This page is for developers who want to customize or extend OpenWISP + RADIUS, whether for bug fixes, new features, or contributions. + + For user guides and general information, please see: + + - :doc:`General OpenWISP Quickstart ` + - :doc:`OpenWISP RADIUS User Docs ` diff --git a/docs/source/assets/design/favicon.png b/docs/source/assets/design/favicon.png deleted file mode 100644 index 3b8cf13f..00000000 Binary files a/docs/source/assets/design/favicon.png and /dev/null differ diff --git a/docs/source/assets/design/radius-logo-dark.svg b/docs/source/assets/design/radius-logo-dark.svg deleted file mode 100644 index 34856eeb..00000000 --- a/docs/source/assets/design/radius-logo-dark.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - - diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index b17b379b..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,165 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -# -# openwisp-radius documentation build configuration file, created by -# sphinx-quickstart on Tue Jun 27 11:13:40 2017. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys - -from openwisp_radius import VERSION, get_version - -sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath('.')))) - - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ['sphinx.ext.autodoc', 'openwisp.sphinx.theme'] - -# Add any paths that contain templates here, relative to this directory. -# templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -from datetime import date - -project = 'openwisp-radius' -copyright = f'2017-{date.today().year} OpenWISP and individual contributors' -author = 'OpenWISP contributors' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. - -# The short X.Y version. -version = f'{VERSION[0]}.{VERSION[1]}' -# The full version, including alpha/beta/rc tags. -release = get_version() - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'openwisp-sphinx-theme' -html_favicon = 'assets/design/favicon.png' -html_logo = 'assets/design/radius-logo-dark.svg' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# html_theme_options = {} -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = 'openwisp-radiusdoc' - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - ( - master_doc, - 'openwisp-radius.tex', - 'openwisp-radius Documentation', - 'Fiorella De Luca', - 'manual', - ), -] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'openwisp-radius', 'openwisp-radius Documentation', [author], 1) -] - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - master_doc, - 'openwisp-radius', - 'openwisp-radius Documentation', - author, - 'openwisp-radius', - 'One line description of project.', - 'Miscellaneous', - ), -] diff --git a/docs/source/developer/captive_portal_mock.rst b/docs/source/developer/captive_portal_mock.rst deleted file mode 100644 index fb372711..00000000 --- a/docs/source/developer/captive_portal_mock.rst +++ /dev/null @@ -1,36 +0,0 @@ -Captive portal mock views -========================= - -The development environment of openwisp-radius provides two URLs that mock -the behavior of a captive portal, these URLs can be used when testing -frontend applications like `openwisp-wifi-login-pages -`_ during -development. - -.. note:: - - These views are meant to be used just for development and testing. - -Captive Portal Login Mock View ------------------------------- - -- **URL**: ``http://localhost:8000/captive-portal-mock/login/``. -- **POST fields**: ``auth_pass`` or ``password``. - -This view looks for ``auth_pass`` or ``password`` in the POST request -data, and if it finds anything will try to look for any ``RadiusToken`` -instance having its key equal to this value, and if it does find one, it -makes a ``POST`` request to accouting view to create the radius session -related to the user to which the radius token belongs, provided there's no -other open session for the same user. - -Captive Portal Logout Mock View -------------------------------- - -- **URL**: ``http://localhost:8000/captive-portal-mock/logout/``. -- **POST fields**: ``logout_id``. - -This view looks for an entry in the ``radacct`` table with ``session_id`` -equals to what is passed in the ``logout_id`` POST field and if it finds -one, it makes a ``POST`` request to accounting view to flags the session -as terminated by passing ``User-Request`` as termination cause. diff --git a/docs/source/developer/contributing.rst b/docs/source/developer/contributing.rst deleted file mode 100644 index 4803bfd8..00000000 --- a/docs/source/developer/contributing.rst +++ /dev/null @@ -1,91 +0,0 @@ -Contributing -============ - -Thank you for taking the time to contribute to openwisp-radius, please -read the `guide for contributing to openwisp repositories -`_. - -Follow these guidelines to speed up the process. - -.. contents:: **Table of Contents**: - :backlinks: none - :depth: 3 - -.. note:: - - **In order to have your contribution accepted faster**, please read - the `OpenWISP contributing guidelines - `_ and make sure - to follow its guidelines. - -Setup ------ - -Once you have chosen an issue to work on, :ref:`setup your machine for -development `. - -Ensure test coverage does not decrease --------------------------------------- - -First of all, install the test requirements: - -.. code-block:: shell - - workon radius # activate virtualenv - pip install --no-cache-dir -U -r requirements-test.txt - -When you introduce changes, ensure test coverage is not decreased with: - -.. code-block:: shell - - coverage run --source=openwisp_radius runtests.py - -Follow style conventions ------------------------- - -First of all, install the test requirements: - -.. code-block:: shell - - workon radius # activate virtualenv - pip install --no-cache-dir -U -r requirements-test.txt - npm install -g jslint - -Before committing your work check that your changes are not breaking our -`coding style conventions -`_: - -.. code-block:: shell - - # reformat the code according to the conventions - openwisp-qa-format - # run QA checks - ./run-qa-checks - -For more information, please see: - -- `OpenWISP Coding Style Conventions - `_ - -Update the documentation ------------------------- - -If you introduce new features or change existing documented behavior, -please remember to update the documentation! - -The documentation is located in the ``/docs`` directory of the repository. - -To do work on the docs, proceed with the following steps: - -.. code-block:: shell - - workon radius # activate virtualenv - pip install sphinx - cd docs - make html - -Send pull request ------------------ - -Now is time to push your changes to github and open a `pull request -`_! diff --git a/docs/source/developer/setup.rst b/docs/source/developer/setup.rst deleted file mode 100644 index 986ecde1..00000000 --- a/docs/source/developer/setup.rst +++ /dev/null @@ -1,402 +0,0 @@ -Setup -===== - -Try the demo ------------- - -**Need a quick overview?** `Try the OpenWISP Demo -`_. - -Deploy it in production ------------------------ - -An automated installer is available at `ansible-openwisp2 -`_. - -Create a virtual environment ----------------------------- - -Please use a `python virtual environment -`_. It keeps everybody on the -same page, helps reproducing bugs and resolving problems. - -We highly suggest to use **virtualenvwrapper**, please refer to the -official `virtualenvwrapper installation page -`_ and -come back here when ready to proceed. - -.. code-block:: shell - - # create virtualenv - mkvirtualenv radius - -.. note:: - - If you encounter an error like ``Python could not import the module - virtualenvwrapper``, add ``VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3`` - and run ``source virtualenvwrapper.sh`` again :) - -Install required system packages --------------------------------- - -Install packages required by Weasyprint for your OS: - - - `Linux - `_ - - `MacOS - `_ - - `Windows - `_ - -Install stable version from pypi --------------------------------- - -Install from pypi: - -.. code-block:: shell - - # REQUIRED: update base python packages - pip install -U pip setuptools wheel - # install openwisp-radius - pip install openwisp-radius - -Install development version ---------------------------- - -Install tarball: - -.. code-block:: shell - - # REQUIRED: update base python packages - pip install -U pip setuptools wheel - # install openwisp-radius - pip install https://github.com/openwisp/openwisp-radius/tarball/master - -Alternatively you can install via pip using git: - -.. code-block:: shell - - # REQUIRED: update base python packages - pip install -U pip setuptools wheel - # install openwisp-radius - pip install -e git+git://github.com/openwisp/openwisp-radius#egg=openwisp-radius - -If you want to contribute, install your cloned fork: - -.. code-block:: shell - - # REQUIRED: update base python packages - pip install -U pip setuptools wheel - # install your forked openwisp-radius - git clone git@github.com:/openwisp-radius.git - cd openwisp-radius - pip install -e . - -Setup (integrate in an existing django project) ------------------------------------------------ - -The ``settings.py`` file of your project should have at least the -following modules listed ``INSTALLED_APPS``: - -.. code-block:: python - - INSTALLED_APPS = [ - "django.contrib.auth", - "django.contrib.contenttypes", - "django.contrib.sessions", - "django.contrib.messages", - "django.contrib.staticfiles", - "django.contrib.humanize", - # openwisp admin theme - "openwisp_utils.admin_theme", - # all-auth - "django.contrib.sites", - "allauth", - "allauth.account", - # admin - "django.contrib.admin", - # rest framework - "rest_framework", - "django_filters", - # registration - "rest_framework.authtoken", - "dj_rest_auth", - "dj_rest_auth.registration", - # openwisp radius - "openwisp_radius", - "openwisp_users", - "private_storage", - "drf_yasg", - ] - -These modules are optional, add them only if you need the :ref:`social -login ` feature: - -.. code-block:: python - - INSTALLED_APPS += [ - # social login - "allauth.socialaccount", - "allauth.socialaccount.providers.facebook", - "allauth.socialaccount.providers.google", - ] - -Add media locations in ``settings.py``: - -.. code-block:: python - - MEDIA_ROOT = os.path.join(BASE_DIR, "media") - PRIVATE_STORAGE_ROOT = os.path.join(MEDIA_ROOT, "private") - -Also, add ``AUTH_USER_MODEL``, ``AUTHENTICATION_BACKENDS`` and ``SITE_ID`` -to your ``settings.py``: - -.. code-block:: python - - AUTH_USER_MODEL = "openwisp_users.User" - SITE_ID = 1 - AUTHENTICATION_BACKENDS = ( - "openwisp_users.backends.UsersAuthenticationBackend", - ) - -Add allowed freeradius hosts in ``settings.py``: - -.. code-block:: python - - OPENWISP_RADIUS_FREERADIUS_ALLOWED_HOSTS = ["127.0.0.1"] - -.. note:: - - Read more about :ref:`freeradius allowed hosts in settings page - `. - -Add the URLs to your main ``urls.py``: - -.. code-block:: python - - from openwisp_radius.urls import get_urls - - urlpatterns = [ - # ... other urls in your project ... - # django admin interface urls - path("admin/", admin.site.urls), - # openwisp-radius urls - path("api/v1/", include("openwisp_utils.api.urls")), - path("api/v1/", include("openwisp_users.api.urls")), - path("accounts/", include("openwisp_users.accounts.urls")), - path("", include("openwisp_radius.urls")), - ] - -Then run: - -.. code-block:: shell - - ./manage.py migrate - -.. _migrate_existing_freeradius_db: - -Migrating an existing freeradius database ------------------------------------------ - -If you already have a freeradius 3 database with the default schema, you -should be able to use it with openwisp-radius (and extended apps) easily: - -1. first of all, back up your existing database; -2. configure django to connect to your existing database; -3. fake the first migration (which only replicates the default freeradius - schema) and then launch the rest of migrations normally, see the - examples below to see how to do this. - -.. code-block:: shell - - ./manage.py migrate --fake openwisp-radius 0001_initial_freeradius - ./manage.py migrate - -Automated periodic tasks ------------------------- - -Some periodic commands are required in production environments to enable -certain features and facilitate database cleanup. There are two ways to -automate these tasks: - -1. Celery-beat (Recommended Method) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. You need to create a `celery configuration file as it's created in - example file - `_. -2. Add celery to ``__init__.py`` of your project: - -.. code-block:: python - - from .celery import app as celery_app - - __all__ = ["celery_app"] - -3. In the settings.py, `configure the CELERY_BEAT_SCHEDULE -`_. -Some celery tasks take an argument, for instance ``365`` is given here for -``delete_old_radacct`` in the example settings. These arguments are passed -to their respective management commands. More information about these -parameters can be found at the `management commands page -<../user/management_commands.html>`_. - -.. note:: - - Celery tasks do not start with django server and need to be started - seperately, please read about running `celery and celery-beat - <./setup.html#celery-usage>`_ tasks. - -2. Crontab (Legacy Method) -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Edit the crontab with: - -.. code-block:: shell - - crontab -e - -Add and modify the following lines accordingly: - -.. code-block:: shell - - # This command deletes RADIUS accounting sessions older than 365 days - 30 04 * * * /bin/python /manage.py delete_old_radacct 365 - - # This command deletes RADIUS post-auth logs older than 365 days - 30 04 * * * /bin/python /manage.py delete_old_postauth 365 - - # This command closes stale RADIUS sessions that have remained open for 15 days - 30 04 * * * /bin/python /manage.py cleanup_stale_radacct 15 - - # This command deactivates expired user accounts which were created temporarily - # (eg: for en event) and have an expiration date set. - 30 04 * * * /bin/python /manage.py deactivate_expired_users - - # This command deletes users that have expired (and should have - # been deactivated by deactivate_expired_users) for more than - # 18 months (which is the default duration) - 30 04 * * * /bin/python /manage.py delete_old_radiusbatch_users - -Be sure to replace ```` with the absolute path to the -Python virtual environment. - -Also, change ```` to the directory where ``manage.py`` is. - -To get the absolute path to ``manage.py`` when openwisp-radius is -installed for development, navigate to the base directory of the cloned -fork. Then, run: - -.. code-block:: shell - - cd tests/ - pwd - -.. note:: - - More information can be found at the :ref:`management commands page - `. - -.. _installing_for_development: - -Installing for development --------------------------- - -Install python3-dev and gcc: - -.. code-block:: shell - - sudo apt install python3-dev gcc - -Install sqlite: - -.. code-block:: shell - - sudo apt install sqlite3 libsqlite3-dev libpq-dev - -Install mysqlclient: - -.. code-block:: shell - - sudo apt install libmysqlclient-dev libssl-dev - -.. note:: - - If you are on Debian 10 or 9 you may need to install - ``default-libmysqlclient-dev`` instead - -Install xmlsec1: - -.. code-block:: shell - - sudo apt install xmlsec1 - -Install your forked repo: - -.. code-block:: shell - - git clone git://github.com//openwisp-radius - cd openwisp-radius/ - pip install -e .[saml,openvpn_status] - -Install test requirements: - -.. code-block:: shell - - pip install -r requirements-test.txt - -Create database: - -.. code-block:: shell - - cd tests/ - ./manage.py migrate - ./manage.py createsuperuser - -Launch development server: - -.. code-block:: shell - - ./manage.py runserver - -You can access the admin interface at http://127.0.0.1:8000/admin/. - -Run tests with: - -.. code-block:: shell - - ./runtests.py - -.. _celery_usage: - -Celery Usage ------------- - -To run celery, you need to start redis-server. You can `install redis on -your machine `_ or `install docker -`_ and run redis inside docker -container: - -.. code-block:: shell - - docker run -p 6379:6379 --name openwisp-redis -d redis:alpine - -Run celery (it is recommended to use a tool like supervisord in -production): - -.. code-block:: shell - - # Optionally, use ``--detach`` argument to avoid using multiple terminals - celery -A openwisp2 worker -l info - celery -A openwisp2 beat -l info - -Troubleshooting ---------------- - -If you encounter any issue during installation, run: - -.. code-block:: shell - - pip install -e .[saml] -r requirements-test.txt - -instead of ``pip install -r requirements-test.txt`` diff --git a/docs/source/developer/signals.rst b/docs/source/developer/signals.rst deleted file mode 100644 index 0b19244d..00000000 --- a/docs/source/developer/signals.rst +++ /dev/null @@ -1,19 +0,0 @@ -Signals -======= - -``radius_accounting_success`` ------------------------------ - -**Path**: ``openwisp_radius.signals.radius_accounting_success`` - -**Arguments**: - -- ``sender`` : ``AccountingView`` -- ``accounting_data`` (``dict``): accounting information -- ``view``: instance of ``AccountingView`` - -This signal is emitted every time the accounting REST API endpoint -completes successfully, just before the response is returned. - -The ``view`` argument can also be used to access the ``request`` object -i.e. ``view.request``. diff --git a/docs/source/general/changelog.rst b/docs/source/general/changelog.rst deleted file mode 100644 index 525b47cf..00000000 --- a/docs/source/general/changelog.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../CHANGES.rst diff --git a/docs/source/general/goals.rst b/docs/source/general/goals.rst deleted file mode 100644 index 6525061a..00000000 --- a/docs/source/general/goals.rst +++ /dev/null @@ -1,71 +0,0 @@ -Motivations and Goals -===================== - -In this page we explain the goals of this project and the motivations that -led us on this path. - -Motivations ------------ - -The old version of OpenWISP (which we call OpenWISP 1) had a freeradius -module which provided several interesting features: - -- user registration -- account verification with several methods -- user management -- password reset -- basic general statistics -- basic user account page with user's statistics - -But it also had important problems: - -- it was not written with automated testing in mind, so there was a lot of - code which the maintainers didn't want to touch because of fear of - breaking existing features -- it was not written with an international user-base in mind, it contained - a great deal of code which was specific to a single country (Italy) -- it was hard to extend, even small changes required changing its core - code -- the user management code was implemented in a different way compared to - other openwisp1 modules, which added a lot of maintenance overhead -- it used outdated dependencies which over time became vulnerable and were - hard to replace -- **it did not perform hashing of user passwords** -- the documentation did not explain how to properly install and configure - the software - -Similar problems were affecting other modules of OpenWISP 1, that's why -over time we got convinced the best thing was to start fresh using best -practices since the start. - -Project goals -------------- - -The main aim of this project is to offer a web application and -documentation that helps people from all over the world to implement a -wifi network that can use freeradius to authenticate its users, either via -captive portal authentication or WPA2 enterprise, **BUT** this doesn't -mean we want to lock the software to this use case: we want to keep the -software generic enough so it can be useful to implement other use cases -that are related to networking connectivity and network management; **Just -keep in mind our main aim if you plan to contribute to openwisp-radius -please**. - -Other goals are listed below: - -- replace the user management system of OpenWISP 1 by providing a similar - feature set -- provide a web interface to manage a freeradius database -- provide abstract models and admin classes that can be imported, extended - and reused in third party apps -- provide ways to extend the logic of openwisp-radius without changing its - core -- ensure the code is written with an international audience in mind -- maintain a very good automated test suite -- reuse the django user management logic which is very robust and stable -- ensure passwords are hashed with strong algorithms and freeradius can - authorize/authenticate using these hashes (that's why we recommend using - the ``rlm_rest`` freeradius module with the REST API of openwisp-radius) -- integrate openwisp-radius with the rest of the openwisp2 ecosystem -- provide good documentation on how to install the project, configure it - with freeradius and use its most important features diff --git a/docs/source/general/support.rst b/docs/source/general/support.rst deleted file mode 100644 index 0e1c9880..00000000 --- a/docs/source/general/support.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _support: - -Support -======= - -The OpenWISP community is very active and offers best effort support -through the official `OpenWISP Support Channels -`_. - -.. raw:: html - -

- Commercial support is also available, for more information you can reach us at: - - support@openwisp.io. -

diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 80fd17bf..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,71 +0,0 @@ -openwisp-radius -=============== - -.. image:: https://travis-ci.org/openwisp/openwisp-radius.svg?branch=master - :target: https://travis-ci.org/openwisp/openwisp-radius - :alt: CI build status - -.. image:: https://coveralls.io/repos/github/openwisp/openwisp-radius/badge.svg?branch=master - :target: https://coveralls.io/github/openwisp/openwisp-radius?branch=master - :alt: Test Coverage - -.. image:: https://img.shields.io/librariesio/release/github/openwisp/openwisp-radius - :target: https://libraries.io/github/openwisp/openwisp-radius#repository_dependencies - :alt: Dependency monitoring - -.. image:: https://img.shields.io/gitter/room/nwjs/nw.js.svg - :target: https://gitter.im/openwisp/general - :alt: Chat - -.. image:: https://badge.fury.io/py/openwisp-radius.svg - :target: http://badge.fury.io/py/openwisp-radius - :alt: Pypi Version - -.. image:: https://pepy.tech/badge/openwisp-radius - :target: https://pepy.tech/project/openwisp-radius - :alt: Downloads - -.. image:: https://img.shields.io/badge/code%20style-black-000000.svg - :target: https://pypi.org/project/black/ - :alt: code style: black - -**OpenWISP-RADIUS** provides an admin interface to a `freeradius -`_ database and offers features that are common -in WiFi and ISP deployments. - -**Need a quick overview?** `Try the OpenWISP Demo -`_. - -.. note:: - - If you're building a public wifi service, we suggest to take a look at - `openwisp-wifi-login-pages - `_, which is - built to work with openwisp-radius. - -.. image:: https://raw.githubusercontent.com/openwisp/openwisp2-docs/master/assets/design/openwisp-logo-black.svg - :target: http://openwisp.org - -.. toctree:: - :maxdepth: 2 - - /developer/setup - /developer/freeradius - /developer/freeradius_wpa_enterprise - /user/settings - /user/management_commands - /user/importing_users - /user/generating_users - /user/enforcing_limits - /user/registration - /user/social_login - /user/saml - /user/change_of_authorization - /user/api - /developer/signals - /developer/how_to_extend - /developer/captive_portal_mock.rst - /general/support - /developer/contributing - /general/goals - /general/changelog.rst diff --git a/docs/source/user/change_of_authorization.rst b/docs/user/change_of_authorization.rst similarity index 97% rename from docs/source/user/change_of_authorization.rst rename to docs/user/change_of_authorization.rst index 2101033b..771a6f81 100644 --- a/docs/source/user/change_of_authorization.rst +++ b/docs/user/change_of_authorization.rst @@ -8,7 +8,7 @@ Change of Authorization (CoA) The *Change of Authorization (CoA)* is disabled by default. In order to enable this feature you have it enable it via :ref:`global - setting or from the admin interface `. + setting or from the admin interface `. The openwisp-radius module supports the Change of Authorization (CoA) specification of the RADIUS protocol described in `RFC 5176 diff --git a/docs/source/user/enforcing_limits.rst b/docs/user/enforcing_limits.rst similarity index 93% rename from docs/source/user/enforcing_limits.rst rename to docs/user/enforcing_limits.rst index d5bd9f11..d1856c6a 100644 --- a/docs/source/user/enforcing_limits.rst +++ b/docs/user/enforcing_limits.rst @@ -1,4 +1,4 @@ -Enforcing session limits +Enforcing Session Limits ======================== The default freeradius schema does not include a table where groups are @@ -21,7 +21,7 @@ For each group, checks and replies can be specified directly in the edit page of a Radius Group (``admin`` > ``groups`` > ``add group`` or ``change group``). -Default groups +Default Groups -------------- Some groups are created automatically by **openwisp-radius** during the @@ -41,9 +41,9 @@ nor it can be flagged as non-default: to set another group as default simply check that group as the default one, save and **openwisp-radius** will remove the default flag from the old default group. -.. _counters: +.. _radius_counters: -How limits are enforced: counters +How Limits are Enforced: Counters --------------------------------- In Freeradius, this kind of feature is implemented with the @@ -75,7 +75,7 @@ during a specific day is below the value indicated in the time with a ``Session-Timeout`` reply message or rejecting the authorization if the limit has been passed. -.. _daily_traffic_counter: +.. _radius_daily_traffic_counter: ``DailyTrafficCounter`` ~~~~~~~~~~~~~~~~~~~~~~~ @@ -89,8 +89,8 @@ has been passed. The attributes used for the check and or the reply message are configurable because it can differ from NAS to NAS, see -:ref:`traffic_counter_check_name` :ref:`traffic_counter_reply_name` for -more information. +:ref:`radius_traffic_counter_check_name` +:ref:`radius_traffic_counter_reply_name` for more information. ``MonthlyTrafficCounter`` ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -103,7 +103,7 @@ remaining octets with a reply message or rejecting the authorization if the limit has been passed. The reply message is configurable because it can differ from NAS to NAS, -:ref:`traffic_counter_reply_name` for more information. +:ref:`radius_traffic_counter_reply_name` for more information. ``MonthlySubscriptionTrafficCounter`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -111,7 +111,7 @@ The reply message is configurable because it can differ from NAS to NAS, .. important:: This counter is not enabled by default. It can be enabled via the - :ref:`counter_related_settings`. + :ref:`radius_counter_related_settings`. Same as ``MonthlyTrafficCounter``, but with the difference that the reset period depends on the day in which the user subscribed to the service: if @@ -119,7 +119,7 @@ the user signed up (or their account was created by an admin) on a date like November 15 2022, the reset period will start on the 15th day of every month. -Database support +Database Support ~~~~~~~~~~~~~~~~ The counters described above are available for PostgreSQL, MySQL, SQLite @@ -136,9 +136,9 @@ Django Settings ~~~~~~~~~~~~~~~ The settings available to control the behavior of counters are described -in :ref:`counter_related_settings`. +in :ref:`radius_counter_related_settings`. -Writing custom counter classes +Writing Custom Counter Classes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is possible to write custom counter classes to satisfy any need. @@ -165,7 +165,7 @@ Please look at the source code of OpenWISP RADIUS to find out more. `_ Once the new class is ready, you will need to add it to -:ref:`counters_setting`. +:ref:`radius_counters_setting`. It is also possible to implement a check class in a completely custom fashion (that is, not inheriting from ``BaseCounter``), the only diff --git a/docs/source/user/generating_users.rst b/docs/user/generating_users.rst similarity index 92% rename from docs/source/user/generating_users.rst rename to docs/user/generating_users.rst index 411779fd..290c29ad 100644 --- a/docs/source/user/generating_users.rst +++ b/docs/user/generating_users.rst @@ -1,5 +1,3 @@ -.. _generating_users: - Generating users ================ @@ -44,18 +42,18 @@ Once the batch object has been created, a PDF containing the user credentials can be downloaded by using the "Download user credentials" button in the upper right corner of the page: -.. image:: /images/download_user_credentials_button.png +.. image:: ../images/download_user_credentials_button.png :alt: Downlaod user credentials button in admin interface The contents of the PDF is in format of a table of users & their passwords: -.. image:: /images/pdf_of_user_list.png +.. image:: ../images/pdf_of_user_list.png :alt: Sample contents of the user credentials PDF file Usage Demonstration: -.. image:: /images/add_users_prefix.gif +.. image:: ../images/add_users_prefix.gif :alt: Demo: adding users from prefix Management command: ``prefix_add_users`` @@ -84,4 +82,5 @@ prefix. Usage is as shown below. REST API: Batch user creation ----------------------------- -See API documentation: :ref:`Batch user creation `. +See API documentation: :ref:`Batch user creation +`. diff --git a/docs/source/user/importing_users.rst b/docs/user/importing_users.rst similarity index 95% rename from docs/source/user/importing_users.rst rename to docs/user/importing_users.rst index 21fcc756..70bda5d4 100644 --- a/docs/source/user/importing_users.rst +++ b/docs/user/importing_users.rst @@ -1,5 +1,3 @@ -.. _importing_users: - Importing users =============== @@ -21,7 +19,7 @@ many features included in it such as: This operation can be performed via the admin interface, with a management command or via the REST API. -.. _csv_format: +.. _radius_csv_format: CSV Format ---------- @@ -85,14 +83,14 @@ Using the admin interface .. note:: The CSV uploaded must follow the :ref:`CSV format described above - `. + `. To generate users from the admin interface, go to ``Home > Batch user creation operations > Add`` (URL: ``/admin/openwisp_radius/radiusbatch/add``), set ``Strategy`` to ``Import from CSV``, choose the CSV file to upload and save. -.. image:: /images/add_users_csv.gif +.. image:: ../images/add_users_csv.gif :alt: Demo: adding users from CSV Management command: ``batch_add_users`` @@ -116,4 +114,5 @@ This command imports users from a csv file. Usage is as shown below. REST API: Batch user creation ----------------------------- -See :ref:`API documentation: Batch user creation `. +See :ref:`API documentation: Batch user creation +`. diff --git a/docs/user/intro.rst b/docs/user/intro.rst new file mode 100644 index 00000000..e807345e --- /dev/null +++ b/docs/user/intro.rst @@ -0,0 +1,13 @@ +RADIUS: Features +================ + +The RADIUS module provides the following features: + +- :doc:`Registration of new users ` +- :ref:`SMS verification ` +- :doc:`importing_users` +- :doc:`generating_users` +- :doc:`social_login` +- :doc:`saml` +- :doc:`enforcing_limits` +- :doc:`rest-api` diff --git a/docs/source/user/management_commands.rst b/docs/user/management_commands.rst similarity index 91% rename from docs/source/user/management_commands.rst rename to docs/user/management_commands.rst index aa2df790..549736ea 100644 --- a/docs/source/user/management_commands.rst +++ b/docs/user/management_commands.rst @@ -1,5 +1,3 @@ -.. _management_commands: - Management commands =================== @@ -70,8 +68,9 @@ For example: :ref:`Find out more about this feature in its dedicated page ` -This command deactivates expired user accounts which were created -temporarily (eg: for en event) and have an expiration date set. +This command deactivates expired user accounts which were created with +batch operation temporarily (eg: for en event) and have an expiration date +set. .. code-block:: shell @@ -80,15 +79,15 @@ temporarily (eg: for en event) and have an expiration date set. ``delete_old_radiusbatch_users`` -------------------------------- -This command deletes users that have expired (and should have been -deactivated by ``deactivate_expired_users``) for more than the specified -````. +This command deletes users created using batch operation that have expired +(and should have been deactivated by ``deactivate_expired_users``) for +more than the specified ````. .. code-block:: shell ./manage.py delete_old_radiusbatch_users --older-than-months -Note that the default duration is set to 18 months. +Note that the default duration is set to **18 months**. ``delete_unverified_users`` --------------------------- @@ -103,7 +102,7 @@ management command.** ./manage.py delete_unverified_users --older-than-days -Note that the default duration is set to 1 day. +Note that the default duration is set to **1 day**. It is also possible to exclude users that have registered using specified methods. You can specify multiple methods separated by comma(`,`). @@ -122,7 +121,7 @@ there is an easy migration script that will import your freeradius database, sites, social website account users, users & groups to openwisp-radius instance: -:: +.. code-block:: shell ./manage.py upgrade_from_django_freeradius @@ -130,7 +129,7 @@ The management command accepts an argument ``--backup``, that you can pass to give the location of the backup files, by default it looks in the ``tests/`` directory, eg: -:: +.. code-block:: shell ./manage.py upgrade_from_django_freeradius --backup /home/user/django_freeradius/ @@ -155,7 +154,7 @@ eg: created using prefix, please manually preserve the PDF files if you want to access the data in the future. -.. _convert_called_station_id: +.. _radius_convert_called_station_id: ``convert_called_station_id`` ----------------------------- diff --git a/docs/source/user/registration.rst b/docs/user/registration.rst similarity index 71% rename from docs/source/user/registration.rst rename to docs/user/registration.rst index 452121d4..1e8b9875 100644 --- a/docs/source/user/registration.rst +++ b/docs/user/registration.rst @@ -7,9 +7,8 @@ of new users via REST API so you can implement registration and password reset directly from your captive page. The registration API endpoint is described in :ref:`API: User Registration -`. +`. If you need users to self-register to a public wifi service, we suggest to -take a look at `openwisp-wifi-login-pages -`_, which is built -to work with openwisp-radius. +take a look at :doc:`OpenWISP WiFi Login Pages `, +which is built to work with openwisp-radius. diff --git a/docs/source/user/api.rst b/docs/user/rest-api.rst similarity index 89% rename from docs/source/user/api.rst rename to docs/user/rest-api.rst index 40e53481..cb58b572 100644 --- a/docs/source/user/api.rst +++ b/docs/user/rest-api.rst @@ -1,9 +1,9 @@ -API Documentation -================= +REST API Reference +================== -.. contents:: **Table of Contents**: - :backlinks: none - :depth: 4 +.. contents:: **Table of contents**: + :depth: 2 + :local: .. important:: @@ -11,33 +11,39 @@ API Documentation turned off by setting :ref:`OPENWISP_RADIUS_API ` to ``False``. +.. _radius_live_documentation: + Live documentation ------------------ -.. image:: /images/swagger_api.png +.. image:: ../images/swagger_api.png :alt: Swagger API Documentation A general live API documentation (following the OpenAPI specification) at ``/api/v1/docs/``. +.. _radius_browsable_web_interface: + Browsable web interface ----------------------- -.. image:: /images/drf_api_interface.png +.. image:: ../images/drf_api_interface.png :alt: API Interface Additionally, opening any of the endpoints :ref:`listed below -` directly in the browser will show the `browsable API -interface of Django-REST-Framework +` directly in the browser will show the `browsable +API interface of Django-REST-Framework `_, which makes it even easier to find out the details of each endpoint. +.. _radius_rest_endpoints: + FreeRADIUS API Endpoints ------------------------ The following section is dedicated to API endpoints that are designed to -be consumed by FreeRADIUS (:ref:`Authorize `, :ref:`Post Auth -`, :ref:`Accounting `). +be consumed by FreeRADIUS (:ref:`Authorize `, :ref:`Post +Auth `, :ref:`Accounting `). .. important:: @@ -45,7 +51,7 @@ be consumed by FreeRADIUS (:ref:`Authorize `, :ref:`Post Auth the :ref:`freeradius allowed hosts list `. -.. _freeradius_api_authentication: +.. _radius_freeradius_api_authentication: FreeRADIUS API Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -61,14 +67,14 @@ Radius User Token This method relies on the presence of a special token which was obtained by the user when authenticating via the :ref:`Obtain Auth Token View -`, this means the user would have to log in -through something like a web form first. +`, this means the user would have to +log in through something like a web form first. The flow works as follows: 1. the user enters credentials in a login form belonging to a specific organization and submits, the credentials are then sent to the - :ref:`Obtain Auth Token View `; + :ref:`Obtain Auth Token View `; 2. if credentials are correct, a **radius user token** associated to the user and organization is created and returned in the response; 3. the login page or app must then initiate the HTTP request to the web @@ -87,13 +93,13 @@ same OpenWISP instance. .. note:: By default, ```` is valid for authentication for one - request only and a new ```` needs to be `obtained for - each request <#login-obtain-user-auth-token>`_. However, if - `OPENWISP_RADIUS_DISPOSABLE_RADIUS_USER_TOKEN - <./settings.html#openwisp-radius-disposable-radius-user-token>`_ is - set to ``False``, the ```` is valid for authentication - as long as freeradius accounting ``Stop`` request is not sent or the - token is not deleted. + request only and a new ```` needs to be :ref:`obtained + for each request `. However, if + :ref:`OPENWISP_RADIUS_DISPOSABLE_RADIUS_USER_TOKEN + ` is set to ``False``, + the ```` is valid for authentication as long as + freeradius accounting ``Stop`` request is not sent or the token is not + deleted. .. warning:: @@ -102,7 +108,7 @@ same OpenWISP instance. single user account cannot consume services from multiple organizations simultaneously. -.. _bearer_token: +.. _radius_bearer_token: Bearer token ++++++++++++ @@ -114,8 +120,8 @@ specific organization is sent in each request, see :ref:`freeradius_site` for more information on the FreeRADIUS site configuration. The (:ref:`Organization UUID and Organization RADIUS token -`) are sent in the authorization header of the -HTTP request in the form of a Bearer token, eg: +`) are sent in the authorization header of +the HTTP request in the form of a Bearer token, eg: .. code-block:: text @@ -126,7 +132,7 @@ HTTP request in the form of a Bearer token, eg: This method is recommended if you are using only one organization and you have no need nor intention of adding more organizations in the future. -.. _querystring: +.. _radius_querystring: Querystring +++++++++++ @@ -143,7 +149,7 @@ This method is not recommended for production usage, it should be used for testing and debugging only (because webservers can include the querystring parameters in their logs). -.. _organization_uuid_token: +.. _radius_organization_uuid_token: Organization UUID & RADIUS API Token ++++++++++++++++++++++++++++++++++++ @@ -152,7 +158,7 @@ You can get (and set) the value of the OpenWISP RADIUS API token in the organization configuration page on the OpenWISP dashboard (select your organization in ``/admin/openwisp_users/organization/``): -.. image:: /images/token.png +.. image:: ../images/token.png :alt: Organization Radius Token .. note:: @@ -165,13 +171,13 @@ You will also need the UUID of your organization from the organization change page (select your organization in ``/admin/openwisp_users/organization/``): -.. image:: /images/org_uuid.png +.. image:: ../images/org_uuid.png :alt: Organization UUID -Requests authorizing with :ref:`bearer-token ` or -:ref:`querystring ` method **must** contain organization UUID -& token. If the tokens are missing or invalid, the request will receive a -``403`` HTTP error. +Requests authorizing with :ref:`bearer-token ` or +:ref:`querystring ` method **must** contain +organization UUID & token. If the tokens are missing or invalid, the +request will receive a ``403`` HTTP error. For information on how to configure FreeRADIUS to send the bearer tokens, see :ref:`freeradius_site`. @@ -207,12 +213,10 @@ The rate descriptions used in ``DEFAULT_THROTTLE_RATES`` may include ``second``, ``minute``, ``hour`` or ``day`` as the throttle period, setting it to ``None`` will result in no throttling. -.. _list_of_endpoints: - List of Endpoints ~~~~~~~~~~~~~~~~~ -.. _authorize: +.. _radius_authorize: Authorize +++++++++ @@ -254,7 +258,7 @@ empty or it can contain an explicit rejection, depending on how the :ref:`OPENWISP_RADIUS_API_AUTHORIZE_REJECT ` setting is configured. -.. _post_auth: +.. _radius_post_auth: Post Auth +++++++++ @@ -282,7 +286,7 @@ calling_station_id Calling Station ID Returns an empty response body in order to instruct FreeRADIUS to avoid processing the response body. -.. _accounting: +.. _radius_accounting: Accounting ++++++++++ @@ -418,8 +422,8 @@ their phone number, etc.). .. note:: The API endpoints described below do not require the - :ref:`Organization API Token ` described in - the beginning of this document. + :ref:`Organization API Token ` + described in the beginning of this document. Some endpoints require the sending of the user API access token sent in the form of a "Bearer Token", example: @@ -432,7 +436,7 @@ the form of a "Bearer Token", example: List of Endpoints ~~~~~~~~~~~~~~~~~ -.. _user_registration: +.. _radius_user_registration: User Registration +++++++++++++++++ @@ -480,7 +484,7 @@ simple, but can be :ref:`enabled through configuration `; if identity verification is disabled for a particular org, an empty string will be acceptable. -.. _registering_to_multiple_organizations: +.. _radius_registering_to_multiple_organizations: Registering to Multiple Organizations ..................................... @@ -501,12 +505,12 @@ in the UI. E.g.: } The existing user can register with a new organization using the -:ref:`login endpoint `. The user will also -get membership of the new organization only if the organization has +:ref:`login endpoint `. The user will +also get membership of the new organization only if the organization has :ref:`user registration enabled `. -.. _reset_password: +.. _radius_reset_password: Reset password ++++++++++++++ @@ -532,7 +536,7 @@ Confirm reset password ++++++++++++++++++++++ Allows users to confirm their reset password after having it requested via -the :ref:`Reset password ` endpoint. +the :ref:`Reset password ` endpoint. .. code-block:: text @@ -557,7 +561,7 @@ Change password **Requires the user auth token (Bearer Token)**. Allows users to change their password after using the :ref:`Reset password -` endpoint. +` endpoint. .. code-block:: text @@ -575,7 +579,7 @@ new_password string confirm_password string ================ =========== -.. _login_obtain_user_auth_token: +.. _radius_login_obtain_user_auth_token: Login (Obtain User Auth Token) ++++++++++++++++++++++++++++++ @@ -591,8 +595,8 @@ Returns: - ``radius_user_token``: the user radius token, which can be used to authenticate the user in the captive portal by sending it in place of the user password (it will be passed to freeradius which in turn will - send it to the :ref:`authorize API endpoint ` which will - recognize the token as the user passsword) + send it to the :ref:`authorize API endpoint ` which + will recognize the token as the user passsword) - ``key``: the user API access token, which will be needed to authenticate the user to eventual subsequent API requests (eg: change password) - ``is_active`` if it's ``false`` it means the user has been banned @@ -618,7 +622,7 @@ If an existing user account tries to authenticate to an organization of which they're not member of, then they would be automatically added as members (if registration is enabled for that org). Please refer to :ref:`"Registering to Multiple Organizations" -`. +`. This endpoint updates the user language preference field according to the ``Accept-Language`` HTTP header. @@ -654,8 +658,8 @@ token the rest auth token to validate ===== =============================== The user information is returned in the response (similarly to -:ref:`Obtain User Auth Token `), along with -the following additional parameter: +:ref:`Obtain User Auth Token `), +along with the following additional parameter: - ``response_code``: string indicating whether the result is successful or not, to be used for translation. @@ -738,7 +742,7 @@ Responds only to **GET**. No parameters required. -.. _verify_validate_sms_token: +.. _radius_verify_validate_sms_token: Verify/Validate SMS token +++++++++++++++++++++++++ @@ -780,7 +784,7 @@ Change phone number Allows users to change their phone number, will flag the user as inactive and send them a verification code via SMS. The phone number of the user is updated only after this verification code has been :ref:`validated -`. +`. .. code-block:: text @@ -796,13 +800,13 @@ Param Description phone_number string ============ =========== -.. _batch_user_creation: +.. _radius_batch_user_creation: Batch user creation +++++++++++++++++++ This API endpoint allows to use the features described in -:doc:`/user/importing_users` and :doc:`/user/generating_users`. +:doc:`importing_users` and :doc:`generating_users`. .. code-block:: text @@ -811,7 +815,7 @@ This API endpoint allows to use the features described in .. note:: This API endpoint allows to use the features described in - :doc:`/user/importing_users` and :doc:`/user/generating_users`. + :doc:`importing_users` and :doc:`generating_users`. Responds only to **POST**, used to save a ``RadiusBatch`` instance. diff --git a/docs/source/user/saml.rst b/docs/user/saml.rst similarity index 82% rename from docs/source/user/saml.rst rename to docs/user/saml.rst index 1bee17b3..a1ffe933 100644 --- a/docs/source/user/saml.rst +++ b/docs/user/saml.rst @@ -1,5 +1,3 @@ -.. _saml_: - Single Sign-On (SAML) ===================== @@ -8,7 +6,7 @@ Single Sign-On (SAML) The SAML registration method is disabled by default. In order to enable this feature you have to follow the :ref:`SAML - setup instructions ` below and then activate it via + setup instructions ` below and then activate it via :ref:`global setting or from the admin interface `. @@ -26,8 +24,9 @@ form: ``username`` should obviously used for the username field, while ``token`` should be used for the password field. The third parameter, ``login_method=saml``, is needed because it allows -the captive page to remember that the user logged in via SAML, because it -will need to perform the :ref:`SAML logout ` later on. +the captive page to remember that the user logged in via SAML. This +information will be used later on when performing the :ref:`SAML logout +`. The internal REST API of openwisp-radius will recognize the token and authorize the user. @@ -40,24 +39,23 @@ is signing-in with a SSO. .. note:: If you're building a public wifi service, we suggest to take a look at - `openwisp-wifi-login-pages - `_, which is + :doc:`OpenWISP WiFi Login Pages `, which is built to work with openwisp-radius. -.. _setup_saml: +.. _radius_setup_saml: Setup ----- Install required system dependencies: -:: +.. code-block:: shell sudo apt install xmlsec1 Install Python dependencies: -:: +.. code-block:: shell pip install openwisp-radius[saml] @@ -127,11 +125,11 @@ Substitute ``openwisp2.mywifiproject.com``, hostname of your openwisp-radius instance, your captive page and the organization slug respectively. -Alternatively, you can take a look at `openwisp-wifi-login-pages -`_, which provides -buttons for Single Sign-On (SAML) by default. +Alternatively, you can take a look at :doc:`OpenWISP WiFi Login Pages +`, which provides buttons for Single Sign-On +(SAML) by default. -.. _logout: +.. _radius_saml_logout: Logout ------ @@ -139,22 +137,19 @@ Logout When logging out a user which logged in via SAML, the captive page should also call the SAML logout URL: ``/radius/saml2/logout/``. -The `openwisp-wifi-login-pages -`_ app supports -this with minimal configuration, refer to the `"Configuring SAML Login & -Logout" -`_ -section. +The :doc:`OpenWISP WiFi Login Pages ` app +supports this with minimal configuration, refer to the :doc:`OpenWISP WiFi +Login Pages ` section. Settings -------- -See :ref:`SAML related settings `. +See :ref:`SAML related settings `. FAQs ---- -.. _preventing_change_in_username_of_registered_user: +.. _radius_prevent_registered_user_username_change: Preventing change in username of a registered user ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -169,7 +164,7 @@ details of the user are updated with the information received from SAML Identity Provider. If a user (who has registered on OpenWISP with a different method from -SAML) logs into OpenWISP with SAML, then the default behaviour of OpenWISP +SAML) logs into OpenWISP with SAML, then the default behavior of OpenWISP RADIUS prevents updating username of this user. Because, this operation could render the user's old credentials useless. If you want to update the username in such scenarios with details received from Identity Provider, diff --git a/docs/source/user/settings.rst b/docs/user/settings.rst similarity index 91% rename from docs/source/user/settings.rst rename to docs/user/settings.rst index 8632b268..89523a6f 100644 --- a/docs/source/user/settings.rst +++ b/docs/user/settings.rst @@ -1,5 +1,11 @@ -Available settings -================== +Settings +======== + +.. include:: /partials/settings-note.rst + +.. contents:: **Table of contents**: + :depth: 1 + :local: Admin related settings ---------------------- @@ -168,7 +174,7 @@ This value can be overridden per organization in the organization change page. You can skip setting this option if you intend to set it from organization change page for each organization. -.. image:: /images/freeradius_allowed_hosts.png +.. image:: ../images/freeradius_allowed_hosts.png :alt: Organization change page freeradius settings .. code-block:: python @@ -182,7 +188,7 @@ organization change page for each organization. If this option and organization change page option are both empty, then all freeradius API requests for the organization will return ``403``. -.. _coa_enabled_setting: +.. _radius_coa_enabled_setting: ``OPENWISP_RADIUS_COA_ENABLED`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -192,18 +198,18 @@ all freeradius API requests for the organization will return ``403``. If set to ``True``, openwisp-radius will update the NAS with the user's current RADIUS attributes whenever the ``RadiusGroup`` of user is changed. This allow enforcing of rate limits on active RADIUS sessions without -requiring users to re-authenticate. For more details, :ref:`read the +requiring users to re-authenticate. For more details, :doc:`read the dedicated section for configuring openwisp-radius and NAS for using CoA `. This can be overridden for each organization separately via the organization radius settings section of the admin interface. -.. image:: /images/organization_coa_enabled.png +.. image:: ../images/organization_coa_enabled.png :alt: CoA enabled -```RADCLIENT_ATTRIBUTE_DICTIONARIES``` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``RADCLIENT_ATTRIBUTE_DICTIONARIES`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ============ ======== **type**: ``list`` @@ -266,7 +272,7 @@ By default, an instance of This setting allows to specify the parameters to connect to the different OpenVPN management interfaces available for an organization. This setting is used by the :ref:`convert_called_station_id -` command. +` command. It should contain configuration in following format: @@ -311,7 +317,8 @@ created. **Default**: ``u'%a %b %d %H:%M:%S %Y'`` Specifies the datetime format of OpenVPN management status parser used by -the :ref:`convert_called_station_id ` command. +the :ref:`convert_called_station_id ` +command. ``OPENWISP_RADIUS_UNVERIFY_INACTIVE_USERS`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -369,6 +376,8 @@ value: ``https://myradius.myapp.com``. Indicates whether the REST API of openwisp-radius is enabled or not. +.. _openwisp_radius_disposable_radius_user_token: + ``OPENWISP_RADIUS_DISPOSABLE_RADIUS_USER_TOKEN`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -388,8 +397,8 @@ manage to intercept it somehow. **Default**: ``False`` -Indicates wether the :ref:`Authorize API view ` will return -``{"control:Auth-Type": "Reject"}`` or not. +Indicates wether the :ref:`Authorize API view ` will +return ``{"control:Auth-Type": "Reject"}`` or not. Rejecting an authorization request explicitly will prevent freeradius from attempting to perform authorization with other mechanisms (eg: radius @@ -425,7 +434,7 @@ accounting will be saved as usual. This setting is used to specify a list of international mobile prefixes which should be allowed to register into the system via the :ref:`user -registration API `. +registration API `. That is, only users with phone numbers using the specified international prefixes will be allowed to register. @@ -478,7 +487,7 @@ phone numbers uses the same pattern (e.g. USA). Setting the value to This global setting is used to specify if the optional user fields (``first_name``, ``last_name``, ``location`` and ``birth_date``) shall be disabled (hence ignored), allowed or required in the :ref:`User -Registration API `. +Registration API `. The allowed values are: @@ -511,7 +520,7 @@ needed, by going to ``Home › Users and Organizations › Organizations > Edit organization`` and then scrolling down to ``ORGANIZATION RADIUS SETTINGS``. -.. image:: /images/optional_fields.png +.. image:: ../images/optional_fields.png :alt: optional field setting By default the fields at organization level hold a ``NULL`` value, which @@ -537,9 +546,8 @@ means that the global setting specified in ``settings.py`` will be used. A dictionary representing the frontend URLs through which end users can complete the password reset operation. -The frontend could be `openwisp-wifi-login-pages -`_ or another -in-house captive page solution. +The frontend could be :doc:`OpenWISP WiFi Login Pages +` or another in-house captive page solution. Keys of the dictionary must be either UUID of organizations or ``__all__``, which is the fallback URL that will be used in case there's @@ -557,13 +565,12 @@ The meaning of the variables in the string is the following: - ``{uid}``: uid of the password reset request - ``{token}``: token of the password reset request -If you're using `openwisp-wifi-login-pages -`_, the -configuration is fairly simple, in case the nodejs app is installed in the -same domain of openwisp-radius, you only have to ensure the domain field -in the main Site object is correct, if instead the nodejs app is deployed -on a different domain, say ``login.wifiservice.com``, the configuration -should be simply changed to: +If you're using :doc:`OpenWISP WiFi Login Pages +`, the configuration is fairly simple, in case +the nodejs app is installed in the same domain of openwisp-radius, you +only have to ensure the domain field in the main Site object is correct, +if instead the nodejs app is deployed on a different domain, say +``login.wifiservice.com``, the configuration should be simply changed to: .. code-block:: python @@ -587,7 +594,7 @@ interface**, by going to *Organizations* then edit a specific organization and scroll down to *"Organization RADIUS settings"*, as shown in the screenshot below. -.. image:: /images/organization_registration_setting.png +.. image:: ../images/organization_registration_setting.png :alt: Organization RADIUS settings .. note:: @@ -607,7 +614,8 @@ screenshot below. .. note:: If you're looking for instructions on how to configure SMS sending, - see :ref:`SMS Token Related Settings `. + see :ref:`SMS Token Related Settings + `. If :ref:`Identity verification is required `, this setting indicates @@ -617,7 +625,7 @@ number via SMS. This can be overridden for each organization separately via the organization radius settings section of the admin interface. -.. image:: /images/organization_sms_verification_setting.png +.. image:: ../images/organization_sms_verification_setting.png :alt: SMS verification enabled .. _openwisp_radius_needs_identity_verification: @@ -636,7 +644,7 @@ interface**, by going to *Organizations* then edit a specific organization and scroll down to *"Organization RADIUS settings"*, as shown in the screenshot below. -.. image:: /images/mac-address-roaming.png +.. image:: ../images/mac-address-roaming.png :alt: Organization MAC Address Roaming settings .. note:: @@ -663,7 +671,7 @@ verification method. The following choices are available by default: - ``email``: Email (No Identity Verification) - ``mobile_phone``: Mobile phone number :ref:`verification via SMS ` -- ``social_login``: :ref:`social login feature ` +- ``social_login``: :doc:`social login feature ` .. note:: @@ -735,8 +743,8 @@ For example: Payment flows and credit/debit card verification are fully implemented in **OpenWISP Subscriptions**, a premium module available only to - customers of the :ref:`commercial support offering of OpenWISP - `. + customers of the `commercial support offering of OpenWISP + `_. Email related settings ---------------------- @@ -782,18 +790,18 @@ core settings under ``DEFAULT_FROM_EMAIL``. Currently, ``DEFAULT_FROM_EMAIL`` is set to to ``webmaster@localhost``. -.. _counter_related_settings: +.. _radius_counter_related_settings: Counter related settings ------------------------ -.. _counters_setting: +.. _radius_counters_setting: ``OPENWISP_RADIUS_COUNTERS`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**Default**: depends on the database backend in use, see :ref:`counters` -to find out what are the default counters enabled. +**Default**: depends on the database backend in use, see +:ref:`radius_counters` to find out what are the default counters enabled. It's a list of strings, each representing the python path to a counter class. @@ -813,35 +821,35 @@ to include the new classes, eg: OPENWISP_RADIUS_COUNTERS = [ # default counters for PostgreSQL, may be removed if not needed "openwisp_radius.counters.postgresql.daily_counter.DailyCounter", - "openwisp_radius.counters.postgresql.daily_traffic_counter.DailyTrafficCounter", + "openwisp_radius.counters.postgresql.radius_daily_traffic_counter.DailyTrafficCounter", # custom counters "myproject.counters.CustomCounter1", "myproject.counters.CustomCounter2", ] -.. _traffic_counter_check_name: +.. _radius_traffic_counter_check_name: ``OPENWISP_RADIUS_TRAFFIC_COUNTER_CHECK_NAME`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Default**: ``Max-Daily-Session-Traffic`` -Used by :ref:`daily_traffic_counter`, it indicates the check attribute -which is looked for in the database to find the maximum amount of daily -traffic which users having the default ``users`` radius group assigned can -consume. +Used by :ref:`radius_daily_traffic_counter`, it indicates the check +attribute which is looked for in the database to find the maximum amount +of daily traffic which users having the default ``users`` radius group +assigned can consume. -.. _traffic_counter_reply_name: +.. _radius_traffic_counter_reply_name: ``OPENWISP_RADIUS_TRAFFIC_COUNTER_REPLY_NAME`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **Default**: ``CoovaChilli-Max-Total-Octets`` -Used by :ref:`daily_traffic_counter`, it indicates the reply attribute -which is returned to the NAS to indicate how much remaining traffic users -which users having the default ``users`` radius group assigned can -consume. +Used by :ref:`radius_daily_traffic_counter`, it indicates the reply +attribute which is returned to the NAS to indicate how much remaining +traffic users which users having the default ``users`` radius group +assigned can consume. It should be changed according to the NAS software in use, for example, if using PfSense, this setting should be set to ``pfSense-Max-Total-Octets``. @@ -865,12 +873,12 @@ type in the API response for ``ChilliSpot-Max-Input-Octets`` attribute: "ChilliSpot-Max-Input-Octets": "bytes" } -.. _social_login_settings: +.. _radius_social_login_settings: Social Login related settings ----------------------------- -The following settings are related to the :ref:`social login feature +The following settings are related to the :doc:`social login feature `. .. _openwisp_radius_social_registration_enabled: @@ -889,7 +897,7 @@ interface**, by going to *Organizations* then edit a specific organization and scroll down to *"Organization RADIUS settings"*, as shown in the screenshot below. -.. image:: /images/organization_social_login_setting.png +.. image:: ../images/organization_social_login_setting.png :alt: Organization social login settings .. note:: @@ -899,12 +907,12 @@ screenshot below. otherwise, if all the organization use the same configuration, we recommend changing the global setting. -.. _saml_settings: +.. _radius_saml_settings: SAML related settings --------------------- -The following settings are related to the :ref:`SAML feature `. +The following settings are related to the :doc:`SAML feature `. .. _openwisp_radius_saml_registration_enabled: @@ -922,7 +930,7 @@ interface**, by going to *Organizations* then edit a specific organization and scroll down to *"Organization RADIUS settings"*, as shown in the screenshot below. -.. image:: /images/organization_saml_setting.png +.. image:: ../images/organization_saml_setting.png :alt: Organization SAML settings .. note:: @@ -960,10 +968,10 @@ valid identity verifiers. Allows updating username of a registered user with the value received from SAML Identity Provider. Read the :ref:`FAQs in SAML integration -documentation ` for +documentation ` for details. -.. _sms_token_related_settings: +.. _radius_sms_token_related_settings: SMS token related settings -------------------------- diff --git a/docs/source/user/social_login.rst b/docs/user/social_login.rst similarity index 85% rename from docs/source/user/social_login.rst rename to docs/user/social_login.rst index 66bcb66e..4dcfac60 100644 --- a/docs/source/user/social_login.rst +++ b/docs/user/social_login.rst @@ -1,5 +1,3 @@ -.. _social_login: - Social Login ============ @@ -8,8 +6,8 @@ Social Login The social login feature is disabled by default. In order to enable this feature you have to follow the :ref:`setup - instructions ` below and then activate it via - :ref:`global setting or from the admin interface + instructions ` below and then activate it + via :ref:`global setting or from the admin interface `. Social login is supported by generating an additional temporary token @@ -33,11 +31,10 @@ the user is signing-in with a social network. .. note:: If you're building a public wifi service, we suggest to take a look at - `openwisp-wifi-login-pages - `_, which is + :doc:`OpenWISP WiFi Login Pages `, which is built to work with openwisp-radius. -.. _setup_social_login: +.. _radius_setup_social_login: Setup ----- @@ -46,7 +43,7 @@ Install ``django-allauth``: :: - pip install django-allauth + pip install django-allauth[socialaccount] Ensure your ``settings.py`` looks like the following (we will show how to configure of the facebook social provider): @@ -104,7 +101,7 @@ Configure the social account application Refer to the django-allauth documentation to find out `how to complete the configuration of a sample facebook login app -`_. +`_. Captive page button example --------------------------- @@ -127,11 +124,11 @@ Substitute ``openwisp2.mywifiproject.com``, your openwisp-radius instance, your captive page and the organization slug respectively. -Alternatively, you can take a look at `openwisp-wifi-login-pages -`_, which provides -buttons for Facebook, Google and Twitter by default. +Alternatively, you can take a look at :doc:`OpenWISP WiFi Login Pages +`, which provides buttons for Facebook, Google +and Twitter by default. Settings -------- -See :ref:`social login related settings `. +See :ref:`social login related settings `.