hostport

package
v0.6.13 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package hostport forwards raw-TCP host ports in the kernel (plans/ingress-proxy-routing.md §3.5, task T7, decision "kernel DNAT").

Raw-TCP exposures used to be one Caddy layer4 server per host port. Every expose, unexpose, stop and failover was a Caddy config write, and each write reloads Caddy's whole config. Moving them into sandboxd userspace would have reset every TCP session on each sandboxd restart, because an accepted socket dies with its process. Kernel forwarding avoids both: bytes never touch sandboxd, sessions live in conntrack and survive any sandboxd restart, and sandboxd only programs rules.

nat    PREROUTING / OUTPUT (dst-type LOCAL) ─▶ AEROLVM-HOSTPORT
         -p tcp --dport HP  -j DNAT --to ip:port    owner → container
                                                    ingress → owner:HP
         -p tcp --dport HP  -j REDIRECT --to-ports R  wake / WASM / isolate
                                                    (sandboxd splices; it
                                                    reads SO_ORIGINAL_DST)
nat    POSTROUTING ─▶ AEROLVM-HOSTPORT-POST
         -p tcp -d ip --dport port -j MASQUERADE    ingress → owner hop only,
                                                    so replies return here
filter FORWARD (pos 1) ─▶ AEROLVM-HOSTPORT-FWD
         -p tcp -m conntrack --ctstate DNAT --ctorigdstport HP -j ACCEPT
         both directions of the DNAT'd connection, ahead of any DROP policy

net.ipv4.ip_forward is switched on at bootstrap. A pure ingress node runs no sandbox runtime, so nothing else enables it, and the kernel silently dropped every DNAT'd packet bound for a remote owner. Found live on cluster-hetero-lite-routing: every raw-TCP dial through the ingress-only node timed out.

Every rule carries the comment "aerolvm-hp-<HP>", so Reconcile can find drift after a restart without trusting in-memory state. Removing a port also flushes its conntrack entries: without that, DNAT'd sessions outlive the rule and an unexpose would not actually cut access.

Index

Constants

View Source
const (
	ChainNAT  = "AEROLVM-HOSTPORT"
	ChainPost = "AEROLVM-HOSTPORT-POST"
	ChainFwd  = "AEROLVM-HOSTPORT-FWD"
)

Variables

This section is empty.

Functions

func FlushConntrack

func FlushConntrack(hostPort int) error

FlushConntrack drops tracked TCP connections whose ORIGINAL destination port is hostPort. Without this, DNAT'd sessions outlive their rule and an unexpose would not cut access.

Types

type Backend

type Backend interface {
	ChainExists(table, chain string) (bool, error)
	NewChain(table, chain string) error
	Exists(table, chain string, spec ...string) (bool, error)
	Insert(table, chain string, pos int, spec ...string) error
	Append(table, chain string, spec ...string) error
	Delete(table, chain string, spec ...string) error
	// List returns a chain's rules in iptables-save form ("-A CHAIN ...").
	List(table, chain string) ([]string, error)
}

Backend is the iptables subset the forwarder needs. It is implemented by NewIPTablesBackend in production and by an in-memory table in tests.

func NewIPTablesBackend

func NewIPTablesBackend() (Backend, error)

NewIPTablesBackend returns the production backend (IPv4).

type ConntrackFlusher

type ConntrackFlusher func(hostPort int) error

ConntrackFlusher drops tracked TCP connections whose original destination port is hostPort. Linux uses netlink; elsewhere it is a no-op.

type Forwarder

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

Forwarder owns the three chains and the per-port rules.

func New

func New(b Backend, flush ConntrackFlusher) *Forwarder

func (*Forwarder) Ensure

func (f *Forwarder) Ensure(hp int, t Target) error

Ensure forwards hp to t, idempotently. A changed target replaces the old rules. Sessions already tracked keep their original mapping until they end; that is how a sandbox wake (Redirect → DNAT) keeps the connection that woke it.

func (*Forwarder) Ports

func (f *Forwarder) Ports() []int

Ports lists the host ports currently forwarded (in memory), sorted.

func (*Forwarder) PruneUnasserted

func (f *Forwarder) PruneUnasserted() error

PruneUnasserted is Reconcile with desired = every rule asserted through Ensure since this process started. Call it after the boot re-assert pass (owner reconcile + ingress reconcile) has replayed every live exposure: what's left in the kernel belongs to exposures that went away while sandboxd was down. Stale rules are dangerous: a reused container IP would expose the new sandbox's port. The desired set is taken under the same lock, so a concurrent Ensure is never pruned.

func (*Forwarder) Reconcile

func (f *Forwarder) Reconcile(desired map[int]Target) error

Reconcile makes the kernel match desired exactly. Rules this forwarder owns (by comment) that are not desired, or no longer match, are deleted, and their conntrack entries flushed. Every desired rule is ensured. It runs at boot and periodically, so drift from a restart, a manual flush or a crashed apply heals, and nothing is inferred from in-memory state alone.

func (*Forwarder) Remove

func (f *Forwarder) Remove(hp int) error

Remove stops forwarding hp and flushes its tracked connections, so an unexpose actually cuts access. It is idempotent.

type Kind

type Kind int

Kind is how a host port is forwarded.

const (
	// DNAT rewrites to Addr. Masquerade is set for a remote target (the
	// ingress → owner hop), so the owner replies to this node.
	DNAT Kind = iota
	// Redirect delivers to the local sandboxd listener on RedirectPort, for
	// targets the kernel can't reach directly: stopped/wake sandboxes, and
	// WASM/isolate loopback mediators.
	Redirect
)

type Target

type Target struct {
	Kind         Kind
	Addr         netip.AddrPort
	Masquerade   bool
	RedirectPort int
}

Target is where one host port goes.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL