linux

type Callbacks ¶

type Callbacks struct {
	TunCreated           func(tun gtun.Tun)
	TunConfigured        func(tun gtun.Tun, opts sysnet.TunOpts)
	DefaultTunCreated    func(tun sysnet.DefaultTun)
	DefaultTunConfigured func(tun sysnet.DefaultTun, opts sysnet.DefaultTunOpts)
	DefaultTunClosed     func()
	RoutingApplied       func(config routing.Config)
	DNSConfigured        func(server netip.Addr)
	KillswitchUpdated    func(rules killswitch.AllowRules)
}

Callbacks are optional hooks fired after successful lifecycle operations. Implementations must be quick; System never requires callbacks to be set.

type Config ¶

type Config struct {
	Features  FeatureConfig
	Allocator *linuxsubnet.CombinedAllocator

	DNSProvider    dns.DNSProvider
	RoutingManager RoutingManager
	Connmark       ConnmarkManager
	Pmark          PmarkController
	Killswitch     KillswitchClient
	TUNFactory     TUNFactory
	TunConfig      TunConfigurator

	RuleTracker *multirule.Tracker
	OwnerLookup func(sockowner.FlowTuple) (*sockowner.SocketOwner, error)

	PacketListen PacketListenFunc
	TUNIndex     TUNIndexFunc

	AppBypassMark uint32
	AppBypassMask uint32
	UserMark      uint32
	UserMarkMask  uint32
	PmarkPriority int

	DefaultTunBaseName string

	KillswitchAllowExclude bool
	Logf                   func(format string, args ...any)
	Callbacks              Callbacks

	// ExtraClosers are resources owned by System in addition to the standard
	// injected components. They are closed by System.Close after DNS, routing,
	// and killswitch state has been released.
	ExtraClosers []io.Closer
}

Config supplies System dependencies. Privileged integrations are injected so tests and embedders can choose exactly which Linux components System owns.

type ConnmarkManager ¶ added in v0.2.2

type ConnmarkManager interface {
	Apply(linuxconnmark.Config) error
	Rollback() error
	Close() error
}

ConnmarkManager is the nftables conntrack-mark surface used by System.

type DNSConfig ¶

type DNSConfig struct {
	Mode DNSMode

	ResolvconfInterface    string
	ResolvedInterfaceIndex int
	FallbackServers        []netip.AddrPort
}

DNSConfig configures the DNSProvider built by New.

FallbackServers are used by DNS providers only when no usable original upstream resolver is available. ResolvconfInterface is the provider-owned resolvconf record name; when empty, "sysnet-linux" is used.

type DNSMode ¶

type DNSMode string

DNSMode selects the host DNS integration used by New.

DNSModeAuto uses dns.DnsMode to detect the host DNS integration.

const (
	DNSModeAuto             DNSMode = ""
	DNSModeDisabled         DNSMode = "disabled"
	DNSModeDirect           DNSMode = "direct"
	DNSModeOpenresolv       DNSMode = "openresolv"
	DNSModeDebianResolvconf DNSMode = "debian-resolvconf"
	DNSModeResolved         DNSMode = "systemd-resolved"
)

type FeatureConfig ¶

type FeatureConfig struct {
	Tun             bool
	DefaultTun      bool
	DynTun          bool
	DynDefaultTun   bool
	TunNames        bool
	DefaultTunNames bool
	StrictMode      bool
	TunRules        bool
	MatcherRules    bool
	DNSControl      bool
	Routing         bool
	Pmark           bool
	Killswitch      bool
}

FeatureConfig describes features requested by the caller. Effective feature support is the requested value degraded by the components supplied in Config.

type KillswitchClient ¶

type KillswitchClient interface {
	CreateTMPRuleset(killswitch.AllowRules) (uint64, error)
	UpdateTMPRuleset(uint64, killswitch.AllowRules) error
	DeleteTMPRuleset(uint64) error
	Close() error
}

KillswitchClient is the killswitch temporary-ruleset surface used by System.

type PacketListenFunc ¶

type PacketListenFunc func(ctx context.Context, network, address string) (net.PacketConn, error)

PacketListenFunc opens the UDP socket backing the DefaultTun DNS server.

type PmarkConfig ¶

type PmarkConfig struct {
	PinPath string

	Callbacks            pmark.Callbacks
	TombCollectionEvents uint64
	TombTTL              time.Duration
	Priority             int
}

PmarkConfig configures the optional p-mark integration built by New.

P-mark is attempted only when PinPath is non-empty. This avoids creating a global bpffs directory implicitly. When enabled, New also starts the fwmark eBPF manager, because DefaultTun include/exclude rules need p-mark values to become socket fwmarks before routing can see them.

