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 (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
- type UDPCallback
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type NetStack ¶
type NetStack struct {
// contains filtered or unexported fields
}
NetStack implements the ns.NetStack interface for our raw stack.
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 ¶
Close tears down listeners, connections, endpoints and the debug server. It is best-effort and idempotent.
func (*NetStack) DebugHTTPAddr ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
SetServiceProxyEnabled toggles the localhost proxy feature for TCP flows addressed to serviceIPv4.
func (*NetStack) StartDNSServer ¶
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 ¶
UDPCallback is a function type for handling UDP packets
Source Files
Directories