Networking Overview

Stratum's networking stack runs entirely in the Linux kernel as eBPF programs attached at the XDP and TC hooks, with no user-space packet processing in the fast path. Every network you define is a managed L2 segment — with a subnet, a DHCP pool, and a DNS zone — bridged into the host's workload bridge, and each usable address is materialized into an endpoint profile (IP ↔ MAC). This page describes the overall model and how a packet moves through it. Follow the links in each section for deeper coverage.

The two bridges

Every node owns two Linux bridges:

Bridge	Purpose
`cnv-mgmt-br0`	Carries agent control traffic, cluster communication, and the Gateway HA heartbeat. Keep this reachable at all times.
`cnv-user-br0`	Carries all workload traffic. This is where networks and their eBPF programs live.

The split is deliberate: workload saturation or a misconfigured network policy cannot starve the control plane.

Networks as L2 segments

A network is a named managed L2 segment attached to cnv-user-br0. Creating one provisions:

A VLAN or flat L2 domain on the bridge.
An IP subnet and gateway address owned by the agent.
A DHCP pool for automatic address assignment.
An authoritative DNS zone (e.g. app-net.internal) with per-endpoint records.
An endpoint profile (IP ↔ generated MAC) for each usable host address, which you claim with network attach.

sudo cenvero-str-ctl network create \
  --name app-net \
  --cidr 10.20.0.0/24 \
  --gateway 10.20.0.1

A single node can host many independent networks with non-overlapping subnets. In a cluster, the VXLAN overlay stretches each network across every node so an endpoint can move hosts without changing its IP — see Clustering Overview.

The in-kernel data plane

When a packet arrives on a physical NIC or leaves a workload's interface, Stratum's eBPF programs make the forwarding decision in the kernel at interrupt time, before the packet ever touches a socket or a user-space process. The programs implement:

NIC-level filtering — drops spoofed or unauthorized frames at the earliest possible point.
Per-bridge MAC enforcement and anti-spoofing — ensures only the agent can introduce new addresses to the bridge, and binds each endpoint's IP↔MAC with Dynamic ARP Inspection and IPv6 ND inspection so endpoints cannot impersonate each other (see Zero-Trust Firewall).
Dual-stack L3/L4 firewall — an ordered IPv4/IPv6 ACL plus a source-IP blocklist, folded into the attached bridge and gateway programs so the same verdict is applied wherever traffic enters.
Egress bandwidth shaping — a per-CPU token-bucket rate limiter at the TC egress hook enforces per-tenant bandwidth caps without a separate QoS daemon.
VXLAN overlay — encapsulates frames for inter-host delivery when a destination endpoint lives on a different node, using real kernel VXLAN devices.

A separate L4 load-balancer fast-path (xdp_lb) is shipped but its datapath attach is not yet wired — see Load Balancer for its current status.

The kernel module (cenvero_stratum.ko) is an optional component that, when installed, owns the managed interfaces from boot so no other process can rebind or reconfigure them; the eBPF datapath runs with or without it. The eBPF programs are always in place before any traffic can flow.

How a packet flows

An inbound packet from a physical NIC to an endpoint on the same host follows this path:

Physical NIC (rx)
  → XDP NIC-level filter  (drop spoofs, enforce ACLs)
  → cnv-user-br0  (L2 forwarding decision)
  → XDP bridge MAC check  (verify source MAC is registered)
  → endpoint's interface

A packet destined for an endpoint on a different node:

Physical NIC (rx)
  → XDP NIC-level filter
  → VXLAN overlay decap
  → cnv-user-br0 (as if local)
  → endpoint's interface

Egress from an endpoint follows the reverse, with the TC egress hook applying bandwidth limits before the frame leaves the host.

Firewall and routing

The firewall is a dual-stack L3/L4 ACL operating at the network level. For a zero-trust posture, set its default action to deny so all inter-network and external traffic is blocked unless you add an explicit allow rule. See Zero-Trust Firewall.