xt

Documentation

Overview

Package xt implements dedicated types for (some) of the "Info" payload in Match and Target expressions that bridge between the nftables and xtables worlds.

Bridging between the more unified world of nftables and the slightly heterogenous world of xtables comes with some caveats. Unmarshalling the extension/translation information in Match and Target expressions requires information about the table family the information belongs to, as well as type and type revision information. In consequence, unmarshalling the Match and Target Info field payloads often (but not necessarily always) require the table family and revision information, so it gets passed to the type-specific unmarshallers.

To complicate things more, even marshalling requires knowledge about the enclosing table family. The NatRange/NatRange2 types are an example, where it is necessary to differentiate between IPv4 and IPv6 address marshalling. Due to Go's net.IP habit to normally store IPv4 addresses as IPv4-compatible IPv6 addresses (see also RFC 4291, section 2.5.5.1) marshalling must be handled differently in the context of an IPv6 table compared to an IPv4 table. In an IPv4 table, an IPv4-compatible IPv6 address must be marshalled as a 32bit address, whereas in an IPv6 table the IPv4 address must be marshalled as an 128bit IPv4-compatible IPv6 address. Not relying on heuristics here we avoid behavior unexpected and most probably unknown to our API users. The net.IP habit of storing IPv4 addresses in two different storage formats is already a source for trouble, especially when comparing net.IPs from different Go module sources. We won't add to this confusion. (...or maybe we can, because of it?)

An important property of all types of Info extension/translation payloads is that their marshalling and unmarshalling doesn't follow netlink's TLV (tag-length-value) architecture. Instead, Info payloads a basically plain binary blobs of their respective type-specific data structures, so host platform/architecture alignment and data type sizes apply. The alignedbuff package implements the different required data types alignments.

Please note that Info payloads are always padded at their end to the next uint64 alignment. Kernel code is checking for the padded payload size and will reject payloads not correctly padded at their ends.

Most of the time, we find explifcitly sized (unsigned integer) data types. However, there are notable exceptions where "unsigned int" is used: on 64bit platforms this mostly translates into 32bit(!). This differs from Go mapping uint to uint64 instead. This package currently clamps its mapping of C's "unsigned int" to Go's uint32 for marshalling and unmarshalling. If in the future 128bit platforms with a differently sized C unsigned int should come into production, then the alignedbuff package will need to be adapted accordingly, as it abstracts away this data type handling.

Index

• func Marshal(fam TableFamily, rev uint32, info InfoAny) ([]byte, error)
• type AddrType
• type AddrTypeFlags
• type AddrTypeV1
• type ConntrackFlags
• type ConntrackMtinfo1
• type ConntrackMtinfo2
• type ConntrackMtinfo3
• type ConntrackMtinfoBase
• type InfoAny
  • func Unmarshal(name string, fam TableFamily, rev uint32, data []byte) (InfoAny, error)
• type NatIPv4MultiRangeCompat
• type NatIPv4Range
• type NatRange
• type NatRange2
• type NatRangeFlags
• type TableFamily
• type Tcp
• type TcpInvFlagset
• type Udp
• type UdpInvFlagset
• type Unknown

Functions

func Marshal

func Marshal(fam TableFamily, rev uint32, info InfoAny) ([]byte, error)

Marshal a Match or Target Info type into its binary representation.

Types

type AddrType

type AddrType struct {
	Source       uint16
	Dest         uint16
	InvertSource bool
	InvertDest   bool
}

Rev. 0, see https://elixir.bootlin.com/linux/v5.17.7/source/include/uapi/linux/netfilter/xt_addrtype.h#L38

type AddrTypeFlags

type AddrTypeFlags uint32

const (
	AddrTypeUnspec AddrTypeFlags = 1 << iota
	AddrTypeUnicast
	AddrTypeLocal
	AddrTypeBroadcast
	AddrTypeAnycast
	AddrTypeMulticast
	AddrTypeBlackhole
	AddrTypeUnreachable
	AddrTypeProhibit
	AddrTypeThrow
	AddrTypeNat
	AddrTypeXresolve
)

type AddrTypeV1

type AddrTypeV1 struct {
	Source uint16
	Dest   uint16
	Flags  AddrTypeFlags
}

See https://elixir.bootlin.com/linux/v5.17.7/source/include/uapi/linux/netfilter/xt_addrtype.h#L31

type ConntrackFlags

type ConntrackFlags uint16

const (
	ConntrackState ConntrackFlags = 1 << iota
	ConntrackProto
	ConntrackOrigSrc
	ConntrackOrigDst
	ConntrackReplSrc
	ConntrackReplDst
	ConntrackStatus
	ConntrackExpires
	ConntrackOrigSrcPort
	ConntrackOrigDstPort
	ConntrackReplSrcPort
	ConntrackReplDstPrt
	ConntrackDirection
	ConntrackStateAlias
)

type ConntrackMtinfo1

type ConntrackMtinfo1 struct {
	ConntrackMtinfoBase
	StateMask  uint8
	StatusMask uint8
}

See https://elixir.bootlin.com/linux/v5.17.7/source/include/uapi/linux/netfilter/xt_conntrack.h#L38

type ConntrackMtinfo2

type ConntrackMtinfo2 struct {
	ConntrackMtinfoBase
	StateMask  uint16
	StatusMask uint16
}

See https://elixir.bootlin.com/linux/v5.17.7/source/include/uapi/linux/netfilter/xt_conntrack.h#L51

type ConntrackMtinfo3

