137 lines
3.2 KiB
Markdown
137 lines
3.2 KiB
Markdown
# 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
|
|
|
|
```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 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
|
|
|
|
```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
|
|
|
|
`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:
|
|
|
|
```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.
|