Traffic Control

Backends

Selection:

traffic {
    control {
        backend tc       // or: vpp
        interface eth0 {
            qdisc {
                type htb
                class fast {
                    rate 10mbit
                    ceil 20mbit
                }
            }
        }
    }
}

tc Backend: Original Qdisc Snapshot

Before installing its own root qdisc, the tc backend snapshots the interface's existing one so the interface can be restored exactly. A qdisc whose parameters this backend cannot reproduce is refused rather than approximated, and the apply fails naming it (protocol.md).

noqueue is snapshotted and restored. It is the default root on every virtual interface (veth, dummy, bridge, and anything else the kernel gives no real queue), so it is the state a QoS config is most often applied from. It carries no reconstructable parameters, but it is the absence of a discipline, so it is exactly restorable: the restore deletes whatever root Ze installed rather than replacing it, which returns the interface to noqueue. Adding a qdisc named noqueue is not the inverse operation, and a snapshot restored by deletion fails closed if a caller routes it down the replace path.

Other GenericQdisc types (mq, clsact, ...) stay rejected: those carry state this backend cannot reproduce.

tc Backend: Filter Priorities

The kernel keeps exactly one tcf_proto per (parent, priority), and that instance carries a single link-layer protocol (tcf_chain_tp_find, net/sched/cls_api.c). A second filter at the same priority with a different protocol is rejected with EINVAL.

Ze therefore allocates one priority per link-layer protocol: the IPv4 (ETH_P_IP) and IPv6 (ETH_P_IPV6) halves of a DSCP or protocol match get distinct priorities, as does a mark filter (ETH_P_ALL). With a shared priority the qdisc and class were created, the IPv4 filter was accepted, and the IPv6 filter at the same priority was refused.

VPP Backend: Compatibility Matrix

The VPP backend rejects qdisc and filter types that cannot be represented faithfully in VPP. Rejection fires at ze config commit (daemon config-verify) with a message of the form <type>: not supported by backend vpp, so operators learn about incompatibilities before the config lands rather than after Apply.

protocol and dscp filters are supported; mark is rejected. A class may carry match protocol <n> or match dscp <n>: the backend then builds per-family (IPv4 + IPv6) classify tables, adds a session steering the match to the class policer (ClassifyAddDelSession.HitNextIndex = policer index), and binds the tables to the interface's policer-classify feature so only matching traffic is policed. Protocol matches the packet at absolute frame offset 23 for IPv4 protocol and 20 for IPv6 next-header. DSCP matches the DiffServ Code Point at its own absolute offset: IPv4 TOS byte 15 with mask 0xFC, IPv6 traffic-class bytes 14 and 15 with masks 0x0F and 0xC0. The initial fw-7 attempt matched the wrong offset and never attached the table (silent no-op); the current pipeline is golden-vector tested and validated against real VPP v25.10.

A DSCP filter polices DSCP-matched traffic. It is not a QoS remark: the record/map/mark pipeline cannot police, so it is not the mechanism here.

Rate limiting without filters is still useful for single-rate use: one HTB or TBF class with rate/ceil values becomes one VPP policer on interface egress that enforces the operator's rate. Multi-class steering is supported when EVERY class on the interface carries a protocol or dscp filter: the classes then share chained classify tables and each gets its own policer. A multi-class config with one unfiltered class is rejected.

Policer name length: the backend composes a VPP policer name as ze/<iface>/<class> and VPP caps names at 64 bytes. If that compound exceeds 64 bytes, the verifier rejects the commit with a message naming the full name and the limit so the operator can shorten the class or interface name. No silent truncation -- two distinct classes must never produce the same stored policer name.

VPP Backend: Operational Notes

• VPP must be running when traffic-control config applies. If VPP is not reachable, Apply waits up to 5 seconds for the GoVPP connection and then returns vpp not connected after 5s. The commit fails and the operator is expected to start VPP and retry. There is no silent fallback.
• Rates round up. Ze uses bps internally; VPP uses kbps. 1500 bps becomes 2 kbps at the VPP layer. Rates above approximately 4.3 Tbps overflow VPP's uint32 kbps and are rejected explicitly.
• No reconciliation by the backend. The traffic component tracks the previous config and invokes Apply with the new full desired state on every reload. The backend diffs against the last applied policers and unbinds/deletes ones no longer referenced.
• Interface must exist in VPP. Names come from the config and are looked up via SwInterfaceDump each apply. An unknown interface name fails the apply with interface "<name>" not present in vpp.

Failure Modes