nftables
packageThis package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version
Modules with tagged versions give importers more predictable builds.
Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Documentation¶
Overview¶
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 aTable usingNewTable. Then, retrieveaModifier, add commands to it, and apply the updates.
For example:
t, _ := NewTable(...)tm := t.Modifier()// Then a sequence of ...tm.Create(<object>)tm.Delete(<object>)// Apply the updates with ...err := tm.Apply(ctx)
The objects are any of:BaseChain,Chain,Rule,VMap,VMapElement,Set,SetElement
The modifier can be reused to apply the same set of commands again or, moreusefully, reversed in order to revert its changes. SeeModifier.Reverse.
[Modifier.Apply] can only be called afterEnable, and only ifEnable returnstrue (meaning an "nft" executable was found).Enabled can be called to checkwhether nftables has been enabled.
Be aware:
- The implementation is far from complete, only functionality needed so-far hasbeen included. Currently, there's only a limited set of chain/map/set types,there's no way to delete sets/maps etc.
- 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 reporteduntil Apply is called.
- Also in the category of no-error-checking, there's no reference checking. If youdelete a chain that's still referred to by a map, set or another chain, "nft" willreport an error when Apply is called.
- Error checking here is meant to help spot logical errors in the code, like addinga 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 createdby this package it will be flushed. Putting it another way, this package iswrite-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 Disable()
- func Enable() error
- func Enabled() bool
- type BaseChain
- type BaseChainHook
- type BaseChainPolicy
- type BaseChainType
- type Chain
- type Family
- type Modifier
- type NftType
- type Obj
- type Rule
- type RuleGroup
- type Set
- type SetElement
- type Table
- func (t *Table) Apply(ctx context.Context, tm Modifier) (retErr error)
- func (t Table) Close() error
- func (t Table) Family() Family
- func (t Table) IsValid() bool
- func (t Table) Name() string
- func (t Table) Reload(ctx context.Context) error
- func (t Table) SetBaseChainPolicy(ctx context.Context, chainName string, policy BaseChainPolicy) error
- type VMap
- type VMapElement
Constants¶
const (BaseChainPriorityRaw = -300BaseChainPriorityMangle = -150BaseChainPriorityDstNAT = -100BaseChainPriorityFilter = 0BaseChainPrioritySecurity = 50BaseChainPrioritySrcNAT = 100)
Standard priority values for base chains.(Not for the bridge family, those are different.)
Variables¶
This section is empty.
Functions¶
Types¶
typeBaseChain¶
type BaseChain struct {NamestringChainTypeBaseChainTypeHookBaseChainHookPriorityintPolicyBaseChainPolicy// Defaults to BaseChainPolicyAccept}BaseChain constructs a new nftables base chain and returns a [ChainRef].
Seehttps://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 thenextTable.Apply before new rules are added.
typeBaseChainHook¶
type BaseChainHookstring
BaseChainHook enumerates the base chain hook types.Seehttps://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Base_chain_hooks
const (BaseChainHookIngressBaseChainHook = "ingress"BaseChainHookPreroutingBaseChainHook = "prerouting"BaseChainHookInputBaseChainHook = "input"BaseChainHookForwardBaseChainHook = "forward"BaseChainHookOutputBaseChainHook = "output"BaseChainHookPostroutingBaseChainHook = "postrouting")
typeBaseChainPolicy¶
type BaseChainPolicystring
BaseChainPolicy enumerates base chain policies.Seehttps://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Base_chain_policy
const (BaseChainPolicyAcceptBaseChainPolicy = "accept"BaseChainPolicyDropBaseChainPolicy = "drop")
typeBaseChainType¶
type BaseChainTypestring
BaseChainType enumerates the base chain types.Seehttps://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Base_chain_types
const (BaseChainTypeFilterBaseChainType = "filter"BaseChainTypeRouteBaseChainType = "route"BaseChainTypeNATBaseChainType = "nat")
typeChain¶
type Chain struct {Namestring}Chain implements theObj interface, it can be passed to aModifier to create or delete a chain.
typeModifier¶
type Modifier struct {// contains filtered or unexported fields}Modifier is used to apply changes to a Table.
func (*Modifier)Reverse¶
Reverse returns a Modifier that will undo the actions of tm.Its operations are performed in reverse order, creates becomedeletes, and deletes become creates.
Most operations are fully reversible (chains/maps/sets must beempty before they're deleted, so no information is lost). But,there are exceptions, noted in comments in the object definitions.
Applying the updates in a reversed modifier may not work ifany of the objects have been removed or modified since theywere added. For example, if a Modifier creates a chain then anotherModifier adds rules, the reversed Modifier will not be able todelete the chain as it is not empty.
typeNftType¶
type NftTypestring
NftType enumerates nft types that can be used to define maps/sets etc.
typeObj¶
type Obj interface {// contains filtered or unexported methods}Obj is an object that can be given to aModifier, representing annftables object for it to create or delete.
typeRule¶
type Rule struct {ChainstringGroupRuleGroupRule []string// IgnoreExist suppresses errors about deleting a rule that does not exist// or creating a rule that does already exist.//// Note that, when set, reversing the [Modifier] may not do what you want! For// example, if the original modifier deleted a rule that did not exist, the// reversed modifier will create that rule.IgnoreExistbool}Rule implements theObj interface, it can be passed to aModifier to create or delete a rule in a chain.
typeRuleGroup¶
type RuleGroupint
RuleGroup is used to allocate rules within a chain to a group. These groups arepurely an internal construct, nftables knows nothing about them. Within groupsrules retain the order in which they were added, and groups are ordered fromlowest to highest numbered group.
typeSetElement¶
SetElement implements theObj interface, it can be passed to aModifier to create or delete an entry in a set.
typeTable¶
type Table struct {// contains filtered or unexported fields}Table is a handle for an nftables table.
funcNewTable¶
NewTable creates a new nftables table and returns aTable
Seehttps://wiki.nftables.org/wiki-nftables/index.php/Configuring_tables
To modify the table, instantiate aModifier, add commands to it, and callTable.Apply.
It's flushed in case it already exists in the host's nftables - when thathappens, 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 doanything disruptive unless referred to by rules, and they will be flushed ifthey get re-created via theTable, whenTable.Apply is next called(so, before they can be used by a new rule).
To fully delete an underlying nftables table, if one already exists,useTable.Reload after creating the table.
func (*Table)Apply¶
Apply makes incremental updates to nftables. If there's a validationerror in any of the enqueued objects, or an error applying the updatesto the underlying nftables, theTable will be unmodified.
func (Table)Close¶
Close releases resources associated with the table. It does not modify or deletethe underlying nftables table.
func (Table)SetBaseChainPolicy¶
SetBaseChainPolicy sets the default policy for a base chain. The updateis applied immediately, unlike creation/deletion of objects via aModifierwhich are not applied until [Modifier.Apply] is called.