uspfilter

package
v0.78.1 Latest Latest
Warning

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

 Go to latest Published: Sep 4, 2026 License: BSD-3-Clause Imports: 32 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	// EnvDisableConntrack disables the stateful filter, replies to outbound traffic won't be allowed.
	EnvDisableConntrack = "NB_DISABLE_CONNTRACK"

	// EnvDisableUserspaceRouting disables userspace routing, to-be-routed packets will be dropped.
	EnvDisableUserspaceRouting = "NB_DISABLE_USERSPACE_ROUTING"

	// EnvDisableMSSClamping disables TCP MSS clamping for forwarded traffic.
	EnvDisableMSSClamping = "NB_DISABLE_MSS_CLAMPING"

	// EnvForceUserspaceRouter is a deprecated alias for
	// NB_FORCE_USERSPACE_FIREWALL: the userspace firewall always routes in
	// userspace, so forcing one forces the other. Kept for backward
	// compatibility.
	EnvForceUserspaceRouter = "NB_FORCE_USERSPACE_ROUTER"

	// EnvEnableLocalForwarding enables forwarding of local traffic to the native stack for internal (non-NetBird) interfaces.
	// Default off as it might be security risk because sockets listening on localhost only will become accessible.
	EnvEnableLocalForwarding = "NB_ENABLE_LOCAL_FORWARDING"

	// EnvEnableNetstackLocalForwarding is an alias for EnvEnableLocalForwarding.
	// In netstack mode, it enables forwarding of local traffic to the native stack for all interfaces.
	EnvEnableNetstackLocalForwarding = "NB_ENABLE_NETSTACK_LOCAL_FORWARDING"
)
View Source 
const (

	// EnvFragmentMaxEntries overrides defaultMaxFragmentEntries.
	EnvFragmentMaxEntries = "NB_FRAGMENT_MAX_ENTRIES"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Config added in v0.78.0 

type Config struct {
	// IFace is the overlay interface the filter attaches to.
	IFace Iface
	// InterfaceAllower opens the NetBird interface in foreign kernel filter
	// chains so the kernel doesn't drop traffic the userspace firewall handles.
	// Nil in netstack mode, on non-Linux platforms without a backend, or when
	// neither nftables nor iptables is available. firewalld trust is applied by
	// the manager regardless, since firewalld owns its own chains and we cannot
	// insert into them.
	InterfaceAllower InterfaceAllower
	// DisableServerRoutes indicates whether server routes are disabled.
	DisableServerRoutes bool
	FlowLogger          nftypes.FlowLogger
	MTU                 uint16
}

Config holds the dependencies and options for the userspace firewall.

type ForwarderAction added in v0.36.6 

type ForwarderAction struct {
	Action     string
	RemoteAddr string
	Error      error
}

type HooksFilter added in v0.68.2 

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

HooksFilter is a minimal packet filter that only handles outbound DNS hooks. It is installed on the WireGuard interface when the userspace bind is active but a full firewall filter (Manager) is not needed because a native kernel firewall (nftables/iptables) handles packet filtering.

func (*HooksFilter) FilterInbound added in v0.68.2 

func (f *HooksFilter) FilterInbound([]byte, int) bool

FilterInbound allows all inbound packets (native firewall handles filtering).

func (*HooksFilter) FilterOutbound added in v0.68.2 

func (f *HooksFilter) FilterOutbound(packetData []byte, _ int) bool

FilterOutbound checks outbound packets for DNS hook matches. Only IPv4 packets matching the registered hook IP:port are intercepted. IPv6 and non-IP packets pass through unconditionally.

func (*HooksFilter) SetTCPPacketHook added in v0.68.2 

func (f *HooksFilter) SetTCPPacketHook(ip netip.Addr, dPort uint16, hook func([]byte) bool)

SetTCPPacketHook registers the TCP packet hook.

func (*HooksFilter) SetUDPPacketHook added in v0.68.2 

func (f *HooksFilter) SetUDPPacketHook(ip netip.Addr, dPort uint16, hook func([]byte) bool)

SetUDPPacketHook registers the UDP packet hook.

type Iface added in v0.78.0 

type Iface interface {
	Name() string
	Address() wgaddr.Address
	SetFilter(device.PacketFilter) error
	GetWGDevice() *wgdevice.Device
}

Iface is the network interface the userspace firewall attaches to: the methods of the WireGuard device it actually uses.

type InterfaceAllower added in v0.78.0 

type InterfaceAllower interface {
	Apply() error
	Close() error
}

InterfaceAllower opens the NetBird interface in the host firewall so it doesn't drop traffic the userspace firewall handles, without taking over packet filtering. Implementations (nftables, iptables, firewalld, the windows netsh rule) are selected per platform and injected into Create; Apply runs at creation and Close on teardown.

type Manager 

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

Manager userspace firewall manager

func Create 

func Create(cfg Config) (_ *Manager, err error)

func (*Manager) AddDNATRule added in v0.38.0 

func (m *Manager) AddDNATRule(firewall.ForwardRule) (firewall.Rule, error)

AddDNATRule adds outbound DNAT rule for forwarding external traffic to NetBird network.

func (*Manager) AddFilterRule added in v0.78.0 

func (m *Manager) AddFilterRule(
	id []byte,
	sources []netip.Prefix,
	destination firewall.Network,
	proto firewall.Protocol,
	sPort, dPort *firewall.Port,
	action firewall.Action,
) (firewall.Rule, error)

AddFilterRule is the unified entry point for both peer (input chain) and route (forward chain) filtering rules. The destination distinguishes the two semantics: a zero Network installs an input-side rule that matches by source only; a set Network installs a forward-side rule that also matches the destination.

func (*Manager) AddInboundDNAT added in v0.59.9 

func (m *Manager) AddInboundDNAT(localAddr netip.Addr, protocol firewall.Protocol, originalPort, translatedPort uint16) error

AddInboundDNAT adds an inbound DNAT rule redirecting traffic from NetBird peers to local services.

func (*Manager) AddInternalDNATMapping added in v0.50.0 

func (m *Manager) AddInternalDNATMapping(originalAddr, translatedAddr netip.Addr) error

AddInternalDNATMapping adds a 1:1 IP address mapping for internal DNAT translation.

func (*Manager) AddNatRule added in v0.30.0 

func (m *Manager) AddNatRule(firewall.RouterPair) error

func (*Manager) AddOutputDNAT added in v0.68.0 

func (m *Manager) AddOutputDNAT(netip.Addr, firewall.Protocol, uint16, uint16) error

AddOutputDNAT is not supported by the userspace firewall: it backs kernel DNS redirection, but userspace DNS is served in-process on the gVisor netstack, so this should never be called.

func (*Manager) Close added in v0.37.2 

func (m *Manager) Close(*statemanager.Manager) error

Close cleans up the firewall manager: removes rules, closes trackers, and closes the interface allower.

func (*Manager) DeleteDNATRule added in v0.38.0 

func (m *Manager) DeleteDNATRule(firewall.Rule) error

DeleteDNATRule deletes outbound DNAT rule.

func (*Manager) DeleteFilterRule added in v0.78.0 

func (m *Manager) DeleteFilterRule(rule firewall.Rule) error

DeleteFilterRule deletes a filtering rule. The rule's underlying type is used to route to the correct internal path.

func (*Manager) DisableRouting added in v0.36.6 

func (m *Manager) DisableRouting() error

func (*Manager) EnableRouting added in v0.36.6 

func (m *Manager) EnableRouting() error

func (*Manager) FilterInbound added in v0.50.0 

func (m *Manager) FilterInbound(packetData []byte, size int) bool

FilterInbound filters incoming packets

func (*Manager) FilterOutbound added in v0.50.0 

func (m *Manager) FilterOutbound(packetData []byte, size int) bool

FilterOutbound filters outgoing packets

func (*Manager) Flush added in v0.21.9 

func (m *Manager) Flush() error

Flush doesn't need to be implemented for this manager

func (*Manager) Init added in v0.30.3 

func (m *Manager) Init(*statemanager.Manager) error

func (*Manager) IsServerRouteSupported added in v0.24.4 

func (m *Manager) IsServerRouteSupported() bool

func (*Manager) IsStateful added in v0.46.0 

func (m *Manager) IsStateful() bool

func (*Manager) RegisterNetstackService added in v0.59.12 

func (m *Manager) RegisterNetstackService(protocol nftypes.Protocol, port uint16)

RegisterNetstackService registers a service as listening on the netstack for the given protocol and port

func (*Manager) RemoveInboundDNAT added in v0.59.9 

func (m *Manager) RemoveInboundDNAT(localAddr netip.Addr, protocol firewall.Protocol, originalPort, translatedPort uint16) error

RemoveInboundDNAT removes an inbound DNAT rule.

func (*Manager) RemoveInternalDNATMapping added in v0.50.0 

func (m *Manager) RemoveInternalDNATMapping(originalAddr netip.Addr) error

RemoveInternalDNATMapping removes a 1:1 IP address mapping.

func (*Manager) RemoveNatRule added in v0.30.0 

func (m *Manager) RemoveNatRule(firewall.RouterPair) error

RemoveNatRule removes a routing firewall rule

func (*Manager) RemoveOutputDNAT added in v0.68.0 

func (m *Manager) RemoveOutputDNAT(netip.Addr, firewall.Protocol, uint16, uint16) error

RemoveOutputDNAT is a no-op for the userspace firewall (see AddOutputDNAT).

func (*Manager) SetLegacyManagement added in v0.30.0 

func (m *Manager) SetLegacyManagement(bool) error

SetLegacyManagement is a no-op for the userspace firewall: it only matters when an old management server can't send route firewall rules, which the userspace router doesn't rely on.

func (*Manager) SetLogLevel added in v0.36.6 

func (m *Manager) SetLogLevel(level log.Level)

SetLogLevel sets the log level for the firewall manager

func (*Manager) SetPacketCapture added in v0.70.5 

func (m *Manager) SetPacketCapture(pc forwarder.PacketCapture)

SetPacketCapture sets or clears packet capture on the forwarder endpoint. This captures outbound response packets that bypass the FilteredDevice in netstack mode.

func (*Manager) SetTCPPacketHook added in v0.68.0 

func (m *Manager) SetTCPPacketHook(ip netip.Addr, dPort uint16, hook func(packet []byte) bool)

SetTCPPacketHook sets the outbound TCP packet hook. Pass nil hook to remove.

func (*Manager) SetUDPPacketHook added in v0.68.0 

func (m *Manager) SetUDPPacketHook(ip netip.Addr, dPort uint16, hook func(packet []byte) bool)

SetUDPPacketHook sets the outbound UDP packet hook. Pass nil hook to remove.

func (*Manager) SetupEBPFProxyNoTrack added in v0.64.2 

func (m *Manager) SetupEBPFProxyNoTrack(uint16, uint16) error

SetupEBPFProxyNoTrack is not supported by the userspace firewall: eBPF isn't used in userspace mode, so this should never be called.

func (*Manager) TracePacket added in v0.36.6 

func (m *Manager) TracePacket(packetData []byte, direction fw.RuleDirection) *PacketTrace

func (*Manager) TracePacketFromBuilder added in v0.36.6 

func (m *Manager) TracePacketFromBuilder(builder *PacketBuilder) (*PacketTrace, error)

func (*Manager) UnregisterNetstackService added in v0.59.12 

func (m *Manager) UnregisterNetstackService(protocol nftypes.Protocol, port uint16)

UnregisterNetstackService removes a service from the netstack registry

func (*Manager) UpdateLocalIPs added in v0.36.6 

func (m *Manager) UpdateLocalIPs() error

UpdateLocalIPs updates the list of local IPs

func (*Manager) UpdateSet added in v0.43.0 

func (m *Manager) UpdateSet(set firewall.Set, prefixes []netip.Prefix) error

UpdateSet updates the rule destinations associated with the given set by merging the existing prefixes with the new ones, then deduplicating.

type PacketBuilder added in v0.36.6 

type PacketBuilder struct {
	SrcIP       netip.Addr
	DstIP       netip.Addr
	Protocol    fw.Protocol
	SrcPort     uint16
	DstPort     uint16
	ICMPType    uint8
	ICMPCode    uint8
	Direction   fw.RuleDirection
	PayloadSize int
	TCPState    *TCPState
}

func (*PacketBuilder) Build added in v0.36.6 

func (p *PacketBuilder) Build() ([]byte, error)

type PacketStage added in v0.36.6 

type PacketStage int
const (
	StageReceived PacketStage = iota
	StageInboundPortDNAT
	StageInbound1to1NAT
	StageConntrack
	StagePeerACL
	StageRouting
	StageRouteACL
	StageForwarding
	StageCompleted
	StageOutbound1to1NAT
	StageOutboundPortReverse
)

func (PacketStage) String added in v0.36.6 

func (s PacketStage) String() string

type PacketTrace added in v0.36.6 

type PacketTrace struct {
	SourceIP        netip.Addr
	DestinationIP   netip.Addr
	Protocol        string
	SourcePort      uint16
	DestinationPort uint16
	Direction       fw.RuleDirection
	Results         []TraceResult
}

func (*PacketTrace) AddResult added in v0.36.6 

func (t *PacketTrace) AddResult(stage PacketStage, message string, allowed bool)

func (*PacketTrace) AddResultWithForwarder added in v0.36.6 

func (t *PacketTrace) AddResultWithForwarder(stage PacketStage, message string, allowed bool, action *ForwarderAction)

type PeerRule added in v0.36.6 

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

PeerRule to handle management of rules

func (*PeerRule) ID added in v0.38.0 

func (r *PeerRule) ID() firewall.RuleID

ID returns the rule id

type RouteRule added in v0.36.6 

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

func (*RouteRule) ID added in v0.38.0 

func (r *RouteRule) ID() firewall.RuleID

ID returns the rule id

type TCPState added in v0.36.6 

type TCPState struct {
	SYN bool
	ACK bool
	FIN bool
	RST bool
	PSH bool
	URG bool
}

type TraceResult added in v0.36.6 

type TraceResult struct {
	Timestamp       time.Time
	Stage           PacketStage
	Message         string
	Allowed         bool
	ForwarderAction *ForwarderAction
}

Source Files

View all Source files

Directories

Path Synopsis
Package log provides a high-performance, non-blocking logger for userspace networking
 Package log provides a high-performance, non-blocking logger for userspace networking

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.