netstack

Documentation

Overview

Package raw implements a tiny, purpose-built, in-VM L2/L3 network stack.

The goals are:

• Minimal correctness for ARP, IPv4, ICMP, UDP, and a very small TCP subset sufficient for inbound connections to a handful of services.
• Zero external dependencies beyond the project itself and stdlib.
• Explicit memory management: packet/frame buffers are drawn from small sync.Pools to reduce allocations.

Notes and limitations:

• No IPv6 support.
• No IP fragmentation/reassembly.
• Very small portion of TCP is implemented (SYN/ACK/FIN, no retransmits, no congestion control, no window scaling, no options beyond header size).
• MAC learning is simplistic: records latest observed source MAC.
• Certain counters and debug helpers are best effort only.

Index

• type NetStack
  • func New(l *slog.Logger) *NetStack
  • func (ns *NetStack) AttachNetworkInterface() (*NetworkInterface, error)
  • func (ns *NetStack) BindUDPCallback(address string, callback UDPCallback) error
  • func (ns *NetStack) Close() error
  • func (ns *NetStack) DebugHTTPAddr() string
  • func (ns *NetStack) DialInternalContext(ctx context.Context, network, address string) (net.Conn, error)
  • func (ns *NetStack) EnableDebugHTTP(addr string) error
  • func (ns *NetStack) ListenInternal(network, address string) (net.Listener, error)
  • func (ns *NetStack) ListenPacketInternal(network, address string) (net.PacketConn, error)
  • func (ns *NetStack) OpenPacketCapture(out io.Writer) error
  • func (ns *NetStack) SetGuestMAC(mac net.HardwareAddr) error
  • func (ns *NetStack) SetInternetAccessEnabled(enabled bool)
  • func (ns *NetStack) SetOutboundTCPDialer(dial func(ctx context.Context, addr *net.TCPAddr) (net.Conn, error))
  • func (ns *NetStack) SetServiceProxyEnabled(enabled bool)
  • func (ns *NetStack) StartDNSServer() error
  • func (ns *NetStack) StopDNSServer()
• type NetworkInterface
  • func (nic *NetworkInterface) AttachVirtioBackend(handler func(frame []byte) error)
  • func (nic *NetworkInterface) DeliverGuestPacket(packet []byte, release func()) error
• type UDPCallback

Types

type NetStack

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

NetStack implements the ns.NetStack interface for our raw stack.

func New

func New(l *slog.Logger) *NetStack

New constructs a NetStack with defaults.

func (*NetStack) AttachNetworkInterface

func (ns *NetStack) AttachNetworkInterface() (*NetworkInterface, error)

AttachNetworkInterface binds a new interface to the stack.

The returned object is used by the hypervisor side to deliver packets.

func (*NetStack) BindUDPCallback

func (ns *NetStack) BindUDPCallback(address string, callback UDPCallback) error

BindUDPCallback binds a UDP port to a callback function.

func (*NetStack) Close

func (ns *NetStack) Close() error

Close tears down listeners, connections, endpoints and the debug server. It is best-effort and idempotent.

func (*NetStack) DebugHTTPAddr

func (ns *NetStack) DebugHTTPAddr() string

DebugHTTPAddr returns the bound address of the debug HTTP server.

func (*NetStack) DialInternalContext

func (ns *NetStack) DialInternalContext(
	ctx context.Context,
	network, address string,
) (net.Conn, error)

DialInternalContext is not supported in the raw stack.

func (*NetStack) EnableDebugHTTP

func (ns *NetStack) EnableDebugHTTP(addr string) error

EnableDebugHTTP starts a small debug server exposing internal state at /status.

BUG: The code uses sync.WaitGroup but calls debugWG.Go(...). WaitGroup does not have a Go method; this will not compile unless debugWG is some wrapper type elsewhere. Either change to Add/Done or use errgroup.Group.

func (*NetStack) ListenInternal

func (ns *NetStack) ListenInternal(
	network, address string,
) (net.Listener, error)

ListenInternal binds a TCP listener on a given port.

func (*NetStack) ListenPacketInternal

func (ns *NetStack) ListenPacketInternal(
	network, address string,
) (net.PacketConn, error)

ListenPacketInternal binds a UDP endpoint on a given port.

func (*NetStack) OpenPacketCapture

func (ns *NetStack) OpenPacketCapture(out io.Writer) error

OpenPacketCapture enables streaming packet capture to the given writer.

func (*NetStack) SetGuestMAC

func (ns *NetStack) SetGuestMAC(mac net.HardwareAddr) error

SetGuestMAC sets the expected guest MAC for filtering and transmission.

func (*NetStack) SetInternetAccessEnabled

func (ns *NetStack) SetInternetAccessEnabled(enabled bool)

SetInternetAccessEnabled toggles access to real DNS lookups, etc.

func (*NetStack) SetOutboundTCPDialer

func (ns *NetStack) SetOutboundTCPDialer(dial func(ctx context.Context, addr *net.TCPAddr) (net.Conn, error))

SetOutboundTCPDialer overrides how outbound TCP connections are created for transparent proxying. If dial is nil, the default dialer is restored.

func (*NetStack) SetServiceProxyEnabled

func (ns *NetStack) SetServiceProxyEnabled(enabled bool)

SetServiceProxyEnabled toggles the localhost proxy feature for TCP flows addressed to serviceIPv4.

func (*NetStack) StartDNSServer

func (ns *NetStack) StartDNSServer() error

StartDNSServer binds UDP:53 and serves using a tiny DNS responder.

The server resolves a few internal hostnames, then optionally falls back to real DNS if allowInternet is true.

func (*NetStack) StopDNSServer

func (ns *NetStack) StopDNSServer()

type NetworkInterface

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

NetworkInterface is the concrete virtio-like interface that the guest uses to deliver and receive frames. It satisfies ns.NetworkInterface.

func (*NetworkInterface) AttachVirtioBackend

func (nic *NetworkInterface) AttachVirtioBackend(handler func(frame []byte) error)

AttachVirtioBackend sets the transmit callback to the hypervisor.

func (*NetworkInterface) DeliverGuestPacket

func (nic *NetworkInterface) DeliverGuestPacket(
	packet []byte,
	release func(),
) error

DeliverGuestPacket is called by the hypervisor when the guest transmits.

type UDPCallback

type UDPCallback func(ep *udpCallbackEndpoint, data []byte, addr net.UDPAddr)

UDPCallback is a function type for handling UDP packets