type ConntrackMtinfo3 struct {
	ConntrackMtinfo2
	OrigSrcPortHigh uint16
	OrigDstPortHigh uint16
	ReplSrcPortHigh uint16
	ReplDstPortHigh uint16
}

See https://elixir.bootlin.com/linux/v5.17.7/source/include/uapi/linux/netfilter/xt_conntrack.h#L64

type ConntrackMtinfoBase

type ConntrackMtinfoBase struct {
	OrigSrcAddr net.IP
	OrigSrcMask net.IPMask
	OrigDstAddr net.IP
	OrigDstMask net.IPMask
	ReplSrcAddr net.IP
	ReplSrcMask net.IPMask
	ReplDstAddr net.IP
	ReplDstMask net.IPMask
	ExpiresMin  uint32
	ExpiresMax  uint32
	L4Proto     uint16
	OrigSrcPort uint16
	OrigDstPort uint16
	ReplSrcPort uint16
	ReplDstPort uint16
	MatchFlags  uint16
	InvertFlags uint16
}

type InfoAny

type InfoAny interface {
	// contains filtered or unexported methods
}

InfoAny is a (un)marshaling implemented by any info type.

func Unmarshal

func Unmarshal(name string, fam TableFamily, rev uint32, data []byte) (InfoAny, error)

Unmarshal Info binary payload into its corresponding dedicated type as indicated by the name argument. In several cases, unmarshalling depends on the specific table family the Target or Match expression with the info payload belongs to, as well as the specific info structure revision.

type NatIPv4MultiRangeCompat

type NatIPv4MultiRangeCompat []NatIPv4Range

NatIPv4MultiRangeCompat despite being a slice of NAT IPv4 ranges is currently allowed to only hold exactly one element.

See https://elixir.bootlin.com/linux/v5.17.7/source/include/uapi/linux/netfilter/nf_nat.h#L33

type NatIPv4Range

type NatIPv4Range struct {
	Flags   uint // sic!
	MinIP   net.IP
	MaxIP   net.IP
	MinPort uint16
	MaxPort uint16
}

See https://elixir.bootlin.com/linux/v5.17.7/source/include/uapi/linux/netfilter/nf_nat.h#L25

type NatRange

type NatRange struct {
	Flags   uint   // sic! platform/arch/compiler-dependent uint size
	MinIP   net.IP // always taking up space for an IPv6 address
	MaxIP   net.IP // dito
	MinPort uint16
	MaxPort uint16
}

see: https://elixir.bootlin.com/linux/v5.17.7/source/include/uapi/linux/netfilter/nf_nat.h#L38

type NatRange2

type NatRange2 struct {
	NatRange
	BasePort uint16
}

see: https://elixir.bootlin.com/linux/v5.17.7/source/include/uapi/linux/netfilter/nf_nat.h#L46

type NatRangeFlags

type NatRangeFlags uint

const (
	NatRangeMapIPs NatRangeFlags = (1 << iota)
	NatRangeProtoSpecified
	NatRangeProtoRandom
	NatRangePersistent
	NatRangeProtoRandomFully
	NatRangeProtoOffset
	NatRangeNetmap

	NatRangeMask NatRangeFlags = (1 << iota) - 1

	NatRangeProtoRandomAll = NatRangeProtoRandom | NatRangeProtoRandomFully
)

See: https://elixir.bootlin.com/linux/v5.17.7/source/include/uapi/linux/netfilter/nf_nat.h#L8

type TableFamily

type TableFamily byte

TableFamily specifies the address family of the table Match or Target Info data is contained in. On purpose, we don't import the expr package here in order to keep the option open to import this package instead into expr.

type Tcp

type Tcp struct {
	SrcPorts  [2]uint16     // min, max source port range
	DstPorts  [2]uint16     // min, max destination port range
	Option    uint8         // TCP option if non-zero
	FlagsMask uint8         // TCP flags mask
	FlagsCmp  uint8         // TCP flags compare
	InvFlags  TcpInvFlagset // Inverse flags
}

Tcp is the Match.Info payload for the tcp xtables extension (https://wiki.nftables.org/wiki-nftables/index.php/Supported_features_compared_to_xtables#tcp).

See https://elixir.bootlin.com/linux/v5.17.7/source/include/uapi/linux/netfilter/xt_tcpudp.h#L8

type TcpInvFlagset

type TcpInvFlagset uint8

const (
	TcpInvSrcPorts TcpInvFlagset = 1 << iota
	TcpInvDestPorts
	TcpInvFlags
	TcpInvOption
	TcpInvMask TcpInvFlagset = (1 << iota) - 1
)

type Udp

type Udp struct {
	SrcPorts [2]uint16     // min, max source port range
	DstPorts [2]uint16     // min, max destination port range
	InvFlags UdpInvFlagset // Inverse flags
}

Tcp is the Match.Info payload for the tcp xtables extension (https://wiki.nftables.org/wiki-nftables/index.php/Supported_features_compared_to_xtables#tcp).

See https://elixir.bootlin.com/linux/v5.17.7/source/include/uapi/linux/netfilter/xt_tcpudp.h#L25

type UdpInvFlagset

type UdpInvFlagset uint8

const (
	UdpInvSrcPorts UdpInvFlagset = 1 << iota
	UdpInvDestPorts
	UdpInvMask UdpInvFlagset = (1 << iota) - 1
)

type Unknown

type Unknown []byte

Unknown represents the bytes Info payload for unknown Info types where no dedicated match/target info type has (yet) been defined.