Install stable version from pypi

Install from pypi:

pip install netdiff

Install development version

Install tarball:

pip install https://github.com/openwisp/netdiff/tarball/master

Alternatively you can install via pip using git:

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

If you want to contribute, install your cloned fork:

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

Basic Usage Example

Calculate diff of an OLSR 0.6.x topology:

from netdiff import OlsrParser
from netdiff import diff

old = OlsrParser(file="./stored-olsr.json")
new = OlsrParser(url="http://127.0.0.1:9090")
diff(old, new)

In alternative, you may also use the subtraction operator:

from netdiff import OlsrParser
from netdiff import diff

old = OlsrParser(file="./stored-olsr.json")
new = OlsrParser(url="http://127.0.0.1:9090")
old - new

The output will be an ordered dictionary with three keys:

• added

• removed

• changed

Each key will contain a dict compatible with the NetJSON NetworkGraph format representing respectively:

• the nodes and links that have been added to the topology

• the nodes and links that have been removed from the topology

• the nodes and links that are present in both topologies but their attributes have changed

If no changes are present, keys will contain None.

So if between old and new there are no changes, the result will be:

{"added": None, "removed": None, "changed": None}

While if there are changes, the result will look like:

{
    "added": {
        "type": "NetworkGraph",
        "protocol": "OLSR",
        "version": "0.6.6",
        "revision": "5031a799fcbe17f61d57e387bc3806de",
        "metric": "ETX",
        "nodes": [
            {
                "id": "10.150.0.7",
                "label": "Node A",
                "local_addresses": [],
                "properties": {},
            },
            {
                "id": "10.150.0.6",
                "label": "Node B",
                "local_addresses": ["10.56.2.1"],
                "properties": {"hostname": "nodeb.lan"},
            },
        ],
        "links": [
            {
                "source": "10.150.0.3",
                "target": "10.150.0.7",
                "cost": 1.50390625,
                "cost_text": "",
                "properties": {},
            },
            {
                "source": "10.150.0.3",
                "target": "10.150.0.6",
                "cost": 1.0,
                "cost_text": "",
                "properties": {},
            },
        ],
    },
    "removed": {
        "type": "NetworkGraph",
        "protocol": "OLSR",
        "version": "0.6.6",
        "revision": "5031a799fcbe17f61d57e387bc3806de",
        "metric": "ETX",
        "nodes": [
            {
                "id": "10.150.0.8",
                "label": "Node C",
                "local_addresses": [],
                "properties": {},
            }
        ],
        "links": [
            {
                "source": "10.150.0.7",
                "target": "10.150.0.8",
                "cost": 1.0,
                "cost_text": "",
                "properties": {},
            }
        ],
    },
    "changed": {
        "type": "NetworkGraph",
        "protocol": "OLSR",
        "version": "0.6.6",
        "revision": "5031a799fcbe17f61d57e387bc3806de",
        "metric": "ETX",
        "nodes": [],
        "links": [
            {
                "source": "10.150.0.3",
                "target": "10.150.0.2",
                "cost": 1.0,
                "cost_text": "",
                "properties": {},
            }
        ],
    },
}

Parsers

Parsers are classes that extend netdiff.base.BaseParser and implement a parse method which is in charge of converting a python data structure into networkx.Graph object and return the result.

Parsers also have a json method which returns valid NetJSON output.

The available parsers are:

• netdiff.OlsrParser: parser for the olsrd jsoninfo plugin or the older txtinfo plugin

• netdiff.BatmanParser: parser for the batman-advanced alfred tool (supports also the legacy txtinfo format inherited from olsrd)

• netdiff.Bmx6Parser: parser for the BMX6 b6m tool

• netdiff.CnmlParser: parser for CNML 0.1

• netdiff.NetJsonParser: parser for the NetJSON NetworkGraph format

• netdiff.OpenvpnParser: parser for the OpenVPN status file

• netdiff.WireguardParser: parser for the Wireguard VPN (the command to use is wg show all dump)

• netdiff.ZeroTierParser: parser for ZeroTier VPN (the command to use is zerotier-cli peers -j or access the peers information through the ZeroTier Service API)

from netdiff import BatmanParser

BatmanParser(file="./my-stored-topology.json")

from netdiff import NetJsonParser

url = "https://raw.githubusercontent.com/interop-dev/netjson/master/examples/network-graph.json"
NetJsonParser(url=url)

from netdiff import OlsrParser

OlsrParser(url="telnet://127.0.1", timeout=5)

from netdiff import NetJsonParser

OlsrParser(url="https://myserver.mydomain.com/topology.json", verify=False)

NetJSON output

Netdiff parsers can return a valid NetJSON NetworkGraph object:

from netdiff import OlsrParser

olsr = OlsrParser(url="telnet://127.0.0.1:9090")

# will return a dict
olsr.json(dict=True)

# will return a JSON formatted string
print(olsr.json(indent=4))

Output:

{
    "type": "NetworkGraph",
    "protocol": "OLSR",
    "version": "0.6.6",
    "revision": "5031a799fcbe17f61d57e387bc3806de",
    "metric": "ETX",
    "nodes": [
        {
            "id": "10.150.0.3"
        },
        {
            "id": "10.150.0.2"
        },
        {
            "id": "10.150.0.4"
        }
    ],
    "links": [
        {
            "source": "10.150.0.3",
            "target": "10.150.0.2",
            "cost": 2.4
        },
        {
            "source": "10.150.0.3",
            "target": "10.150.0.4",
            "cost": 1.0
        }
    ]
}

Exceptions

All the exceptions are subclasses of netdiff.exceptions.NetdiffException.

def to_python(self, data):
    try:
        return super().to_python(data)
    except ConversionException as e:
        return self._txtinfo_to_jsoninfo(e.data)

Specialized features

Known Issues

LoadPlugin "olsrd_jsoninfo.so.0.0"
{
    PlParam "httpheaders" "yes"   # add this line
    PlParam "Port" "9090"
    PlParam "accept" "0.0.0.0"
}

Running tests

Install your forked repo:

git clone git://github.com/<your_fork>/netdiff
cd netdiff/
python setup.py develop

Install test requirements:

pip install -r requirements-test.txt

Run tests with:

./runtests.py
./run-qa-checks

Alternatively, you can use the nose2 command (which has a ton of available options):

nose2
nose2 tests.test_olsr  # run only olsr related tests
nose2 tests/test_olsr.py  # variant form of the previous command
nose2 tests.test_olsr:TestOlsrParser  # variant form of the previous command
nose2 tests.test_olsr:TestOlsrParser.test_parse  # run specific test

See test coverage with:

coverage run --source=netdiff runtests.py && coverage report

Contributing

Please refer to the OpenWISP contributing guidelines.

Support

See OpenWISP Support Channels.

Changelog

See CHANGES.

License

See LICENSE.