NAME

Langertha::Holmgang::Sim::Linux::Nft - Evaluates the nftables ruleset of a simulated Linux device against a packet

VERSION

version 0.001

SYNOPSIS

use Langertha::Holmgang::Sim::Linux::Nft ();

my ( $verdict, $why ) = Langertha::Holmgang::Sim::Linux::Nft::verdict( $dev, {
    hook => 'input', iif => 'eth0', saddr => '203.0.113.7', daddr => '198.51.100.2',
    proto => 'tcp', dport => 22,                     # ct: new (default)
} );
# ( 'accept' | 'drop', 'inet filter input: tcp dport 22 drop' )
# ( undef, 'nicht auswertbar: …' ) when a rule on the way is not understood

my $err = Langertha::Holmgang::Sim::Linux::Nft::parse_error('ip saddr @admins tcp dport ssh accept');   # undef = understood

DESCRIPTION

Evaluates an nftables ruleset (nft in the state of a device of type linux, see Langertha::Holmgang::Sim::Linux) by its behaviour: what happens to a given packet? So every technically correct way of writing a rule counts (port as number or service name, set or single rules, named set, vmap, own chain with jump), and a rule in the wrong place stands out even when its text is right.

Path of the packet: all base chains with the packet's hook and type filter in tables of a matching family (inet for IPv4 and IPv6, ip IPv4 only, ip6 IPv6 only), ordered by priority (number or raw, mangle, dstnat, filter, security, srcnat, also filter - 5). accept ends only the chain — the next base chain keeps checking; drop/reject end everything. At the end of a base chain its policy applies; jump returns, goto does not, return returns to the calling chain.

Packet: hook, iif, oif, saddr, daddr (IPv4 or IPv6 — the family follows from the address), proto (tcp, udp, icmp, icmpv6), sport, dport, icmp_type (default echo-request), icmp_code, ct (default new), ct_status (e.g. dnat for a forwarded connection; several separated by commas).

Understood expressions: iifname/oifname/iif/oif (also with meta, wildcard *), ip/ip6 saddr|daddr (address, prefix, range a-b, set { … }, named set @name), ip protocol, ip6 nexthdr, meta l4proto, meta nfproto, tcp/udp/th dport|sport (number, service name, range, set, named set), ct state (also a,b), ct status, icmp type|code, icmpv6 type|code, comparison with !=, vmap after each of these expressions; without effect on the verdict: counter, log …, tcp option maxseg size set …, limit rate … (matches; over never matches), comment "…". Verdicts: accept, drop, reject [with …], jump, goto, return, continue. Everything else is not evaluable: the verdict is then undef with a reason, and the Linux simulator records a gap in the simulation when such a rule is added (cai-platform docs/entwurf-evals.md §3.3.2).

Named sets live per table in the state:

nft:
  inet filter:
    sets: { admins: { type: ipv4_addr, flags: [interval], elements: [ 10.1.0.7, 10.1.0.32/28 ] } }
    chains: { … }

parse

my ( $rule, $err ) = parse($rule_text);
# { matches => [ { field, neg, val } | { field, vmap } ], verdict => { accept => 1 } | undef }

Splits a rule into expressions and verdict; if it cannot be evaluated, $rule is undef and $err names the reason.

parse_error

my $err = parse_error($rule_text);   # undef: evaluable

The reason a rule cannot be evaluated, otherwise undef.

syntax_error

my $err = syntax_error($rule_text);   # undef: nft syntax (even if not evaluable)

Error text as from nft when a rule starts with a word that does not exist in nft at that position (e.g. a number without position), or has a value nft does not know (ICMP type like neighbor-solicit instead of nd-neighbor-solicit, service name, address, ct state); otherwise undef. Real expressions that are merely not modelled (fib, meta mark …) are not a syntax error but a gap in the simulation.

verdict

my ( $verdict, $why ) = verdict( $dev, \%packet );

accept or drop and the place that decided (table, chain, rule text or policy). If a rule on the way cannot be evaluated, the verdict is undef and $why names it.

boot_verdict

my ( $verdict, $why ) = boot_verdict( $dev, \%packet, '/etc/nftables.conf' );

Like "verdict", but for the ruleset after a reboot: empty ruleset, then the file loaded like nft -f (service nftables at boot). If the file does not load, the verdict is undef and $why names the error.

SUPPORT

Issues

Please report bugs and feature requests at https://github.com/Getty/langertha-holmgang/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.