Reusable django app for collecting and visualizing network topology.
Table of Contents:
- Current features
- Project goals
- Install stable version from pypi
- Install development version
- Setup (integrate in an existing django project)
- Management Commands
- Installing for development
- network topology collector supporting different formats:
- NetJSON NetworkGraph
- OLSR (jsoninfo/txtinfo)
- batman-adv (jsondoc/txtinfo)
- BMX6 (q6m)
- CNML 1.0
- additional formats can be added by specifying custom parsers
network topology visualizer based on netjsongraph.js
simple HTTP API that exposes data in NetJSON NetworkGraph format
admin interface that allows to easily manage, audit and debug topologies and their relative data (nodes, links)
receive topology from multiple nodes
- make it easy to visualize network topology data for the formats supported by netdiff
- expose topology data via RESTful resources in NetJSON NetworkGraph format
- make it easy to integrate in larger django projects to improve reusability
- make it easy to extend its models by providing abstract models (needs improvement in this point)
- provide ways to customize or replace the visualizer (needs improvement in this point)
- keep the core very simple
- provide ways to extend the default behaviour
- encourage new features to be published as extensions
Install stable version from pypi
Install from pypi:
pip install django-netjsongraph
Install development version
pip install https://github.com/netjson/django-netjsongraph/tarball/master
Alternatively you can install via pip using git:
pip install -e git+git://github.com/netjson/django-netjsongraph#egg=django-netjsongraph
If you want to contribute, install your cloned fork:
git clone firstname.lastname@example.org:<your_fork>/django-netjsongraph.git cd django-netjsongraph python setup.py develop
Setup (integrate in an existing django project)
INSTALLED_APPS = [ # other apps 'rest_framework', 'django_netjsongraph' # ... ]
Include urls in your urlconf (you can change the prefixes according to your needs):
from django.conf.urls import include, url from django_netjsongraph.api import urls as netjsongraph_api from django_netjsongraph.visualizer import urls as netjsongraph_visualizer urlpatterns = [ # your URLs ... url(r'^api/', include(netjsongraph_api)), url(r'', include(netjsongraph_visualizer)), ]
Create database tables:
After topology URLs (URLs exposing the files that the topology of the network) have been
added in the admin, the
update_topology management command can be used to collect data
and start playing with the network graph:
The management command accepts a
--label argument that will be used to search in
topology labels, eg:
./manage.py update_topology --label mytopology
update_topology management command will automatically try to log errors.
For a good default
LOGGING configuration refer to the test settings.
There are mainly two ways of collecting topology information:
- FETCH strategy
- RECEIVE strategy
Topology instance has a
strategy field which can be set to the desired setting.
Topology data will be fetched from a URL.
When some links are not detected anymore they will be flagged as "down" straightaway.
Topology data is sent directly from one or more nodes of the network.
The collector waits to receive data in the payload of a POST HTTP request;
when such a request is received, a
key parameter it's first checked against
If the request is authorized the collector proceeds to update the topology.
If the data is sent from one node only, it's highly advised to set the
expiration_time of the
Topology instance to
0 (seconds), this way the
system works just like in the FETCH strategy, with the only difference that
the data is sent by one node instead of fetched by the collector.
If the data is sent from multiple nodes, you SHOULD set the
Topology instance to a value slightly higher than the interval used
by nodes to send the topology, this way links will be flagged as "down" only if
they haven't been detected for a while. This mechanism allows to visualize the
topology even if the network has been split in several parts, the disadvantage
is that it will take a bit more time to detect links that go offline.
Additional custom netdiff parsers.
String representing python module to import on initialization.
Useful for loading django signals or to define custom behaviour.
Timeout when fetching topology URLs.
If a link is down for more days than this number, it will be deleted by the
update_topology management command.
Setting this to
False will disable this feature.
Installing for development
sudo apt-get install sqlite3 libsqlite3-dev
Install your forked repo:
git clone git://github.com/<your_fork>/django-netjsongraph cd django-netjsongraph/ python setup.py develop
Install test requirements:
pip install -r requirements-test.txt
cd tests/ ./manage.py migrate ./manage.py createsuperuser
Launch development server:
Run tests with:
First off, thanks for taking the time to read these guidelines.
Trying to follow these guidelines is important in order to minimize waste and avoid misunderstandings.
- Ensure your changes meet the Project Goals
- If you found a bug please send a failing test with a patch
- If you want to add a new feature, announce your intentions in the issue tracker
- Fork this repo and install it by following the instructions in Installing for development
- Follow PEP8, Style Guide for Python Code
- Write code
- Write tests for your code
- Ensure all tests pass
- Ensure test coverage is not under 90%
- Document your changes
- Send pull request