177 lines
4.3 KiB
Markdown
177 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
dotnet build
|
|
```
|
|
|
|
`dotnet build` compiles the native SWIG wrapper (`libLibNftablesBindings.so`) from the checked-in generated C wrapper code.
|
|
|
|
## Test
|
|
|
|
```bash
|
|
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
|
|
|
|
```csharp
|
|
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
|
|
|
|
```csharp
|
|
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:
|
|
|
|
```bash
|
|
./eng/build-native.sh
|
|
```
|
|
|
|
- Regenerate SWIG bindings:
|
|
|
|
```bash
|
|
./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.
|