Skip to main content

JSON parsing Linux Network Namespace (netns) topology builder.

Project description


JSON parsing Linux Network Namespace (netns) topology builder.


From PyPI:

  • pip install json2netns

From GitHub:

  • pip install git+git://


The script takes a JSON config file and drives namespace creation from that JSON toplogy file. Lets look at the following simple two network namespace topology:

json2netns sample topology

We have two namespaces that have 1 direct connection via a veth. It also has a OOB (Out of Band) set of interfaces that allow the main Linux Network Namespace to communicate with the netns directly.

  • By default it even bridges with a physical interface to allow external packets to be routed into the netns if desired from a physical NIC.


The above topology is represented by sample.json. This config is also used by unittests to ensure correct functioning. We can add to it over time as we add more features.

Small 1 NS Example JSON Config

    "namespaces": {
        "left": {
            "id": 1,
            "interfaces": {
                "left0": {
                    "prefixes": ["fd00::1/64", ""],
                    "peer_name": "right0",
                    "type": "veth"
                "lo": {
                    "prefixes": ["fd00:1::/64", ""],
                    "type": "loopback"
            "oob": false,
            "routes": {}
    "oob": {},
    "physical_int": ""


After installing just point json2netns at a config file and run as root (in the future we could make it capability aware too - PR Welcome!).

  • usage: json2netns [-h] [-d] [--validate] [--workers WORKERS] config action


  • create: Create the interfaces and namespaces + bring interfaces up
  • check: Print the interface addressing + v4/6 routing tables to stdout
  • delete: Remove the namespaces and all interfaces


The code has been attmepted to be very object oriented. Please try to use inheritence and keep new interface types sub classes of Interface etc. for all code additons.

Development 'editable' Install

python3 -m venv [--upgrade-deps] /tmp/tj
/tmp/tj/bin/pip install -r requirements_test.txt
/tmp/tj/bin/pip install -e .

Run Tests

For testing we use ptr.

/tmp/tj/bin/ptr [-k] [--print-cov] [--debug]
  • -k: keep venv ptr creates
  • --print-cov: handy to see what coverage is on all files
  • --debug: Handy to see all commands run so you can run a step manually

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for json2netns, version 2021.5.27
Filename, size File type Python version Upload date Hashes
Filename, size json2netns-2021.5.27-py3-none-any.whl (13.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size json2netns-2021.5.27.tar.gz (12.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page