package nftables

import "github.com/dotcloud/docker/libnetwork/internal/nftables"

Package nftables provides methods to create an nftables table and manage its maps, sets, chains, and rules.

To use it, the first step is to create a TableRef using NewTable. The table can then be populated and managed using that ref.

Modifications to the table are only applied (sent to "nft") when TableRef.Apply is called. This means a number of updates can be made, for example, adding all the rules needed for a docker network - and those rules will then be applied atomically in a single "nft" run.

TableRef.Apply can only be called after Enable, and only if Enable returns true (meaning an "nft" executable was found). Enabled can be called to check whether nftables has been enabled.

Be aware:

• The implementation is far from complete, only functionality needed so-far has been included. Currently, there's only a limited set of chain/map/set types, there's no way to delete sets/maps etc.
• There's no rollback so, once changes have been made to a TableRef, if the Apply fails there is no way to undo changes. The TableRef will be out-of-sync with the actual state of nftables.
• This is a thin layer between code and "nft", it doesn't do much error checking. So, for example, if you get the syntax of a rule wrong the issue won't be reported until Apply is called.
• Also in the category of no-error-checking, there's no reference checking. If you delete a chain that's still referred to by a map, set or another chain, "nft" will report an error when Apply is called.
• Error checking here is meant to help spot logical errors in the code, like adding a rule twice, which would be fine by "nft" as it'd just create a duplicate rule.
• The existing state of a table in the ruleset is irrelevant, once a Table is created by this package it will be flushed. Putting it another way, this package is write-only, it does not load any state from the host.
• Errors from "nft" are logged along with the line-numbered command that failed, that's the place to look when things go wrong.

Index ¶

• Constants
• func Enable() bool
• func Enabled() bool
• type BaseChainHook
• type BaseChainType
• type ChainRef
• func (c ChainRef) AppendRule(group RuleGroup, rule string, args ...interface{}) error
• func (c ChainRef) DeleteRule(group RuleGroup, rule string, args ...interface{}) error
• func (c ChainRef) SetPolicy(policy string) error
• type ChainUpdateFunc
• type Family
• type RuleGroup
• type SetRef
• func (s SetRef) AddElement(element string) error
• func (s SetRef) DeleteElement(element string) error
• type TableRef
• func NewTable(family Family, name string) (TableRef, error)
• func (t TableRef) Apply(ctx context.Context) error
• func (t TableRef) BaseChain(name string, chainType BaseChainType, hook BaseChainHook, priority int) (ChainRef, error)
• func (t TableRef) Chain(name string) ChainRef
• func (t TableRef) ChainUpdateFunc(name string, enable bool) ChainUpdateFunc
• func (t TableRef) DeleteChain(name string) error
• func (t TableRef) Family() Family
• func (t TableRef) InterfaceVMap(name string) VMapRef
• func (t TableRef) PrefixSet(name string) SetRef
• type VMapRef
• func (v VMapRef) AddElement(key string, verdict string) error
• func (v VMapRef) DeleteElement(key string) error

Constants ¶

const (
	BaseChainPriorityRaw      = -300
	BaseChainPriorityMangle   = -150
	BaseChainPriorityDstNAT   = -100
	BaseChainPriorityFilter   = 0
	BaseChainPrioritySecurity = 50
	BaseChainPrioritySrcNAT   = 100
)

Standard priority values for base chains. (Not for the bridge family, those are different.)

Functions ¶

func Enable ¶

func Enable() bool

Enable checks whether the "nft" tool is available, and returns true if it is. Subsequent calls to Enabled will return the same result.

func Enabled ¶

func Enabled() bool

Enabled returns true if the "nft" tool is available and Enable has been called.

Types ¶

type BaseChainHook ¶

type BaseChainHook string

BaseChainHook enumerates the base chain hook types. See https://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Base_chain_hooks

const (
	BaseChainHookIngress     BaseChainHook = "ingress"
	BaseChainHookPrerouting  BaseChainHook = "prerouting"
	BaseChainHookInput       BaseChainHook = "input"
	BaseChainHookForward     BaseChainHook = "forward"
	BaseChainHookOutput      BaseChainHook = "output"
	BaseChainHookPostrouting BaseChainHook = "postrouting"
)

type BaseChainType ¶

type BaseChainType string

BaseChainType enumerates the base chain types. See https://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Base_chain_types

const (
	BaseChainTypeFilter BaseChainType = "filter"
	BaseChainTypeRoute  BaseChainType = "route"
	BaseChainTypeNAT    BaseChainType = "nat"
)

type ChainRef ¶

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

ChainRef is a handle for an nftables chain.

func (ChainRef) AppendRule ¶

func (c ChainRef) AppendRule(group RuleGroup, rule string, args ...interface{}) error

AppendRule appends a rule to a RuleGroup in a ChainRef.

func (ChainRef) DeleteRule ¶

func (c ChainRef) DeleteRule(group RuleGroup, rule string, args ...interface{}) error

DeleteRule deletes a rule from a RuleGroup in a ChainRef. It is an error to delete from a group that does not exist, or to delete a rule that does not exist.

