Documentation
¶
Overview ¶
Package netstack implements the netstack VTEP datapath driver: it splices a gVisor channel.Endpoint (the overlay-side, userspace L3 link) to the ICX engine, moving encap'd frames over an injected underlay transport.
It is the unprivileged, software-only driver of the vtep family. The driver owns neither the gVisor stack nor the underlay socket — both are injected by the consumer:
- apoxy-cli builds a full netstack.Stack (SOCKS, SNAT, TCP/UDP forwarders) and supplies its channel.Endpoint plus an l2pc-backed underlay.
- clrk attaches to the sentry's existing netstack (the geneve0 NIC) and supplies its own UDP underlay socket.
Both consume the same engine + pump; only the stack construction and the underlay differ. This is the consumer-locality seam: the overlay consumer lives inside a userspace netstack, so the driver is software.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Engine is the ICX engine performing encap/decap + crypto. *icx.Handler
// satisfies this; it must be configured in layer3 mode.
Engine vtep.EngineXfrm
// Endpoint is the overlay-side gVisor link endpoint. The consumer owns the
// enclosing stack.Stack and NIC; the datapath only reads/injects frames.
Endpoint *channel.Endpoint
// Underlay is the encap'd-frame transport. See Underlay.
Underlay Underlay
// FlushInterval overrides how often scheduled frames are flushed. Zero uses
// defaultFlushInterval.
FlushInterval time.Duration
}
Config configures a Datapath. Engine, Endpoint and Underlay are required.
type Datapath ¶
type Datapath struct {
// contains filtered or unexported fields
}
Datapath splices a channel.Endpoint to the ICX engine over an underlay. It implements vtep.Datapath.
func New ¶
New creates a Datapath. It registers for endpoint write notifications; the pumps do not run until Run is called.
func (*Datapath) Close ¶
Close stops the datapath's outbound pump and detaches from the endpoint. It does not close the injected endpoint's stack or the underlay — those are the consumer's to close. Closing the underlay is what unblocks the inbound pump.
Detaching the endpoint (RemoveNotify) happens first so the stack stops invoking WriteNotify, then done is closed to stop the outbound pump. wake is never closed, so a WriteNotify racing with teardown can't panic.
func (*Datapath) Run ¶
Run drives the two pump loops and blocks until shutdown. Cancelling ctx (or calling Close) stops the outbound pump; the inbound pump unblocks only when the consumer closes the injected underlay, since its blocking ReadFrame can't be interrupted otherwise. Therefore Run returns once BOTH have happened — cancelling ctx alone is not sufficient, the consumer must also close the underlay (apoxy-cli's ICXNetwork.Close and clrk's sentry teardown both do). A nil return means a clean shutdown. Run must not be called more than once.
func (*Datapath) WriteNotify ¶
func (d *Datapath) WriteNotify()
WriteNotify is invoked by the channel endpoint when netstack has an outbound packet ready. It coalesces a wakeup; draining and batching happen in the outbound pump. It is safe to call concurrently with Close: wake is never closed, so the send either buffers (capacity 1) or falls through to default.
type Underlay ¶
type Underlay interface {
// ReadFrame reads a single underlay frame into buf, returning its length.
// A length of 0 with a nil error is skipped.
ReadFrame(buf []byte) (int, error)
// WriteFrames writes a batch of underlay frames, returning the number actually
// sent. A short write (n < len(frames)) is permitted — a batched datagram send
// can put fewer frames on the wire than offered (EAGAIN, a mid-batch error, or
// a platform whose batch syscall degrades to one message per call). The datapath
// drains the unsent suffix (frames[n:]) by calling again, so implementations
// must NOT silently drop the tail. A zero return with a nil error is treated as
// a stall. The frames are owned by the caller and remain valid only until the
// call returns, so implementations must not retain them.
WriteFrames(frames [][]byte) (int, error)
}
Underlay is the physical/underlay frame transport the datapath reads encap'd frames from and writes them to. apoxy-cli's *l2pc.L2PacketConn satisfies this via a thin adapter; clrk supplies its own UDP-backed implementation.
The datapath does not own the underlay's lifecycle — the consumer closes it. Closing the underlay is also what unblocks a running Run: ReadFrame must return an error satisfying errors.Is(err, net.ErrClosed) once closed.
Source Files