libnftables-dotnet

libnftables-dotnet is a typed-first .NET wrapper over system-installed libnftables, with a high-level object model for common workflows and low-level SWIG-generated bindings for advanced control.

Current Scope

This library is intentionally narrow.

• High-level managed API:
  • typed NftRuleset / NftTable / NftSet / NftMap / NftChain / NftRule authoring
  • RenderRuleset
  • ValidateRuleset
  • ApplyRuleset
  • Snapshot
  • Restore
• Low-level managed wrapper:
  • NftContext for direct control over flags, buffering, include paths, variables, and command execution

Non-goals for the current release:

• Full nft expression parity and snapshot parsing back into object models
• Event monitoring or subscriptions
• Cross-platform support beyond Linux x64

Runtime Support

Native operations currently support:

• Linux only
• x64 only
• System-installed libnftables

The package includes the generated Linux x64 native wrapper, but it still depends on the host system providing libnftables.

Requirements

• Linux
• libnftables headers and shared library installed
• gcc
• .NET SDK 10+
• swig only if you regenerate bindings

On Debian/Ubuntu-like systems, the runtime dependency is typically installed from the system package repository. Exact package names can vary by distro.

Build

dotnet build

dotnet build compiles the native SWIG wrapper (libLibNftablesBindings.so) from the checked-in generated C wrapper code.

Test

dotnet test LibNftables.slnx

The test suite contains:

• Managed/unit tests that do not require a native runtime
• Native integration tests that self-gate when libnftables is unavailable
• Capability-dependent tests that only run when CAP_NET_ADMIN is available

High-Level Example

using LibNftables;

INftablesClient client = new NftablesClient();

var ruleset = new NftRuleset();
var table = new NftTable
{
    Family = NftFamily.Inet,
    Name = "filter",
};
var blocked = new NftSet
{
    Name = "blocked_ipv4",
    Type = NftSetType.Ipv4Address,
};
blocked.Elements.Add(NftValue.Address(System.Net.IPAddress.Parse("10.0.0.1")));
blocked.Elements.Add(NftValue.Address(System.Net.IPAddress.Parse("10.0.0.2")));
table.Sets.Add(blocked);

var chain = new NftChain
{
    Name = "input",
    Type = NftChainType.Filter,
    Hook = NftHook.Input,
    Priority = 0,
    Policy = NftChainPolicy.Drop,
};
chain.Rules.Add(new NftRule
{
    InputInterface = NftValue.Interface("eth0"),
    SourceAddressSetName = "blocked_ipv4",
    TransportProtocol = NftTransportProtocol.Tcp,
    DestinationPort = NftValue.Port(22),
    Verdict = NftVerdict.Accept,
});
table.Chains.Add(chain);

ruleset.Tables.Add(table);

string preview = client.RenderRuleset(ruleset);
var validation = client.ValidateRuleset(ruleset);
if (validation.IsValid)
{
    client.ApplyRuleset(ruleset);
}

Raw command text remains available through NftApplyRequest as a fallback for nft syntax not yet modeled by the typed API.

Low-Level Example

using LibNftables;

using var context = new NftContext();
context.DryRun = true;
context.BufferOutput();
context.BufferError();

context.RunCommand("add table inet demo");

string? output = context.GetOutputBuffer();
string? error = context.GetErrorBuffer();

Troubleshooting

NftNativeLoadException

This usually means one of these is missing or incompatible:

• the bundled wrapper libLibNftablesBindings.so
• the host libnftables shared library
• Linux x64 runtime compatibility

NftUnsupportedException

This is expected on:

• non-Linux hosts
• non-x64 processes

NftPermissionException

Some operations require elevated privileges or CAP_NET_ADMIN, especially when interacting with the live ruleset.

Validation failures

ValidateRuleset returns IsValid = false for invalid nft syntax after rendering the typed model. ApplyRuleset and Restore throw when the typed/request shape is invalid or native parsing fails.

Bindings and Regeneration

• Native wrapper build only:

./eng/build-native.sh

• Regenerate SWIG bindings:

./eng/regen-bindings.sh

Low-level generated binding reference:

• docs/low-level-bindings-reference.md

Generated SWIG files under src/LibNftables.Bindings/Generated/ are generated artifacts and should not be edited by hand.