netset

README

netset

netset is a small Go package for managing Linux ipset sets and nftables sets through netlink, without external dependencies.

The public API follows the shape of github.com/nadoo/ipset for existing ipset users, and adds an NFTSet client for nftables.

ipset

package main

import "github.com/nadoo/netset"

func main() {
	if err := netset.Init(); err != nil {
		panic(err)
	}

	_ = netset.Destroy("myset")
	if err := netset.Create("myset"); err != nil {
		panic(err)
	}
	_ = netset.Add("myset", "1.1.1.1")
	_ = netset.Add("myset", "2.2.2.0/24")
}

nftables set

The nftables table must already exist. Use OptInterval() when the set will store CIDR prefixes, and use OptIPv6() when creating a set for IPv6 keys. The address version and interval mode are fixed after creation. A timeout must also be enabled when the set is created before per-element timeout overrides can be used.

package main

import "github.com/nadoo/netset"

func main() {
	s, err := netset.NewNFTSet("filter", "myset", netset.OptFamily(netset.FamilyINet), netset.OptInterval())
	if err != nil {
		panic(err)
	}
	defer s.Close()

	_ = s.Destroy()
	if err := s.Create(); err != nil {
		panic(err)
	}
	_ = s.Add("1.1.1.1")
	_ = s.Add("2.2.2.0/24")
}

On non-Linux platforms the constructors return an unsupported-platform error.

Documentation

Index

• Variables
• func Add(setName, entry string, opts ...Option) error
• func Create(setName string, opts ...Option) error
• func Del(setName, entry string) error
• func Destroy(setName string) error
• func Flush(setName string) error
• func Init() error
• type Family
• type IPSet
  • func NewIPSet() (*IPSet, error)
  • func (s *IPSet) Add(setName, entry string, opts ...Option) error
  • func (s *IPSet) AddAddr(setName string, ip netip.Addr, opts ...Option) error
  • func (s *IPSet) AddPrefix(setName string, prefix netip.Prefix, opts ...Option) error
  • func (s *IPSet) Close() error
  • func (s *IPSet) Create(setName string, opts ...Option) error
  • func (s *IPSet) Del(setName, entry string) error
  • func (s *IPSet) DelAddr(setName string, ip netip.Addr) error
  • func (s *IPSet) DelPrefix(setName string, prefix netip.Prefix) error
  • func (s *IPSet) Destroy(setName string) error
  • func (s *IPSet) Flush(setName string) error
• type NFTSet
  • func NewNFTSet(table, setName string, opts ...Option) (*NFTSet, error)
  • func (s *NFTSet) Add(entry string, opts ...Option) error
  • func (s *NFTSet) AddAddr(ip netip.Addr, opts ...Option) error
  • func (s *NFTSet) AddPrefix(prefix netip.Prefix, opts ...Option) error
  • func (s *NFTSet) Close() error
  • func (s *NFTSet) Create(opts ...Option) error
  • func (s *NFTSet) Del(entry string) error
  • func (s *NFTSet) DelAddr(ip netip.Addr) error
  • func (s *NFTSet) DelPrefix(prefix netip.Prefix) error
  • func (s *NFTSet) Destroy() error
  • func (s *NFTSet) Flush() error
• type Option
  • func OptExcl() Option
  • func OptFamily(f Family) Option
  • func OptIPv6() Option
  • func OptInterval() Option
  • func OptTimeout(timeout uint32) Option
• type Options

Variables

var (
	// ErrUnsupported is returned on platforms without netfilter netlink support.
	ErrUnsupported = netlink.ErrUnsupported

	// ErrNotInitialized is returned by package-level ipset helpers before Init.
	ErrNotInitialized = errors.New("netset: ipset client is not initialized")
)

Functions

func Add

func Add(setName, entry string, opts ...Option) error

Add adds an address or CIDR prefix to an ipset.

func Create

func Create(setName string, opts ...Option) error

Create creates a hash:net ipset.

func Del

func Del(setName, entry string) error

Del deletes an address or CIDR prefix from an ipset.

func Destroy

func Destroy(setName string) error

Destroy destroys an ipset.

func Flush

func Flush(setName string) error

Flush flushes an ipset.

func Init

func Init() error

Init prepares the package-level ipset client.

