Skip to content
django app for IP address management, WIP
Branch: master
Clone or download
nemesisdesign Merge pull request #72 from atb00ker/qa
[qa] Improve model testcases
Latest commit 1659d12 Feb 1, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
django_ipam
docs/images
tests
.coveragerc [general] Added basic app structure and logic May 15, 2018
.gitignore
.jslintrc
.travis.yml
LICENSE
README.rst
requirements-test.txt
requirements.txt
runcheckmigration
runtests.py
setup.cfg
setup.py

README.rst

django-ipam

Requirements Status

Django-ipam is part of the OpenWISP project.



Available Features

  • IPv4 and IPv6 IP address management
  • IPv4 and IPv6 Subnet management
  • Automatic free space display for all subnets
  • Visual display for a specific subnet
  • IP request module
  • RESTful API to for CRUD operations
  • Possibility to search for an IP or subnet
  • CSV Import and Export of subnets and their IPs

Project Goals

  • provide a django reusable app with features of IP Address management
  • provide abstract models which can be extended into other django based apps

Dependencies

  • Python 3.4 or higher
  • Django 2.0 or higher

Install Development Version

Install for development version:

pip install -r requirements-test.txt

Install the development version using the following commands:

git clone https://github.com/openwisp/django-ipam.git
cd django-ipam
python setup.py develop

Launch the development sever:

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

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


Run Tests

Install test requirements:

pip install -r requirements-test.txt

Then run the test suite:

./runtests.py

Setup (Integrate into other Django Apps)

Add django_ipam to INSTALLED_APPS:

INSTALLED_APPS = [
    # other apps
    'django_ipam',
]

Add the URLs to your main urls.py:

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

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

Then run:

./manage.py migrate

Visual Display of subnets

Django-ipam provides a graphical representation of a subnet which shows the available free space under any subnet.

https://raw.githubusercontent.com/openwisp/django-ipam/master/docs/images/visual-display.png


RESTful API

API Authentication

The API authentication is based on session based authentication via Django REST framework. This authentication scheme uses Django's default session backend for authentication.

http -a username:password <HTTP verb> <api url>

Pagination

API pagination is provided with the help page parameter. The default page size is 10 which can be overridden using the page_size parameter.

/api/v1/<api endpoint url>/?page=1&page_size=10

Get First Available IP

A model method to fetch the next available IP address under a specific subnet. This method can also be accessed via a RESTful API.

django_ipam/base/models.py

GET

Returns the next available IP address under a subnet.

/api/v1/subnet/<subnet_id>/get-first-available-ip/

Request IP

A model method to create and fetch the next available IP address record under a subnet.

POST

Creates a record for next available IP address and returns JSON data of that record.

POST /api/v1/subnet/<subnet_id>/request-ip/
Param Description
description Optional description for the IP address

Response

{
    "ip_address": "ip_address",
    "subnet": "subnet_uuid",
    "description": "optional description"
}

IpAddress-Subnet List and Create View

An api enpoint to retrieve or create IP addresses under a specific subnet.

GET

Returns the list of IP addresses under a particular subnet.

/api/v1/subnet/<subnet_id>/ip-address/

POST

Create a new IP Address.

/api/v1/subnet/<subnet_id>/ip-address/
Param Description
ip_address IPv6/IPv4 address value
subnet Subnet UUID
description Optional description for the IP address

Subnet List/Create View

An api endpoint to create or retrieve the list of subnet instances.

GET

Returns the list of Subnet instances.

/api/v1/subnet

POST

Create a new Subnet.

/api/v1/subnet
Param Description
subnet Subnet value in CIDR format
master_subnet Master Subnet UUID
description Optional description for the IP address

Subnet View

An api endpoint for retrieving, updating or deleting a subnet instance.

GET

Get details of a Subnet instance

/api/v1/subnet/<subnet-id>

DELETE

Delete a Subnet instance

/api/v1/subnet/<subnet-id>

PUT

Update details of a Subnet instance.

/api/v1/subnet/<subnet-id>
Param Description
subnet Subnet value in CIDR format
master_subnet Master Subnet UUID
description Optional description for the IP address

IP Address View

An api enpoint for retrieving, updating or deleting a IP address instance.

GET

Get details of an IP address instance.

/api/v1/ip-address/<ip_address-id>

DELETE

Delete an IP address instance.

/api/v1/ip-address/<ip_address-id>

PUT

Update details of an IP address instance.

/api/v1/ip-address/<ip_address-id>
Param Description
ip_address IPv6/IPv4 value
subnet Subnet UUID
description Optional description for the IP address

Export Subnet View

View to export subnet data.

POST

/api/v1/subnet/<subnet-id>/export

Import Subnet View

View to import subnet data.

POST

/api/v1/import-subnet

Exporting and Importing Subnet

One can easily import and export Subnet data and it's Ip Addresses using django-ipam. This works for both IPv4 and IPv6 types of networks.

Exporting

Data can be exported via the admin interface or by using a management command. The exported data is in .csv file format.

From management command

./manage.py export_subnet <subnet value>

This would export the subnet if it exists on the database.

From admin interface

Data can be exported from the admin interface by just clicking on the export button on the subnet's admin change view.

https://raw.githubusercontent.com/openwisp/django-ipam/master/docs/images/export.png

Importing

Data can be imported via the admin interface or by using a management command. The imported data file can be in .csv, .xls and .xlsx format. While importing data for ip addresses, the system checks if the subnet specified in the import file exists or not. If the subnet does not exists it will be created while importing data.

From management command

./manage.py import_subnet --file=<file path>

From admin interface

Data can be imported from the admin interface by just clicking on the import button on the subnet view.

https://raw.githubusercontent.com/openwisp/django-ipam/master/docs/images/import.png

CSV file format

Follow the following structure while creating csv file to import data.

Subnet Name
Subnet Value

ip_address,description
<ip-address>,<optional-description>
<ip-address>,<optional-description>
<ip-address>,<optional-description>

Extending django-ipam

Extending API Views

The base API view classes can be extended into other django applications.

# your app.api.views
from ..models import Subnet, IpAddress

from .generics import (
    BaseAvailableIpView, BaseExportSubnetView, BaseImportSubnetView, BaseIpAddressListCreateView,
    BaseIpAddressView, BaseRequestIPView, BaseSubnetListCreateView, BaseSubnetView,
)


class AvailableIpView(BaseAvailableIpView):
    subnet_model = Subnet
    queryset = IpAddress.objects.none()


class RequestIPView(BaseRequestIPView):
    subnet_model = Subnet
    queryset = IpAddress.objects.none()


class SubnetIpAddressListCreateView(BaseIpAddressListCreateView):
    subnet_model = Subnet


class SubnetListCreateView(BaseSubnetListCreateView):
    queryset = Subnet.objects.all()


class SubnetVew(BaseSubnetView):
    queryset = Subnet.objects.all()


class IpAddressView(BaseIpAddressView):
    queryset = IpAddress.objects.all()


class ImportSubnetView(BaseImportSubnetView):
    subnet_model = Subnet
    queryset = Subnet.objects.none()


class ExportSubnetView(BaseExportSubnetView):
    subnet_model = Subnet
    queryset = Subnet.objects.none()

Support channels | Issue Tracker | License |

You can’t perform that action at this time.