Important

The development of django-freeradius has moved to openwisp-radius, we highly suggest users and readers of this documentation to migrate or use the more up to date documentation of openwisp-radius.

Setup¶

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.

# 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:

pip install django-freeradius

Install development version¶

Install tarball:

pip install https://github.com/openwisp/django-freeradius/tarball/master

Alternatively you can install via pip using git:

pip install -e git+git://github.com/openwisp/django-freeradius#egg=django-freeradius

If you want to contribute, install your cloned fork:

git clone git@github.com:<your_fork>/django-freeradius.git
cd django-freeradius
python setup.py develop

Setup (integrate in an existing django project)¶

In the django settings.py file of your project, do the following:

add django_freeradius and django_filters to INSTALLED_APPS
set DJANGO_FREERADIUS_API_TOKEN (see API Token for more information):

INSTALLED_APPS = [
    # other apps
    'django_freeradius',
    'django_filters',
]

DJANGO_FREERADIUS_API_TOKEN = '<a-long-secret-value-of-your-choice>'

Add the URLs to your main urls.py:

urlpatterns = [
    # ... other urls in your project ...

    # django-freeradius urls
    # keep the namespace argument unchanged
    url(r'^', include('django_freeradius.urls', namespace='freeradius')),
]

Then run:

./manage.py migrate

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 django-freeradius (and openwisp-radius) easily:

first of all, back up your existing database;
configure django to connect to your existing database;
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.

django-freeradius¶

./manage.py migrate --fake django_freeradius 0001_initial_freeradius
./manage.py migrate

openwisp-radius¶

In case you are using openwisp-radius:

./manage.py migrate --fake openwisp_radius 0001_initial_freeradius
./manage.py migrate

Installing for development¶

Install python3-dev and gcc:

sudo apt-get install python3-dev gcc

Install sqlite:

sudo apt-get install sqlite3 libsqlite3-dev libpq-dev

Install mysqlclient:

sudo apt-get install libmysqlclient-dev libssl-dev

Note

If you are on Debian 10 or 9 you may need to install default-libmysqlclient-dev instead

Install your forked repo:

git clone git://github.com/<your_username>/django-freeradius
cd django-freeradius/
python setup.py develop

Install test requirements:

pip install -r requirements-test.txt

Create database:

cd tests/
./manage.py migrate
./manage.py createsuperuser

Launch development server:

./manage.py runserver

You can access the admin interface at http://127.0.0.1:8000/admin/.

Run tests with:

./runtests.py

Troubleshooting¶

If you encounter any issue during installation, run:

pip install -r requirements.txt -r requirements-test.txt instead of pip install -r requirements-test.txt

instead of pip install -r requirements-test.txt

Automating management commands¶

Some management commands are necessary to enable certain features and also facilitate database cleanup. In a production environment, it is highly recommended to automate the usage of these commands by using cron jobs.

Edit the crontab with:

crontab -e

Add and modify the following lines accordingly:

# This command deletes RADIUS accounting sessions older than 365 days
30 04 * * * <virtualenv_path>/bin/python <full/path/to>/manage.py delete_old_radacct 365

# This command deletes RADIUS post-auth logs older than 365 days
30 04 * * * <virtualenv_path>/bin/python <full/path/to>/manage.py delete_old_postauth 365

# This command closes stale RADIUS sessions that have remained open for 15 days
30 04 * * * <virtualenv_path>/bin/python <full/path/to>/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 * * * <virtualenv_path>/bin/python <full/path/to>/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 * * * <virtualenv_path>/bin/python <full/path/to>/manage.py delete_old_users

Be sure to replace <virtualenv_path> with the absolute path to the Python virtual environment.

Also, change <full/path/to> to the directory where manage.py is.

To get the absolute path to manage.py when django-freeradius is installed for development, navigate to the base directory of the cloned fork. Then, run:

cd tests/
pwd

More information can be found at the management commands page.