Types

type Family

type Family uint8

Family is an nftables netfilter family.

const (
	FamilyUnspec Family = 0
	FamilyINet   Family = 1
	FamilyIPv4   Family = 2
	FamilyARP    Family = 3
	FamilyNetdev Family = 5
	FamilyBridge Family = 7
	FamilyIPv6   Family = 10
)

type IPSet

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

IPSet manages kernel ipset sets through netlink.

func NewIPSet

func NewIPSet() (*IPSet, error)

NewIPSet opens a netlink socket for ipset operations.

func (*IPSet) Add

func (s *IPSet) Add(setName, entry string, opts ...Option) error

func (*IPSet) AddAddr

func (s *IPSet) AddAddr(setName string, ip netip.Addr, opts ...Option) error

AddAddr adds an address to an ipset.

func (*IPSet) AddPrefix

func (s *IPSet) AddPrefix(setName string, prefix netip.Prefix, opts ...Option) error

AddPrefix adds a CIDR prefix to an ipset.

func (*IPSet) Close

func (s *IPSet) Close() error

Close closes the underlying netlink socket.

func (*IPSet) Create

func (s *IPSet) Create(setName string, opts ...Option) error

func (*IPSet) Del

func (s *IPSet) Del(setName, entry string) error

func (*IPSet) DelAddr

func (s *IPSet) DelAddr(setName string, ip netip.Addr) error

DelAddr deletes an address from an ipset.

func (*IPSet) DelPrefix

func (s *IPSet) DelPrefix(setName string, prefix netip.Prefix) error

DelPrefix deletes a CIDR prefix from an ipset.

func (*IPSet) Destroy

func (s *IPSet) Destroy(setName string) error

func (*IPSet) Flush

func (s *IPSet) Flush(setName string) error

type NFTSet

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

NFTSet manages one nftables set in a table.

func NewNFTSet

func NewNFTSet(table, setName string, opts ...Option) (*NFTSet, error)

NewNFTSet opens a netlink socket for an nftables set.

func (*NFTSet) Add

func (s *NFTSet) Add(entry string, opts ...Option) error

Add adds an address or CIDR prefix to the nftables set.

func (*NFTSet) AddAddr

func (s *NFTSet) AddAddr(ip netip.Addr, opts ...Option) error

AddAddr adds an address to the nftables set.

func (*NFTSet) AddPrefix

func (s *NFTSet) AddPrefix(prefix netip.Prefix, opts ...Option) error

AddPrefix adds a CIDR prefix to an interval nftables set.

func (*NFTSet) Close

func (s *NFTSet) Close() error

Close closes the underlying netlink socket.

func (*NFTSet) Create

func (s *NFTSet) Create(opts ...Option) error

Create creates the nftables set. The table must already exist.

func (*NFTSet) Del

func (s *NFTSet) Del(entry string) error

Del deletes an address or CIDR prefix from the nftables set.

func (*NFTSet) DelAddr

func (s *NFTSet) DelAddr(ip netip.Addr) error

DelAddr deletes an address from the nftables set.

func (*NFTSet) DelPrefix

func (s *NFTSet) DelPrefix(prefix netip.Prefix) error

DelPrefix deletes a CIDR prefix from an interval nftables set.

func (*NFTSet) Destroy

func (s *NFTSet) Destroy() error

Destroy destroys the nftables set.

func (*NFTSet) Flush

func (s *NFTSet) Flush() error

Flush deletes all elements from the nftables set.

type Option

type Option func(*Options)

Option configures ipset and nftables set operations.

func OptExcl

func OptExcl() Option

OptExcl asks the kernel to fail if an added element already exists.

func OptFamily

func OptFamily(f Family) Option

OptFamily selects the nftables address family.

func OptIPv6

func OptIPv6() Option

OptIPv6 selects IPv6 entries and set key length.

func OptInterval

func OptInterval() Option

OptInterval creates an nftables interval set and allows CIDR/range elements.

func OptTimeout

func OptTimeout(timeout uint32) Option

OptTimeout sets timeout in seconds where the backend supports it.

type Options

type Options struct {
	IPv6     bool
	Timeout  uint32
	Excl     bool
	Family   Family
	Interval bool
}

Options contains the common operation options supported by netset.