func (ChainRef) SetPolicy ¶

func (c ChainRef) SetPolicy(policy string) error

SetPolicy sets the default policy for a base chain. It is an error to call this for a non-base ChainRef.

type ChainUpdateFunc ¶

type ChainUpdateFunc func(RuleGroup, string, ...interface{}) error

ChainUpdateFunc is a function that can add rules to a chain, or remove rules from it.

type Family ¶

type Family string

Family enumerates address families.

const (
	IPv4 Family = "ip"
	IPv6 Family = "ip6"
)

type RuleGroup ¶

type RuleGroup int

RuleGroup is used to allocate rules within a chain to a group. These groups are purely an internal construct, nftables knows nothing about them. Within groups rules retain the order in which they were added, and groups are ordered from lowest to highest numbered group.

type SetRef ¶

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

SetRef is a handle for an nftables named set.

func (SetRef) AddElement ¶

func (s SetRef) AddElement(element string) error

AddElement adds an element to a set. It is the caller's responsibility to make sure the element has the correct type. It is an error to add an element that is already in the set.

func (SetRef) DeleteElement ¶

func (s SetRef) DeleteElement(element string) error

DeleteElement deletes an element from the set. It is an error to delete an element that is not in the set.

type TableRef ¶

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

TableRef is a handle for an nftables table.

func NewTable ¶

func NewTable(family Family, name string) (TableRef, error)

NewTable creates a new nftables table and returns a TableRef

See https://wiki.nftables.org/wiki-nftables/index.php/Configuring_tables

The table will be created and flushed when TableRef.Apply is next called. It's flushed in case it already exists in the host's nftables - when that happens, rules in its chains will be deleted but not the chains themselves, maps, sets, or elements of maps or sets. But, those un-flushed items can't do anything disruptive unless referred to by rules, and they will be flushed if they get re-created via the TableRef, when TableRef.Apply is next called (so, before they can be used by a new rule).

func (TableRef) Apply ¶

func (t TableRef) Apply(ctx context.Context) error

Apply makes incremental updates to nftables, corresponding to changes to the TableRef since Apply was last called.

func (TableRef) BaseChain ¶

func (t TableRef) BaseChain(name string, chainType BaseChainType, hook BaseChainHook, priority int) (ChainRef, error)

BaseChain constructs a new nftables base chain and returns a ChainRef.

See https://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Adding_base_chains

It is an error to create a base chain that already exists. If the underlying chain already exists, it will be flushed by the next TableRef.Apply before new rules are added.

func (TableRef) Chain ¶

func (t TableRef) Chain(name string) ChainRef

Chain returns a ChainRef for an existing chain (which may be a base chain). If there is no existing chain, a regular chain is added and its ChainRef is returned.

See https://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Adding_regular_chains

If a new ChainRef is created and the underlying chain already exists, it will be flushed by the next TableRef.Apply before new rules are added.

func (TableRef) ChainUpdateFunc ¶

func (t TableRef) ChainUpdateFunc(name string, enable bool) ChainUpdateFunc

ChainUpdateFunc returns a ChainUpdateFunc to add rules to the named chain if enable is true, or to remove rules from the chain if enable is false. (Written as a convenience function to ease migration of iptables functions originally written with an enable flag.)

func (TableRef) DeleteChain ¶

func (t TableRef) DeleteChain(name string) error

DeleteChain deletes a chain. It is an error to delete a chain that does not exist.

func (TableRef) Family ¶

func (t TableRef) Family() Family

Family returns the address family of the nftables table described by TableRef.

func (TableRef) InterfaceVMap ¶

func (t TableRef) InterfaceVMap(name string) VMapRef

InterfaceVMap creates a map from interface name to a verdict and returns a VMapRef, or returns an existing VMapRef if it has already been created.

See https://wiki.nftables.org/wiki-nftables/index.php/Verdict_Maps_(vmaps)

If a VMapRef is created and the underlying map already exists, it will be flushed by the next TableRef.Apply before new elements are added.

func (TableRef) PrefixSet ¶

func (t TableRef) PrefixSet(name string) SetRef

PrefixSet creates a new named nftables set for IPv4 or IPv6 addresses (depending on the address family of the TableRef), and returns its SetRef. Or, if the set has already been created, its SetRef is returned.

(TableRef does not support "inet", only "ip" or "ip6". So the element type can always be determined. But, there's no "inet" element type, so this will need to change if we need an "inet" table.)

See https://wiki.nftables.org/wiki-nftables/index.php/Sets#Named_sets

type VMapRef ¶

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

VMapRef is a handle for an nftables verdict map.

func (VMapRef) AddElement ¶

func (v VMapRef) AddElement(key string, verdict string) error

AddElement adds an element to a verdict map. The caller must ensure the key has the correct type. It is an error to add a key that already exists.

func (VMapRef) DeleteElement ¶

func (v VMapRef) DeleteElement(key string) error

DeleteElement deletes an element from a verdict map. It is an error to delete an element that does not exist.

Source Files ¶

nftables_linux.go