tcattach

Documentation

Overview

Package tcattach binds BPF programs to a netlink link via the kernel's TC clsact qdisc and a direct-action filter at the ingress or egress hook.

The production agent and the test infrastructure both need the same two netlink calls (clsact qdisc replace, BPF filter replace). Centralising them here keeps the agent's attach path and the testenv-side attach for veth pairs from drifting.

Index

• Constants
• Variables
• func AttachTelemetry(link netlink.Link, ingress, egress *ebpf.Program) error
• func IsTelemetryFilterName(name string) bool
• func Replace(link netlink.Link, prog *ebpf.Program, dir Direction, name string) error
• type Direction
• type Hook
• type LinkAttacher
  • func NewLinkAttacher(ingress, egress *ebpf.Program) *LinkAttacher
  • func (a *LinkAttacher) AttachLink(name string) error

Constants

const (
	FilterIngressName = "telemetry_in"
	FilterEgressName  = "telemetry_out"
)

FilterIngressName and FilterEgressName are the labels the agent installs on its clsact ingress and egress filters. Constants are exported because both the zombie hunter and the netlink-driven dynamic attacher need the same vocabulary to recognise filters the agent owns.

Changing either name silently breaks zombie cleanup and dynamic attach. The Hooks table below pairs them with their parent handles as the single source of truth the consumers iterate.

const FilterHandle = 1

FilterHandle is the TC filter handle the agent and testenv use for their direct-action filters. Kept fixed so a re-attach (FilterReplace) always lands on the same slot rather than piling up parallel filters.

const FilterPriority = 1

FilterPriority is the TC filter priority (preference) the agent's filters install at. It must be a fixed non-zero value: at priority 0 the kernel auto-allocates a fresh priority on every call, so a FilterReplace never matches the previous filter — each re-attach stacks another copy and every packet is counted once per copy. Pinning the full (parent, priority, handle) triple makes FilterReplace genuinely idempotent and lets FilterDel address the exact filter the agent installed.

Variables

var Hooks = []Hook{
	{Name: FilterIngressName, Parent: netlink.HANDLE_MIN_INGRESS},
	{Name: FilterEgressName, Parent: netlink.HANDLE_MIN_EGRESS},
}

Hooks is the fixed set of clsact filters AttachTelemetry installs, in attach order (ingress, egress). It is the single source of truth for the (name, parent) pairs the zombie hunter and the dynamic attacher match on, so a hook-location or name change is a one-place edit here rather than a coordinated change across packages.

Functions

func AttachTelemetry

func AttachTelemetry(link netlink.Link, ingress, egress *ebpf.Program) error

AttachTelemetry installs the clsact qdisc on link and binds both telemetry programs in one call — ingress under FilterIngressName, egress under FilterEgressName — so callers cannot mis-pair a direction with the wrong filter name (which would silently break zombie cleanup, since the hunter matches filters by these names).

Attach is all-or-nothing: if the egress filter fails after the ingress filter is installed, the ingress filter is rolled back before returning, so a partial attach never leaves the link carrying one telemetry filter while callers (e.g. the netlink subscriber's Registry) record it as unattached. The rollback is best-effort: a rollback failure is logged at warn, and the zombie hunter reaps the stray filter on the next agent start.

func IsTelemetryFilterName

func IsTelemetryFilterName(name string) bool

IsTelemetryFilterName reports whether name is one the agent installs on a clsact hook (see Hooks). The zombie hunter uses it to recognise orphaned telemetry filters left by a previous crash.

func Replace

func Replace(link netlink.Link, prog *ebpf.Program, dir Direction, name string) error

Replace installs (or replaces) the clsact qdisc on link and binds prog as a BPF filter at the named direction with the given filter name. The qdisc and filter are both replaced rather than added, so a second call with the same direction/name is idempotent.

Types

type Direction

type Direction int

Direction selects which clsact hook a filter attaches to.

const (
	Ingress Direction = iota
	Egress
)

Ingress and Egress are the clsact hook positions a BPF filter can occupy on a link.

type Hook

type Hook struct {
	Name   string
	Parent uint32
}

Hook describes one clsact filter the agent attaches: the filter Name and the kernel Parent handle it lives under.

type LinkAttacher

type LinkAttacher struct {
	// contains filtered or unexported fields
}

LinkAttacher attaches the telemetry programs to an interface looked up by name. It adapts the by-name attach to a single-method seam so the L3 netlink subscriber can drive attach through an interface without importing this (L1) package or holding *ebpf.Program — the agent composition root wires a LinkAttacher in as that interface.

func NewLinkAttacher

func NewLinkAttacher(ingress, egress *ebpf.Program) *LinkAttacher

NewLinkAttacher returns a LinkAttacher bound to the ingress and egress telemetry programs.

func (*LinkAttacher) AttachLink

func (a *LinkAttacher) AttachLink(name string) error

AttachLink looks up the named interface and attaches both telemetry programs via AttachTelemetry (all-or-nothing). Returns an error if the interface is missing or either attach fails.