Skip to content

Commit

Permalink
[radius-docs] Restructured Documentation: New Unified Documentation W…
Browse files Browse the repository at this point in the history
…ebsite
  • Loading branch information
pandafy committed Aug 22, 2024
1 parent 0663ac3 commit 451be48
Show file tree
Hide file tree
Showing 49 changed files with 676 additions and 1,288 deletions.
36 changes: 31 additions & 5 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ openwisp-radius
:target: https://pypi.org/project/black/
:alt: code style: black

---

**Need a quick overview?** `Try the OpenWISP Demo <https://openwisp.org/demo.html>`_.

**OpenWISP RADIUS** provides a web interface to a `freeradius <https://freeradius.org/>`_ database,
Expand All @@ -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
<https://openwisp-radius.readthedocs.io/en/latest/developer/how_to_extend.html>`_.

- `Documentation <http://openwisp-radius.readthedocs.io/en/latest/>`_
- `Change log <https://github.com/openwisp/openwisp-radius/blob/master/CHANGES.rst>`_
- `Support <http://openwisp.org/support.html>`_
- `Issue Tracker <https://github.com/openwisp/openwisp-radius/issues>`_
- `License <https://github.com/openwisp/openwisp-radius/blob/master/LICENSE>`_
Documentation
-------------

- `Usage documentation <https://openwisp.io/docs/dev/radius/>`_
- `Developer documentation
<https://openwisp.io/docs/dev/radius/developer/>`_

Contributing
------------

Please refer to the `OpenWISP contributing guidelines
<http://openwisp.io/docs/developer/contributing.html>`_.

Changelog
---------

See `CHANGES
<https://github.com/openwisp/openwisp-radius/blob/master/CHANGES.rst>`_.

License
-------

See `LICENSE
<https://github.com/openwisp/openwisp-radius/blob/master/LICENSE>`_.

Support
-------

See `OpenWISP Support Channels <http://openwisp.org/support.html>`_.

.. image:: https://raw.githubusercontent.com/openwisp/openwisp2-docs/master/assets/design/openwisp-logo-black.svg
:target: http://openwisp.org
20 changes: 0 additions & 20 deletions docs/Makefile

This file was deleted.

50 changes: 23 additions & 27 deletions docs/source/developer/freeradius.rst → docs/deploy/freeradius.rst
Original file line number Diff line number Diff line change
@@ -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
<https://freeradius.org>`_ in order to make it work with `OpenWISP RADIUS
<https://github.com/openwisp/openwisp-radius/>`_ for Captive Portal
authentication.
<https://freeradius.org>`_ 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.
Expand All @@ -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
<https://github.com/openwisp/openwisp-wifi-login-pages>`_ web app is
an open source solution which integrates with OpenWISP RADIUS to
The :doc:`OpenWISP WiFi Login Pages </wifi-login-pages/index>` 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
<https://github.com/openwisp/openwisp-wifi-login-pages>`_.
For more information see: :doc:`OpenWISP WiFi Login Pages
</wifi-login-pages/index>`

How to install freeradius 3
---------------------------
Expand Down Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -206,16 +202,16 @@ Example configuration using the PostgreSQL database:
password = "<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`,
Expand All @@ -225,8 +221,8 @@ you have to do the following:
- uncomment the line which starts with ``# api_token_header``
- substitute the occurrences of ``<org_uuid>`` and
``<org_radius_api_token>`` 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
Expand Down Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -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 <installing_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``.
Expand Down Expand Up @@ -349,8 +345,8 @@ OpenWISP RADIUS instead uses the FreeRADIUS `rlm_rest
<https://networkradius.com/doc/current/raddb/mods-available/rest.html>`_
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
<https://docs.djangoproject.com/en/dev/topics/auth/>`_).
topics see :ref:`radius_configure_rest_module` and `User authentication in
Django <https://docs.djangoproject.com/en/dev/topics/auth/>`_).

When migrating from existing FreeRADIUS deployments or in cases where it
is preferred to use the FreeRADIUS *radcheck* table for storing user
Expand Down Expand Up @@ -383,7 +379,7 @@ ensure the ``authorize`` section of your site as follows contains the
# ...
}
.. _debugging:
.. _radius_debugging:

Debugging
---------
Expand Down Expand Up @@ -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"
Expand All @@ -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"
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,22 @@ Freeradius Setup for WPA Enterprise (EAP-TTLS-PAP) authentication
=================================================================

This guide explains how to install and configure `freeradius 3
<https://freeradius.org>`_ in order to make it work with `OpenWISP RADIUS
<https://github.com/openwisp/openwisp-radius/>`_ for WPA Enterprise
EAP-TTLS-PAP authentication.
<https://freeradius.org>`_ 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 <generating_users>`, :ref:`imported from CSV
<importing_users>`, or can self register through a web page which makes
use of the :ref:`registration REST API <user_registration>` (like
`openwisp-wifi-login-pages
<https://github.com/openwisp/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 <radius_user_registration>`
(like :doc:`OpenWISP WiFi Login Pages </wifi-login-pages/index>`).

Prerequisites
-------------

Execute the steps explained in the following sections of the
:ref:`freeradius guide for captive portal authentication
<freeradius_setup_for_captive_portal>`:
:doc:`freeradius guide for captive portal authentication <freeradius>`:

- How to install freeradius 3
- Enable the configured modules
Expand All @@ -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
~~~~~~~~~~~~~~~~~~~
Expand All @@ -48,8 +45,8 @@ Let's create the site for an hypotethical organization called org-A.

Don't forget to substitute the occurrences of ``<org_uuid>`` and
``<org_radius_api_token>`` 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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -258,8 +255,8 @@ Final steps
-----------

Once the configurations are ready, you should :ref:`restart freeradius
<restart_freeradius>` and :ref:`then test/troubleshoot/debug your setup
<debugging>`.
<radius_restart_freeradius>` and :ref:`then test/troubleshoot/debug your
setup <radius_debugging>`.

Implementing other EAP scenarios
--------------------------------
Expand All @@ -273,5 +270,5 @@ the `django-x509 <https://github.com/openwisp/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 <support>`.
If you're interested in this feature, let us know via the `support
channels <https://openwisp.org/support.html>`_.
Loading

0 comments on commit 451be48

Please sign in to comment.