Elixir interface to Linux nftables via libnftables JSON API.

NFTables provides a high-level, idiomatic Elixir API for managing nftables rules, using the official libnftables library with JSON for all communication.

Quick Start

Start the NFTables port process and build firewall rules:

# Start the port process
{:ok, pid} = NFTables.Port.start_link()

# Create a simple firewall
import NFTables.Expr

NFTables.add(table: "filter", family: :inet)
|> NFTables.add(chain: "INPUT", type: :filter, hook: :input, priority: 0, policy: :drop)
|> NFTables.add(rule: state([:established, :related]) |> accept())
|> NFTables.add(rule: tcp() |> dport(22) |> accept())
|> NFTables.submit(pid: pid)

# Clean up when done
NFTables.Port.stop(pid)

Import Options

You have two ways to import expression building functions:

Option 1: Use Macro (Import Everything)

The simplest approach - automatically imports all expression modules:

use NFTables

This imports NFTables.Expr and all sub-modules, giving you access to all expression building functions. Best for interactive use or when you need many different types of expressions.

Option 2: Selective Imports (Import What You Need)

For production code, you may prefer explicit imports:

import NFTables.Expr
import NFTables.Expr.{Port, TCP, Verdict}

This gives you fine-grained control and makes dependencies explicit. Best for production code where you want to minimize namespace pollution.

Both approaches are equally valid - choose based on your preferences and use case.

Main API Functions

Building Rules

• add/1-2 - Add tables, chains, rules, sets, etc.
• delete/1-2 - Delete objects
• flush/1-2 - Flush objects (remove contents)
• flush_ruleset/0-2 - Flush entire ruleset
• insert/1-2 - Insert rules at specific positions
• replace/1-2 - Replace rules at specific handles
• rename/1-2 - Rename chains

Submitting Changes

• submit/1-2 - Submit configuration to nftables

Helper Functions

• to_json/1 - Convert to JSON string
• to_map/1 - Convert to Elixir map
• set_family/2 - Set address family

Module Organization

Core APIs

• NFTables - Main public API (this module)
• NFTables.Expr - Fluent API for building rule expressions
• NFTables.Query - Query tables, chains, rules, and sets

Convenience APIs

• NFTables.Policy - Pre-built security policies (accept_established, allow_ssh, etc.)
• NFTables.NAT - NAT operations (port forwarding, masquerading, etc.)

Execution & Port Management

• NFTables.Port - Port process management (start_link, stop)
• NFTables.Local - Local execution requestor

Internal APIs

• NFTables.Builder - Internal builder implementation (use NFTables API instead)
• NFTables.Decoder - Decode nftables responses
• NFTables.Requestor - Behaviour for custom submission handlers

Pipeline Pattern

All functions return a builder struct that can be piped:

NFTables.add(table: "filter")
|> NFTables.add(chain: "INPUT", type: :filter, hook: :input)
|> NFTables.add(rule: tcp() |> dport(80) |> accept())
|> NFTables.add(rule: tcp() |> dport(443) |> accept())
|> NFTables.submit(pid: pid)

Context Tracking

The builder automatically tracks context (table, chain) so you don't need to repeat it:

NFTables.add(table: "filter", chain: "INPUT", type: :filter, hook: :input)
|> NFTables.add(rule: tcp() |> dport(22) |> accept())
|> NFTables.add(rule: tcp() |> dport(80) |> accept())
# Both rules automatically use filter/INPUT

Examples

Basic Firewall

import NFTables.Expr

NFTables.add(table: "filter")
|> NFTables.add(chain: "INPUT", type: :filter, hook: :input, policy: :drop)
|> NFTables.add(chain: "FORWARD", type: :filter, hook: :forward, policy: :drop)
|> NFTables.add(chain: "OUTPUT", type: :filter, hook: :output, policy: :accept)
|> NFTables.add(rule: iif("lo") |> accept())
|> NFTables.add(rule: state([:established, :related]) |> accept())
|> NFTables.add(rule: tcp() |> dport(22) |> accept())
|> NFTables.submit(pid: pid)

IP Blocking with Sets

NFTables.add(table: "filter")
|> NFTables.add(set: "blocklist", type: :ipv4_addr)
|> NFTables.add(element: ["1.2.3.4", "5.6.7.8"], set: "blocklist")
|> NFTables.add(chain: "INPUT", type: :filter, hook: :input)
|> NFTables.add(rule: ip_saddr() |> set_lookup("@blocklist") |> drop())
|> NFTables.submit(pid: pid)

NAT / Port Forwarding

NFTables.add(table: "nat", family: :ip)
|> NFTables.add(chain: "PREROUTING", type: :nat, hook: :prerouting)
|> NFTables.add(rule: tcp() |> dport(8080) |> dnat("192.168.1.100:80"))
|> NFTables.submit(pid: pid)

JSON API

The underlying JSON format follows the official nftables JSON schema. See: https://wiki.nftables.org/wiki-nftables/index.php/JSON_API

For advanced use cases requiring direct builder access, see NFTables.Builder documentation.