Documentation
¶
Overview ¶
Package firewall manages host-level iptables state owned by kukeon — the FORWARD admission chain that admits traffic to/from kukeon bridges. It is distinct from internal/netpolicy, which installs per-space egress filters: admission lives at host scope and is set up once at `kuke init`, while egress is per-space and applied by the runner when a Space carries an EgressPolicy.
Index ¶
Constants ¶
const BridgeIfaceMatch = "k-+"
BridgeIfaceMatch is the iptables -i / -o interface match that scopes the admission rules to kukeon-managed bridges. The interface name is derived in internal/cni.SafeBridgeName as "k-<8 hex>" so the "+" wildcard matches the hex suffix and admits any kukeon bridge regardless of which space hash it represents.
const ForwardChainName = "KUKEON-FORWARD"
ForwardChainName is the kukeon-owned FORWARD admission chain.
Relative ordering with KUKEON-EGRESS (netpolicy.MasterChainName) is enforced by ensureForwardJump: when KUKEON-EGRESS already lives in FORWARD, the jump to KUKEON-FORWARD is placed immediately after it so per-space egress DROP rules win over the blanket admission. When KUKEON-EGRESS is absent the jump goes to position 1; a later netpolicy.Apply() will insert KUKEON-EGRESS at 1, pushing this jump to 2 (still correct).
Variables ¶
This section is empty.
Functions ¶
func AdmissionRules ¶
func AdmissionRules() [][]string
AdmissionRules returns the ordered iptables rules that populate ForwardChainName. The generator is pure — no I/O, no iptables calls — so tests can verify rule order without fakes.
Each rule carries a -m comment --comment "kukeon-forward:<role>" tag so `iptables -S` is self-documenting and the Install migration path can distinguish kukeon-installed rules from any user rules that happen to share the same chain name.
Rule order:
- RELATED,ESTABLISHED ACCEPT — return-traffic for already-admitted flows so reply packets cannot be dropped by FORWARD's default policy.
- -i k-+ ACCEPT — admit egress originating on a kukeon bridge.
- -o k-+ ACCEPT — admit ingress destined to a kukeon bridge.
func IsIptablesAvailable ¶ added in v0.6.0
func IsIptablesAvailable() bool
IsIptablesAvailable reports whether the iptables binary can be located on PATH. Callers should invoke this before Install on hosts that may not carry iptables (minimal containers, nftables-only distros without the iptables-nft compat shim): without the binary in place every runner call would fail and abort bring-up. The intended caller-side pattern is log WARN and continue, treating absence as "the host owner has opted out of kukeon-managed FORWARD admission".
Types ¶
type CommandRunner ¶
CommandRunner executes an iptables invocation and returns its combined stdout+stderr. Tests inject a fake to capture invocations and return canned output for read-only calls like "-C" or "-L". Mirrors netpolicy.CommandRunner.
type Installer ¶
type Installer struct {
// contains filtered or unexported fields
}
Installer applies and removes the KUKEON-FORWARD admission chain.
func NewInstaller ¶
NewInstaller returns an Installer that shells out to the iptables binary on PATH. Logger is required.
func NewInstallerWithRunner ¶
func NewInstallerWithRunner(logger *slog.Logger, runner CommandRunner) *Installer
NewInstallerWithRunner is the test-hook constructor.
func (*Installer) Install ¶
Install ensures KUKEON-FORWARD exists, contains the admission rules in the expected order, and is jumped to from FORWARD. Idempotent — re-running on a healthy host produces no rule churn (every install step does -C before -I/-A, mirroring the netpolicy pattern).
Upgrade-path migration: when the chain already exists with untagged rules from an older kukeon version, Install flushes it once before re-installing the tagged rules so the chain does not end up carrying both the bare and the tagged variants side by side.
func (*Installer) Remove ¶
Remove deletes the FORWARD jump, flushes, and deletes KUKEON-FORWARD. Safe to call when the chain does not exist; missing-chain failures from flush/delete are demoted to debug logs so reset --purge-system on a host that never installed the chain (or already removed it) does not error.
Source Files