p4net

Mininet-style P4 SDN sandbox in Python.

What it is

p4net brings up real simple_switch_grpc (BMv2) dataplanes inside Linux network namespaces and wires them with veth pairs and tc netem impairment, then drives them through P4Runtime — exactly the way an operational P4 controller would talk to real hardware. The Python API is shaped like Mininet's: declare a Topology of Host, P4Switch, and Link objects, hand it to a Network, get a running playground back.

The framework is geared at P4 development and education: classroom labs, controller prototypes, regression harnesses for forwarding logic, and quick experiments where spinning up a multi-host topology in a few seconds matters more than emulating a specific switch ASIC. There is no Docker, no OpenFlow, no Open vSwitch — the toolchain is p4c, simple_switch_grpc, and the kernel's namespace primitives.

What's in the box

• Topology DSL — Host, P4Switch, Link, Topology with static validation (interface name length, IP collisions, asymmetric vs symmetric impairment conflicts).
• p4c-driven compilation with a content-addressed cache at ~/.cache/p4net/compiler/ — recompile when source, includes, or compiler settings actually change.
• BMv2 lifecycle management — start, wait-for-ready, stop, gRPC port allocation, atexit / signal cleanup safety nets.
• P4Runtime gRPC client — table programming, indirect counter reads, multicast group management, CPU-port packet I/O over the StreamChannel.
• Per-direction link impairment via tc netem — bandwidth, delay, jitter, loss_pct either symmetric, split into *_a_to_b / *_b_to_a, or layered as a symmetric base plus a per-direction *_extra.
• IPv4 and IPv6 host addressing with per-interface sysctl gating (link-local addresses are suppressed on interfaces that don't ask for IPv6).
• Interactive CLI — p4net <topology.py> opens a shell with table dumps, ping matrices, packet send/listen, topology visualization.
• Topology visualization via Topology.to_graphviz() and Topology.render_graphviz() (DOT, PNG, SVG, PDF).
• Unified p4net.* logger hierarchy with documented level conventions and CLI verbosity flags (-v / -vv); see Logging.

Install

pip install p4net

Detailed instructions including the external p4c and BMv2 prerequisites are on the Installation page.

30-second example

from pathlib import Path
from p4net import Network
from p4net.topo import Topology

topo = Topology()
h1 = topo.add_host("h1", ip="10.0.0.1/24", mac="00:00:00:00:00:01")
h2 = topo.add_host("h2", ip="10.0.0.2/24", mac="00:00:00:00:00:02")
s1 = topo.add_switch("s1", p4_src=Path("port_swap.p4"))
topo.add_link(h1, s1, port_b=1)
topo.add_link(h2, s1, port_b=2)

with Network(topo) as net:
    h1, h2 = net.host("h1"), net.host("h2")
    h1.exec(["ip", "neigh", "replace", "10.0.0.2",
             "lladdr", "00:00:00:00:00:02",
             "dev", "h1-eth0", "nud", "permanent"])
    print(h1.ping(h2))   # True

The port_swap.p4 source is in examples/quick_start/.

Where to next

• Quick Start — the same example walked through end to end, with the P4 source.
• Tutorial — a longer walk through dual-stack forwarding, runtime table programming, asymmetric link impairment, and CPU-port packet I/O.
• Architecture — what each package does and the design decisions behind the layout.
• Examples — seven runnable topologies, from port-swap and L3 forwarding to in-band network telemetry (INT).
• CLI Reference — every shell command with synopses and example output.
• API Reference — auto-generated from the Python docstrings.

Project status

p4net v1.8.0 is a stable release. Public interfaces follow the API stability rules, including the deprecation cycle for stable and provisional APIs.

This version adds asynchronous network startup and shutdown, ternary and range matches in the CLI, and a reproducible performance benchmark tool. It fixes compiler cache handling, connection cleanup, interface placement and topology validation. See the Changelog for details and upgrade notes, Known Limitations for current boundaries, and the Roadmap for future plans.