type PmarkController ¶

type PmarkController interface {
	SetChecker(pmark.CheckFunc) (uint64, error)
	ForceProcessTraversal() error
}

PmarkController is the p-mark daemon surface used by System.

type RoutingManager ¶

type RoutingManager interface {
	Apply(routing.Config) error
	Refresh() error
	Rollback(routing.Config) error
	Status() (routing.DesiredState, bool)
	Close() error
}

RoutingManager is the routing.Manager surface used by System.

type System ¶

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

System composes the Linux DNS, TUN, routing, p-mark, and killswitch helpers.

func New(config SystemConfig) (*System, error)

func NewSystem(config Config) (*System, error)

func (s *System) AddTunAddr(t gtun.Tun, addr string) error

func (s *System) AddTunRoute(t gtun.Tun, route string) error

func (s *System) AllocIP() subnet.IPAllocator

func (s *System) AllocSubnet() subnet.SubnetAllocator

func (s *System) BuildDefaultTun(
	opts sysnet.DefaultTunOpts,
) (sysnet.DefaultTun, error)

func (s *System) BuildMatcher(rule sysnet.Rule) (sysnet.Matcher, error)

func (s *System) BuildTun(opts sysnet.TunOpts) (gtun.Tun, error)

func (s *System) Close() error

func (s *System) DefaultTunWarnings(t sysnet.DefaultTun) []sysnet.Warning

func (s *System) Features() sysnet.Features

func (s *System) GetTunAddrs(t gtun.Tun) ([]string, error)

func (s *System) GetTunRotue(t gtun.Tun) ([]string, error)

func (s *System) ListRules() sysnet.RulesInfo

func (s *System) LocalNet() gonnect.Network

func (s *System) OutDNS() gdns.Interface

func (s *System) OutNet() gonnect.Network

func (s *System) RuleCompl(rule sysnet.Rule) (out []string)

func (s *System) RuleVerify(rule sysnet.Rule) bool

func (s *System) SetTunAddrs(t gtun.Tun, addrs []string) error

func (s *System) SetTunMTU(t gtun.Tun, mtu int) error

func (s *System) SetTunName(t gtun.Tun, name string) ([]string, error)

func (s *System) SetTunRoutes(t gtun.Tun, routes []string) error

func (s *System) TunNameVerify(name string) (bool, bool)

func (s *System) TunWarnings(t gtun.Tun) []sysnet.Warning

func (s *System) VerifyDefaultTunOpts(opts sysnet.DefaultTunOpts) error

func (s *System) VerifyTunOpts(opts sysnet.TunOpts) error

type SystemConfig ¶

type SystemConfig struct {
	Features FeatureConfig

	Allocator      linuxsubnet.DefaultAllocatorConfig
	DNS            DNSConfig
	KillswitchPath string
	Pmark          PmarkConfig

	AppBypassMark uint32
	AppBypassMask uint32
	UserMark      uint32
	UserMarkMask  uint32

	DefaultTunBaseName string

	KillswitchAllowExclude bool
	Logf                   func(format string, args ...any)
	Callbacks              Callbacks
}

SystemConfig is the high-level, best-effort constructor configuration used by New.

The zero value requests all System-level features and lets New auto-detect which ones are actually available in the current process environment. Missing privileges, absent /dev/net/tun, unavailable routing/DNS/killswitch/p-mark integrations, and unsupported optional daemons disable the affected features while leaving allocation, OutNet, LocalNet, rule verification, and any other available features usable.

For exact dependency injection, deterministic tests, or integrations that need a DNS provider tied to a TUN created elsewhere, use NewSystem.

type TUNFactory ¶

type TUNFactory interface {
	CreateTUN(baseName string, mtu int) (gtun.Tun, error)
}

TUNFactory creates a native TUN device.

type TUNIndexFunc ¶

type TUNIndexFunc func(gtun.Tun) (int, error)

TUNIndexFunc returns the kernel interface index for a TUN.

type TunConfigurator ¶

type TunConfigurator interface {
	SetTunMTU(gtun.Tun, int) error
	SetTunAddrs(gtun.Tun, []string) error
	AddTunAddr(gtun.Tun, string) error
	GetTunAddrs(gtun.Tun) ([]string, error)
	SetTunRoutes(gtun.Tun, []string) error
	AddTunRoute(gtun.Tun, string) error
	GetTunRotue(gtun.Tun) ([]string, error)
	SetTunName(gtun.Tun, string) ([]string, error)
}

TunConfigurator applies and reads mutable TUN state.