Linx.Netfilter.Set (Linx v0.1.0)

Copy Markdown View Source

An nftables set — a named collection of elements with a uniform key type, used for O(1) lookups in rules.

Sets are the kernel's high-performance match primitive: a rule saying "if source IP is in @blocklist drop" hashes once into the set rather than scanning a hundred individual rules. Concatenations, dynamic sets, and intervals are not yet implemented (see docs/netfilter/DESIGN.md).

Fields

  • :name — set name (unique within the table).
  • :table — owning table's name; nil for free-standing sets.
  • :key_type — element-type atom. The basic atomic types are accepted: :ipv4_addr, :ipv6_addr, :ether_addr, :inet_proto, :inet_service, :mark, :ifname. Concatenations ({:concat, [type1, type2, ...]}) are not yet implemented.
  • :flags — list. Currently accepted: :constant, :interval, :timeout, :dynamic, :auto_merge, :anonymous. The timeout / dynamic / interval flags are not yet fully implemented; the value-type slot is here today.
  • :elements — list of element values matching :key_type. Element-type validation is a basic check; strict validation is not yet implemented.
  • :timeout — default element lifetime in ms; nil for no timeout (default).
  • :gc_interval — kernel's gc cadence in ms; nil to let the kernel choose.
  • :size — maximum element count; nil for unbounded.
  • :handle — kernel-assigned handle; nil until pushed.
  • :comment — round-trips via set userdata.

Construction

iex> Set.new("blocklist", key_type: :ipv4_addr)
{:ok, %Linx.Netfilter.Set{name: "blocklist", key_type: :ipv4_addr, ...}}

iex> Set.new("ssh_clients", key_type: :ipv4_addr,
...>          flags: [:timeout], timeout: 60_000)
{:ok, %Linx.Netfilter.Set{...}}

Errors come back as {:error, {:bad_set, reason}}. Element-shape errors as {:error, {:bad_set_element, reason}}.

References

Summary

Types

flag()
key_type()
t()

Functions

add_elements(set, new_elements)

Adds elements to a set, validating each against the set's :key_type. Returns the updated set or {:error, {:bad_set_element, reason}}.

delete_elements(set, to_remove)

Removes elements from a set. No validation — removes whichever elements match by equality.

new(name, opts)

Builds a set.

new!(name, opts)

Bang variant of new/2.

Types

flag()

@type flag() :: :constant | :interval | :timeout | :dynamic | :auto_merge | :anonymous

key_type()

@type key_type() ::
  :ipv4_addr
  | :ipv6_addr
  | :ether_addr
  | :inet_proto
  | :inet_service
  | :mark
  | :ifname

t()

@type t() :: %Linx.Netfilter.Set{
  comment: String.t() | nil,
  elements: [term()],
  flags: [flag()],
  gc_interval: pos_integer() | nil,
  handle: pos_integer() | nil,
  key_type: key_type(),
  name: String.t(),
  size: pos_integer() | nil,
  table: String.t() | nil,
  timeout: pos_integer() | nil
}

Functions

add_elements(set, new_elements)

@spec add_elements(t(), [term()]) :: {:ok, t()} | {:error, {:bad_set_element, term()}}

Adds elements to a set, validating each against the set's :key_type. Returns the updated set or {:error, {:bad_set_element, reason}}.

delete_elements(set, to_remove)

@spec delete_elements(t(), [term()]) :: {:ok, t()}

Removes elements from a set. No validation — removes whichever elements match by equality.

new(name, opts)

@spec new(
  String.t(),
  keyword()
) :: {:ok, t()} | {:error, {:bad_set, term()}}

Builds a set.

new!(name, opts)

@spec new!(
  String.t(),
  keyword()
) :: t()

Bang variant of new/2.