libnftables-dotnet

libnftables-dotnet is a command-centric .NET wrapper over system-installed libnftables, with low-level SWIG-generated bindings and a small managed API for common workflows.

Current Scope

This library is intentionally narrow.

• High-level managed API:
  • Validate
  • Apply
  • 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:

• Typed .NET models for tables, chains, rules, sets, or maps
• 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 validation = client.Validate(NftApplyRequest.FromText("add table inet my_table"));
if (validation.IsValid)
{
    client.Apply(NftApplyRequest.FromText("add table inet my_table"));
}

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

Validate returns IsValid = false for invalid nft syntax. Apply and Restore throw when the 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.