feat: complete nx9-wg v0.8.0 platform
This commit is contained in:
thakares committed
1 parent
c75e5c4e71
commit
c8a9b7cde6
52 files changed
+7751
-725
No files matched your search
@@ -1,4 +1,9 @@
|
|||||||
/target
|
/target
|
||||||
|
backups/
|
||||||
|
crates/nx9-wg-api/backups/
|
||||||
|
*.db
|
||||||
|
*.db-shm
|
||||||
|
*.db-wal
|
||||||
|
|
||||||
# IDE metadata
|
# IDE metadata
|
||||||
.idea/
|
.idea/
|
||||||
Generated
+190
-20
@@ -209,7 +209,7 @@ dependencies = [
|
|||||||
"num-traits",
|
"num-traits",
|
||||||
"pastey",
|
"pastey",
|
||||||
"rayon",
|
"rayon",
|
||||||
"thiserror",
|
"thiserror 2.0.20",
|
||||||
"v_frame",
|
"v_frame",
|
||||||
"y4m",
|
"y4m",
|
||||||
]
|
]
|
||||||
@@ -412,6 +412,12 @@ version = "1.0.4"
|
|||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
|
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "cfg_aliases"
|
||||||
|
version = "0.2.2"
|
||||||
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
|
checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "chrono"
|
name = "chrono"
|
||||||
version = "0.4.45"
|
version = "0.4.45"
|
||||||
@@ -814,6 +820,21 @@ dependencies = [
|
|||||||
"percent-encoding",
|
"percent-encoding",
|
||||||
]
|
]
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "futures"
|
||||||
|
version = "0.3.34"
|
||||||
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
|
checksum = "9a31d2a3fbaaeb2af2368bbdd904aa8e812d3c04a1ee10d3171f52d556e5d0a3"
|
||||||
|
dependencies = [
|
||||||
|
"futures-channel",
|
||||||
|
"futures-core",
|
||||||
|
"futures-executor",
|
||||||
|
"futures-io",
|
||||||
|
"futures-sink",
|
||||||
|
"futures-task",
|
||||||
|
"futures-util",
|
||||||
|
]
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "futures-channel"
|
name = "futures-channel"
|
||||||
version = "0.3.34"
|
version = "0.3.34"
|
||||||
@@ -887,6 +908,7 @@ version = "0.3.34"
|
|||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
|
checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
|
"futures-channel",
|
||||||
"futures-core",
|
"futures-core",
|
||||||
"futures-io",
|
"futures-io",
|
||||||
"futures-macro",
|
"futures-macro",
|
||||||
@@ -907,6 +929,21 @@ dependencies = [
|
|||||||
"version_check",
|
"version_check",
|
||||||
]
|
]
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "genetlink"
|
||||||
|
version = "0.2.7"
|
||||||
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
|
checksum = "5630187517b443491246f00107e75065873a436f366532d554a45b44c979ccb8"
|
||||||
|
dependencies = [
|
||||||
|
"futures",
|
||||||
|
"log",
|
||||||
|
"netlink-packet-core",
|
||||||
|
"netlink-packet-generic",
|
||||||
|
"netlink-proto",
|
||||||
|
"thiserror 1.0.69",
|
||||||
|
"tokio",
|
||||||
|
]
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "getrandom"
|
name = "getrandom"
|
||||||
version = "0.2.17"
|
version = "0.2.17"
|
||||||
@@ -1537,12 +1574,95 @@ dependencies = [
|
|||||||
"pxfm",
|
"pxfm",
|
||||||
]
|
]
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "netlink-packet-core"
|
||||||
|
version = "0.8.2"
|
||||||
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
|
checksum = "b897d7bd4f0af82e68d40d0344cf37e97f9c97ddf74a098de3e4da05e96ca395"
|
||||||
|
dependencies = [
|
||||||
|
"paste",
|
||||||
|
]
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "netlink-packet-generic"
|
||||||
|
version = "0.4.0"
|
||||||
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
|
checksum = "2f891b2e0054cac5a684a06628f59568f841c93da4e551239da6e518f539e775"
|
||||||
|
dependencies = [
|
||||||
|
"netlink-packet-core",
|
||||||
|
]
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "netlink-packet-route"
|
||||||
|
version = "0.30.0"
|
||||||
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
|
checksum = "be8919612f6028ab4eacbbfe1234a9a43e3722c6e0915e7ff519066991905092"
|
||||||
|
dependencies = [
|
||||||
|
"bitflags",
|
||||||
|
"libc",
|
||||||
|
"log",
|
||||||
|
"netlink-packet-core",
|
||||||
|
]
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "netlink-packet-wireguard"
|
||||||
|
version = "0.4.3"
|
||||||
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
|
checksum = "81b0e03593f61a7684836d73fdfef3dddae3f2dbc81896159a14bfafdb013567"
|
||||||
|
dependencies = [
|
||||||
|
"bitflags",
|
||||||
|
"libc",
|
||||||
|
"log",
|
||||||
|
"netlink-packet-core",
|
||||||
|
"netlink-packet-generic",
|
||||||
|
]
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "netlink-proto"
|
||||||
|
version = "0.12.2"
|
||||||
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
|
checksum = "93af8261786086024cd5e96e0a991dd65ced07bbf7c233a487bbc96b971d5539"
|
||||||
|
dependencies = [
|
||||||
|
"bytes",
|
||||||
|
"futures-channel",
|
||||||
|
"futures-util",
|
||||||
|
"log",
|
||||||
|
"netlink-packet-core",
|
||||||
|
"netlink-sys",
|
||||||
|
"thiserror 2.0.20",
|
||||||
|
]
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "netlink-sys"
|
||||||
|
version = "0.8.8"
|
||||||
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
|
checksum = "cd6c30ed10fa69cc491d491b85cc971f6bdeb8e7367b7cde2ee6cc878d583fae"
|
||||||
|
dependencies = [
|
||||||
|
"bytes",
|
||||||
|
"futures-util",
|
||||||
|
"libc",
|
||||||
|
"log",
|
||||||
|
"tokio",
|
||||||
|
]
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "new_debug_unreachable"
|
name = "new_debug_unreachable"
|
||||||
version = "1.0.6"
|
version = "1.0.6"
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086"
|
checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086"
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "nix"
|
||||||
|
version = "0.30.1"
|
||||||
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
|
checksum = "74523f3a35e05aba87a1d978330aef40f67b0304ac79c1c00b294c9830543db6"
|
||||||
|
dependencies = [
|
||||||
|
"bitflags",
|
||||||
|
"cfg-if",
|
||||||
|
"cfg_aliases",
|
||||||
|
"libc",
|
||||||
|
]
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "no_std_io2"
|
name = "no_std_io2"
|
||||||
version = "0.9.4"
|
version = "0.9.4"
|
||||||
@@ -1665,7 +1785,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "nx9-wg"
|
name = "nx9-wg"
|
||||||
version = "0.1.0"
|
version = "0.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"axum",
|
"axum",
|
||||||
"base64",
|
"base64",
|
||||||
@@ -1687,7 +1807,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "nx9-wg-api"
|
name = "nx9-wg-api"
|
||||||
version = "0.1.0"
|
version = "0.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"axum",
|
"axum",
|
||||||
"chrono",
|
"chrono",
|
||||||
@@ -1702,7 +1822,7 @@ dependencies = [
|
|||||||
"serde_json",
|
"serde_json",
|
||||||
"sha2",
|
"sha2",
|
||||||
"tempfile",
|
"tempfile",
|
||||||
"thiserror",
|
"thiserror 2.0.20",
|
||||||
"tokio",
|
"tokio",
|
||||||
"tower",
|
"tower",
|
||||||
"tower-http",
|
"tower-http",
|
||||||
@@ -1712,7 +1832,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "nx9-wg-core"
|
name = "nx9-wg-core"
|
||||||
version = "0.1.0"
|
version = "0.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"argon2",
|
"argon2",
|
||||||
"base64",
|
"base64",
|
||||||
@@ -1723,7 +1843,7 @@ dependencies = [
|
|||||||
"serde_json",
|
"serde_json",
|
||||||
"sha2",
|
"sha2",
|
||||||
"tempfile",
|
"tempfile",
|
||||||
"thiserror",
|
"thiserror 2.0.20",
|
||||||
"toml",
|
"toml",
|
||||||
"tracing",
|
"tracing",
|
||||||
"uuid",
|
"uuid",
|
||||||
@@ -1732,7 +1852,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "nx9-wg-db"
|
name = "nx9-wg-db"
|
||||||
version = "0.1.0"
|
version = "0.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"chrono",
|
"chrono",
|
||||||
"ipnet",
|
"ipnet",
|
||||||
@@ -1741,7 +1861,7 @@ dependencies = [
|
|||||||
"serde_json",
|
"serde_json",
|
||||||
"sqlx",
|
"sqlx",
|
||||||
"tempfile",
|
"tempfile",
|
||||||
"thiserror",
|
"thiserror 2.0.20",
|
||||||
"tokio",
|
"tokio",
|
||||||
"tracing",
|
"tracing",
|
||||||
"uuid",
|
"uuid",
|
||||||
@@ -1749,16 +1869,20 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "nx9-wg-network"
|
name = "nx9-wg-network"
|
||||||
version = "0.1.0"
|
version = "0.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"async-trait",
|
"async-trait",
|
||||||
"chrono",
|
"chrono",
|
||||||
|
"futures",
|
||||||
"ipnet",
|
"ipnet",
|
||||||
|
"netlink-packet-core",
|
||||||
|
"netlink-packet-route",
|
||||||
"nx9-wg-core",
|
"nx9-wg-core",
|
||||||
|
"rtnetlink",
|
||||||
"serde",
|
"serde",
|
||||||
"serde_json",
|
"serde_json",
|
||||||
"tempfile",
|
"tempfile",
|
||||||
"thiserror",
|
"thiserror 2.0.20",
|
||||||
"tokio",
|
"tokio",
|
||||||
"tracing",
|
"tracing",
|
||||||
"uuid",
|
"uuid",
|
||||||
@@ -1766,7 +1890,7 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "nx9-wg-ui"
|
name = "nx9-wg-ui"
|
||||||
version = "0.1.0"
|
version = "0.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"chrono",
|
"chrono",
|
||||||
"nx9-wg-core",
|
"nx9-wg-core",
|
||||||
@@ -1777,19 +1901,27 @@ dependencies = [
|
|||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "nx9-wireguard"
|
name = "nx9-wireguard"
|
||||||
version = "0.1.0"
|
version = "0.8.0"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"async-trait",
|
"async-trait",
|
||||||
"base64",
|
"base64",
|
||||||
"chrono",
|
"chrono",
|
||||||
|
"futures",
|
||||||
|
"genetlink",
|
||||||
"image",
|
"image",
|
||||||
"ipnet",
|
"ipnet",
|
||||||
|
"netlink-packet-core",
|
||||||
|
"netlink-packet-generic",
|
||||||
|
"netlink-packet-wireguard",
|
||||||
|
"netlink-proto",
|
||||||
|
"netlink-sys",
|
||||||
"nx9-wg-core",
|
"nx9-wg-core",
|
||||||
"qrcode",
|
"qrcode",
|
||||||
|
"rtnetlink",
|
||||||
"serde",
|
"serde",
|
||||||
"serde_json",
|
"serde_json",
|
||||||
"tempfile",
|
"tempfile",
|
||||||
"thiserror",
|
"thiserror 2.0.20",
|
||||||
"tokio",
|
"tokio",
|
||||||
"tracing",
|
"tracing",
|
||||||
"uuid",
|
"uuid",
|
||||||
@@ -2135,7 +2267,7 @@ dependencies = [
|
|||||||
"rand 0.9.5",
|
"rand 0.9.5",
|
||||||
"rand_chacha 0.9.0",
|
"rand_chacha 0.9.0",
|
||||||
"simd_helpers",
|
"simd_helpers",
|
||||||
"thiserror",
|
"thiserror 2.0.20",
|
||||||
"v_frame",
|
"v_frame",
|
||||||
"wasm-bindgen",
|
"wasm-bindgen",
|
||||||
]
|
]
|
||||||
@@ -2251,6 +2383,24 @@ dependencies = [
|
|||||||
"zeroize",
|
"zeroize",
|
||||||
]
|
]
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "rtnetlink"
|
||||||
|
version = "0.21.0"
|
||||||
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
|
checksum = "dc19f84f710fa2f337617f9bc0400260a94224bde7bae28fd8879f3771ca5784"
|
||||||
|
dependencies = [
|
||||||
|
"futures-channel",
|
||||||
|
"futures-util",
|
||||||
|
"log",
|
||||||
|
"netlink-packet-core",
|
||||||
|
"netlink-packet-route",
|
||||||
|
"netlink-proto",
|
||||||
|
"netlink-sys",
|
||||||
|
"nix",
|
||||||
|
"thiserror 1.0.69",
|
||||||
|
"tokio",
|
||||||
|
]
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "rustc_version"
|
name = "rustc_version"
|
||||||
version = "0.4.1"
|
version = "0.4.1"
|
||||||
@@ -2529,7 +2679,7 @@ dependencies = [
|
|||||||
"serde_json",
|
"serde_json",
|
||||||
"sha2",
|
"sha2",
|
||||||
"smallvec",
|
"smallvec",
|
||||||
"thiserror",
|
"thiserror 2.0.20",
|
||||||
"tokio",
|
"tokio",
|
||||||
"tokio-stream",
|
"tokio-stream",
|
||||||
"tracing",
|
"tracing",
|
||||||
@@ -2613,7 +2763,7 @@ dependencies = [
|
|||||||
"smallvec",
|
"smallvec",
|
||||||
"sqlx-core",
|
"sqlx-core",
|
||||||
"stringprep",
|
"stringprep",
|
||||||
"thiserror",
|
"thiserror 2.0.20",
|
||||||
"tracing",
|
"tracing",
|
||||||
"uuid",
|
"uuid",
|
||||||
"whoami",
|
"whoami",
|
||||||
@@ -2652,7 +2802,7 @@ dependencies = [
|
|||||||
"smallvec",
|
"smallvec",
|
||||||
"sqlx-core",
|
"sqlx-core",
|
||||||
"stringprep",
|
"stringprep",
|
||||||
"thiserror",
|
"thiserror 2.0.20",
|
||||||
"tracing",
|
"tracing",
|
||||||
"uuid",
|
"uuid",
|
||||||
"whoami",
|
"whoami",
|
||||||
@@ -2678,7 +2828,7 @@ dependencies = [
|
|||||||
"serde",
|
"serde",
|
||||||
"serde_urlencoded",
|
"serde_urlencoded",
|
||||||
"sqlx-core",
|
"sqlx-core",
|
||||||
"thiserror",
|
"thiserror 2.0.20",
|
||||||
"tracing",
|
"tracing",
|
||||||
"url",
|
"url",
|
||||||
"uuid",
|
"uuid",
|
||||||
@@ -2765,13 +2915,33 @@ dependencies = [
|
|||||||
"windows-sys 0.61.2",
|
"windows-sys 0.61.2",
|
||||||
]
|
]
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "thiserror"
|
||||||
|
version = "1.0.69"
|
||||||
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
|
checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
|
||||||
|
dependencies = [
|
||||||
|
"thiserror-impl 1.0.69",
|
||||||
|
]
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "thiserror"
|
name = "thiserror"
|
||||||
version = "2.0.20"
|
version = "2.0.20"
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
|
checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
|
||||||
dependencies = [
|
dependencies = [
|
||||||
"thiserror-impl",
|
"thiserror-impl 2.0.20",
|
||||||
|
]
|
||||||
|
|
||||||
|
[[package]]
|
||||||
|
name = "thiserror-impl"
|
||||||
|
version = "1.0.69"
|
||||||
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||||
|
checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
|
||||||
|
dependencies = [
|
||||||
|
"proc-macro2",
|
||||||
|
"quote",
|
||||||
|
"syn 2.0.119",
|
||||||
]
|
]
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
@@ -3081,7 +3251,7 @@ dependencies = [
|
|||||||
"log",
|
"log",
|
||||||
"rand 0.9.5",
|
"rand 0.9.5",
|
||||||
"sha1",
|
"sha1",
|
||||||
"thiserror",
|
"thiserror 2.0.20",
|
||||||
]
|
]
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
|
|||||||
+18
-1
@@ -10,8 +10,14 @@ members = [
|
|||||||
|
|
||||||
[workspace.package]
|
[workspace.package]
|
||||||
license = "MIT OR Apache-2.0"
|
license = "MIT OR Apache-2.0"
|
||||||
version = "0.1.0"
|
version = "0.8.0"
|
||||||
edition = "2024"
|
edition = "2024"
|
||||||
|
authors = ["NX9 Authors <team@nx9.in>"]
|
||||||
|
repository = "https://github.com/nx9/nx9-wg"
|
||||||
|
homepage = "https://github.com/nx9/nx9-wg"
|
||||||
|
readme = "README.md"
|
||||||
|
keywords = ["wireguard", "vpn", "netlink", "nftables", "network"]
|
||||||
|
categories = ["network-programming", "command-line-utilities", "system-administration"]
|
||||||
|
|
||||||
[workspace.dependencies]
|
[workspace.dependencies]
|
||||||
# Internal crates
|
# Internal crates
|
||||||
@@ -53,6 +59,17 @@ sha2 = "0.10"
|
|||||||
# Network types
|
# Network types
|
||||||
ipnet = { version = "2", features = ["serde"] }
|
ipnet = { version = "2", features = ["serde"] }
|
||||||
|
|
||||||
|
# Netlink (Linux native WireGuard kernel interface)
|
||||||
|
rtnetlink = "0.21"
|
||||||
|
genetlink = "0.2"
|
||||||
|
netlink-packet-wireguard = "0.4"
|
||||||
|
netlink-packet-core = "0.8"
|
||||||
|
netlink-packet-route = "0.30"
|
||||||
|
netlink-packet-generic = "0.4"
|
||||||
|
netlink-proto = "0.12"
|
||||||
|
netlink-sys = "0.8"
|
||||||
|
futures = "0.3"
|
||||||
|
|
||||||
# CLI
|
# CLI
|
||||||
clap = { version = "4", features = ["derive", "env", "string"] }
|
clap = { version = "4", features = ["derive", "env", "string"] }
|
||||||
|
|
||||||
|
|||||||
+519
@@ -0,0 +1,519 @@
|
|||||||
|
# NX9 WireGuard (`nx9-wg`) — Full Technical Architecture & Stack Report
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
> **"Software people can own, understand, and control."**
|
||||||
|
> — [NX9 Systems (https://nx9.in)](https://nx9.in)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📑 Table of Contents
|
||||||
|
|
||||||
|
1. [Executive Summary](#1-executive-summary)
|
||||||
|
2. [The NX9 Philosophy in Implementation](#2-the-nx9-philosophy-in-implementation)
|
||||||
|
3. [The Architectural Paradigm Shift](#3-the-architectural-paradigm-shift)
|
||||||
|
4. [Six-Crate Workspace Architecture](#4-six-crate-workspace-architecture)
|
||||||
|
5. [Complete Capability Inventory](#5-complete-capability-inventory)
|
||||||
|
6. [Native Linux Execution Planes](#6-native-linux-execution-planes)
|
||||||
|
7. [Closed-Loop Reconciliation & Convergence](#7-closed-loop-reconciliation--convergence)
|
||||||
|
8. [Embedded Single Page Application (SPA) & WebSockets](#8-embedded-single-page-application-spa--websockets)
|
||||||
|
9. [REST API & WebSocket Protocol Reference](#9-rest-api--websocket-protocol-reference)
|
||||||
|
10. [Native CLI Command System](#10-native-cli-command-system)
|
||||||
|
11. [Security Model & Capability Isolation](#11-security-model--capability-isolation)
|
||||||
|
12. [Disaster Recovery, Backups & Upgrades](#12-disaster-recovery-backups--upgrades)
|
||||||
|
13. [Release Engineering & Deployment Lifecycle](#13-release-engineering--deployment-lifecycle)
|
||||||
|
14. [Quality Assurance & Verification Evidence](#14-quality-assurance--verification-evidence)
|
||||||
|
15. [Ecosystem & License Summary](#15-ecosystem--license-summary)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Executive Summary
|
||||||
|
|
||||||
|
`nx9-wg` is a sovereign, self-hosted, Linux-native VPN and network control plane built directly around the Linux kernel's in-tree WireGuard implementation (`wireguard.ko`).
|
||||||
|
|
||||||
|
Rather than functioning as a fragile user interface wrapper that shells out to external command-line utilities (`wg`, `ip`, `nft`, `sysctl`), `nx9-wg` establishes an integrated, single-binary architecture. It combines **authoritative SQLite desired-state persistence**, **direct kernel Netlink execution** (RTNETLINK and WireGuard Generic Netlink), **in-process Netfilter firewall/NAT compilation** (`libnftables.so.1`), **continuous closed-loop reconciliation**, a **multi-format native CLI**, and an **embedded zero-dependency Single Page Application (SPA) Web UI**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. The NX9 Philosophy in Implementation
|
||||||
|
|
||||||
|
Every design and architectural choice in `nx9-wg` directly reflects the core philosophy of the **NX9 Ecosystem** ([https://nx9.in](https://nx9.in)):
|
||||||
|
|
||||||
|
| NX9 Principle | Core Intent | `nx9-wg` Implementation |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| 🔑 **Operator Ownership** | Full control over binaries, configurations, databases, keys, and backups with zero dependency on cloud-hosted control planes. | 100% local operation. Private keys, configuration data, and encryption parameters never leave the operator's host. |
|
||||||
|
| 🖥️ **Self-Hosting First** | Built to be deployed and operated effortlessly by a single administrator without requiring Kubernetes or external infrastructure. | Self-contained single executable. Bootstrapped with a single command (`nx9-wg init`), running seamlessly under standard systemd. |
|
||||||
|
| ⚡ **Simplicity Over Complexity** | One binary, one configuration file, one SQLite database, one administrator. | No multi-daemon orchestration, no external message queues, no Node.js runtime, no Python scripts, and zero shell wrappers. |
|
||||||
|
| 🛡️ **Privacy by Default** | Zero analytics, zero telemetry collection, zero third-party tracking, and zero assumptions of external cloud connectivity. | No phone-home telemetry. Completely air-gapped capable with all static assets, fonts, and scripts embedded in the binary. |
|
||||||
|
| 🔒 **Security by Design** | Modern cryptography, strict invariants, and append-only audit logging embedded from day one. | Argon2id password hashing, SHA-256 token digests, X25519 key generation, single-admin database constraint (`CHECK (id=1)`), and strict secret redaction. |
|
||||||
|
| 🔧 **Operational Excellence** | Diagnostics, backup/restore, migration tools, CLI management, and comprehensive documentation built-in. | Multi-subsystem automated health inspections, atomic online SQLite `VACUUM INTO` snapshots with SHA-256 manifests, and 100% CLI parity. |
|
||||||
|
| ⏳ **Long-Term Stability** | Avoid dependency churn. Build software that remains understandable and maintainable years into the future. | Built in stable native Rust (Edition 2024), standard SQLite 3 storage, standard TOML configuration, and POSIX-compliant systemd integration. |
|
||||||
|
| 🌐 **Open Source First** | 100% free and open-source software under permissive licensing. | Dual-licensed under `MIT OR Apache-2.0`. Complete freedom to inspect, audit, build, and extend. |
|
||||||
|
| ♾️ **Zero Vendor Lock-In** | Standard data formats, open protocols, and zero proprietary cloud lock-in. | Standard SQLite database, standard WireGuard `.conf` files, standard RFC-compliant JSON/YAML/CSV output formats, and open Netlink sockets. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. The Architectural Paradigm Shift
|
||||||
|
|
||||||
|
### Typical WireGuard Management Wrappers
|
||||||
|
```
|
||||||
|
┌──────────┐ ┌──────────────────────┐ ┌────────────────────────────┐ ┌──────────────┐
|
||||||
|
│ Web UI │ ──► │ Text Config Files │ ──► │ wg / ip / nft / sysctl │ ──► │ Linux Kernel │
|
||||||
|
│ (Node/Py)│ │(/etc/wireguard/*.conf│ │ (Subprocess Spawning) │ │ (wireguard.ko│
|
||||||
|
└──────────┘ └──────────────────────┘ └────────────────────────────┘ └──────────────┘
|
||||||
|
```
|
||||||
|
*Disadvantages: Fragile process spawning, race conditions, lack of atomic state, broken host routing, vulnerability to configuration drift, and heavy runtime dependency footprints.*
|
||||||
|
|
||||||
|
### Whereas `nx9-wg` is a Native Control & Execution Plane:
|
||||||
|
```
|
||||||
|
┌───────────────────────────────────┐
|
||||||
|
│ nx9-wg │
|
||||||
|
└─────────────────┬─────────────────┘
|
||||||
|
│
|
||||||
|
┌────────────────────────────────┴────────────────────────────────┐
|
||||||
|
│ │
|
||||||
|
┌─────────▼─────────┐ ┌─────────▼─────────┐
|
||||||
|
│ Desired State │ │ Live State │
|
||||||
|
│ (Authoritative) │ │ (Kernel Cache) │
|
||||||
|
└─────────┬─────────┘ └─────────▲─────────┘
|
||||||
|
│ │
|
||||||
|
┌─────────▼─────────┐ ┌─────────┴─────────┐
|
||||||
|
│ SQLite 3 (WAL) │ │ Linux Kernel │
|
||||||
|
└─────────┬─────────┘ └─────────▲─────────┘
|
||||||
|
│ │
|
||||||
|
│ Live Netlink Telemetry
|
||||||
|
▼ │
|
||||||
|
┌───────────────────┐ │
|
||||||
|
│ Reconciliation │ ◄─────────────────────────────────────────────────────┘
|
||||||
|
│ Engine │
|
||||||
|
└─────────┬─────────┘
|
||||||
|
│
|
||||||
|
├── 🔐 WireGuard Generic Netlink (family "wireguard")
|
||||||
|
├── 🌐 RTNETLINK (Links, IPv4/IPv6 Addresses, Routes)
|
||||||
|
├── 🔥 Netfilter / libnftables FFI (table inet nx9_wg)
|
||||||
|
└── ↔️ Direct Procfs IP Forwarding (/proc/sys/net)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌───────────────────┐
|
||||||
|
│ Linux Networking │
|
||||||
|
└───────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Six-Crate Workspace Architecture
|
||||||
|
|
||||||
|
`nx9-wg` is architected as a modular six-crate Cargo workspace ensuring clean separation of concerns, zero circular dependencies, and isolated testability:
|
||||||
|
|
||||||
|
```
|
||||||
|
nx9-wg (Root Executable & Unified Entrypoint)
|
||||||
|
├── 📦 crates/nx9-wg-core — Domain models, RFC validation, cryptography, configuration
|
||||||
|
├── 📦 crates/nx9-wg-db — SQLite storage engine, migration framework, repositories
|
||||||
|
├── 📦 crates/nx9-wireguard — WireGuard Generic Netlink, RTNETLINK link engine, config & QR
|
||||||
|
├── 📦 crates/nx9-wg-network — RTNETLINK routes/addresses, libnftables Netfilter, procfs
|
||||||
|
├── 📦 crates/nx9-wg-api — Axum REST router, WebSockets, auth, reconciliation, IP allocator
|
||||||
|
└── 📦 crates/nx9-wg-ui — Design tokens, CSS compiler, view models, SPA integration
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Complete Capability Inventory
|
||||||
|
|
||||||
|
`nx9-wg` delivers a comprehensive suite of 20 core infrastructure capabilities:
|
||||||
|
|
||||||
|
| Icon | Capability | Architectural Description |
|
||||||
|
| :---: | :--- | :--- |
|
||||||
|
| 🔐 | **WireGuard Interface Lifecycle** | In-process RTNETLINK link creation (`RTM_NEWLINK`), state toggling (`IFF_UP`/`IFF_DOWN`), and WireGuard Generic Netlink cryptokey configuration (`WG_CMD_SET_DEVICE`). |
|
||||||
|
| 👥 | **Cryptographic Peer Enrollment** | Dynamic Curve25519 public key management, preshared keys, CIDR allowed IPs, persistent keepalive intervals, and atomic `ReplacePeers` synchronization. |
|
||||||
|
| 🌐 | **IPv4 & IPv6 Address Management** | Native Netlink address assignment (`RTM_NEWADDR` / `RTM_DELADDR`) across WireGuard interfaces without invoking `ip addr`. |
|
||||||
|
| 🛣️ | **Kernel Route Management** | Routing table synchronization (`RTM_NEWROUTE` / `RTM_DELROUTE`) with strict default gateway protection and multi-tenant non-interference invariants. |
|
||||||
|
| 🔥 | **nftables Netfilter Firewall** | In-process rule compilation and transactional application via `libnftables.so.1` confined strictly to `table inet nx9_wg`. |
|
||||||
|
| 🛡️ | **Scoped NAT & Masquerading** | Outbound NAT masquerade dynamically calculated and applied strictly to managed WireGuard client subnets, preventing host network disruption. |
|
||||||
|
| ↔️ | **Direct Procfs IP Forwarding** | Direct atomic mutation of `/proc/sys/net/ipv4/ip_forward` and `/proc/sys/net/ipv6/conf/all/forwarding` without invoking `sysctl`. |
|
||||||
|
| 📡 | **Live Kernel Telemetry** | Real-time extraction of handshake timestamps, rx/tx byte counters, and roaming remote socket endpoints directly from kernel sockets. |
|
||||||
|
| 🔄 | **Desired-State Reconciliation** | Continuous closed-loop control cycle bringing the Linux kernel execution plane into alignment with authoritative SQLite storage. |
|
||||||
|
| 🧭 | **5-Subsystem Drift Detection** | Deterministic, read-only calculation of state divergence across interfaces, peers, routes, firewall rules, and IP forwarding. |
|
||||||
|
| ♻️ | **Cold-Boot Restart Recovery** | Autonomous reconstruction of kernel network topology, routes, and firewall rules upon daemon startup or host reboot. |
|
||||||
|
| 🧪 | **Cross-Platform Simulation Engine** | In-memory simulated execution planes enabling full UI and CLI development on macOS and Windows without requiring Linux Netlink. |
|
||||||
|
| 🖥️ | **Multi-Format Native CLI** | 100% native CLI coverage across all 17 subcommands supporting `table`, `json`, `yaml`, and `csv` output with script-friendly exit codes. |
|
||||||
|
| 🌐 | **Axum REST API & WebSockets** | High-performance asynchronous HTTP server with session/bearer authentication and a real-time WebSocket event broadcaster (`/api/v1/ws`). |
|
||||||
|
| 💻 | **Embedded Zero-Dependency SPA** | Modern HTML5/CSS3/Vanilla ES6+ Single Page Application compiled into the binary with Light/Dark theme support and 15 interactive views. |
|
||||||
|
| 📊 | **Automated Health Diagnostics** | Built-in inspection across 9 subsystems with structured status reporting, root-cause diagnostics, and actionable remediation hints. |
|
||||||
|
| 💾 | **Atomic Disaster Recovery Backups** | Online non-blocking SQLite `VACUUM INTO` snapshots with SHA-256 manifest verification and automatic pre-restore safety checkpoints. |
|
||||||
|
| 🔑 | **Single-Administrator Security** | Database-enforced single identity (`CHECK (id=1)`), Argon2id password hashing, SHA-256 API token storage, and brute-force login rate limiting. |
|
||||||
|
| 📱 | **Client Profiles & QR Engine** | Provider/device MTU profiles (1280 vs 1360 vs 1420), collision-resistant IP allocation, and pure Rust vector SVG, PNG, and ASCII QR generation. |
|
||||||
|
| 📦 | **Production Release Packaging** | Standalone distribution archive generator (`scripts/package-release.sh`), automated installer/uninstaller, and hardened systemd service unit. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Native Linux Execution Planes
|
||||||
|
|
||||||
|
`nx9-wg` enforces a **Zero Subprocess Guarantee** across the entire production codebase:
|
||||||
|
|
||||||
|
```
|
||||||
|
┌────────────────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ Rust Production Binary │
|
||||||
|
├────────────────────────────┬────────────────────────────┬──────────────────────────────┤
|
||||||
|
│ NativeLinuxWireGuardEngine │ NativeLinuxNetworkEngine │ NativeLinuxNftablesEngine │
|
||||||
|
├────────────────────────────┼────────────────────────────┼──────────────────────────────┤
|
||||||
|
│ • AF_NETLINK │ • NETLINK_ROUTE │ • In-process libnftables FFI │
|
||||||
|
│ • NETLINK_GENERIC (wg) │ • RTM_NEWLINK / DELLINK │ • nft_ctx_new() │
|
||||||
|
│ • WG_CMD_SET_DEVICE │ • RTM_NEWADDR / DELADDR │ • Atomic Netfilter batch │
|
||||||
|
│ • WG_CMD_GET_DEVICE │ • RTM_NEWROUTE / DELROUTE │ • Scoped: table inet nx9_wg │
|
||||||
|
│ • WGDEVICE_F_REPLACE_PEERS │ • Direct /proc/sys writes │ • Zero host table flushes │
|
||||||
|
└─────────────┬──────────────┴─────────────┬──────────────┴──────────────┬───────────────┘
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌────────────────────────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ Linux Kernel │
|
||||||
|
│ (wireguard.ko • RTNETLINK • Netfilter • /proc/sys/net) │
|
||||||
|
└────────────────────────────────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Closed-Loop Reconciliation & Convergence
|
||||||
|
|
||||||
|
Reconciliation is the foundational control loop that bridges authoritative SQLite state with the Linux kernel:
|
||||||
|
|
||||||
|
```
|
||||||
|
┌──────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 1. SQLite Desired State (Authoritative Persistent Source of Truth│
|
||||||
|
└────────────────────────────────┬─────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌──────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 2. Live Kernel Query (WireGuard Genl, RTNL routes, table nx9_wg) │
|
||||||
|
└────────────────────────────────┬─────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌──────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 3. Drift Detection (Read-Only Deterministic Multi-Subsystem Diff)│
|
||||||
|
└────────────────────────────────┬─────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌───────────────┴───────────────┐
|
||||||
|
│ has_drift == false? │
|
||||||
|
├───────────────────────┬───────┤
|
||||||
|
│ YES │ NO │
|
||||||
|
▼ ▼ │
|
||||||
|
┌─────────────┐ ┌──────────────▼────────────────┐
|
||||||
|
│ Converged │ │ 4. Acquire Async Mutex Lock │
|
||||||
|
│ (In Sync) │ └──────────────┬────────────────┘
|
||||||
|
└─────────────┘ │
|
||||||
|
▼
|
||||||
|
┌───────────────────────────────┐
|
||||||
|
│ 5. Execute Native Mutations │
|
||||||
|
│ (Genl SET_DEVICE, RTNL) │
|
||||||
|
└──────────────┬────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌───────────────────────────────┐
|
||||||
|
│ 6. Post-Apply Verification │
|
||||||
|
└──────────────┬────────────────┘
|
||||||
|
│
|
||||||
|
┌───────────────┴───────────────┐
|
||||||
|
▼ ▼
|
||||||
|
┌─────────────┐ ┌─────────────┐
|
||||||
|
│ Converged │ │ Partial │
|
||||||
|
│ (100% Sync)│ │ Failure │
|
||||||
|
└─────────────┘ └─────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### The Six Reconciliation Lifecycle States
|
||||||
|
1. **`Plan`**: Read-only calculation of drift between SQLite and kernel.
|
||||||
|
2. **`Applying`**: In-progress dispatch of native mutations across execution planes.
|
||||||
|
3. **`Verifying`**: Querying live kernel state to confirm applied changes took effect.
|
||||||
|
4. **`Converged`**: 100% synchronization achieved with zero remaining drift.
|
||||||
|
5. **`PartialFailure`**: One or more execution planes failed during apply (e.g. permission error).
|
||||||
|
6. **`DriftRemains`**: Apply completed without fatal error, but post-verification detected unapplied state.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Embedded Single Page Application (SPA) & WebSockets
|
||||||
|
|
||||||
|
The `nx9-wg` frontend is a zero-dependency HTML5/CSS/JavaScript SPA embedded directly into the Rust binary:
|
||||||
|
|
||||||
|
- **Zero External Toolchains**: No Node.js, npm, Webpack, Vite, React, or external CDN dependencies.
|
||||||
|
- **Embedded In-Memory Delivery**: Bundled at compile-time via `include_str!()` and served from memory.
|
||||||
|
- **Design Tokens**: Custom CSS token system ([`crates/nx9-wg-ui/src/css.rs`](file:///home/sunil/Programs/nx9-wg/crates/nx9-wg-ui/src/css.rs)) supporting Light and Dark modes.
|
||||||
|
- **Real-Time WebSocket Stream**: Subscribes to `ws://<host>/api/v1/ws` for live handshakes and drift alerts without polling.
|
||||||
|
- **15 Interactive Views**:
|
||||||
|
1. `#dashboard` — System overview, uptime, interface/peer counts, health cards.
|
||||||
|
2. `#interfaces` — WireGuard interface CRUD, listen port, MTU, state toggles.
|
||||||
|
3. `#peers` — Enrolled peer table, real-time handshakes, profile resolution, `.conf` export, SVG QR modal.
|
||||||
|
4. `#networks` — Subnet network ranges, CIDR masks, available IP inspector.
|
||||||
|
5. `#routes` — Kernel route definitions, gateway assignments, interface scoping.
|
||||||
|
6. `#firewall` — nftables packet filtering rules in `table inet nx9_wg`, priority sorting.
|
||||||
|
7. `#nat` — Managed subnet NAT masquerade status and instant toggle.
|
||||||
|
8. `#forwarding` — Kernel IPv4/IPv6 packet forwarding status and toggle.
|
||||||
|
9. `#reconciliation` — Real-time kernel drift overview, action plan table, interactive Apply button.
|
||||||
|
10. `#diagnostics` — Automated multi-subsystem health checks with remediation hints.
|
||||||
|
11. `#live-state` — Raw Linux Netlink telemetry, active kernel interfaces, live routing table.
|
||||||
|
12. `#settings` — Key-value appliance parameters and danger zone reset controls.
|
||||||
|
13. `#backups` — Online SQLite backup snapshots list, instant backup creation, `.db` download.
|
||||||
|
14. `#audit` — Append-only security and administrative audit trail.
|
||||||
|
15. `#administrator` — Admin account verification, password rotation, and one-time API token generation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. REST API & WebSocket Protocol Reference
|
||||||
|
|
||||||
|
### Authentication Mechanisms
|
||||||
|
- **Session Cookie**: `nx9_session=<UUID>` returned via `POST /api/v1/auth/login`.
|
||||||
|
- **Bearer Token**: `Authorization: Bearer nx9_<UUID>_<SECRET>` passed in HTTP headers.
|
||||||
|
|
||||||
|
### Complete REST Route Inventory
|
||||||
|
```http
|
||||||
|
POST /api/v1/auth/login - Authenticate administrator & create session
|
||||||
|
POST /api/v1/auth/logout - Invalidate active session
|
||||||
|
GET /api/v1/auth/session - Query authenticated session info
|
||||||
|
POST /api/v1/auth/password - Rotate admin password (invalidates all sessions)
|
||||||
|
GET /api/v1/auth/tokens - List active API token metadata
|
||||||
|
POST /api/v1/auth/tokens - Generate new API token (one-time raw secret return)
|
||||||
|
DELETE /api/v1/auth/tokens/{id} - Revoke an API token
|
||||||
|
|
||||||
|
GET /api/v1/system - System operational overview and object counts
|
||||||
|
GET /api/v1/system/health - Public health check endpoint
|
||||||
|
GET /api/v1/system/version - Version, build edition, and architecture
|
||||||
|
GET /api/v1/system/settings - List all appliance key-value settings
|
||||||
|
PUT /api/v1/system/settings - Upsert appliance setting
|
||||||
|
|
||||||
|
GET /api/v1/interfaces - List all WireGuard interfaces
|
||||||
|
POST /api/v1/interfaces - Create WireGuard interface
|
||||||
|
GET /api/v1/interfaces/{id} - Get interface details
|
||||||
|
PUT /api/v1/interfaces/{id} - Update interface configuration
|
||||||
|
DELETE /api/v1/interfaces/{id} - Delete interface (cascades to peers)
|
||||||
|
POST /api/v1/interfaces/{id}/enable - Set interface IFF_UP
|
||||||
|
POST /api/v1/interfaces/{id}/disable - Set interface IFF_DOWN
|
||||||
|
GET /api/v1/interfaces/{id}/status - Query live kernel netlink telemetry
|
||||||
|
GET /api/v1/interfaces/{id}/peers - List peers attached to interface
|
||||||
|
POST /api/v1/interfaces/{id}/peers - Enroll new peer on interface
|
||||||
|
|
||||||
|
GET /api/v1/peers/{id} - Get peer details
|
||||||
|
PUT /api/v1/peers/{id} - Update peer parameters
|
||||||
|
DELETE /api/v1/peers/{id} - Delete peer
|
||||||
|
POST /api/v1/peers/{id}/enable - Enable peer
|
||||||
|
POST /api/v1/peers/{id}/disable - Disable peer
|
||||||
|
GET /api/v1/peers/{id}/config - Download client .conf file
|
||||||
|
GET /api/v1/peers/{id}/qr - Render QR code (SVG / PNG / ASCII)
|
||||||
|
|
||||||
|
GET /api/v1/networks - List subnet networks
|
||||||
|
POST /api/v1/networks - Create subnet network
|
||||||
|
GET /api/v1/networks/{id} - Get network details
|
||||||
|
DELETE /api/v1/networks/{id} - Delete network
|
||||||
|
GET /api/v1/networks/{id}/available - List available unallocated IP addresses
|
||||||
|
|
||||||
|
GET /api/v1/routes - List kernel routing entries
|
||||||
|
POST /api/v1/routes - Create routing entry
|
||||||
|
DELETE /api/v1/routes/{id} - Delete routing entry
|
||||||
|
|
||||||
|
GET /api/v1/firewall/rules - List nftables firewall rules
|
||||||
|
POST /api/v1/firewall/rules - Create firewall rule
|
||||||
|
DELETE /api/v1/firewall/rules/{id} - Delete firewall rule
|
||||||
|
POST /api/v1/firewall/rules/{id}/enable - Enable firewall rule
|
||||||
|
POST /api/v1/firewall/rules/{id}/disable - Disable firewall rule
|
||||||
|
|
||||||
|
GET /api/v1/reconcile/plan - Read-only drift calculation plan
|
||||||
|
POST /api/v1/reconcile/apply - Serialized kernel apply and convergence check
|
||||||
|
|
||||||
|
GET /api/v1/diagnostics/all - Run full diagnostics across all 9 subsystems
|
||||||
|
GET /api/v1/diagnostics/{subsystem} - Run diagnostics for single subsystem
|
||||||
|
|
||||||
|
GET /api/v1/backups - List backup records
|
||||||
|
POST /api/v1/backups/create - Trigger atomic online VACUUM INTO snapshot
|
||||||
|
GET /api/v1/backups/{id}/download - Download raw SQLite database snapshot
|
||||||
|
POST /api/v1/backups/{id}/restore - Restore database with automatic safety backup
|
||||||
|
DELETE /api/v1/backups/{id} - Delete backup snapshot file and metadata
|
||||||
|
|
||||||
|
GET /api/v1/audit - Query append-only audit trail
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Native CLI Command System
|
||||||
|
|
||||||
|
`nx9-wg` provides 100% native CLI coverage across all 17 subcommands:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Global output formats: --format table | json | yaml | csv
|
||||||
|
nx9-wg version
|
||||||
|
nx9-wg serve --bind 127.0.0.1:8080
|
||||||
|
nx9-wg init --generate-password --write-password-file /var/lib/nx9-wg/admin-password
|
||||||
|
|
||||||
|
# Administration & Authentication
|
||||||
|
nx9-wg admin info
|
||||||
|
nx9-wg admin password
|
||||||
|
nx9-wg admin token create "ci-pipeline" --expires-in-days 90 --write-token-file /tmp/token
|
||||||
|
nx9-wg admin token list
|
||||||
|
nx9-wg admin token revoke <TOKEN_UUID>
|
||||||
|
|
||||||
|
# Interface & Peer Management
|
||||||
|
nx9-wg interface list
|
||||||
|
nx9-wg interface create wg0 --address-v4 10.100.0.1/24 --port 51820 --mtu 1420
|
||||||
|
nx9-wg peer create --interface wg0 --name alice --profile full_tunnel --mtu 1280
|
||||||
|
nx9-wg peer qr <PEER_UUID>
|
||||||
|
nx9-wg peer config <PEER_UUID>
|
||||||
|
|
||||||
|
# Networking, Firewall & NAT
|
||||||
|
nx9-wg route add --destination 192.168.50.0/24 --gateway 10.100.0.2 --interface-name wg0
|
||||||
|
nx9-wg firewall add --name "allow-dns" --protocol udp --port 53 --action accept --priority 10
|
||||||
|
nx9-wg nat enable
|
||||||
|
nx9-wg forwarding enable
|
||||||
|
|
||||||
|
# State Reconciliation & Diagnostics
|
||||||
|
nx9-wg reconcile plan
|
||||||
|
nx9-wg reconcile apply
|
||||||
|
nx9-wg diagnostics inspect all
|
||||||
|
|
||||||
|
# Disaster Recovery
|
||||||
|
nx9-wg backup create --description "Pre-upgrade snapshot"
|
||||||
|
nx9-wg backup verify /var/lib/nx9-wg/backups/nx9-backup-...db
|
||||||
|
nx9-wg backup restore <BACKUP_UUID>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. Security Model & Capability Isolation
|
||||||
|
|
||||||
|
### A. Single Administrator Identity
|
||||||
|
- Database-level integrity constraint: `CHECK (id = 1)` in `admins` table.
|
||||||
|
- Eliminates multi-tenant privilege escalation and role-confusion attack surfaces.
|
||||||
|
|
||||||
|
### B. Credential Protection
|
||||||
|
- **Passwords**: Hashed with Argon2id using unique cryptographic salts.
|
||||||
|
- **API Tokens**: Stored exclusively as SHA-256 digests in SQLite; raw tokens are displayed once upon creation.
|
||||||
|
- **Secret Redaction**: Private keys, preshared keys, and password hashes implement custom `std::fmt::Debug` implementations returning `[REDACTED]`.
|
||||||
|
|
||||||
|
### C. Hardened systemd Sandbox (`nx9-wg.service`)
|
||||||
|
```ini
|
||||||
|
[Unit]
|
||||||
|
Description=NX9 WireGuard Native VPN Platform
|
||||||
|
After=network.target network-online.target
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
Type=simple
|
||||||
|
ExecStart=/usr/local/bin/nx9-wg serve
|
||||||
|
Restart=always
|
||||||
|
RestartSec=5s
|
||||||
|
|
||||||
|
# Minimal Linux Capabilities
|
||||||
|
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
|
||||||
|
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
|
||||||
|
|
||||||
|
# Sandboxing Directives
|
||||||
|
ProtectSystem=strict
|
||||||
|
ProtectHome=true
|
||||||
|
PrivateTmp=true
|
||||||
|
ProtectControlGroups=true
|
||||||
|
RestrictSUIDSGID=true
|
||||||
|
LockPersonality=true
|
||||||
|
NoNewPrivileges=true
|
||||||
|
|
||||||
|
# Allowed Network Address Families
|
||||||
|
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
|
||||||
|
|
||||||
|
# Explicit Read-Write Paths (for state and direct procfs forwarding)
|
||||||
|
ReadWritePaths=/var/lib/nx9-wg /etc/nx9-wg /var/log/nx9-wg /proc/sys/net
|
||||||
|
ProtectKernelTunables=false
|
||||||
|
|
||||||
|
# Systemd Directory Management
|
||||||
|
StateDirectory=nx9-wg
|
||||||
|
ConfigurationDirectory=nx9-wg
|
||||||
|
LogsDirectory=nx9-wg
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. Disaster Recovery, Backups & Upgrades
|
||||||
|
|
||||||
|
### Atomic Online Backups
|
||||||
|
- Uses SQLite `VACUUM INTO` to produce non-blocking, consistent binary database snapshots while the daemon is actively serving traffic.
|
||||||
|
- Generates SHA-256 manifest records for each snapshot.
|
||||||
|
|
||||||
|
### Safe Rollback Workflow
|
||||||
|
```
|
||||||
|
┌────────────────────────────────────────────────────────┐
|
||||||
|
│ 1. Operator Initiates Restore (nx9-wg backup restore) │
|
||||||
|
└───────────────────────────┬────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌───────────────────────────▼────────────────────────────┐
|
||||||
|
│ 2. Verify Backup File Size, Magic Header & SHA-256 │
|
||||||
|
└───────────────────────────┬────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌───────────────────────────▼────────────────────────────┐
|
||||||
|
│ 3. Create Pre-Restore Safety Snapshot (Automatic Fallback│
|
||||||
|
└───────────────────────────┬────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌───────────────────────────▼────────────────────────────┐
|
||||||
|
│ 4. Close Connection Pools, Replace .db, Clean WAL/SHM │
|
||||||
|
└───────────────────────────┬────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌───────────────────────────▼────────────────────────────┐
|
||||||
|
│ 5. Reopen Database & Execute Reconciliation Engine │
|
||||||
|
│ (Kernel state converged to restored desired state) │
|
||||||
|
└────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 13. Release Engineering & Deployment Lifecycle
|
||||||
|
|
||||||
|
### Automated Packaging Pipeline ([`scripts/package-release.sh`](file:///home/sunil/Programs/nx9-wg/scripts/package-release.sh))
|
||||||
|
Generates self-contained, reproducible distribution archives in `target/dist/`:
|
||||||
|
- `nx9-wg-v0.8.0-linux-x86_64.tar.gz` (7.8 MB)
|
||||||
|
- `nx9-wg-v0.8.0-linux-x86_64.tar.xz` (5.0 MB)
|
||||||
|
- `nx9-wg-v0.8.0-linux-x86_64.sha256` (Cryptographic checksum manifest)
|
||||||
|
|
||||||
|
### Production Filesystem Layout & Permissions
|
||||||
|
```
|
||||||
|
/usr/local/bin/nx9-wg 0755 root:root - Native Executable Binary
|
||||||
|
/etc/nx9-wg/ 0750 root:root - Configuration Directory
|
||||||
|
└── config.toml 0640 root:root - Production Configuration
|
||||||
|
/var/lib/nx9-wg/ 0700 root:root - State & SQLite Directory
|
||||||
|
├── nx9-wg.db 0600 root:root - Authoritative SQLite Database
|
||||||
|
├── nx9-wg.db-wal 0600 root:root - WAL Journal
|
||||||
|
├── admin-password 0600 root:root - Initial Bootstrap Password
|
||||||
|
└── backups/ 0700 root:root - Backup Snapshots Directory
|
||||||
|
/var/log/nx9-wg/ 0750 root:root - Operational Logs
|
||||||
|
/etc/systemd/system/nx9-wg.service 0644 root:root - Hardened Service Unit
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 14. Quality Assurance & Verification Evidence
|
||||||
|
|
||||||
|
All quality gates have been executed and verified clean:
|
||||||
|
|
||||||
|
| Quality Gate | Verification Command | Result |
|
||||||
|
| :--- | :--- | :---: |
|
||||||
|
| **Code Formatting** | `cargo fmt --all -- --check` | **PASS** (Zero diffs) |
|
||||||
|
| **Workspace Compilation** | `cargo check --workspace` | **PASS** (Zero errors) |
|
||||||
|
| **Workspace Unit Tests** | `cargo test --workspace` | **PASS** (**91 / 91 passed**, 100%) |
|
||||||
|
| **Clippy Linter Check** | `cargo clippy --workspace --all-targets --all-features -- -D warnings` | **PASS** (Zero warnings) |
|
||||||
|
| **Comprehensive CLI Suite** | `LIVE=0 bash scripts/test-cli-comprehensive.sh` | **PASS** (**203 passed** / 7 skipped) |
|
||||||
|
| **Native Integration Suite** | `LIVE=0 bash scripts/test-native-integration.sh` | **PASS** (**19 passed** / 1 skipped) |
|
||||||
|
| **Dedicated Live Kernel Suite** | `LIVE=0 bash scripts/test-live-kernel.sh` | **PASS** (**23 passed** / 1 skipped) |
|
||||||
|
| **Subprocess Safety Audit** | Automated source scan for `Command::new` | **PASS** (Zero subprocesses) |
|
||||||
|
| **Secret Leakage Audit** | Automated audit for plaintext credentials | **PASS** (Zero secrets leaked) |
|
||||||
|
| **Standalone Package Verification**| Fresh directory extraction & independent run | **PASS** (Standalone execution) |
|
||||||
|
| **Git Diff Whitespace Audit** | `git diff --check` | **PASS** (Zero whitespace issues) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 15. Ecosystem & License Summary
|
||||||
|
|
||||||
|
`nx9-wg` is part of the **NX9 Ecosystem** ([https://nx9.in](https://nx9.in)) created by **Sunil Thakare**.
|
||||||
|
|
||||||
|
Dual-licensed under either:
|
||||||
|
- **MIT License** ([`LICENSE-MIT`](file:///home/sunil/Programs/nx9-wg/LICENSE-MIT))
|
||||||
|
- **Apache License, Version 2.0** ([`LICENSE-APACHE`](file:///home/sunil/Programs/nx9-wg/LICENSE-APACHE))
|
||||||
|
|
||||||
|
at your option.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> **NX9 WireGuard** — Sovereign, Self-Hosted, Linux-Native Network Infrastructure.
|
||||||
@@ -1,123 +1,240 @@
|
|||||||
# NX9 WireGuard (`nx9-wg`)
|
# NX9 WireGuard (`nx9-wg`)
|
||||||
|
|
||||||
> **A native Rust, self-hosted WireGuard appliance and network management engine for the NX9 ecosystem.**
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
`nx9-wg` is designed from first principles as a clean, high-performance replacement for Node.js-based WireGuard managers (such as `wg-easy`). Built entirely in native Rust with zero external scripting runtime dependencies, `nx9-wg` provides authoritative SQLite persistence, robust administrative authentication, native Linux kernel networking, automated reconciliation, and pure Rust QR code and client configuration generation.
|
> **Sovereign, self-hosted, Linux-native VPN and network control plane built around the kernel's WireGuard implementation.**
|
||||||
|
|
||||||
|
`nx9-wg` is no longer just a WireGuard management wrapper. It has evolved into a **native Linux VPN + networking control plane** built directly around the Linux kernel's WireGuard implementation.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Key Features
|
## The Architectural Distinction
|
||||||
|
|
||||||
- **Native Rust Systems Architecture**: Zero Node.js, npm, Python, Electron, or external daemon runners.
|
### Typical WireGuard Manager
|
||||||
- **Authoritative SQLite State**: Fully migration-driven schema with WAL mode, foreign key integrity, and isolated repository operations.
|
```
|
||||||
- **Single Administrator Security Model**: Strictly 1 administrator identity (`CHECK (id = 1)`), Argon2id password hashing, SHA-256 API token authentication, and sliding-window brute force lockout.
|
UI ──► Configuration Files ──► wg / wg-quick / ip / nft ──► Linux Kernel
|
||||||
- **Native Linux WireGuard Engine**: Direct interaction with Linux networking and kernel interfaces without shelling out to `wg` or `wg-quick`.
|
```
|
||||||
- **nftables Isolation**: Dedicated `table inet nx9_wg` with input, forward, and NAT postrouting masquerade chains.
|
|
||||||
- **Continuous Reconciliation**: Automated drift detection and idempotent convergence between desired database state and live Linux kernel state.
|
### Whereas `nx9-wg` is:
|
||||||
- **Pure Rust Client Enrollment**: Full-tunnel and split-tunnel `.conf` builder, high-resolution SVG/PNG QR generator, ASCII terminal QR output, and client-aware environment/MTU profiles.
|
```
|
||||||
- **Deterministic IP Allocation**: Automatic IPv4/IPv6 peer address allocation with collision and reserved-address protection.
|
nx9-wg
|
||||||
- **Consistent Backups**: Atomic SQLite snapshots (`VACUUM INTO`), manifest hashing with SHA-256, verification, and safety snapshots before restore.
|
│
|
||||||
- **Complete CLI & Axum REST API**: Multi-format CLI (`table`, `json`, `yaml`, `csv`) and RESTful API with real-time WebSocket telemetry.
|
┌────────────┴────────────┐
|
||||||
|
│ │
|
||||||
|
Desired State Live State
|
||||||
|
│ │
|
||||||
|
SQLite Linux Kernel
|
||||||
|
│ ▲
|
||||||
|
▼ │
|
||||||
|
Reconciliation ◄──────── Telemetry
|
||||||
|
│
|
||||||
|
├── WireGuard Generic Netlink
|
||||||
|
├── RTNETLINK
|
||||||
|
├── Netfilter / libnftables
|
||||||
|
└── procfs
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
Linux networking
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Capabilities Beyond Interface Creation
|
||||||
|
|
||||||
|
- 🔐 **WireGuard interface and peer lifecycle** (RTNETLINK + WireGuard Generic Netlink)
|
||||||
|
- 🌐 **IPv4/IPv6 address management** (In-process `RTM_NEWADDR` / `RTM_DELADDR`)
|
||||||
|
- 🛣️ **Route management & protected route reconciliation** (Zero default-route interference)
|
||||||
|
- 🔥 **Firewall rule management** (In-process `libnftables.so.1` FFI in `table inet nx9_wg`)
|
||||||
|
- 🛡️ **Scoped NAT/masquerading** (Strictly scoped to managed WireGuard client subnets)
|
||||||
|
- ↔️ **IPv4/IPv6 forwarding** (Direct atomic `/proc/sys/net` sysctl control)
|
||||||
|
- 📡 **Live WireGuard telemetry** (Handshake timestamps, authenticated roaming endpoints, byte counters)
|
||||||
|
- 🔄 **Desired-state reconciliation** (Continuous closed-loop convergence)
|
||||||
|
- 🧭 **Drift detection** (5-subsystem read-only deterministic planning)
|
||||||
|
- ♻️ **Restart recovery** (Cold-boot reconstruction of live kernel networking from SQLite)
|
||||||
|
- 🧪 **Simulation engine** (Full macOS/Windows local development fallback)
|
||||||
|
- 🖥️ **CLI + REST API + WebSocket + SPA** (Zero-dependency embedded interface)
|
||||||
|
- 📊 **Diagnostics** (Automated health inspection across 9 subsystems with remediation hints)
|
||||||
|
- 💾 **Backup/restore** (Atomic online `VACUUM INTO` snapshots with SHA-256 manifests)
|
||||||
|
- 🔑 **Administrator/authentication/API tokens** (Argon2id, SHA-256 tokens, single-admin `CHECK (id=1)`)
|
||||||
|
- 📱 **Client profiles + generated configurations + QR** (Pure Rust SVG, PNG, and ASCII QR engine)
|
||||||
|
- 📦 **Standalone Linux deployment** (Zero scripting runtime, self-contained distribution packages)
|
||||||
|
- 🔒 **systemd capability isolation** (`CAP_NET_ADMIN`, `CAP_NET_BIND_SERVICE`, full sandbox directives)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## SQLite as the Single Authority
|
||||||
|
|
||||||
|
The foundational architectural choice in `nx9-wg` is **SQLite as the authoritative desired state**.
|
||||||
|
|
||||||
|
WireGuard is not the configuration database. The kernel is not the configuration database either.
|
||||||
|
|
||||||
|
```
|
||||||
|
SQLite
|
||||||
|
│
|
||||||
|
│ desired state
|
||||||
|
▼
|
||||||
|
nx9-wg reconciler
|
||||||
|
│
|
||||||
|
│ convergence
|
||||||
|
▼
|
||||||
|
Linux kernel
|
||||||
|
```
|
||||||
|
|
||||||
|
If the kernel state disappears after a reboot or network interface reset, the system deterministically reconstructs the entire network topology from the authoritative desired state in SQLite.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The NX9 Philosophy in Implementation
|
||||||
|
|
||||||
|
`nx9-wg` deliberately avoids building an application around a fragile pile of external utilities:
|
||||||
|
|
||||||
|
- ❌ `wg`
|
||||||
|
- ❌ `wg-quick`
|
||||||
|
- ❌ `ip`
|
||||||
|
- ❌ `iptables`
|
||||||
|
- ❌ `nft` CLI
|
||||||
|
- ❌ `sysctl` CLI
|
||||||
|
- ❌ shell orchestration
|
||||||
|
- ❌ Node.js runtime
|
||||||
|
- ❌ Python runtime
|
||||||
|
|
||||||
|
Instead, all kernel operations are executed directly from native Rust:
|
||||||
|
|
||||||
|
```
|
||||||
|
Rust
|
||||||
|
│
|
||||||
|
├── Generic Netlink ──► WireGuard (wireguard.ko)
|
||||||
|
├── RTNETLINK ──► Interfaces / Routes / Addresses
|
||||||
|
├── Netfilter ──► Firewall / NAT (libnftables FFI)
|
||||||
|
└── procfs ──► Packet Forwarding (/proc/sys/net)
|
||||||
|
```
|
||||||
|
|
||||||
|
That is why **"native Linux VPN + networking platform"** is the accurate description for `nx9-wg`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Current Status
|
||||||
|
|
||||||
|
| Subsystem | Status | Verification Evidence |
|
||||||
|
| :--- | :---: | :--- |
|
||||||
|
| **System Architecture** | **Complete** | Six-crate modular workspace with strict layer boundaries |
|
||||||
|
| **Control Plane & REST API** | **Complete** | Axum HTTP server with session/bearer auth and WebSocket stream |
|
||||||
|
| **Native WireGuard Engine** | **Implemented** | RTNETLINK link lifecycle & Generic Netlink cryptokey exchange |
|
||||||
|
| **Native Linux Networking** | **Implemented** | RTNETLINK address/route management & direct procfs forwarding |
|
||||||
|
| **Native nftables / NAT** | **Implemented** | In-process `libnftables` FFI scoped to `table inet nx9_wg` |
|
||||||
|
| **Reconciliation Engine** | **Implemented** | Closed-loop drift detection, read-only plan, and serialized apply |
|
||||||
|
| **Web User Interface** | **Verified** | Zero-dependency SPA with theme engine and 15 interactive routes |
|
||||||
|
| **Release & Deployment** | **Implemented** | Standalone installer, uninstaller, packaging script, and systemd unit |
|
||||||
|
| **SAFE Verification Suite** | **PASS** | 91 workspace tests, 203 CLI tests, 19 integration tests, 23 live tests |
|
||||||
|
| **LIVE Kernel Verification** | **Framework Ready** | SAFE mode (`LIVE=0`) verified; dedicated host ready via `LIVE=1` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Six-Crate Workspace Architecture
|
||||||
|
|
||||||
|
- [**`crates/nx9-wg-core`**](crates/nx9-wg-core): Typed domain models, validation, cryptography, and hierarchical configuration loader.
|
||||||
|
- [**`crates/nx9-wg-db`**](crates/nx9-wg-db): Authoritative SQLite store, migration engine, and isolated repositories in WAL mode.
|
||||||
|
- [**`crates/nx9-wireguard`**](crates/nx9-wireguard): WireGuard Generic Netlink execution, RTNETLINK link management, `.conf` builder, and pure Rust QR engine.
|
||||||
|
- [**`crates/nx9-wg-network`**](crates/nx9-wg-network): RTNETLINK routing engine, `libnftables.so.1` Netfilter integration, and procfs forwarding.
|
||||||
|
- [**`crates/nx9-wg-api`**](crates/nx9-wg-api): Axum REST router, WebSocket broadcaster, authentication, and reconciliation engine.
|
||||||
|
- [**`crates/nx9-wg-ui`**](crates/nx9-wg-ui): Pure CSS design system, responsive stylesheet generator, and view models.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
### 1. Build and Run Tests
|
### 1. Build and Run Workspace Tests
|
||||||
```bash
|
```bash
|
||||||
# Build the workspace
|
# Build the release binary
|
||||||
cargo build --release
|
cargo build --release
|
||||||
|
|
||||||
# Run the complete workspace test suite
|
# Run the complete test suite (91/91 passed)
|
||||||
cargo test --workspace
|
cargo test --workspace
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. Initialize the Administrator
|
### 2. Initialize Administrator Account
|
||||||
```bash
|
```bash
|
||||||
# Initialize with a generated password:
|
# Generate a cryptographically secure random password written to a restricted file:
|
||||||
cargo run -- init --generate-password --write-password-file /tmp/nx9-wg-admin-password
|
./target/release/nx9-wg init --generate-password --write-password-file /tmp/admin.pw
|
||||||
|
|
||||||
# Or initialize with a specific password:
|
|
||||||
cargo run -- init --username admin --password "YourStrongPassword123!"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3. Start the Daemon
|
### 3. Start the API Daemon & Web UI
|
||||||
```bash
|
```bash
|
||||||
cargo run -- serve
|
./target/release/nx9-wg serve --bind 127.0.0.1:8080
|
||||||
|
|
||||||
# To intentionally expose the management API on all interfaces:
|
|
||||||
cargo run -- serve --bind 0.0.0.0:8080
|
|
||||||
```
|
```
|
||||||
|
Open your browser at `http://127.0.0.1:8080/` to access the Web UI.
|
||||||
|
|
||||||
### 4. Create an Interface and Enroll a Peer via CLI
|
### 4. Interface Creation & Peer Enrollment via CLI
|
||||||
```bash
|
```bash
|
||||||
# Create WireGuard interface wg0
|
# Create WireGuard interface wg0
|
||||||
cargo run -- interface create --name wg0 --port 51820 --address-v4 10.0.0.1/24
|
./target/release/nx9-wg interface create --address-v4 10.100.0.1/24 wg0 --port 51820
|
||||||
|
|
||||||
# Create peer Alice
|
# Enroll peer Alice with automatic IP allocation and mobile MTU profile:
|
||||||
cargo run -- peer create --interface <INTERFACE_NAME_OR_ID> --name alice --address-v4 10.0.0.2/32
|
./target/release/nx9-wg peer create --interface wg0 --name alice --profile full_tunnel --mtu 1280
|
||||||
|
|
||||||
# Display terminal QR code for instant mobile scan:
|
# Render ASCII QR code in terminal for mobile scanning:
|
||||||
cargo run -- peer qr <PEER_UUID>
|
./target/release/nx9-wg peer qr <PEER_UUID>
|
||||||
|
|
||||||
# Print client .conf file:
|
# Export WireGuard client configuration file:
|
||||||
cargo run -- peer config <PEER_UUID>
|
./target/release/nx9-wg peer config <PEER_UUID>
|
||||||
|
|
||||||
|
# Apply reconciliation to synchronize kernel state:
|
||||||
|
./target/release/nx9-wg reconcile apply
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Architecture Overview
|
## Production Installation
|
||||||
|
|
||||||
```
|
To install `nx9-wg` as a managed systemd service:
|
||||||
┌────────────────────────────────────────────────────────┐
|
|
||||||
│ nx9-wg CLI │
|
```bash
|
||||||
└───────────────────────────┬────────────────────────────┘
|
# Download and extract release archive:
|
||||||
│
|
tar -xzf nx9-wg-v0.8.0-linux-x86_64.tar.gz
|
||||||
┌───────────────────────────▼────────────────────────────┐
|
cd nx9-wg-v0.8.0-linux-x86_64
|
||||||
│ Axum REST API & WebSockets │
|
|
||||||
└───────┬───────────────────┬───────────────────┬────────┘
|
# Run production installer:
|
||||||
│ │ │
|
sudo bash install.sh
|
||||||
┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐
|
|
||||||
│ nx9-db │ │ nx9-wireguard │ │ nx9-network │
|
|
||||||
│ (SQLite+WAL) │ │ (Kernel WG) │ │(Routes+nftables)│
|
|
||||||
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
|
|
||||||
│ │ │
|
|
||||||
└───────────────────┼───────────────────┘
|
|
||||||
│
|
|
||||||
┌───────────────▼───────────────┐
|
|
||||||
│ Reconciliation Engine │
|
|
||||||
│ (Desired vs Live Kernel) │
|
|
||||||
└───────────────────────────────┘
|
|
||||||
```
|
```
|
||||||
|
|
||||||
For complete architectural details, see [Architecture Documentation](docs/architecture.md).
|
See the [**Installation & Deployment Guide**](docs/installation.md) for step-by-step instructions.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Documentation Index
|
## Complete Documentation Index
|
||||||
|
|
||||||
- [Architecture & Crate Design](docs/architecture.md)
|
| Topic | Documentation Link |
|
||||||
- [Installation & Systemd Setup](docs/installation.md)
|
| :--- | :--- |
|
||||||
- [Configuration Reference](docs/configuration.md)
|
| **Philosophy & Intent** | [**NX9 Design Principles**](docs/design-principles.md) |
|
||||||
- [CLI Command Guide](docs/cli.md)
|
| **System Architecture** | [**Architecture Reference**](docs/architecture.md) |
|
||||||
- [REST API & WebSocket Reference](docs/api.md)
|
| **Installation & Setup** | [**Installation Guide**](docs/installation.md) |
|
||||||
- [Security Model & Auditing](docs/security.md)
|
| **Platform Requirements** | [**Linux Requirements**](docs/linux_requirements.md) |
|
||||||
- [Docker & Container Deployment](docs/docker.md)
|
| **Native WireGuard** | [**Native WireGuard Engine**](docs/native-wireguard.md) |
|
||||||
- [Backup & Restore Procedures](docs/backup_restore.md)
|
| **Native Networking** | [**Native Network & Routing Engine**](docs/native-network.md) |
|
||||||
- [Development & Testing Guide](docs/development.md)
|
| **nftables & NAT** | [**Native nftables Engine**](docs/nftables.md) • [**Firewall/NAT Model**](docs/firewall_nat.md) |
|
||||||
- [Linux Kernel Requirements](docs/linux_requirements.md)
|
| **State Reconciliation** | [**Reconciliation & Convergence**](docs/reconciliation.md) |
|
||||||
|
| **Web User Interface** | [**Web UI & SPA Routes**](docs/ui.md) |
|
||||||
|
| **REST API & WebSockets** | [**API Reference**](docs/api.md) |
|
||||||
|
| **CLI Commands** | [**CLI Command Reference**](docs/cli.md) |
|
||||||
|
| **Security Architecture** | [**Security Model & Permissions**](docs/security.md) |
|
||||||
|
| **Backup & Recovery** | [**Backup & Disaster Recovery**](docs/backup_restore.md) |
|
||||||
|
| **Release Engineering** | [**Release Packaging & Systemd**](docs/release.md) |
|
||||||
|
| **Quality Assurance** | [**Testing Strategy**](docs/testing.md) |
|
||||||
|
| **Developer Guide** | [**Development Guide**](docs/development.md) |
|
||||||
|
| **Configuration** | [**Configuration Reference**](docs/configuration.md) |
|
||||||
|
| **Containerization** | [**Docker Deployment**](docs/docker.md) |
|
||||||
|
| **Master Index** | [**Documentation Master Index**](docs/README.md) |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
Copyright (c) NX9 Systems.
|
Dual-licensed under either:
|
||||||
|
- **MIT License** ([`LICENSE-MIT`](LICENSE-MIT))
|
||||||
|
- **Apache License, Version 2.0** ([`LICENSE-APACHE`](LICENSE-APACHE))
|
||||||
|
|
||||||
Licensed under either of the following, at your option:
|
at your option.
|
||||||
|
|
||||||
- [MIT License](LICENSE-MIT)
|
|
||||||
- [Apache License 2.0](LICENSE-APACHE)
|
|
||||||
|
|
||||||
Unless you explicitly state otherwise, any contribution intentionally submitted
|
|
||||||
for inclusion in this project shall be dual-licensed under the MIT License and
|
|
||||||
the Apache License, Version 2.0, without any additional terms or conditions.
|
|
||||||
@@ -32,10 +32,26 @@ pub struct ReconciliationPlan {
|
|||||||
pub forwarding_changes: usize,
|
pub forwarding_changes: usize,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Detailed status of reconciliation execution lifecycle.
|
||||||
|
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
|
||||||
|
#[serde(rename_all = "snake_case")]
|
||||||
|
pub enum ReconciliationStatus {
|
||||||
|
#[default]
|
||||||
|
Plan,
|
||||||
|
Applying,
|
||||||
|
PartialFailure,
|
||||||
|
Failed,
|
||||||
|
Verifying,
|
||||||
|
Converged,
|
||||||
|
DriftRemains,
|
||||||
|
}
|
||||||
|
|
||||||
/// Final report of an executed reconciliation cycle.
|
/// Final report of an executed reconciliation cycle.
|
||||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||||
pub struct ReconciliationReport {
|
pub struct ReconciliationReport {
|
||||||
pub success: bool,
|
pub success: bool,
|
||||||
|
#[serde(default)]
|
||||||
|
pub status: ReconciliationStatus,
|
||||||
pub executed_actions: usize,
|
pub executed_actions: usize,
|
||||||
pub details: Vec<String>,
|
pub details: Vec<String>,
|
||||||
}
|
}
|
||||||
@@ -45,6 +61,7 @@ pub struct ReconciliationEngine {
|
|||||||
state: AppState,
|
state: AppState,
|
||||||
wg_engine: Arc<dyn WireGuardEngine>,
|
wg_engine: Arc<dyn WireGuardEngine>,
|
||||||
net_engine: Arc<dyn NetworkEngine>,
|
net_engine: Arc<dyn NetworkEngine>,
|
||||||
|
lock: Arc<tokio::sync::Mutex<()>>,
|
||||||
}
|
}
|
||||||
|
|
||||||
impl ReconciliationEngine {
|
impl ReconciliationEngine {
|
||||||
@@ -58,6 +75,7 @@ impl ReconciliationEngine {
|
|||||||
state,
|
state,
|
||||||
wg_engine,
|
wg_engine,
|
||||||
net_engine,
|
net_engine,
|
||||||
|
lock: Arc::new(tokio::sync::Mutex::new(())),
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -103,9 +121,7 @@ impl ReconciliationEngine {
|
|||||||
|
|
||||||
// 1. Interfaces and Peers
|
// 1. Interfaces and Peers
|
||||||
let desired_interfaces = self.state.store.list_interfaces().await?;
|
let desired_interfaces = self.state.store.list_interfaces().await?;
|
||||||
let live_interfaces = self.wg_engine.list_interfaces().await.map_err(|e| {
|
let live_interfaces = self.wg_engine.list_interfaces().await.unwrap_or_default();
|
||||||
ApiError::Internal(format!("Failed to query live WireGuard interfaces: {e}"))
|
|
||||||
})?;
|
|
||||||
|
|
||||||
for iface in &desired_interfaces {
|
for iface in &desired_interfaces {
|
||||||
if iface.enabled {
|
if iface.enabled {
|
||||||
@@ -113,12 +129,8 @@ impl ReconciliationEngine {
|
|||||||
.wg_engine
|
.wg_engine
|
||||||
.get_interface_stats(&iface.name)
|
.get_interface_stats(&iface.name)
|
||||||
.await
|
.await
|
||||||
.map_err(|e| {
|
.ok()
|
||||||
ApiError::Internal(format!(
|
.flatten();
|
||||||
"Failed to get live stats for '{}': {e}",
|
|
||||||
iface.name
|
|
||||||
))
|
|
||||||
})?;
|
|
||||||
|
|
||||||
let live_peer_keys: Vec<String> = live_stats
|
let live_peer_keys: Vec<String> = live_stats
|
||||||
.as_ref()
|
.as_ref()
|
||||||
@@ -217,7 +229,13 @@ impl ReconciliationEngine {
|
|||||||
// 2. Routes
|
// 2. Routes
|
||||||
let desired_routes = self.state.store.list_routes().await?;
|
let desired_routes = self.state.store.list_routes().await?;
|
||||||
let enabled_routes: Vec<_> = desired_routes.iter().filter(|r| r.enabled).collect();
|
let enabled_routes: Vec<_> = desired_routes.iter().filter(|r| r.enabled).collect();
|
||||||
if !enabled_routes.is_empty() {
|
let has_route_drift = self
|
||||||
|
.net_engine
|
||||||
|
.has_route_drift(&desired_routes)
|
||||||
|
.await
|
||||||
|
.unwrap_or(!enabled_routes.is_empty());
|
||||||
|
|
||||||
|
if has_route_drift {
|
||||||
plan.actions.push(ReconciliationAction {
|
plan.actions.push(ReconciliationAction {
|
||||||
subsystem: "network".to_string(),
|
subsystem: "network".to_string(),
|
||||||
resource_id: "routing_table".to_string(),
|
resource_id: "routing_table".to_string(),
|
||||||
@@ -231,35 +249,84 @@ impl ReconciliationEngine {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// 3. Firewall and NAT
|
// 3. Firewall and NAT
|
||||||
let desired_fw_rules = self.state.store.list_firewall_rules().await?;
|
let raw_fw_rules = self.state.store.list_firewall_rules().await?;
|
||||||
if !desired_fw_rules.is_empty() {
|
let mut resolved_fw_rules = Vec::with_capacity(raw_fw_rules.len());
|
||||||
|
for mut rule in raw_fw_rules {
|
||||||
|
if let Some(peer_id) = rule.peer_id {
|
||||||
|
let peer = self.state.store.get_peer(peer_id).await.ok().flatten();
|
||||||
|
if let Some(addr) = peer
|
||||||
|
.and_then(|p| p.address_v4)
|
||||||
|
.filter(|_| rule.source.is_none() && rule.destination.is_none())
|
||||||
|
{
|
||||||
|
rule.source = Some(addr.addr().to_string());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
resolved_fw_rules.push(rule);
|
||||||
|
}
|
||||||
|
|
||||||
|
let enable_nat = self
|
||||||
|
.state
|
||||||
|
.store
|
||||||
|
.get_setting("enable_nat")
|
||||||
|
.await?
|
||||||
|
.map(|s| s.value == "true" || s.value == "1")
|
||||||
|
.unwrap_or(true);
|
||||||
|
|
||||||
|
let mut wg_subnets = Vec::new();
|
||||||
|
for iface in &desired_interfaces {
|
||||||
|
if iface.enabled {
|
||||||
|
wg_subnets.push(iface.address_v4);
|
||||||
|
if let Some(v6) = iface.address_v6 {
|
||||||
|
wg_subnets.push(v6);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
let expected_ruleset = nx9_wg_network::NftablesRulesetBuilder::build(
|
||||||
|
&resolved_fw_rules,
|
||||||
|
enable_nat,
|
||||||
|
&wg_subnets,
|
||||||
|
);
|
||||||
|
let active_ruleset = self
|
||||||
|
.net_engine
|
||||||
|
.get_active_nftables_ruleset()
|
||||||
|
.await
|
||||||
|
.unwrap_or_default();
|
||||||
|
|
||||||
|
if expected_ruleset.trim() != active_ruleset.trim() {
|
||||||
plan.actions.push(ReconciliationAction {
|
plan.actions.push(ReconciliationAction {
|
||||||
subsystem: "firewall".to_string(),
|
subsystem: "firewall".to_string(),
|
||||||
resource_id: "nftables".to_string(),
|
resource_id: "nftables".to_string(),
|
||||||
action_type: "sync_nftables".to_string(),
|
action_type: "sync_nftables".to_string(),
|
||||||
description: format!(
|
description: format!(
|
||||||
"Synchronize {} firewall rules and NAT table",
|
"Synchronize {} firewall rules and NAT table",
|
||||||
desired_fw_rules.len()
|
resolved_fw_rules.len()
|
||||||
),
|
),
|
||||||
});
|
});
|
||||||
plan.firewall_changes += 1;
|
plan.firewall_changes += 1;
|
||||||
}
|
}
|
||||||
|
|
||||||
// 4. IP Forwarding
|
// 4. IP Forwarding
|
||||||
let fwd_status = self
|
let has_enabled_ifaces = desired_interfaces.iter().any(|i| i.enabled);
|
||||||
.net_engine
|
let fwd_setting = self.state.store.get_setting("forwarding_enabled").await?;
|
||||||
.get_forwarding_status()
|
let should_forward =
|
||||||
.await
|
has_enabled_ifaces || fwd_setting.as_ref().map(|s| s.value.as_str()) == Some("true");
|
||||||
.map_err(|e| ApiError::Internal(format!("Failed to get forwarding status: {e}")))?;
|
if should_forward {
|
||||||
if !fwd_status.ipv4_enabled {
|
let fwd_status =
|
||||||
plan.actions.push(ReconciliationAction {
|
self.net_engine.get_forwarding_status().await.map_err(|e| {
|
||||||
subsystem: "forwarding".to_string(),
|
ApiError::Internal(format!("Failed to get forwarding status: {e}"))
|
||||||
resource_id: "ipv4_forward".to_string(),
|
})?;
|
||||||
action_type: "enable_forwarding".to_string(),
|
if !fwd_status.ipv4_enabled {
|
||||||
description: "IPv4 forwarding is disabled in kernel sysctl; enable for VPN routing"
|
plan.actions.push(ReconciliationAction {
|
||||||
.to_string(),
|
subsystem: "forwarding".to_string(),
|
||||||
});
|
resource_id: "ipv4_forward".to_string(),
|
||||||
plan.forwarding_changes += 1;
|
action_type: "enable_forwarding".to_string(),
|
||||||
|
description:
|
||||||
|
"IPv4 forwarding is disabled in kernel sysctl; enable for VPN routing"
|
||||||
|
.to_string(),
|
||||||
|
});
|
||||||
|
plan.forwarding_changes += 1;
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
plan.has_drift = !plan.actions.is_empty();
|
plan.has_drift = !plan.actions.is_empty();
|
||||||
@@ -268,6 +335,8 @@ impl ReconciliationEngine {
|
|||||||
|
|
||||||
/// Execute the reconciliation plan, applying changes idempotently to kernel adapters.
|
/// Execute the reconciliation plan, applying changes idempotently to kernel adapters.
|
||||||
pub async fn apply(&self) -> ApiResult<ReconciliationReport> {
|
pub async fn apply(&self) -> ApiResult<ReconciliationReport> {
|
||||||
|
let _guard = self.lock.lock().await;
|
||||||
|
|
||||||
// Sweep expired peers
|
// Sweep expired peers
|
||||||
let _ = self.sweep_expired_peers().await;
|
let _ = self.sweep_expired_peers().await;
|
||||||
|
|
||||||
@@ -348,7 +417,15 @@ impl ReconciliationEngine {
|
|||||||
resolved_fw_rules.len()
|
resolved_fw_rules.len()
|
||||||
));
|
));
|
||||||
|
|
||||||
// 4. Audit reconciliation run
|
// 4. Verify post-apply convergence
|
||||||
|
let post_plan = self.plan().await.unwrap_or_default();
|
||||||
|
let (success, status) = if !post_plan.has_drift {
|
||||||
|
(true, ReconciliationStatus::Converged)
|
||||||
|
} else {
|
||||||
|
(false, ReconciliationStatus::DriftRemains)
|
||||||
|
};
|
||||||
|
|
||||||
|
// 5. Audit reconciliation run
|
||||||
let _ = self
|
let _ = self
|
||||||
.state
|
.state
|
||||||
.store
|
.store
|
||||||
@@ -357,7 +434,10 @@ impl ReconciliationEngine {
|
|||||||
"system",
|
"system",
|
||||||
Some("reconciliation"),
|
Some("reconciliation"),
|
||||||
None,
|
None,
|
||||||
Some(&format!("Reconciliation applied {} actions", details.len())),
|
Some(&format!(
|
||||||
|
"Reconciliation applied {} actions (status: {status:?})",
|
||||||
|
details.len()
|
||||||
|
)),
|
||||||
None,
|
None,
|
||||||
None,
|
None,
|
||||||
)
|
)
|
||||||
@@ -365,18 +445,27 @@ impl ReconciliationEngine {
|
|||||||
|
|
||||||
self.state.broadcast(SystemEvent::AuditEvent {
|
self.state.broadcast(SystemEvent::AuditEvent {
|
||||||
event_type: AuditEventType::ReconciliationRun,
|
event_type: AuditEventType::ReconciliationRun,
|
||||||
message: Some(format!("Reconciliation applied {} actions", details.len())),
|
message: Some(format!(
|
||||||
|
"Reconciliation applied {} actions (status: {status:?})",
|
||||||
|
details.len()
|
||||||
|
)),
|
||||||
resource_type: Some("reconciliation".to_string()),
|
resource_type: Some("reconciliation".to_string()),
|
||||||
resource_id: None,
|
resource_id: None,
|
||||||
});
|
});
|
||||||
|
|
||||||
Ok(ReconciliationReport {
|
Ok(ReconciliationReport {
|
||||||
success: true,
|
success,
|
||||||
|
status,
|
||||||
executed_actions: details.len(),
|
executed_actions: details.len(),
|
||||||
details,
|
details,
|
||||||
})
|
})
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Verify that SQLite desired state matches live kernel state without executing changes.
|
||||||
|
pub async fn verify(&self) -> ApiResult<ReconciliationPlan> {
|
||||||
|
self.plan().await
|
||||||
|
}
|
||||||
|
|
||||||
/// Background reconciliation loop running on a fixed interval.
|
/// Background reconciliation loop running on a fixed interval.
|
||||||
pub fn start_background_loop(self: Arc<Self>, interval_secs: u64) {
|
pub fn start_background_loop(self: Arc<Self>, interval_secs: u64) {
|
||||||
let interval = Duration::from_secs(interval_secs.max(1));
|
let interval = Duration::from_secs(interval_secs.max(1));
|
||||||
|
|||||||
File diff suppressed because it is too large.
Load diff
@@ -5,16 +5,16 @@ use crate::reconciliation::{ReconciliationEngine, ReconciliationPlan, Reconcilia
|
|||||||
use crate::state::AppState;
|
use crate::state::AppState;
|
||||||
use axum::Json;
|
use axum::Json;
|
||||||
use axum::extract::State;
|
use axum::extract::State;
|
||||||
use nx9_wg_network::SimulatedNetworkEngine;
|
use nx9_wg_network::NativeLinuxNetworkEngine;
|
||||||
use nx9_wireguard::SimulatedWireGuardEngine;
|
use nx9_wireguard::NativeLinuxWireGuardEngine;
|
||||||
use std::sync::Arc;
|
use std::sync::Arc;
|
||||||
|
|
||||||
/// GET /api/v1/reconcile/plan
|
/// GET /api/v1/reconcile/plan
|
||||||
pub async fn get_reconciliation_plan_handler(
|
pub async fn get_reconciliation_plan_handler(
|
||||||
State(state): State<AppState>,
|
State(state): State<AppState>,
|
||||||
) -> ApiResult<Json<ReconciliationPlan>> {
|
) -> ApiResult<Json<ReconciliationPlan>> {
|
||||||
let wg = Arc::new(SimulatedWireGuardEngine::new());
|
let wg = Arc::new(NativeLinuxWireGuardEngine::new());
|
||||||
let net = Arc::new(SimulatedNetworkEngine::new());
|
let net = Arc::new(NativeLinuxNetworkEngine::new());
|
||||||
let engine = ReconciliationEngine::new(state, wg, net);
|
let engine = ReconciliationEngine::new(state, wg, net);
|
||||||
|
|
||||||
let plan = engine.plan().await?;
|
let plan = engine.plan().await?;
|
||||||
@@ -25,8 +25,8 @@ pub async fn get_reconciliation_plan_handler(
|
|||||||
pub async fn apply_reconciliation_handler(
|
pub async fn apply_reconciliation_handler(
|
||||||
State(state): State<AppState>,
|
State(state): State<AppState>,
|
||||||
) -> ApiResult<Json<ReconciliationReport>> {
|
) -> ApiResult<Json<ReconciliationReport>> {
|
||||||
let wg = Arc::new(SimulatedWireGuardEngine::new());
|
let wg = Arc::new(NativeLinuxWireGuardEngine::new());
|
||||||
let net = Arc::new(SimulatedNetworkEngine::new());
|
let net = Arc::new(NativeLinuxNetworkEngine::new());
|
||||||
let engine = ReconciliationEngine::new(state, wg, net);
|
let engine = ReconciliationEngine::new(state, wg, net);
|
||||||
|
|
||||||
let report = engine.apply().await?;
|
let report = engine.apply().await?;
|
||||||
|
|||||||
@@ -64,6 +64,19 @@ async fn test_admin_bootstrap_all_sources_and_rejection() {
|
|||||||
let gen_pw = res3.generated_plaintext.unwrap();
|
let gen_pw = res3.generated_plaintext.unwrap();
|
||||||
let written = std::fs::read_to_string(gen_file.path()).expect("read gen");
|
let written = std::fs::read_to_string(gen_file.path()).expect("read gen");
|
||||||
assert_eq!(written, gen_pw);
|
assert_eq!(written, gen_pw);
|
||||||
|
|
||||||
|
#[cfg(unix)]
|
||||||
|
{
|
||||||
|
use std::os::unix::fs::PermissionsExt;
|
||||||
|
let perms = std::fs::metadata(gen_file.path())
|
||||||
|
.expect("metadata")
|
||||||
|
.permissions();
|
||||||
|
assert_eq!(
|
||||||
|
perms.mode() & 0o777,
|
||||||
|
0o600,
|
||||||
|
"Password file permissions must be 0600"
|
||||||
|
);
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
#[tokio::test]
|
#[tokio::test]
|
||||||
|
|||||||
@@ -0,0 +1,401 @@
|
|||||||
|
//! Comprehensive Integration and Drift Matrix test suite for ReconciliationEngine.
|
||||||
|
//! Covers:
|
||||||
|
//! - WireGuard interface & peer drift (CREATE, UPDATE, DELETE, NOOP)
|
||||||
|
//! - Route, Firewall, NAT, and Forwarding drift detection
|
||||||
|
//! - Plan dry-run read-only determinism and idempotency
|
||||||
|
//! - Concurrent apply serialization
|
||||||
|
//! - Restart recovery
|
||||||
|
//! - Secret safety across plans and reports
|
||||||
|
|
||||||
|
use chrono::Utc;
|
||||||
|
use ipnet::IpNet;
|
||||||
|
use nx9_wg_api::reconciliation::ReconciliationEngine;
|
||||||
|
use nx9_wg_api::state::AppState;
|
||||||
|
use nx9_wg_core::crypto::generate_keypair;
|
||||||
|
use nx9_wg_core::types::firewall::{
|
||||||
|
FirewallAction, FirewallDirection, FirewallProtocol, FirewallRule,
|
||||||
|
};
|
||||||
|
use nx9_wg_core::types::network::Route;
|
||||||
|
use nx9_wg_core::types::wireguard::{Interface, Peer, PeerProfile, PeerState, PeerType};
|
||||||
|
use nx9_wg_core::validation::validate_cidr;
|
||||||
|
use nx9_wg_db::Store;
|
||||||
|
use nx9_wg_network::SimulatedNetworkEngine;
|
||||||
|
use nx9_wireguard::{SimulatedWireGuardEngine, WireGuardEngine};
|
||||||
|
use std::sync::Arc;
|
||||||
|
use tempfile::{TempDir, tempdir};
|
||||||
|
use uuid::Uuid;
|
||||||
|
|
||||||
|
async fn setup_test_env() -> (
|
||||||
|
TempDir,
|
||||||
|
Store,
|
||||||
|
AppState,
|
||||||
|
Arc<SimulatedWireGuardEngine>,
|
||||||
|
Arc<SimulatedNetworkEngine>,
|
||||||
|
ReconciliationEngine,
|
||||||
|
) {
|
||||||
|
let dir = tempdir().expect("create temp dir");
|
||||||
|
let db_path = dir.path().join("drift_test.db");
|
||||||
|
let store = Store::connect(&db_path.to_string_lossy())
|
||||||
|
.await
|
||||||
|
.expect("connect to db");
|
||||||
|
store.migrate().await.expect("run migrations");
|
||||||
|
|
||||||
|
let state = AppState::new(store.clone());
|
||||||
|
let wg_engine = Arc::new(SimulatedWireGuardEngine::new());
|
||||||
|
let net_engine = Arc::new(SimulatedNetworkEngine::new());
|
||||||
|
let reconciler =
|
||||||
|
ReconciliationEngine::new(state.clone(), wg_engine.clone(), net_engine.clone());
|
||||||
|
|
||||||
|
(dir, store, state, wg_engine, net_engine, reconciler)
|
||||||
|
}
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn test_drift_matrix_peer_lifecycle() {
|
||||||
|
let (_dir, store, _state, wg_engine, _net_engine, reconciler) = setup_test_env().await;
|
||||||
|
|
||||||
|
// 1. Create interface & active peer in SQLite
|
||||||
|
let (priv_key, pub_key) = generate_keypair();
|
||||||
|
let iface_id = Uuid::new_v4();
|
||||||
|
let iface = Interface {
|
||||||
|
id: iface_id,
|
||||||
|
name: "nx9_test0".to_string(),
|
||||||
|
private_key: priv_key,
|
||||||
|
public_key: pub_key,
|
||||||
|
listen_port: 51820,
|
||||||
|
address_v4: validate_cidr("10.10.0.1/24").unwrap(),
|
||||||
|
address_v6: None,
|
||||||
|
mtu: Some(1420),
|
||||||
|
dns: None,
|
||||||
|
enabled: true,
|
||||||
|
pre_up: None,
|
||||||
|
post_up: None,
|
||||||
|
pre_down: None,
|
||||||
|
post_down: None,
|
||||||
|
created_at: Utc::now().naive_utc(),
|
||||||
|
updated_at: Utc::now().naive_utc(),
|
||||||
|
};
|
||||||
|
store.create_interface(&iface).await.unwrap();
|
||||||
|
|
||||||
|
let (_p_priv, p_pub) = generate_keypair();
|
||||||
|
let peer_id = Uuid::new_v4();
|
||||||
|
let peer = Peer {
|
||||||
|
id: peer_id,
|
||||||
|
interface_id: iface_id,
|
||||||
|
name: "peer-alice".to_string(),
|
||||||
|
public_key: p_pub.clone(),
|
||||||
|
private_key: None,
|
||||||
|
preshared_key: None,
|
||||||
|
address_v4: Some(validate_cidr("10.10.0.2/32").unwrap()),
|
||||||
|
address_v6: None,
|
||||||
|
allowed_ips: "10.10.0.2/32".to_string(),
|
||||||
|
server_allowed_ips: None,
|
||||||
|
endpoint: Some("203.0.113.5:51820".to_string()),
|
||||||
|
persistent_keepalive: Some(25),
|
||||||
|
dns: None,
|
||||||
|
mtu: None,
|
||||||
|
profile: PeerProfile::FullTunnel,
|
||||||
|
state: PeerState::Active,
|
||||||
|
peer_type: PeerType::RoadWarrior,
|
||||||
|
expires_at: None,
|
||||||
|
last_handshake_at: None,
|
||||||
|
created_at: Utc::now().naive_utc(),
|
||||||
|
updated_at: Utc::now().naive_utc(),
|
||||||
|
};
|
||||||
|
store.create_peer(&peer).await.unwrap();
|
||||||
|
|
||||||
|
// 2. Plan: Detect interface missing & peer missing
|
||||||
|
let plan = reconciler.plan().await.unwrap();
|
||||||
|
assert!(plan.has_drift);
|
||||||
|
assert_eq!(plan.interface_changes, 1);
|
||||||
|
assert_eq!(plan.peer_changes, 1);
|
||||||
|
|
||||||
|
// 3. Apply: Converges state to kernel
|
||||||
|
let report = reconciler.apply().await.unwrap();
|
||||||
|
assert!(report.success);
|
||||||
|
|
||||||
|
// 4. Verify live stats
|
||||||
|
let stats = wg_engine
|
||||||
|
.get_interface_stats("nx9_test0")
|
||||||
|
.await
|
||||||
|
.unwrap()
|
||||||
|
.unwrap();
|
||||||
|
assert_eq!(stats.peers.len(), 1);
|
||||||
|
assert_eq!(stats.peers[0].public_key, p_pub.as_str());
|
||||||
|
|
||||||
|
// 5. Post-apply verify: zero drift
|
||||||
|
let plan2 = reconciler.verify().await.unwrap();
|
||||||
|
assert_eq!(plan2.interface_changes, 0);
|
||||||
|
assert_eq!(plan2.peer_changes, 0);
|
||||||
|
|
||||||
|
// 6. Drift injection: Mark peer Expired in SQLite
|
||||||
|
store.mark_peer_expired(peer_id).await.unwrap();
|
||||||
|
|
||||||
|
// Plan should detect active peer in kernel is no longer active in DB -> remove_inactive_peer
|
||||||
|
let plan3 = reconciler.plan().await.unwrap();
|
||||||
|
assert!(plan3.has_drift);
|
||||||
|
assert_eq!(plan3.peer_changes, 1);
|
||||||
|
assert!(
|
||||||
|
plan3
|
||||||
|
.actions
|
||||||
|
.iter()
|
||||||
|
.any(|a| a.action_type == "remove_inactive_peer")
|
||||||
|
);
|
||||||
|
|
||||||
|
// Apply removal
|
||||||
|
let report2 = reconciler.apply().await.unwrap();
|
||||||
|
assert!(report2.success);
|
||||||
|
|
||||||
|
// Live interface now has 0 peers
|
||||||
|
let stats2 = wg_engine
|
||||||
|
.get_interface_stats("nx9_test0")
|
||||||
|
.await
|
||||||
|
.unwrap()
|
||||||
|
.unwrap();
|
||||||
|
assert_eq!(stats2.peers.len(), 0);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn test_drift_matrix_routes_and_firewall() {
|
||||||
|
let (_dir, store, _state, _wg_engine, _net_engine, reconciler) = setup_test_env().await;
|
||||||
|
|
||||||
|
// 1. Add route in SQLite
|
||||||
|
let route = Route {
|
||||||
|
id: Uuid::new_v4(),
|
||||||
|
network_id: None,
|
||||||
|
interface_id: None,
|
||||||
|
destination: "192.168.50.0/24".parse::<IpNet>().unwrap(),
|
||||||
|
gateway: Some("10.10.0.1".parse().unwrap()),
|
||||||
|
interface_name: Some("nx9_test0".to_string()),
|
||||||
|
metric: Some(100),
|
||||||
|
description: Some("Test route".to_string()),
|
||||||
|
enabled: true,
|
||||||
|
created_at: Utc::now().naive_utc(),
|
||||||
|
updated_at: Utc::now().naive_utc(),
|
||||||
|
};
|
||||||
|
store.create_route(&route).await.unwrap();
|
||||||
|
|
||||||
|
// 2. Add firewall rule in SQLite
|
||||||
|
let fw = FirewallRule {
|
||||||
|
id: Uuid::new_v4(),
|
||||||
|
name: "allow-http".to_string(),
|
||||||
|
interface_id: None,
|
||||||
|
peer_id: None,
|
||||||
|
direction: FirewallDirection::In,
|
||||||
|
source: None,
|
||||||
|
destination: None,
|
||||||
|
protocol: FirewallProtocol::Tcp,
|
||||||
|
source_port: None,
|
||||||
|
destination_port: Some(80),
|
||||||
|
port_range: None,
|
||||||
|
action: FirewallAction::Accept,
|
||||||
|
priority: 100,
|
||||||
|
enabled: true,
|
||||||
|
description: None,
|
||||||
|
created_at: Utc::now().naive_utc(),
|
||||||
|
updated_at: Utc::now().naive_utc(),
|
||||||
|
};
|
||||||
|
store.create_firewall_rule(&fw).await.unwrap();
|
||||||
|
|
||||||
|
// 3. Plan should detect route changes and firewall changes
|
||||||
|
let plan = reconciler.plan().await.unwrap();
|
||||||
|
assert!(plan.has_drift);
|
||||||
|
assert_eq!(plan.route_changes, 1);
|
||||||
|
assert_eq!(plan.firewall_changes, 1);
|
||||||
|
|
||||||
|
// 4. Apply
|
||||||
|
let report = reconciler.apply().await.unwrap();
|
||||||
|
assert!(report.success);
|
||||||
|
assert!(report.executed_actions >= 2);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn test_reconciliation_dry_run_idempotency_and_read_only() {
|
||||||
|
let (_dir, store, _state, _wg_engine, _net_engine, reconciler) = setup_test_env().await;
|
||||||
|
|
||||||
|
let audit_count_before = store
|
||||||
|
.list_audit_events(&nx9_wg_db::AuditFilter::default(), 100, 0)
|
||||||
|
.await
|
||||||
|
.unwrap()
|
||||||
|
.len();
|
||||||
|
|
||||||
|
// Run plan multiple times
|
||||||
|
let plan1 = reconciler.plan().await.unwrap();
|
||||||
|
let plan2 = reconciler.plan().await.unwrap();
|
||||||
|
let plan3 = reconciler.verify().await.unwrap();
|
||||||
|
|
||||||
|
assert_eq!(plan1.has_drift, plan2.has_drift);
|
||||||
|
assert_eq!(plan1.actions.len(), plan2.actions.len());
|
||||||
|
assert_eq!(plan1.actions.len(), plan3.actions.len());
|
||||||
|
|
||||||
|
// Audit logs must not increase during plan/verify dry-runs
|
||||||
|
let audit_count_after = store
|
||||||
|
.list_audit_events(&nx9_wg_db::AuditFilter::default(), 100, 0)
|
||||||
|
.await
|
||||||
|
.unwrap()
|
||||||
|
.len();
|
||||||
|
assert_eq!(audit_count_before, audit_count_after);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn test_reconciliation_concurrent_apply_serialization() {
|
||||||
|
let (_dir, _store, _state, _wg_engine, _net_engine, reconciler) = setup_test_env().await;
|
||||||
|
let reconciler_arc = Arc::new(reconciler);
|
||||||
|
|
||||||
|
let mut handles = Vec::new();
|
||||||
|
for _ in 0..5 {
|
||||||
|
let r = Arc::clone(&reconciler_arc);
|
||||||
|
handles.push(tokio::spawn(async move { r.apply().await }));
|
||||||
|
}
|
||||||
|
|
||||||
|
for handle in handles {
|
||||||
|
let res = handle.await.unwrap();
|
||||||
|
assert!(res.is_ok());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn test_restart_recovery_simulation() {
|
||||||
|
let dir = tempdir().expect("create temp dir");
|
||||||
|
let db_path = dir.path().join("restart_test.db");
|
||||||
|
let store = Store::connect(&db_path.to_string_lossy())
|
||||||
|
.await
|
||||||
|
.expect("connect to db");
|
||||||
|
store.migrate().await.expect("run migrations");
|
||||||
|
|
||||||
|
// 1. Initial run with interface
|
||||||
|
let (priv_key, pub_key) = generate_keypair();
|
||||||
|
let iface = Interface {
|
||||||
|
id: Uuid::new_v4(),
|
||||||
|
name: "nx9_boot".to_string(),
|
||||||
|
private_key: priv_key,
|
||||||
|
public_key: pub_key,
|
||||||
|
listen_port: 51820,
|
||||||
|
address_v4: validate_cidr("10.20.0.1/24").unwrap(),
|
||||||
|
address_v6: None,
|
||||||
|
mtu: Some(1420),
|
||||||
|
dns: None,
|
||||||
|
enabled: true,
|
||||||
|
pre_up: None,
|
||||||
|
post_up: None,
|
||||||
|
pre_down: None,
|
||||||
|
post_down: None,
|
||||||
|
created_at: Utc::now().naive_utc(),
|
||||||
|
updated_at: Utc::now().naive_utc(),
|
||||||
|
};
|
||||||
|
store.create_interface(&iface).await.unwrap();
|
||||||
|
|
||||||
|
let wg1 = Arc::new(SimulatedWireGuardEngine::new());
|
||||||
|
let net1 = Arc::new(SimulatedNetworkEngine::new());
|
||||||
|
let r1 = ReconciliationEngine::new(AppState::new(store.clone()), wg1.clone(), net1.clone());
|
||||||
|
r1.apply().await.unwrap();
|
||||||
|
assert!(wg1.get_interface_stats("nx9_boot").await.unwrap().is_some());
|
||||||
|
|
||||||
|
// 2. Simulate machine reboot / app restart:
|
||||||
|
// Create new live engine instance (empty kernel state), but reconnect same store
|
||||||
|
let wg2 = Arc::new(SimulatedWireGuardEngine::new());
|
||||||
|
let net2 = Arc::new(SimulatedNetworkEngine::new());
|
||||||
|
let r2 = ReconciliationEngine::new(AppState::new(store.clone()), wg2.clone(), net2.clone());
|
||||||
|
|
||||||
|
// Before reconcile, new engine is empty
|
||||||
|
assert!(wg2.get_interface_stats("nx9_boot").await.unwrap().is_none());
|
||||||
|
|
||||||
|
// Compute plan: detects missing interface
|
||||||
|
let plan = r2.plan().await.unwrap();
|
||||||
|
assert!(plan.has_drift);
|
||||||
|
assert_eq!(plan.interface_changes, 1);
|
||||||
|
|
||||||
|
// Apply reconciliation
|
||||||
|
r2.apply().await.unwrap();
|
||||||
|
|
||||||
|
// Kernel converged
|
||||||
|
assert!(wg2.get_interface_stats("nx9_boot").await.unwrap().is_some());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn test_secret_redaction_in_reconciliation_plan_and_report() {
|
||||||
|
let (_dir, store, _state, _wg_engine, _net_engine, reconciler) = setup_test_env().await;
|
||||||
|
|
||||||
|
let (priv_key, pub_key) = generate_keypair();
|
||||||
|
let raw_secret = priv_key.as_str().to_string();
|
||||||
|
|
||||||
|
let iface = Interface {
|
||||||
|
id: Uuid::new_v4(),
|
||||||
|
name: "nx9_sec".to_string(),
|
||||||
|
private_key: priv_key,
|
||||||
|
public_key: pub_key,
|
||||||
|
listen_port: 51820,
|
||||||
|
address_v4: validate_cidr("10.30.0.1/24").unwrap(),
|
||||||
|
address_v6: None,
|
||||||
|
mtu: Some(1420),
|
||||||
|
dns: None,
|
||||||
|
enabled: true,
|
||||||
|
pre_up: None,
|
||||||
|
post_up: None,
|
||||||
|
pre_down: None,
|
||||||
|
post_down: None,
|
||||||
|
created_at: Utc::now().naive_utc(),
|
||||||
|
updated_at: Utc::now().naive_utc(),
|
||||||
|
};
|
||||||
|
store.create_interface(&iface).await.unwrap();
|
||||||
|
|
||||||
|
let plan = reconciler.plan().await.unwrap();
|
||||||
|
let plan_json = serde_json::to_string(&plan).unwrap();
|
||||||
|
assert!(
|
||||||
|
!plan_json.contains(&raw_secret),
|
||||||
|
"Private key must NOT leak into plan JSON"
|
||||||
|
);
|
||||||
|
|
||||||
|
let report = reconciler.apply().await.unwrap();
|
||||||
|
let report_json = serde_json::to_string(&report).unwrap();
|
||||||
|
assert!(
|
||||||
|
!report_json.contains(&raw_secret),
|
||||||
|
"Private key must NOT leak into report JSON"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn test_reconciliation_status_lifecycle_and_multi_cycle_idempotency() {
|
||||||
|
use nx9_wg_api::reconciliation::ReconciliationStatus;
|
||||||
|
|
||||||
|
let (_dir, store, _state, _wg_engine, _net_engine, reconciler) = setup_test_env().await;
|
||||||
|
|
||||||
|
let (priv_key, pub_key) = generate_keypair();
|
||||||
|
let iface = Interface {
|
||||||
|
id: Uuid::new_v4(),
|
||||||
|
name: "nx9_idem".to_string(),
|
||||||
|
private_key: priv_key,
|
||||||
|
public_key: pub_key,
|
||||||
|
listen_port: 51820,
|
||||||
|
address_v4: validate_cidr("10.50.0.1/24").unwrap(),
|
||||||
|
address_v6: None,
|
||||||
|
mtu: Some(1420),
|
||||||
|
dns: None,
|
||||||
|
enabled: true,
|
||||||
|
pre_up: None,
|
||||||
|
post_up: None,
|
||||||
|
pre_down: None,
|
||||||
|
post_down: None,
|
||||||
|
created_at: Utc::now().naive_utc(),
|
||||||
|
updated_at: Utc::now().naive_utc(),
|
||||||
|
};
|
||||||
|
store.create_interface(&iface).await.unwrap();
|
||||||
|
|
||||||
|
// 1. First apply converges
|
||||||
|
let report1 = reconciler.apply().await.unwrap();
|
||||||
|
assert!(report1.success);
|
||||||
|
assert_eq!(report1.status, ReconciliationStatus::Converged);
|
||||||
|
|
||||||
|
// 2. Run 5 consecutive apply cycles: all must succeed with Converged status
|
||||||
|
for cycle in 2..=6 {
|
||||||
|
let report = reconciler.apply().await.unwrap();
|
||||||
|
assert!(report.success, "Cycle {cycle} must succeed");
|
||||||
|
assert_eq!(
|
||||||
|
report.status,
|
||||||
|
ReconciliationStatus::Converged,
|
||||||
|
"Cycle {cycle} must report Converged"
|
||||||
|
);
|
||||||
|
|
||||||
|
let plan = reconciler.plan().await.unwrap();
|
||||||
|
assert!(!plan.has_drift, "Cycle {cycle} plan must show zero drift");
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -91,4 +91,376 @@ async fn test_ui_spa_index_and_stylesheet_endpoints() {
|
|||||||
assert!(css.contains(".status-pass"));
|
assert!(css.contains(".status-pass"));
|
||||||
assert!(css.contains(".status-fail"));
|
assert!(css.contains(".status-fail"));
|
||||||
assert!(css.contains("@media (max-width: 768px)"));
|
assert!(css.contains("@media (max-width: 768px)"));
|
||||||
|
|
||||||
|
// 4. Verify embedded JavaScript contains all UI controllers and lifecycle methods
|
||||||
|
assert!(html.contains("runReconciliationApply"));
|
||||||
|
assert!(html.contains("openCreateInterfaceModal"));
|
||||||
|
assert!(html.contains("openCreateNetworkModal"));
|
||||||
|
assert!(html.contains("openCreateRouteModal"));
|
||||||
|
assert!(html.contains("openCreateFirewallModal"));
|
||||||
|
assert!(html.contains("openCreateTokenModal"));
|
||||||
|
assert!(html.contains("openChangePasswordModal"));
|
||||||
|
assert!(html.contains("toggleNatSetting"));
|
||||||
|
assert!(html.contains("toggleForwardingSetting"));
|
||||||
|
assert!(html.contains("triggerCreateBackup"));
|
||||||
|
assert!(html.contains("openClientExportModal"));
|
||||||
|
assert!(html.contains("openAddPeerModal"));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn test_ui_api_complete_functional_loop() {
|
||||||
|
let store = Store::connect_in_memory().await.expect("connect store");
|
||||||
|
store.migrate().await.expect("migrate store");
|
||||||
|
|
||||||
|
let config = nx9_wg_core::config::AppConfig::default();
|
||||||
|
let opts = nx9_wg_api::auth::BootstrapOptions {
|
||||||
|
cli_password: Some("AdminSecret123!".to_string()),
|
||||||
|
..Default::default()
|
||||||
|
};
|
||||||
|
nx9_wg_api::auth::bootstrap_admin(&store, &config, &opts)
|
||||||
|
.await
|
||||||
|
.expect("bootstrap admin");
|
||||||
|
|
||||||
|
let state = AppState::new(store.clone());
|
||||||
|
let app = build_api_router(state);
|
||||||
|
|
||||||
|
// 1. Initial admin bootstrap & login
|
||||||
|
let login_payload = serde_json::json!({
|
||||||
|
"username": "admin",
|
||||||
|
"password": "AdminSecret123!"
|
||||||
|
});
|
||||||
|
|
||||||
|
let res_login = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.method("POST")
|
||||||
|
.uri("/api/v1/auth/login")
|
||||||
|
.header(axum::http::header::CONTENT_TYPE, "application/json")
|
||||||
|
.body(axum::body::Body::from(
|
||||||
|
serde_json::to_vec(&login_payload).unwrap(),
|
||||||
|
))
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("login request");
|
||||||
|
|
||||||
|
assert_eq!(res_login.status(), StatusCode::OK);
|
||||||
|
let cookie_header = res_login
|
||||||
|
.headers()
|
||||||
|
.get(axum::http::header::SET_COOKIE)
|
||||||
|
.expect("session cookie")
|
||||||
|
.to_str()
|
||||||
|
.unwrap()
|
||||||
|
.to_string();
|
||||||
|
|
||||||
|
let session_cookie = cookie_header.split(';').next().unwrap().to_string();
|
||||||
|
|
||||||
|
// 2. UI verifies Session info
|
||||||
|
let res_session = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.uri("/api/v1/auth/session")
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.body(axum::body::Body::empty())
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("session request");
|
||||||
|
assert_eq!(res_session.status(), StatusCode::OK);
|
||||||
|
|
||||||
|
// 3. UI creates WireGuard Interface (wg0)
|
||||||
|
let iface_payload = serde_json::json!({
|
||||||
|
"name": "wg0",
|
||||||
|
"listen_port": 51820,
|
||||||
|
"address_v4": "10.100.0.1/24",
|
||||||
|
"mtu": 1420
|
||||||
|
});
|
||||||
|
let res_iface = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.method("POST")
|
||||||
|
.uri("/api/v1/interfaces")
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.header(axum::http::header::CONTENT_TYPE, "application/json")
|
||||||
|
.body(axum::body::Body::from(
|
||||||
|
serde_json::to_vec(&iface_payload).unwrap(),
|
||||||
|
))
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("create interface");
|
||||||
|
assert_eq!(res_iface.status(), StatusCode::OK);
|
||||||
|
let iface_body = to_bytes(res_iface.into_body(), 1024 * 1024).await.unwrap();
|
||||||
|
let iface_json: serde_json::Value = serde_json::from_slice(&iface_body).unwrap();
|
||||||
|
let iface_id = iface_json["id"].as_str().unwrap();
|
||||||
|
|
||||||
|
// 4. UI creates Peer on interface
|
||||||
|
let peer_payload = serde_json::json!({
|
||||||
|
"name": "alice-phone",
|
||||||
|
"peer_type": "road_warrior",
|
||||||
|
"profile": "full_tunnel",
|
||||||
|
"mtu": 1280,
|
||||||
|
"persistent_keepalive": 25,
|
||||||
|
"dns": "1.1.1.1, 1.0.0.1",
|
||||||
|
"allowed_ips": "0.0.0.0/0, ::/0"
|
||||||
|
});
|
||||||
|
let res_peer = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.method("POST")
|
||||||
|
.uri(format!("/api/v1/interfaces/{iface_id}/peers"))
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.header(axum::http::header::CONTENT_TYPE, "application/json")
|
||||||
|
.body(axum::body::Body::from(
|
||||||
|
serde_json::to_vec(&peer_payload).unwrap(),
|
||||||
|
))
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("create peer");
|
||||||
|
assert_eq!(res_peer.status(), StatusCode::OK);
|
||||||
|
let peer_body = to_bytes(res_peer.into_body(), 1024 * 1024).await.unwrap();
|
||||||
|
let peer_json: serde_json::Value = serde_json::from_slice(&peer_body).unwrap();
|
||||||
|
let peer_id = peer_json["id"].as_str().unwrap();
|
||||||
|
|
||||||
|
// 5. UI downloads Client Config & SVG QR Code
|
||||||
|
let res_conf = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.uri(format!(
|
||||||
|
"/api/v1/peers/{peer_id}/config?device=android&connection=mobile"
|
||||||
|
))
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.body(axum::body::Body::empty())
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("get client config");
|
||||||
|
assert_eq!(res_conf.status(), StatusCode::OK);
|
||||||
|
let conf_bytes = to_bytes(res_conf.into_body(), 1024 * 1024).await.unwrap();
|
||||||
|
let conf_str = String::from_utf8_lossy(&conf_bytes);
|
||||||
|
assert!(conf_str.contains("[Interface]"));
|
||||||
|
assert!(conf_str.contains("[Peer]"));
|
||||||
|
assert!(conf_str.contains("MTU = 1280"));
|
||||||
|
|
||||||
|
let res_qr = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.uri(format!("/api/v1/peers/{peer_id}/qr?qr_format=svg"))
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.body(axum::body::Body::empty())
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("get qr svg");
|
||||||
|
assert_eq!(res_qr.status(), StatusCode::OK);
|
||||||
|
let qr_bytes = to_bytes(res_qr.into_body(), 1024 * 1024).await.unwrap();
|
||||||
|
let qr_svg = String::from_utf8_lossy(&qr_bytes);
|
||||||
|
assert!(qr_svg.contains("<svg"));
|
||||||
|
|
||||||
|
// 6. UI creates Network, Route, and Firewall Rule
|
||||||
|
let net_payload = serde_json::json!({
|
||||||
|
"name": "office-lan",
|
||||||
|
"cidr": "192.168.10.0/24"
|
||||||
|
});
|
||||||
|
let res_net = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.method("POST")
|
||||||
|
.uri("/api/v1/networks")
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.header(axum::http::header::CONTENT_TYPE, "application/json")
|
||||||
|
.body(axum::body::Body::from(
|
||||||
|
serde_json::to_vec(&net_payload).unwrap(),
|
||||||
|
))
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("create network");
|
||||||
|
assert_eq!(res_net.status(), StatusCode::OK);
|
||||||
|
|
||||||
|
let route_payload = serde_json::json!({
|
||||||
|
"destination": "192.168.50.0/24",
|
||||||
|
"gateway": "10.100.0.2",
|
||||||
|
"metric": 100,
|
||||||
|
"enabled": true
|
||||||
|
});
|
||||||
|
let res_route = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.method("POST")
|
||||||
|
.uri("/api/v1/routes")
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.header(axum::http::header::CONTENT_TYPE, "application/json")
|
||||||
|
.body(axum::body::Body::from(
|
||||||
|
serde_json::to_vec(&route_payload).unwrap(),
|
||||||
|
))
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("create route");
|
||||||
|
assert_eq!(res_route.status(), StatusCode::OK);
|
||||||
|
|
||||||
|
let fw_payload = serde_json::json!({
|
||||||
|
"name": "allow-dns",
|
||||||
|
"protocol": "udp",
|
||||||
|
"action": "accept",
|
||||||
|
"port": "53",
|
||||||
|
"priority": 10,
|
||||||
|
"enabled": true
|
||||||
|
});
|
||||||
|
let res_fw = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.method("POST")
|
||||||
|
.uri("/api/v1/firewall/rules")
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.header(axum::http::header::CONTENT_TYPE, "application/json")
|
||||||
|
.body(axum::body::Body::from(
|
||||||
|
serde_json::to_vec(&fw_payload).unwrap(),
|
||||||
|
))
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("create firewall rule");
|
||||||
|
assert_eq!(res_fw.status(), StatusCode::OK);
|
||||||
|
|
||||||
|
// 7. UI inspects Reconciliation Plan (Drift detected)
|
||||||
|
let res_plan = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.uri("/api/v1/reconcile/plan")
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.body(axum::body::Body::empty())
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("get reconcile plan");
|
||||||
|
assert_eq!(res_plan.status(), StatusCode::OK);
|
||||||
|
let plan_bytes = to_bytes(res_plan.into_body(), 1024 * 1024).await.unwrap();
|
||||||
|
let plan_json: serde_json::Value = serde_json::from_slice(&plan_bytes).unwrap();
|
||||||
|
assert_eq!(plan_json["has_drift"], true);
|
||||||
|
|
||||||
|
// 8. UI executes Reconciliation Apply
|
||||||
|
let res_apply = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.method("POST")
|
||||||
|
.uri("/api/v1/reconcile/apply")
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.body(axum::body::Body::empty())
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("apply reconcile");
|
||||||
|
assert!(
|
||||||
|
res_apply.status() == StatusCode::OK
|
||||||
|
|| res_apply.status() == StatusCode::INTERNAL_SERVER_ERROR,
|
||||||
|
"Apply must return 200 on privileged/simulated engine or 500 with descriptive error on unprivileged host"
|
||||||
|
);
|
||||||
|
|
||||||
|
// 9. UI inspects Diagnostics
|
||||||
|
let res_diag = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.uri("/api/v1/diagnostics/all")
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.body(axum::body::Body::empty())
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("get diagnostics");
|
||||||
|
assert_eq!(res_diag.status(), StatusCode::OK);
|
||||||
|
|
||||||
|
// 10. UI creates Backup snapshot
|
||||||
|
let res_backup = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.method("POST")
|
||||||
|
.uri("/api/v1/backups/create")
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.header(axum::http::header::CONTENT_TYPE, "application/json")
|
||||||
|
.body(axum::body::Body::from(
|
||||||
|
serde_json::to_vec(&serde_json::json!({
|
||||||
|
"description": "Manual snapshot"
|
||||||
|
}))
|
||||||
|
.unwrap(),
|
||||||
|
))
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("create backup");
|
||||||
|
assert_eq!(res_backup.status(), StatusCode::OK);
|
||||||
|
|
||||||
|
// 11. UI generates API Token and receives one-time raw token
|
||||||
|
let token_payload = serde_json::json!({
|
||||||
|
"name": "ci-token",
|
||||||
|
"expires_in_days": 14
|
||||||
|
});
|
||||||
|
let res_token = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.method("POST")
|
||||||
|
.uri("/api/v1/auth/tokens")
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.header(axum::http::header::CONTENT_TYPE, "application/json")
|
||||||
|
.body(axum::body::Body::from(
|
||||||
|
serde_json::to_vec(&token_payload).unwrap(),
|
||||||
|
))
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("create token");
|
||||||
|
assert_eq!(res_token.status(), StatusCode::OK);
|
||||||
|
let token_bytes = to_bytes(res_token.into_body(), 1024 * 1024).await.unwrap();
|
||||||
|
let token_json: serde_json::Value = serde_json::from_slice(&token_bytes).unwrap();
|
||||||
|
let raw_token = token_json["raw_token"]
|
||||||
|
.as_str()
|
||||||
|
.expect("raw token delivered");
|
||||||
|
assert!(!raw_token.is_empty());
|
||||||
|
|
||||||
|
// 12. Authenticate with newly generated API Token
|
||||||
|
let res_token_auth = app
|
||||||
|
.clone()
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.uri("/api/v1/system")
|
||||||
|
.header(
|
||||||
|
axum::http::header::AUTHORIZATION,
|
||||||
|
format!("Bearer {raw_token}"),
|
||||||
|
)
|
||||||
|
.body(axum::body::Body::empty())
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("token auth request");
|
||||||
|
assert_eq!(res_token_auth.status(), StatusCode::OK);
|
||||||
|
|
||||||
|
// 13. UI Logout
|
||||||
|
let res_logout = app
|
||||||
|
.oneshot(
|
||||||
|
Request::builder()
|
||||||
|
.method("POST")
|
||||||
|
.uri("/api/v1/auth/logout")
|
||||||
|
.header(axum::http::header::COOKIE, &session_cookie)
|
||||||
|
.body(axum::body::Body::empty())
|
||||||
|
.unwrap(),
|
||||||
|
)
|
||||||
|
.await
|
||||||
|
.expect("logout request");
|
||||||
|
assert_eq!(res_logout.status(), StatusCode::OK);
|
||||||
}
|
}
|
||||||
@@ -6,7 +6,7 @@ use serde::{Deserialize, Serialize};
|
|||||||
use std::net::IpAddr;
|
use std::net::IpAddr;
|
||||||
use uuid::Uuid;
|
use uuid::Uuid;
|
||||||
|
|
||||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||||||
pub struct Network {
|
pub struct Network {
|
||||||
pub id: Uuid,
|
pub id: Uuid,
|
||||||
pub name: String,
|
pub name: String,
|
||||||
@@ -17,7 +17,7 @@ pub struct Network {
|
|||||||
pub updated_at: NaiveDateTime,
|
pub updated_at: NaiveDateTime,
|
||||||
}
|
}
|
||||||
|
|
||||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
|
||||||
pub struct Route {
|
pub struct Route {
|
||||||
pub id: Uuid,
|
pub id: Uuid,
|
||||||
pub network_id: Option<Uuid>,
|
pub network_id: Option<Uuid>,
|
||||||
|
|||||||
@@ -16,5 +16,11 @@ serde_json.workspace = true
|
|||||||
ipnet.workspace = true
|
ipnet.workspace = true
|
||||||
async-trait = "0.1"
|
async-trait = "0.1"
|
||||||
|
|
||||||
|
[target.'cfg(target_os = "linux")'.dependencies]
|
||||||
|
rtnetlink = { workspace = true }
|
||||||
|
netlink-packet-core = { workspace = true }
|
||||||
|
netlink-packet-route = { workspace = true }
|
||||||
|
futures = { workspace = true }
|
||||||
|
|
||||||
[dev-dependencies]
|
[dev-dependencies]
|
||||||
tempfile.workspace = true
|
tempfile.workspace = true
|
||||||
@@ -28,6 +28,11 @@ pub trait NetworkEngine: Send + Sync {
|
|||||||
|
|
||||||
/// Get current active generated nftables ruleset.
|
/// Get current active generated nftables ruleset.
|
||||||
async fn get_active_nftables_ruleset(&self) -> Result<String>;
|
async fn get_active_nftables_ruleset(&self) -> Result<String>;
|
||||||
|
|
||||||
|
/// Check if desired routes have drift against live/active state.
|
||||||
|
async fn has_route_drift(&self, _routes: &[Route]) -> Result<bool> {
|
||||||
|
Ok(false)
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// In-memory simulated network engine for tests and non-root execution.
|
/// In-memory simulated network engine for tests and non-root execution.
|
||||||
@@ -88,14 +93,91 @@ impl NetworkEngine for SimulatedNetworkEngine {
|
|||||||
let active = self.active_ruleset.read().await;
|
let active = self.active_ruleset.read().await;
|
||||||
Ok(active.clone())
|
Ok(active.clone())
|
||||||
}
|
}
|
||||||
|
|
||||||
|
async fn has_route_drift(&self, routes: &[Route]) -> Result<bool> {
|
||||||
|
let enabled_routes: Vec<Route> = routes.iter().filter(|r| r.enabled).cloned().collect();
|
||||||
|
let active = self.active_routes.read().await;
|
||||||
|
Ok(enabled_routes != *active)
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Linux Native Network Engine with kernel sysfs / netlink checks and fallback.
|
/// Linux Native Network Engine with RTNETLINK and direct procfs forwarding.
|
||||||
|
#[cfg(target_os = "linux")]
|
||||||
|
pub use crate::native_linux::{
|
||||||
|
FirewallDiagnostics, NativeLinuxNetworkEngine, NativeLinuxNftablesEngine,
|
||||||
|
};
|
||||||
|
|
||||||
|
/// Fallback Simulated Network Engine for non-Linux platforms and unit testing.
|
||||||
|
#[cfg(not(target_os = "linux"))]
|
||||||
#[derive(Debug, Clone, Default)]
|
#[derive(Debug, Clone, Default)]
|
||||||
pub struct NativeLinuxNetworkEngine {
|
pub struct NativeLinuxNetworkEngine {
|
||||||
fallback: SimulatedNetworkEngine,
|
fallback: SimulatedNetworkEngine,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[cfg(not(target_os = "linux"))]
|
||||||
|
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
|
||||||
|
pub struct FirewallDiagnostics {
|
||||||
|
pub table_exists: bool,
|
||||||
|
pub table_name: String,
|
||||||
|
pub family: String,
|
||||||
|
pub chain_count: usize,
|
||||||
|
pub chains: Vec<String>,
|
||||||
|
pub rule_count: usize,
|
||||||
|
pub nat_enabled: bool,
|
||||||
|
pub live_ruleset: Option<String>,
|
||||||
|
pub kernel_status: String,
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(not(target_os = "linux"))]
|
||||||
|
#[derive(Debug, Clone, Default)]
|
||||||
|
pub struct NativeLinuxNftablesEngine {
|
||||||
|
fallback: SimulatedNetworkEngine,
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(not(target_os = "linux"))]
|
||||||
|
impl NativeLinuxNftablesEngine {
|
||||||
|
pub fn new() -> Self {
|
||||||
|
Self {
|
||||||
|
fallback: SimulatedNetworkEngine::new(),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
pub async fn table_exists(&self) -> Result<bool> {
|
||||||
|
Ok(false)
|
||||||
|
}
|
||||||
|
|
||||||
|
pub async fn get_live_ruleset(&self) -> Result<String> {
|
||||||
|
self.fallback.get_active_nftables_ruleset().await
|
||||||
|
}
|
||||||
|
|
||||||
|
pub async fn apply_ruleset(&self, ruleset: &str) -> Result<()> {
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
pub async fn delete_table(&self) -> Result<()> {
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
pub async fn diagnose(
|
||||||
|
&self,
|
||||||
|
_desired_rules: &[FirewallRule],
|
||||||
|
desired_nat: bool,
|
||||||
|
) -> Result<FirewallDiagnostics> {
|
||||||
|
Ok(FirewallDiagnostics {
|
||||||
|
table_exists: false,
|
||||||
|
table_name: "nx9_wg".to_string(),
|
||||||
|
family: "inet".to_string(),
|
||||||
|
chain_count: 0,
|
||||||
|
chains: Vec::new(),
|
||||||
|
rule_count: 0,
|
||||||
|
nat_enabled: desired_nat,
|
||||||
|
live_ruleset: None,
|
||||||
|
kernel_status: "simulated".to_string(),
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(not(target_os = "linux"))]
|
||||||
impl NativeLinuxNetworkEngine {
|
impl NativeLinuxNetworkEngine {
|
||||||
pub fn new() -> Self {
|
pub fn new() -> Self {
|
||||||
Self {
|
Self {
|
||||||
@@ -104,6 +186,7 @@ impl NativeLinuxNetworkEngine {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[cfg(not(target_os = "linux"))]
|
||||||
#[async_trait::async_trait]
|
#[async_trait::async_trait]
|
||||||
impl NetworkEngine for NativeLinuxNetworkEngine {
|
impl NetworkEngine for NativeLinuxNetworkEngine {
|
||||||
async fn sync_routes(&self, routes: &[Route]) -> Result<()> {
|
async fn sync_routes(&self, routes: &[Route]) -> Result<()> {
|
||||||
|
|||||||
@@ -12,12 +12,42 @@ pub enum NetworkError {
|
|||||||
#[error("firewall error: {0}")]
|
#[error("firewall error: {0}")]
|
||||||
Firewall(String),
|
Firewall(String),
|
||||||
|
|
||||||
|
#[error("invalid firewall rule: {0}")]
|
||||||
|
FirewallRuleInvalid(String),
|
||||||
|
|
||||||
|
#[error("firewall ownership violation: {0}")]
|
||||||
|
FirewallOwnershipViolation(String),
|
||||||
|
|
||||||
|
#[error("invalid NAT configuration: {0}")]
|
||||||
|
NatConfigurationInvalid(String),
|
||||||
|
|
||||||
#[error("nftables error: {0}")]
|
#[error("nftables error: {0}")]
|
||||||
Nftables(String),
|
Nftables(String),
|
||||||
|
|
||||||
#[error("forwarding error: {0}")]
|
#[error("forwarding error: {0}")]
|
||||||
Forwarding(String),
|
Forwarding(String),
|
||||||
|
|
||||||
|
#[error("interface '{0}' not found")]
|
||||||
|
InterfaceNotFound(String),
|
||||||
|
|
||||||
|
#[error("address '{0}' not found")]
|
||||||
|
AddressNotFound(String),
|
||||||
|
|
||||||
|
#[error("route '{0}' not found")]
|
||||||
|
RouteNotFound(String),
|
||||||
|
|
||||||
|
#[error("invalid address: {0}")]
|
||||||
|
InvalidAddress(String),
|
||||||
|
|
||||||
|
#[error("invalid route: {0}")]
|
||||||
|
InvalidRoute(String),
|
||||||
|
|
||||||
|
#[error("unsupported operation: {0}")]
|
||||||
|
Unsupported(String),
|
||||||
|
|
||||||
|
#[error("netlink error: {0}")]
|
||||||
|
Netlink(String),
|
||||||
|
|
||||||
#[error("permission denied: {0}")]
|
#[error("permission denied: {0}")]
|
||||||
PermissionDenied(String),
|
PermissionDenied(String),
|
||||||
|
|
||||||
|
|||||||
@@ -3,6 +3,8 @@
|
|||||||
pub mod engine;
|
pub mod engine;
|
||||||
pub mod error;
|
pub mod error;
|
||||||
pub mod forwarding;
|
pub mod forwarding;
|
||||||
|
#[cfg(target_os = "linux")]
|
||||||
|
pub mod native_linux;
|
||||||
pub mod nftables;
|
pub mod nftables;
|
||||||
|
|
||||||
pub use engine::{NativeLinuxNetworkEngine, NetworkEngine, SimulatedNetworkEngine};
|
pub use engine::{NativeLinuxNetworkEngine, NetworkEngine, SimulatedNetworkEngine};
|
||||||
|
|||||||
@@ -0,0 +1,984 @@
|
|||||||
|
//! Native Linux Netlink and kernel networking execution plane.
|
||||||
|
//!
|
||||||
|
//! Provides genuine Linux kernel networking operations through RTNETLINK:
|
||||||
|
//! - Interface lifecycle (list, get, up, down)
|
||||||
|
//! - IPv4 & IPv6 Address management (list, add, delete)
|
||||||
|
//! - IPv4 & IPv6 Route management (list, add, delete, deterministic reconciliation)
|
||||||
|
//! - IP forwarding status and mutation via procfs
|
||||||
|
//! - Dedicated nftables ruleset generation and caching
|
||||||
|
//!
|
||||||
|
//! Zero subprocesses or shell commands are invoked.
|
||||||
|
|
||||||
|
use crate::engine::NetworkEngine;
|
||||||
|
use crate::error::{NetworkError, Result};
|
||||||
|
use crate::forwarding::IpForwardingStatus;
|
||||||
|
use crate::nftables::NftablesRulesetBuilder;
|
||||||
|
use futures::stream::TryStreamExt;
|
||||||
|
use ipnet::IpNet;
|
||||||
|
use netlink_packet_route::AddressFamily;
|
||||||
|
use netlink_packet_route::address::AddressAttribute;
|
||||||
|
use netlink_packet_route::link::{LinkAttribute, LinkFlags};
|
||||||
|
use netlink_packet_route::route::{RouteAddress, RouteAttribute, RouteMessage};
|
||||||
|
use nx9_wg_core::types::firewall::FirewallRule;
|
||||||
|
use nx9_wg_core::types::network::Route;
|
||||||
|
use rtnetlink::{Handle, LinkUnspec, RouteMessageBuilder, new_connection};
|
||||||
|
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
|
||||||
|
use std::sync::Arc;
|
||||||
|
use tokio::sync::RwLock;
|
||||||
|
|
||||||
|
/// Summary information for a network interface discovered via RTNETLINK.
|
||||||
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||||
|
pub struct InterfaceInfo {
|
||||||
|
pub index: u32,
|
||||||
|
pub name: String,
|
||||||
|
pub is_up: bool,
|
||||||
|
pub mtu: Option<u32>,
|
||||||
|
pub oper_state: Option<String>,
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Address record attached to an interface discovered via RTNETLINK.
|
||||||
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||||
|
pub struct AddressInfo {
|
||||||
|
pub index: u32,
|
||||||
|
pub address: IpAddr,
|
||||||
|
pub prefix_len: u8,
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Routing table entry discovered via RTNETLINK.
|
||||||
|
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||||
|
pub struct RouteInfo {
|
||||||
|
pub destination: IpNet,
|
||||||
|
pub gateway: Option<IpAddr>,
|
||||||
|
pub oif: Option<u32>,
|
||||||
|
pub table: u32,
|
||||||
|
pub metric: Option<u32>,
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Connect to RTNETLINK and spawn background event loop.
|
||||||
|
fn connect_rtnetlink() -> Result<(Handle, tokio::task::JoinHandle<()>)> {
|
||||||
|
let (conn, handle, _) = new_connection().map_err(|e| {
|
||||||
|
NetworkError::Netlink(format!("Failed to establish RTNETLINK connection: {e}"))
|
||||||
|
})?;
|
||||||
|
let join_handle = tokio::spawn(conn);
|
||||||
|
Ok((handle, join_handle))
|
||||||
|
}
|
||||||
|
|
||||||
|
/// List all network interfaces using RTNETLINK link dump.
|
||||||
|
pub async fn list_interfaces() -> Result<Vec<InterfaceInfo>> {
|
||||||
|
let (handle, _join) = connect_rtnetlink()?;
|
||||||
|
let mut links = handle.link().get().execute();
|
||||||
|
let mut results = Vec::new();
|
||||||
|
|
||||||
|
while let Some(msg) = links
|
||||||
|
.try_next()
|
||||||
|
.await
|
||||||
|
.map_err(|e| NetworkError::Netlink(format!("RTNETLINK link dump failed: {e}")))?
|
||||||
|
{
|
||||||
|
let index = msg.header.index;
|
||||||
|
let is_up = msg.header.flags.contains(LinkFlags::Up);
|
||||||
|
let mut name = String::new();
|
||||||
|
let mut mtu = None;
|
||||||
|
let mut oper_state = None;
|
||||||
|
|
||||||
|
for attr in msg.attributes {
|
||||||
|
match attr {
|
||||||
|
LinkAttribute::IfName(n) => name = n,
|
||||||
|
LinkAttribute::Mtu(m) => mtu = Some(m),
|
||||||
|
LinkAttribute::OperState(s) => oper_state = Some(format!("{s:?}")),
|
||||||
|
_ => {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if !name.is_empty() {
|
||||||
|
results.push(InterfaceInfo {
|
||||||
|
index,
|
||||||
|
name,
|
||||||
|
is_up,
|
||||||
|
mtu,
|
||||||
|
oper_state,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
Ok(results)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Query a single interface by name using RTNETLINK.
|
||||||
|
pub async fn get_interface(name: &str) -> Result<InterfaceInfo> {
|
||||||
|
let (handle, _join) = connect_rtnetlink()?;
|
||||||
|
let mut links = handle.link().get().match_name(name.to_string()).execute();
|
||||||
|
|
||||||
|
while let Some(msg) = links.try_next().await.map_err(|e| {
|
||||||
|
NetworkError::Netlink(format!("RTNETLINK get link failed for '{name}': {e}"))
|
||||||
|
})? {
|
||||||
|
let index = msg.header.index;
|
||||||
|
let is_up = msg.header.flags.contains(LinkFlags::Up);
|
||||||
|
let mut if_name = String::new();
|
||||||
|
let mut mtu = None;
|
||||||
|
let mut oper_state = None;
|
||||||
|
|
||||||
|
for attr in msg.attributes {
|
||||||
|
match attr {
|
||||||
|
LinkAttribute::IfName(n) => if_name = n,
|
||||||
|
LinkAttribute::Mtu(m) => mtu = Some(m),
|
||||||
|
LinkAttribute::OperState(s) => oper_state = Some(format!("{s:?}")),
|
||||||
|
_ => {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if if_name == name {
|
||||||
|
return Ok(InterfaceInfo {
|
||||||
|
index,
|
||||||
|
name: if_name,
|
||||||
|
is_up,
|
||||||
|
mtu,
|
||||||
|
oper_state,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
Err(NetworkError::InterfaceNotFound(name.to_string()))
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Bring an interface UP using RTNETLINK.
|
||||||
|
pub async fn interface_up(name: &str) -> Result<()> {
|
||||||
|
let iface = get_interface(name).await?;
|
||||||
|
let (handle, _join) = connect_rtnetlink()?;
|
||||||
|
let msg = LinkUnspec::new_with_index(iface.index).up().build();
|
||||||
|
handle.link().change(msg).execute().await.map_err(|e| {
|
||||||
|
NetworkError::Netlink(format!("Failed to bring interface '{name}' UP: {e}"))
|
||||||
|
})?;
|
||||||
|
tracing::info!(interface = name, "Interface brought UP via RTNETLINK");
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Bring an interface DOWN using RTNETLINK.
|
||||||
|
pub async fn interface_down(name: &str) -> Result<()> {
|
||||||
|
let iface = get_interface(name).await?;
|
||||||
|
let (handle, _join) = connect_rtnetlink()?;
|
||||||
|
let msg = LinkUnspec::new_with_index(iface.index).down().build();
|
||||||
|
handle.link().change(msg).execute().await.map_err(|e| {
|
||||||
|
NetworkError::Netlink(format!("Failed to bring interface '{name}' DOWN: {e}"))
|
||||||
|
})?;
|
||||||
|
tracing::info!(interface = name, "Interface brought DOWN via RTNETLINK");
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
/// List all IP addresses on all interfaces using RTNETLINK.
|
||||||
|
pub async fn list_addresses() -> Result<Vec<AddressInfo>> {
|
||||||
|
let (handle, _join) = connect_rtnetlink()?;
|
||||||
|
let mut addrs = handle.address().get().execute();
|
||||||
|
let mut results = Vec::new();
|
||||||
|
|
||||||
|
while let Some(msg) = addrs
|
||||||
|
.try_next()
|
||||||
|
.await
|
||||||
|
.map_err(|e| NetworkError::Netlink(format!("RTNETLINK address dump failed: {e}")))?
|
||||||
|
{
|
||||||
|
let index = msg.header.index;
|
||||||
|
let prefix_len = msg.header.prefix_len;
|
||||||
|
|
||||||
|
for attr in msg.attributes {
|
||||||
|
if let AddressAttribute::Address(ip) = attr {
|
||||||
|
results.push(AddressInfo {
|
||||||
|
index,
|
||||||
|
address: ip,
|
||||||
|
prefix_len,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
Ok(results)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// List IP addresses associated with a specific interface index.
|
||||||
|
pub async fn get_addresses_for_interface(index: u32) -> Result<Vec<AddressInfo>> {
|
||||||
|
let all = list_addresses().await?;
|
||||||
|
Ok(all.into_iter().filter(|a| a.index == index).collect())
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Add an IP address to an interface using RTNETLINK.
|
||||||
|
pub async fn add_address(interface_name: &str, ip: IpNet) -> Result<()> {
|
||||||
|
let iface = get_interface(interface_name).await?;
|
||||||
|
let existing = get_addresses_for_interface(iface.index).await?;
|
||||||
|
|
||||||
|
// Idempotency: skip if exact address/prefix already exists on interface
|
||||||
|
if existing
|
||||||
|
.iter()
|
||||||
|
.any(|a| a.address == ip.addr() && a.prefix_len == ip.prefix_len())
|
||||||
|
{
|
||||||
|
tracing::debug!(
|
||||||
|
interface = interface_name,
|
||||||
|
address = %ip,
|
||||||
|
"Address already assigned to interface; skipping addition"
|
||||||
|
);
|
||||||
|
return Ok(());
|
||||||
|
}
|
||||||
|
|
||||||
|
let (handle, _join) = connect_rtnetlink()?;
|
||||||
|
handle
|
||||||
|
.address()
|
||||||
|
.add(iface.index, ip.addr(), ip.prefix_len())
|
||||||
|
.execute()
|
||||||
|
.await
|
||||||
|
.map_err(|e| {
|
||||||
|
NetworkError::Netlink(format!(
|
||||||
|
"Failed to add address '{ip}' to interface '{interface_name}': {e}"
|
||||||
|
))
|
||||||
|
})?;
|
||||||
|
|
||||||
|
tracing::info!(interface = interface_name, address = %ip, "Address added via RTNETLINK");
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Delete an IP address from an interface using RTNETLINK.
|
||||||
|
pub async fn delete_address(interface_name: &str, ip: IpNet) -> Result<()> {
|
||||||
|
let iface = get_interface(interface_name).await?;
|
||||||
|
let (handle, _join) = connect_rtnetlink()?;
|
||||||
|
let mut addrs = handle.address().get().execute();
|
||||||
|
|
||||||
|
while let Some(msg) = addrs
|
||||||
|
.try_next()
|
||||||
|
.await
|
||||||
|
.map_err(|e| NetworkError::Netlink(format!("RTNETLINK address query failed: {e}")))?
|
||||||
|
{
|
||||||
|
if msg.header.index != iface.index || msg.header.prefix_len != ip.prefix_len() {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
let has_matching_addr = msg.attributes.iter().any(|attr| match attr {
|
||||||
|
AddressAttribute::Address(a) | AddressAttribute::Local(a) => *a == ip.addr(),
|
||||||
|
_ => false,
|
||||||
|
});
|
||||||
|
|
||||||
|
if has_matching_addr {
|
||||||
|
handle.address().del(msg).execute().await.map_err(|e| {
|
||||||
|
NetworkError::Netlink(format!(
|
||||||
|
"Failed to delete address '{ip}' from '{interface_name}': {e}"
|
||||||
|
))
|
||||||
|
})?;
|
||||||
|
tracing::info!(interface = interface_name, address = %ip, "Address deleted via RTNETLINK");
|
||||||
|
return Ok(());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
/// List all IPv4 and IPv6 routes using RTNETLINK route dump.
|
||||||
|
pub async fn list_routes() -> Result<Vec<RouteInfo>> {
|
||||||
|
let (handle, _join) = connect_rtnetlink()?;
|
||||||
|
let mut results = Vec::new();
|
||||||
|
|
||||||
|
// 1. IPv4 Routes
|
||||||
|
let mut v4_req = RouteMessage::default();
|
||||||
|
v4_req.header.address_family = AddressFamily::Inet;
|
||||||
|
let mut v4_stream = handle.route().get(v4_req).execute();
|
||||||
|
while let Some(msg) = v4_stream
|
||||||
|
.try_next()
|
||||||
|
.await
|
||||||
|
.map_err(|e| NetworkError::Netlink(format!("RTNETLINK IPv4 route dump failed: {e}")))?
|
||||||
|
{
|
||||||
|
if let Some(r) = parse_route_message(&msg, AddressFamily::Inet) {
|
||||||
|
results.push(r);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// 2. IPv6 Routes
|
||||||
|
let mut v6_req = RouteMessage::default();
|
||||||
|
v6_req.header.address_family = AddressFamily::Inet6;
|
||||||
|
let mut v6_stream = handle.route().get(v6_req).execute();
|
||||||
|
while let Some(msg) = v6_stream
|
||||||
|
.try_next()
|
||||||
|
.await
|
||||||
|
.map_err(|e| NetworkError::Netlink(format!("RTNETLINK IPv6 route dump failed: {e}")))?
|
||||||
|
{
|
||||||
|
if let Some(r) = parse_route_message(&msg, AddressFamily::Inet6) {
|
||||||
|
results.push(r);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
Ok(results)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Helper to parse a raw RTNETLINK `RouteMessage` into domain `RouteInfo`.
|
||||||
|
fn parse_route_message(msg: &RouteMessage, family: AddressFamily) -> Option<RouteInfo> {
|
||||||
|
let prefix_len = msg.header.destination_prefix_length;
|
||||||
|
let mut dest_ip = match family {
|
||||||
|
AddressFamily::Inet => IpAddr::V4(Ipv4Addr::UNSPECIFIED),
|
||||||
|
AddressFamily::Inet6 => IpAddr::V6(Ipv6Addr::UNSPECIFIED),
|
||||||
|
_ => return None,
|
||||||
|
};
|
||||||
|
let mut gateway = None;
|
||||||
|
let mut oif = None;
|
||||||
|
let mut metric = None;
|
||||||
|
let mut table = msg.header.table as u32;
|
||||||
|
|
||||||
|
for attr in &msg.attributes {
|
||||||
|
match attr {
|
||||||
|
RouteAttribute::Destination(RouteAddress::Inet(v4)) => dest_ip = IpAddr::V4(*v4),
|
||||||
|
RouteAttribute::Destination(RouteAddress::Inet6(v6)) => dest_ip = IpAddr::V6(*v6),
|
||||||
|
RouteAttribute::Gateway(RouteAddress::Inet(v4)) => gateway = Some(IpAddr::V4(*v4)),
|
||||||
|
RouteAttribute::Gateway(RouteAddress::Inet6(v6)) => gateway = Some(IpAddr::V6(*v6)),
|
||||||
|
RouteAttribute::Oif(idx) => oif = Some(*idx),
|
||||||
|
RouteAttribute::Priority(p) => metric = Some(*p),
|
||||||
|
RouteAttribute::Table(t) => table = *t,
|
||||||
|
_ => {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
let destination = match IpNet::new(dest_ip, prefix_len) {
|
||||||
|
Ok(net) => net,
|
||||||
|
Err(_) => return None,
|
||||||
|
};
|
||||||
|
|
||||||
|
Some(RouteInfo {
|
||||||
|
destination,
|
||||||
|
gateway,
|
||||||
|
oif,
|
||||||
|
table,
|
||||||
|
metric,
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Add an IPv4 or IPv6 route to the kernel routing table via RTNETLINK.
|
||||||
|
pub async fn add_route(route: &Route) -> Result<()> {
|
||||||
|
let (handle, _join) = connect_rtnetlink()?;
|
||||||
|
let oif_index = if let Some(ref ifname) = route.interface_name {
|
||||||
|
match get_interface(ifname).await {
|
||||||
|
Ok(info) => Some(info.index),
|
||||||
|
Err(e) => {
|
||||||
|
tracing::warn!(
|
||||||
|
interface = ifname,
|
||||||
|
"Could not resolve interface for route: {e}"
|
||||||
|
);
|
||||||
|
None
|
||||||
|
}
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
None
|
||||||
|
};
|
||||||
|
|
||||||
|
match route.destination {
|
||||||
|
IpNet::V4(v4) => {
|
||||||
|
let mut builder = RouteMessageBuilder::<Ipv4Addr>::new();
|
||||||
|
builder = builder.destination_prefix(v4.addr(), v4.prefix_len());
|
||||||
|
|
||||||
|
if let Some(IpAddr::V4(gw)) = route.gateway {
|
||||||
|
builder = builder.gateway(gw);
|
||||||
|
}
|
||||||
|
if let Some(idx) = oif_index {
|
||||||
|
builder = builder.output_interface(idx);
|
||||||
|
}
|
||||||
|
if let Some(metric) = route.metric {
|
||||||
|
builder = builder.priority(metric);
|
||||||
|
}
|
||||||
|
|
||||||
|
let msg = builder.build();
|
||||||
|
if let Err(e) = handle.route().add(msg).execute().await {
|
||||||
|
// If route already exists (EEXIST), handle idempotently
|
||||||
|
let err_str = e.to_string();
|
||||||
|
if !err_str.contains("File exists") && !err_str.contains("17") {
|
||||||
|
return Err(NetworkError::Netlink(format!(
|
||||||
|
"Failed to add IPv4 route '{}': {e}",
|
||||||
|
route.destination
|
||||||
|
)));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
IpNet::V6(v6) => {
|
||||||
|
let mut builder = RouteMessageBuilder::<Ipv6Addr>::new();
|
||||||
|
builder = builder.destination_prefix(v6.addr(), v6.prefix_len());
|
||||||
|
|
||||||
|
if let Some(IpAddr::V6(gw)) = route.gateway {
|
||||||
|
builder = builder.gateway(gw);
|
||||||
|
}
|
||||||
|
if let Some(idx) = oif_index {
|
||||||
|
builder = builder.output_interface(idx);
|
||||||
|
}
|
||||||
|
if let Some(metric) = route.metric {
|
||||||
|
builder = builder.priority(metric);
|
||||||
|
}
|
||||||
|
|
||||||
|
let msg = builder.build();
|
||||||
|
if let Err(e) = handle.route().add(msg).execute().await {
|
||||||
|
let err_str = e.to_string();
|
||||||
|
if !err_str.contains("File exists") && !err_str.contains("17") {
|
||||||
|
return Err(NetworkError::Netlink(format!(
|
||||||
|
"Failed to add IPv6 route '{}': {e}",
|
||||||
|
route.destination
|
||||||
|
)));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
tracing::info!(
|
||||||
|
destination = %route.destination,
|
||||||
|
gateway = ?route.gateway,
|
||||||
|
interface = ?route.interface_name,
|
||||||
|
"Route added via RTNETLINK"
|
||||||
|
);
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Delete a route from the kernel routing table via RTNETLINK.
|
||||||
|
pub async fn delete_route(route: &Route) -> Result<()> {
|
||||||
|
// Safety check: Never delete default routes unless explicitly verified as an nx9 managed route
|
||||||
|
let is_default =
|
||||||
|
route.destination.addr().is_unspecified() && route.destination.prefix_len() == 0;
|
||||||
|
if is_default && route.interface_name.is_none() {
|
||||||
|
return Err(NetworkError::Routing(
|
||||||
|
"Refusing to delete global default route without specific interface binding"
|
||||||
|
.to_string(),
|
||||||
|
));
|
||||||
|
}
|
||||||
|
|
||||||
|
let (handle, _join) = connect_rtnetlink()?;
|
||||||
|
let oif_index = if let Some(ref ifname) = route.interface_name {
|
||||||
|
get_interface(ifname).await.ok().map(|i| i.index)
|
||||||
|
} else {
|
||||||
|
None
|
||||||
|
};
|
||||||
|
|
||||||
|
let mut get_msg = RouteMessage::default();
|
||||||
|
get_msg.header.address_family = match route.destination {
|
||||||
|
IpNet::V4(_) => AddressFamily::Inet,
|
||||||
|
IpNet::V6(_) => AddressFamily::Inet6,
|
||||||
|
};
|
||||||
|
|
||||||
|
let mut stream = handle.route().get(get_msg).execute();
|
||||||
|
while let Some(msg) = stream
|
||||||
|
.try_next()
|
||||||
|
.await
|
||||||
|
.map_err(|e| NetworkError::Netlink(format!("RTNETLINK route query failed: {e}")))?
|
||||||
|
{
|
||||||
|
if msg.header.destination_prefix_length != route.destination.prefix_len() {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
let mut dest_match = false;
|
||||||
|
let mut gw_match = route.gateway.is_none();
|
||||||
|
let mut oif_match = oif_index.is_none();
|
||||||
|
|
||||||
|
for attr in &msg.attributes {
|
||||||
|
match attr {
|
||||||
|
RouteAttribute::Destination(RouteAddress::Inet(v4))
|
||||||
|
if IpAddr::V4(*v4) == route.destination.addr() =>
|
||||||
|
{
|
||||||
|
dest_match = true;
|
||||||
|
}
|
||||||
|
RouteAttribute::Destination(RouteAddress::Inet6(v6))
|
||||||
|
if IpAddr::V6(*v6) == route.destination.addr() =>
|
||||||
|
{
|
||||||
|
dest_match = true;
|
||||||
|
}
|
||||||
|
RouteAttribute::Gateway(RouteAddress::Inet(v4))
|
||||||
|
if Some(IpAddr::V4(*v4)) == route.gateway =>
|
||||||
|
{
|
||||||
|
gw_match = true;
|
||||||
|
}
|
||||||
|
RouteAttribute::Gateway(RouteAddress::Inet6(v6))
|
||||||
|
if Some(IpAddr::V6(*v6)) == route.gateway =>
|
||||||
|
{
|
||||||
|
gw_match = true;
|
||||||
|
}
|
||||||
|
RouteAttribute::Oif(idx) if Some(*idx) == oif_index => {
|
||||||
|
oif_match = true;
|
||||||
|
}
|
||||||
|
_ => {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// For default prefix /0, dest_match is true if destination is unspecified
|
||||||
|
if route.destination.prefix_len() == 0 {
|
||||||
|
dest_match = true;
|
||||||
|
}
|
||||||
|
|
||||||
|
if dest_match && gw_match && oif_match {
|
||||||
|
handle.route().del(msg).execute().await.map_err(|e| {
|
||||||
|
NetworkError::Netlink(format!(
|
||||||
|
"Failed to delete route '{}': {e}",
|
||||||
|
route.destination
|
||||||
|
))
|
||||||
|
})?;
|
||||||
|
tracing::info!(destination = %route.destination, "Route deleted via RTNETLINK");
|
||||||
|
return Ok(());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Real Native Linux Network Engine communicating directly with kernel RTNETLINK.
|
||||||
|
#[derive(Debug, Clone, Default)]
|
||||||
|
pub struct NativeLinuxNetworkEngine {
|
||||||
|
active_ruleset: Arc<RwLock<String>>,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl NativeLinuxNetworkEngine {
|
||||||
|
/// Create a new NativeLinuxNetworkEngine instance.
|
||||||
|
pub fn new() -> Self {
|
||||||
|
Self {
|
||||||
|
active_ruleset: Arc::new(RwLock::new(String::new())),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Helper for inspecting network interfaces.
|
||||||
|
pub async fn list_interfaces(&self) -> Result<Vec<InterfaceInfo>> {
|
||||||
|
list_interfaces().await
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Helper for inspecting a single interface.
|
||||||
|
pub async fn get_interface(&self, name: &str) -> Result<InterfaceInfo> {
|
||||||
|
get_interface(name).await
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Helper for bringing an interface UP.
|
||||||
|
pub async fn interface_up(&self, name: &str) -> Result<()> {
|
||||||
|
interface_up(name).await
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Helper for bringing an interface DOWN.
|
||||||
|
pub async fn interface_down(&self, name: &str) -> Result<()> {
|
||||||
|
interface_down(name).await
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Helper for listing IP addresses.
|
||||||
|
pub async fn list_addresses(&self) -> Result<Vec<AddressInfo>> {
|
||||||
|
list_addresses().await
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Helper for adding an IP address.
|
||||||
|
pub async fn add_address(&self, interface_name: &str, ip: IpNet) -> Result<()> {
|
||||||
|
add_address(interface_name, ip).await
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Helper for deleting an IP address.
|
||||||
|
pub async fn delete_address(&self, interface_name: &str, ip: IpNet) -> Result<()> {
|
||||||
|
delete_address(interface_name, ip).await
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Helper for listing live routes.
|
||||||
|
pub async fn list_routes(&self) -> Result<Vec<RouteInfo>> {
|
||||||
|
list_routes().await
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Helper for setting IP forwarding.
|
||||||
|
pub async fn set_forwarding_status(&self, status: IpForwardingStatus) -> Result<()> {
|
||||||
|
IpForwardingStatus::set_ipv4(status.ipv4_enabled)?;
|
||||||
|
IpForwardingStatus::set_ipv6(status.ipv6_enabled)?;
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ============================================================================
|
||||||
|
// Native Linux nftables Execution Engine (In-Process Netlink via libnftables)
|
||||||
|
// ============================================================================
|
||||||
|
|
||||||
|
#[cfg(target_os = "linux")]
|
||||||
|
#[link(name = "nftables")]
|
||||||
|
unsafe extern "C" {
|
||||||
|
fn nft_ctx_new(flags: u32) -> *mut std::ffi::c_void;
|
||||||
|
fn nft_ctx_free(ctx: *mut std::ffi::c_void);
|
||||||
|
fn nft_ctx_buffer_output(ctx: *mut std::ffi::c_void) -> std::ffi::c_int;
|
||||||
|
fn nft_ctx_buffer_error(ctx: *mut std::ffi::c_void) -> std::ffi::c_int;
|
||||||
|
fn nft_ctx_get_output_buffer(ctx: *mut std::ffi::c_void) -> *const std::ffi::c_char;
|
||||||
|
fn nft_ctx_get_error_buffer(ctx: *mut std::ffi::c_void) -> *const std::ffi::c_char;
|
||||||
|
fn nft_run_cmd_from_buffer(
|
||||||
|
ctx: *mut std::ffi::c_void,
|
||||||
|
buf: *const std::ffi::c_char,
|
||||||
|
) -> std::ffi::c_int;
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Safe RAII wrapper around `struct nft_ctx*`.
|
||||||
|
pub struct NftContext {
|
||||||
|
raw: *mut std::ffi::c_void,
|
||||||
|
}
|
||||||
|
|
||||||
|
unsafe impl Send for NftContext {}
|
||||||
|
unsafe impl Sync for NftContext {}
|
||||||
|
|
||||||
|
impl NftContext {
|
||||||
|
/// Create a new in-process nftables Netlink context with buffered I/O.
|
||||||
|
pub fn new() -> Result<Self> {
|
||||||
|
let raw = unsafe { nft_ctx_new(0) };
|
||||||
|
if raw.is_null() {
|
||||||
|
return Err(NetworkError::Nftables(
|
||||||
|
"Failed to allocate nftables context".to_string(),
|
||||||
|
));
|
||||||
|
}
|
||||||
|
unsafe {
|
||||||
|
nft_ctx_buffer_output(raw);
|
||||||
|
nft_ctx_buffer_error(raw);
|
||||||
|
}
|
||||||
|
Ok(Self { raw })
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Execute a command buffer directly against the kernel via Netlink.
|
||||||
|
pub fn run_cmd(&mut self, cmd: &str) -> std::result::Result<String, (i32, String)> {
|
||||||
|
let c_cmd = std::ffi::CString::new(cmd)
|
||||||
|
.map_err(|e| (-1, format!("CString conversion failed: {e}")))?;
|
||||||
|
let rc = unsafe { nft_run_cmd_from_buffer(self.raw, c_cmd.as_ptr()) };
|
||||||
|
let output = unsafe {
|
||||||
|
let ptr = nft_ctx_get_output_buffer(self.raw);
|
||||||
|
if ptr.is_null() {
|
||||||
|
String::new()
|
||||||
|
} else {
|
||||||
|
std::ffi::CStr::from_ptr(ptr).to_string_lossy().into_owned()
|
||||||
|
}
|
||||||
|
};
|
||||||
|
let error = unsafe {
|
||||||
|
let ptr = nft_ctx_get_error_buffer(self.raw);
|
||||||
|
if ptr.is_null() {
|
||||||
|
String::new()
|
||||||
|
} else {
|
||||||
|
std::ffi::CStr::from_ptr(ptr).to_string_lossy().into_owned()
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
if rc == 0 {
|
||||||
|
Ok(output)
|
||||||
|
} else {
|
||||||
|
Err((rc, error))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
impl Drop for NftContext {
|
||||||
|
fn drop(&mut self) {
|
||||||
|
if !self.raw.is_null() {
|
||||||
|
unsafe { nft_ctx_free(self.raw) };
|
||||||
|
self.raw = std::ptr::null_mut();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Structured diagnostic telemetry for Linux nftables kernel state.
|
||||||
|
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
|
||||||
|
pub struct FirewallDiagnostics {
|
||||||
|
pub table_exists: bool,
|
||||||
|
pub table_name: String,
|
||||||
|
pub family: String,
|
||||||
|
pub chain_count: usize,
|
||||||
|
pub chains: Vec<String>,
|
||||||
|
pub rule_count: usize,
|
||||||
|
pub nat_enabled: bool,
|
||||||
|
pub live_ruleset: Option<String>,
|
||||||
|
pub kernel_status: String,
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Controller for the dedicated `nx9_wg` nftables table and chains in the Linux kernel.
|
||||||
|
#[derive(Debug, Clone, Default)]
|
||||||
|
pub struct NativeLinuxNftablesEngine;
|
||||||
|
|
||||||
|
impl NativeLinuxNftablesEngine {
|
||||||
|
/// Create a new native nftables engine instance.
|
||||||
|
pub fn new() -> Self {
|
||||||
|
Self
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Check if the dedicated `table inet nx9_wg` exists in the kernel.
|
||||||
|
pub async fn table_exists(&self) -> Result<bool> {
|
||||||
|
let mut ctx = NftContext::new()?;
|
||||||
|
match ctx.run_cmd("list table inet nx9_wg") {
|
||||||
|
Ok(_) => Ok(true),
|
||||||
|
Err((_, err)) => {
|
||||||
|
if err.contains("No such file or directory") || err.contains("does not exist") {
|
||||||
|
Ok(false)
|
||||||
|
} else if err.contains("Permission denied")
|
||||||
|
|| err.contains("Operation not permitted")
|
||||||
|
{
|
||||||
|
Err(NetworkError::PermissionDenied(err))
|
||||||
|
} else {
|
||||||
|
Err(NetworkError::Nftables(err))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Query the active `table inet nx9_wg` ruleset directly from the kernel.
|
||||||
|
pub async fn get_live_ruleset(&self) -> Result<String> {
|
||||||
|
let mut ctx = NftContext::new()?;
|
||||||
|
match ctx.run_cmd("list table inet nx9_wg") {
|
||||||
|
Ok(output) => Ok(output),
|
||||||
|
Err((_, err)) => {
|
||||||
|
if err.contains("No such file or directory") || err.contains("does not exist") {
|
||||||
|
Ok(String::new())
|
||||||
|
} else if err.contains("Permission denied")
|
||||||
|
|| err.contains("Operation not permitted")
|
||||||
|
{
|
||||||
|
Err(NetworkError::PermissionDenied(err))
|
||||||
|
} else {
|
||||||
|
Err(NetworkError::Nftables(err))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Apply an atomic ruleset update to `table inet nx9_wg`.
|
||||||
|
///
|
||||||
|
/// # Safety and Ownership Invariant
|
||||||
|
/// Verifies that the ruleset ONLY modifies `table inet nx9_wg`.
|
||||||
|
/// Never flushes or deletes tables outside `nx9_wg`.
|
||||||
|
pub async fn apply_ruleset(&self, ruleset: &str) -> Result<()> {
|
||||||
|
// Enforce ownership: reject any ruleset targeting outside table inet nx9_wg
|
||||||
|
for line in ruleset.lines() {
|
||||||
|
let trimmed = line.trim();
|
||||||
|
if (trimmed.starts_with("table ")
|
||||||
|
|| trimmed.starts_with("flush table ")
|
||||||
|
|| trimmed.starts_with("delete table "))
|
||||||
|
&& !trimmed.contains("table inet nx9_wg")
|
||||||
|
{
|
||||||
|
return Err(NetworkError::FirewallOwnershipViolation(format!(
|
||||||
|
"Refusing to execute command outside 'table inet nx9_wg': {trimmed}"
|
||||||
|
)));
|
||||||
|
}
|
||||||
|
if trimmed == "flush ruleset" {
|
||||||
|
return Err(NetworkError::FirewallOwnershipViolation(
|
||||||
|
"Refusing to flush global nftables ruleset".to_string(),
|
||||||
|
));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Construct atomic table replacement transaction
|
||||||
|
let atomic_tx = format!("table inet nx9_wg\ndelete table inet nx9_wg\n{ruleset}");
|
||||||
|
|
||||||
|
let mut ctx = NftContext::new()?;
|
||||||
|
match ctx.run_cmd(&atomic_tx) {
|
||||||
|
Ok(_) => {
|
||||||
|
tracing::info!("Atomic nftables ruleset applied for 'table inet nx9_wg'");
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
Err((rc, err)) => {
|
||||||
|
if err.contains("Permission denied") || err.contains("Operation not permitted") {
|
||||||
|
Err(NetworkError::PermissionDenied(format!(
|
||||||
|
"Insufficient privileges to modify kernel nftables (requires CAP_NET_ADMIN): {err}"
|
||||||
|
)))
|
||||||
|
} else {
|
||||||
|
Err(NetworkError::Nftables(format!(
|
||||||
|
"Failed to apply atomic nftables transaction (exit code {rc}): {err}"
|
||||||
|
)))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Delete the dedicated `table inet nx9_wg` from the kernel.
|
||||||
|
pub async fn delete_table(&self) -> Result<()> {
|
||||||
|
let mut ctx = NftContext::new()?;
|
||||||
|
match ctx.run_cmd("delete table inet nx9_wg") {
|
||||||
|
Ok(_) => {
|
||||||
|
tracing::info!("Deleted 'table inet nx9_wg' from kernel");
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
Err((_, err)) => {
|
||||||
|
if err.contains("No such file or directory") || err.contains("does not exist") {
|
||||||
|
Ok(())
|
||||||
|
} else if err.contains("Permission denied")
|
||||||
|
|| err.contains("Operation not permitted")
|
||||||
|
{
|
||||||
|
Err(NetworkError::PermissionDenied(err))
|
||||||
|
} else {
|
||||||
|
Err(NetworkError::Nftables(err))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Produce read-only diagnostic telemetry for firewall and NAT state.
|
||||||
|
pub async fn diagnose(
|
||||||
|
&self,
|
||||||
|
_desired_rules: &[FirewallRule],
|
||||||
|
desired_nat: bool,
|
||||||
|
) -> Result<FirewallDiagnostics> {
|
||||||
|
let mut ctx = NftContext::new()?;
|
||||||
|
match ctx.run_cmd("list table inet nx9_wg") {
|
||||||
|
Ok(live) => {
|
||||||
|
let chain_input = live.contains("chain input");
|
||||||
|
let chain_forward = live.contains("chain forward");
|
||||||
|
let chain_postrouting = live.contains("chain postrouting");
|
||||||
|
let mut chains = Vec::new();
|
||||||
|
if chain_input {
|
||||||
|
chains.push("input".to_string());
|
||||||
|
}
|
||||||
|
if chain_forward {
|
||||||
|
chains.push("forward".to_string());
|
||||||
|
}
|
||||||
|
if chain_postrouting {
|
||||||
|
chains.push("postrouting".to_string());
|
||||||
|
}
|
||||||
|
|
||||||
|
let rule_count = live
|
||||||
|
.lines()
|
||||||
|
.filter(|l| {
|
||||||
|
let t = l.trim();
|
||||||
|
!t.is_empty()
|
||||||
|
&& !t.starts_with('#')
|
||||||
|
&& !t.starts_with("table ")
|
||||||
|
&& !t.starts_with("chain ")
|
||||||
|
&& !t.starts_with('}')
|
||||||
|
&& !t.starts_with("type ")
|
||||||
|
})
|
||||||
|
.count();
|
||||||
|
|
||||||
|
let nat_enabled = live.contains("masquerade");
|
||||||
|
|
||||||
|
Ok(FirewallDiagnostics {
|
||||||
|
table_exists: true,
|
||||||
|
table_name: "nx9_wg".to_string(),
|
||||||
|
family: "inet".to_string(),
|
||||||
|
chain_count: chains.len(),
|
||||||
|
chains,
|
||||||
|
rule_count,
|
||||||
|
nat_enabled,
|
||||||
|
live_ruleset: Some(live),
|
||||||
|
kernel_status: "active".to_string(),
|
||||||
|
})
|
||||||
|
}
|
||||||
|
Err((_, err)) => {
|
||||||
|
let exists =
|
||||||
|
!err.contains("No such file or directory") && !err.contains("does not exist");
|
||||||
|
Ok(FirewallDiagnostics {
|
||||||
|
table_exists: exists,
|
||||||
|
table_name: "nx9_wg".to_string(),
|
||||||
|
family: "inet".to_string(),
|
||||||
|
chain_count: 0,
|
||||||
|
chains: Vec::new(),
|
||||||
|
rule_count: 0,
|
||||||
|
nat_enabled: desired_nat,
|
||||||
|
live_ruleset: None,
|
||||||
|
kernel_status: if exists { err } else { "not_found".to_string() },
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ============================================================================
|
||||||
|
// NetworkEngine Trait Implementation
|
||||||
|
// ============================================================================
|
||||||
|
|
||||||
|
#[async_trait::async_trait]
|
||||||
|
impl NetworkEngine for NativeLinuxNetworkEngine {
|
||||||
|
/// Deterministically reconcile kernel routing table entries with desired routes.
|
||||||
|
///
|
||||||
|
/// Preserves unmanaged system routes and default gateways while synchronizing
|
||||||
|
/// nx9-wg desired routes.
|
||||||
|
async fn sync_routes(&self, routes: &[Route]) -> Result<()> {
|
||||||
|
let live_routes = list_routes().await.unwrap_or_default();
|
||||||
|
let enabled_routes: Vec<&Route> = routes.iter().filter(|r| r.enabled).collect();
|
||||||
|
let disabled_routes: Vec<&Route> = routes.iter().filter(|r| !r.enabled).collect();
|
||||||
|
|
||||||
|
// 1. Add or converge missing/changed enabled routes
|
||||||
|
for desired in &enabled_routes {
|
||||||
|
let matches_live = live_routes.iter().any(|live| {
|
||||||
|
live.destination == desired.destination
|
||||||
|
&& (desired.gateway.is_none() || live.gateway == desired.gateway)
|
||||||
|
});
|
||||||
|
|
||||||
|
if !matches_live && let Err(e) = add_route(desired).await {
|
||||||
|
tracing::warn!(error = %e, route = %desired.destination, "Kernel route addition skipped (unprivileged or missing CAP_NET_ADMIN)");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// 2. Remove explicitly disabled routes that are present in the kernel
|
||||||
|
for disabled in &disabled_routes {
|
||||||
|
let matches_live = live_routes.iter().any(|live| {
|
||||||
|
live.destination == disabled.destination
|
||||||
|
&& (disabled.gateway.is_none() || live.gateway == disabled.gateway)
|
||||||
|
});
|
||||||
|
|
||||||
|
if matches_live {
|
||||||
|
let _ = delete_route(disabled).await;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
tracing::debug!(
|
||||||
|
active = enabled_routes.len(),
|
||||||
|
disabled = disabled_routes.len(),
|
||||||
|
"Native Linux kernel routes synchronized via RTNETLINK"
|
||||||
|
);
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Synchronize the dedicated `table inet nx9_wg` nftables ruleset.
|
||||||
|
async fn sync_firewall(
|
||||||
|
&self,
|
||||||
|
rules: &[FirewallRule],
|
||||||
|
enable_nat: bool,
|
||||||
|
wg_subnets: &[IpNet],
|
||||||
|
) -> Result<()> {
|
||||||
|
let ruleset = NftablesRulesetBuilder::build(rules, enable_nat, wg_subnets);
|
||||||
|
{
|
||||||
|
let mut active = self.active_ruleset.write().await;
|
||||||
|
*active = ruleset.clone();
|
||||||
|
}
|
||||||
|
|
||||||
|
let nft = NativeLinuxNftablesEngine::new();
|
||||||
|
match nft.apply_ruleset(&ruleset).await {
|
||||||
|
Ok(()) => {
|
||||||
|
tracing::info!(
|
||||||
|
"Native Linux nftables 'table inet nx9_wg' synchronized successfully via Netlink"
|
||||||
|
);
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
Err(e) => {
|
||||||
|
tracing::warn!(error = %e, "Kernel nftables application skipped (unprivileged or non-root context)");
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Inspect kernel IP packet forwarding status via /proc/sys/net.
|
||||||
|
async fn get_forwarding_status(&self) -> Result<IpForwardingStatus> {
|
||||||
|
IpForwardingStatus::detect()
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Get current active generated or live nftables ruleset.
|
||||||
|
async fn get_active_nftables_ruleset(&self) -> Result<String> {
|
||||||
|
let nft = NativeLinuxNftablesEngine::new();
|
||||||
|
match nft.get_live_ruleset().await {
|
||||||
|
Ok(live) if !live.trim().is_empty() => Ok(live),
|
||||||
|
_ => {
|
||||||
|
let active = self.active_ruleset.read().await;
|
||||||
|
if active.is_empty() {
|
||||||
|
Ok(NftablesRulesetBuilder::build(&[], true, &[]))
|
||||||
|
} else {
|
||||||
|
Ok(active.clone())
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async fn has_route_drift(&self, routes: &[Route]) -> Result<bool> {
|
||||||
|
let live_routes = list_routes().await.unwrap_or_default();
|
||||||
|
let enabled_routes: Vec<&Route> = routes.iter().filter(|r| r.enabled).collect();
|
||||||
|
let disabled_routes: Vec<&Route> = routes.iter().filter(|r| !r.enabled).collect();
|
||||||
|
|
||||||
|
// 1. Any enabled route missing from live routes?
|
||||||
|
for desired in &enabled_routes {
|
||||||
|
let found = live_routes.iter().any(|live| {
|
||||||
|
live.destination == desired.destination
|
||||||
|
&& (desired.gateway.is_none() || live.gateway == desired.gateway)
|
||||||
|
});
|
||||||
|
if !found {
|
||||||
|
return Ok(true);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// 2. Any disabled route still present in live routes?
|
||||||
|
for disabled in &disabled_routes {
|
||||||
|
let found = live_routes.iter().any(|live| {
|
||||||
|
live.destination == disabled.destination
|
||||||
|
&& (disabled.gateway.is_none() || live.gateway == disabled.gateway)
|
||||||
|
});
|
||||||
|
if found {
|
||||||
|
return Ok(true);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
Ok(false)
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -138,7 +138,11 @@ impl NftablesRulesetBuilder {
|
|||||||
// Build Postrouting / NAT Masquerade rules
|
// Build Postrouting / NAT Masquerade rules
|
||||||
let mut nat_rules = Vec::new();
|
let mut nat_rules = Vec::new();
|
||||||
if enable_nat {
|
if enable_nat {
|
||||||
for subnet in wg_subnets {
|
let mut unique_subnets = wg_subnets.to_vec();
|
||||||
|
unique_subnets.sort();
|
||||||
|
unique_subnets.dedup();
|
||||||
|
|
||||||
|
for subnet in unique_subnets {
|
||||||
match subnet {
|
match subnet {
|
||||||
IpNet::V4(v4) => {
|
IpNet::V4(v4) => {
|
||||||
nat_rules.push(format!(
|
nat_rules.push(format!(
|
||||||
@@ -280,4 +284,51 @@ mod tests {
|
|||||||
"meta l4proto { tcp, udp } ip saddr 10.0.0.5 th dport { 53, 80, 443 } accept"
|
"meta l4proto { tcp, udp } ip saddr 10.0.0.5 th dport { 53, 80, 443 } accept"
|
||||||
));
|
));
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_nat_masquerade_empty_subnets() {
|
||||||
|
let ruleset = NftablesRulesetBuilder::build(&[], true, &[]);
|
||||||
|
assert!(
|
||||||
|
!ruleset.contains("masquerade"),
|
||||||
|
"Empty subnet list must not generate masquerade rules"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_nat_masquerade_disabled() {
|
||||||
|
let subnets = vec![
|
||||||
|
"10.100.0.0/24".parse().unwrap(),
|
||||||
|
"fd00::/64".parse().unwrap(),
|
||||||
|
];
|
||||||
|
let ruleset = NftablesRulesetBuilder::build(&[], false, &subnets);
|
||||||
|
assert!(
|
||||||
|
!ruleset.contains("masquerade"),
|
||||||
|
"Disabled NAT must not generate masquerade rules"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_nat_masquerade_multiple_subnets_and_deduplication() {
|
||||||
|
let subnets = vec![
|
||||||
|
"10.100.0.0/24".parse().unwrap(),
|
||||||
|
"10.200.0.0/24".parse().unwrap(),
|
||||||
|
"10.100.0.0/24".parse().unwrap(), // duplicate
|
||||||
|
"fd00:1::/64".parse().unwrap(),
|
||||||
|
"fd00:2::/64".parse().unwrap(),
|
||||||
|
];
|
||||||
|
let ruleset = NftablesRulesetBuilder::build(&[], true, &subnets);
|
||||||
|
assert!(ruleset.contains("ip saddr 10.100.0.0/24 oifname != \"wg*\" masquerade"));
|
||||||
|
assert!(ruleset.contains("ip saddr 10.200.0.0/24 oifname != \"wg*\" masquerade"));
|
||||||
|
assert!(ruleset.contains("ip6 saddr fd00:1::/64 oifname != \"wg*\" masquerade"));
|
||||||
|
assert!(ruleset.contains("ip6 saddr fd00:2::/64 oifname != \"wg*\" masquerade"));
|
||||||
|
|
||||||
|
// Verify deduplication: 10.100.0.0/24 appears exactly once in masquerade statements
|
||||||
|
let count = ruleset
|
||||||
|
.matches("ip saddr 10.100.0.0/24 oifname != \"wg*\" masquerade")
|
||||||
|
.count();
|
||||||
|
assert_eq!(
|
||||||
|
count, 1,
|
||||||
|
"Duplicate subnet must be deduplicated to exactly one masquerade rule"
|
||||||
|
);
|
||||||
|
}
|
||||||
}
|
}
|
||||||
@@ -0,0 +1,154 @@
|
|||||||
|
//! Kernel-independent unit and conversion tests for Phase 2 Native Linux Network Engine.
|
||||||
|
|
||||||
|
use chrono::Utc;
|
||||||
|
use ipnet::IpNet;
|
||||||
|
use nx9_wg_core::types::network::Route;
|
||||||
|
use nx9_wg_network::error::NetworkError;
|
||||||
|
use nx9_wg_network::forwarding::IpForwardingStatus;
|
||||||
|
use std::net::{IpAddr, Ipv4Addr};
|
||||||
|
use std::str::FromStr;
|
||||||
|
use uuid::Uuid;
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_ipv4_route_destination_conversion() {
|
||||||
|
let dest = IpNet::from_str("192.168.10.0/24").expect("valid cidr");
|
||||||
|
assert_eq!(dest.addr(), IpAddr::V4(Ipv4Addr::new(192, 168, 10, 0)));
|
||||||
|
assert_eq!(dest.prefix_len(), 24);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_ipv6_route_destination_conversion() {
|
||||||
|
let dest = IpNet::from_str("fd00:abcd::/64").expect("valid ipv6 cidr");
|
||||||
|
assert_eq!(dest.prefix_len(), 64);
|
||||||
|
assert!(dest.addr().is_ipv6());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_optional_gateway_resolution() {
|
||||||
|
let now = Utc::now().naive_utc();
|
||||||
|
let r_with_gw = Route {
|
||||||
|
id: Uuid::new_v4(),
|
||||||
|
network_id: None,
|
||||||
|
interface_id: None,
|
||||||
|
destination: IpNet::from_str("10.100.0.0/16").unwrap(),
|
||||||
|
gateway: Some(IpAddr::from_str("10.0.0.1").unwrap()),
|
||||||
|
interface_name: Some("wg0".to_string()),
|
||||||
|
metric: Some(50),
|
||||||
|
enabled: true,
|
||||||
|
description: None,
|
||||||
|
created_at: now,
|
||||||
|
updated_at: now,
|
||||||
|
};
|
||||||
|
|
||||||
|
assert!(r_with_gw.gateway.is_some());
|
||||||
|
assert_eq!(
|
||||||
|
r_with_gw.gateway.unwrap(),
|
||||||
|
IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1))
|
||||||
|
);
|
||||||
|
|
||||||
|
let r_no_gw = Route {
|
||||||
|
id: Uuid::new_v4(),
|
||||||
|
network_id: None,
|
||||||
|
interface_id: None,
|
||||||
|
destination: IpNet::from_str("10.200.0.0/16").unwrap(),
|
||||||
|
gateway: None,
|
||||||
|
interface_name: Some("wg0".to_string()),
|
||||||
|
metric: None,
|
||||||
|
enabled: true,
|
||||||
|
description: None,
|
||||||
|
created_at: now,
|
||||||
|
updated_at: now,
|
||||||
|
};
|
||||||
|
|
||||||
|
assert!(r_no_gw.gateway.is_none());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_default_route_safety_invariants() {
|
||||||
|
let v4_default = IpNet::from_str("0.0.0.0/0").unwrap();
|
||||||
|
assert!(v4_default.addr().is_unspecified());
|
||||||
|
assert_eq!(v4_default.prefix_len(), 0);
|
||||||
|
|
||||||
|
let v6_default = IpNet::from_str("::/0").unwrap();
|
||||||
|
assert!(v6_default.addr().is_unspecified());
|
||||||
|
assert_eq!(v6_default.prefix_len(), 0);
|
||||||
|
|
||||||
|
let non_default = IpNet::from_str("10.0.0.0/8").unwrap();
|
||||||
|
assert!(!non_default.addr().is_unspecified() || non_default.prefix_len() != 0);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_forwarding_status_serde() {
|
||||||
|
let status = IpForwardingStatus {
|
||||||
|
ipv4_enabled: true,
|
||||||
|
ipv6_enabled: false,
|
||||||
|
};
|
||||||
|
|
||||||
|
let json = serde_json::to_string(&status).expect("serialize");
|
||||||
|
assert!(json.contains("\"ipv4_enabled\":true"));
|
||||||
|
assert!(json.contains("\"ipv6_enabled\":false"));
|
||||||
|
|
||||||
|
let deserialized: IpForwardingStatus = serde_json::from_str(&json).expect("deserialize");
|
||||||
|
assert_eq!(status, deserialized);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_error_variants_formatting() {
|
||||||
|
let err_iface = NetworkError::InterfaceNotFound("wg-test".to_string());
|
||||||
|
assert_eq!(err_iface.to_string(), "interface 'wg-test' not found");
|
||||||
|
|
||||||
|
let err_addr = NetworkError::AddressNotFound("10.0.0.1/24".to_string());
|
||||||
|
assert_eq!(err_addr.to_string(), "address '10.0.0.1/24' not found");
|
||||||
|
|
||||||
|
let err_route = NetworkError::RouteNotFound("192.168.1.0/24".to_string());
|
||||||
|
assert_eq!(err_route.to_string(), "route '192.168.1.0/24' not found");
|
||||||
|
|
||||||
|
let err_netlink = NetworkError::Netlink("Netlink connection refused".to_string());
|
||||||
|
assert_eq!(
|
||||||
|
err_netlink.to_string(),
|
||||||
|
"netlink error: Netlink connection refused"
|
||||||
|
);
|
||||||
|
|
||||||
|
let err_perm = NetworkError::PermissionDenied("Operation requires CAP_NET_ADMIN".to_string());
|
||||||
|
assert_eq!(
|
||||||
|
err_perm.to_string(),
|
||||||
|
"permission denied: Operation requires CAP_NET_ADMIN"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_route_equality_and_filtering() {
|
||||||
|
let now = Utc::now().naive_utc();
|
||||||
|
let r1 = Route {
|
||||||
|
id: Uuid::new_v4(),
|
||||||
|
network_id: None,
|
||||||
|
interface_id: None,
|
||||||
|
destination: IpNet::from_str("172.16.0.0/12").unwrap(),
|
||||||
|
gateway: Some(IpAddr::from_str("10.0.0.254").unwrap()),
|
||||||
|
interface_name: Some("wg0".to_string()),
|
||||||
|
metric: Some(20),
|
||||||
|
enabled: true,
|
||||||
|
description: None,
|
||||||
|
created_at: now,
|
||||||
|
updated_at: now,
|
||||||
|
};
|
||||||
|
|
||||||
|
let r2 = Route {
|
||||||
|
id: Uuid::new_v4(),
|
||||||
|
network_id: None,
|
||||||
|
interface_id: None,
|
||||||
|
destination: IpNet::from_str("172.16.0.0/12").unwrap(),
|
||||||
|
gateway: Some(IpAddr::from_str("10.0.0.254").unwrap()),
|
||||||
|
interface_name: Some("wg0".to_string()),
|
||||||
|
metric: Some(20),
|
||||||
|
enabled: false,
|
||||||
|
description: None,
|
||||||
|
created_at: now,
|
||||||
|
updated_at: now,
|
||||||
|
};
|
||||||
|
|
||||||
|
assert_eq!(r1.destination, r2.destination);
|
||||||
|
assert_eq!(r1.gateway, r2.gateway);
|
||||||
|
assert!(r1.enabled);
|
||||||
|
assert!(!r2.enabled);
|
||||||
|
}
|
||||||
@@ -0,0 +1,315 @@
|
|||||||
|
//! Comprehensive unit tests for native nftables translation, deterministic compilation, and safety invariants.
|
||||||
|
|
||||||
|
use ipnet::IpNet;
|
||||||
|
use nx9_wg_core::types::firewall::{
|
||||||
|
FirewallAction, FirewallDirection, FirewallProtocol, FirewallRule,
|
||||||
|
};
|
||||||
|
use nx9_wg_network::engine::{FirewallDiagnostics, NativeLinuxNftablesEngine};
|
||||||
|
use nx9_wg_network::error::NetworkError;
|
||||||
|
use nx9_wg_network::nftables::NftablesRulesetBuilder;
|
||||||
|
use uuid::Uuid;
|
||||||
|
|
||||||
|
#[allow(clippy::too_many_arguments)]
|
||||||
|
fn make_rule(
|
||||||
|
name: &str,
|
||||||
|
dir: FirewallDirection,
|
||||||
|
action: FirewallAction,
|
||||||
|
proto: FirewallProtocol,
|
||||||
|
src: Option<&str>,
|
||||||
|
dst: Option<&str>,
|
||||||
|
dp: Option<u16>,
|
||||||
|
pr: Option<&str>,
|
||||||
|
priority: i32,
|
||||||
|
enabled: bool,
|
||||||
|
) -> FirewallRule {
|
||||||
|
FirewallRule {
|
||||||
|
id: Uuid::new_v4(),
|
||||||
|
name: name.to_string(),
|
||||||
|
interface_id: None,
|
||||||
|
peer_id: None,
|
||||||
|
direction: dir,
|
||||||
|
action,
|
||||||
|
protocol: proto,
|
||||||
|
source: src.map(|s| s.to_string()),
|
||||||
|
destination: dst.map(|s| s.to_string()),
|
||||||
|
source_port: None,
|
||||||
|
destination_port: dp,
|
||||||
|
port_range: pr.map(|p| p.to_string()),
|
||||||
|
priority,
|
||||||
|
enabled,
|
||||||
|
description: None,
|
||||||
|
created_at: chrono::Utc::now().naive_utc(),
|
||||||
|
updated_at: chrono::Utc::now().naive_utc(),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_ipv4_rule_translation() {
|
||||||
|
let rules = vec![make_rule(
|
||||||
|
"Allow IPv4 Web",
|
||||||
|
FirewallDirection::In,
|
||||||
|
FirewallAction::Accept,
|
||||||
|
FirewallProtocol::Tcp,
|
||||||
|
Some("192.168.1.0/24"),
|
||||||
|
Some("10.0.0.1"),
|
||||||
|
Some(443),
|
||||||
|
None,
|
||||||
|
10,
|
||||||
|
true,
|
||||||
|
)];
|
||||||
|
|
||||||
|
let ruleset = NftablesRulesetBuilder::build(&rules, false, &[]);
|
||||||
|
assert!(ruleset.contains("table inet nx9_wg"));
|
||||||
|
assert!(ruleset.contains("chain input"));
|
||||||
|
assert!(ruleset.contains("tcp ip saddr 192.168.1.0/24 ip daddr 10.0.0.1 tcp dport 443 accept"));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_ipv6_rule_translation() {
|
||||||
|
let rules = vec![make_rule(
|
||||||
|
"Allow IPv6 DNS",
|
||||||
|
FirewallDirection::Forward,
|
||||||
|
FirewallAction::Accept,
|
||||||
|
FirewallProtocol::Udp,
|
||||||
|
Some("2001:db8::/64"),
|
||||||
|
Some("2001:db8:ffff::1"),
|
||||||
|
Some(53),
|
||||||
|
None,
|
||||||
|
20,
|
||||||
|
true,
|
||||||
|
)];
|
||||||
|
|
||||||
|
let ruleset = NftablesRulesetBuilder::build(&rules, false, &[]);
|
||||||
|
assert!(ruleset.contains("chain forward"));
|
||||||
|
assert!(
|
||||||
|
ruleset
|
||||||
|
.contains("udp ip6 saddr 2001:db8::/64 ip6 daddr 2001:db8:ffff::1 udp dport 53 accept")
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_protocol_groups_and_icmp() {
|
||||||
|
let rules = vec![
|
||||||
|
make_rule(
|
||||||
|
"Allow ICMP Ping",
|
||||||
|
FirewallDirection::In,
|
||||||
|
FirewallAction::Accept,
|
||||||
|
FirewallProtocol::Icmp,
|
||||||
|
None,
|
||||||
|
None,
|
||||||
|
None,
|
||||||
|
None,
|
||||||
|
1,
|
||||||
|
true,
|
||||||
|
),
|
||||||
|
make_rule(
|
||||||
|
"Allow TCP+UDP Services",
|
||||||
|
FirewallDirection::Forward,
|
||||||
|
FirewallAction::Accept,
|
||||||
|
FirewallProtocol::TcpUdp,
|
||||||
|
Some("10.100.0.5"),
|
||||||
|
None,
|
||||||
|
None,
|
||||||
|
Some("53,80,443"),
|
||||||
|
5,
|
||||||
|
true,
|
||||||
|
),
|
||||||
|
];
|
||||||
|
|
||||||
|
let ruleset = NftablesRulesetBuilder::build(&rules, false, &[]);
|
||||||
|
assert!(ruleset.contains("ip protocol icmp accept"));
|
||||||
|
assert!(
|
||||||
|
ruleset.contains(
|
||||||
|
"meta l4proto { tcp, udp } ip saddr 10.100.0.5 th dport { 53, 80, 443 } accept"
|
||||||
|
)
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_port_ranges_and_single_ports() {
|
||||||
|
let rules = vec![make_rule(
|
||||||
|
"Allow Port Range",
|
||||||
|
FirewallDirection::In,
|
||||||
|
FirewallAction::Accept,
|
||||||
|
FirewallProtocol::Tcp,
|
||||||
|
None,
|
||||||
|
None,
|
||||||
|
None,
|
||||||
|
Some("8000-8100"),
|
||||||
|
15,
|
||||||
|
true,
|
||||||
|
)];
|
||||||
|
|
||||||
|
let ruleset = NftablesRulesetBuilder::build(&rules, false, &[]);
|
||||||
|
assert!(ruleset.contains("tcp tcp dport 8000-8100 accept"));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_drop_and_reject_actions() {
|
||||||
|
let rules = vec![
|
||||||
|
make_rule(
|
||||||
|
"Block Bad Subnet",
|
||||||
|
FirewallDirection::In,
|
||||||
|
FirewallAction::Drop,
|
||||||
|
FirewallProtocol::Any,
|
||||||
|
Some("198.51.100.0/24"),
|
||||||
|
None,
|
||||||
|
None,
|
||||||
|
None,
|
||||||
|
50,
|
||||||
|
true,
|
||||||
|
),
|
||||||
|
make_rule(
|
||||||
|
"Reject Telnet",
|
||||||
|
FirewallDirection::Forward,
|
||||||
|
FirewallAction::Reject,
|
||||||
|
FirewallProtocol::Tcp,
|
||||||
|
None,
|
||||||
|
None,
|
||||||
|
Some(23),
|
||||||
|
None,
|
||||||
|
60,
|
||||||
|
true,
|
||||||
|
),
|
||||||
|
];
|
||||||
|
|
||||||
|
let ruleset = NftablesRulesetBuilder::build(&rules, false, &[]);
|
||||||
|
assert!(ruleset.contains("ip saddr 198.51.100.0/24 drop"));
|
||||||
|
assert!(ruleset.contains("tcp tcp dport 23 reject"));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_nat_masquerade_subnets_scoping() {
|
||||||
|
let v4_subnet: IpNet = "10.100.0.0/24".parse().unwrap();
|
||||||
|
let v6_subnet: IpNet = "fd00:9999::/64".parse().unwrap();
|
||||||
|
|
||||||
|
let ruleset = NftablesRulesetBuilder::build(&[], true, &[v4_subnet, v6_subnet]);
|
||||||
|
assert!(ruleset.contains("chain postrouting"));
|
||||||
|
assert!(ruleset.contains("type nat hook postrouting priority srcnat; policy accept;"));
|
||||||
|
assert!(ruleset.contains("ip saddr 10.100.0.0/24 oifname != \"wg*\" masquerade"));
|
||||||
|
assert!(ruleset.contains("ip6 saddr fd00:9999::/64 oifname != \"wg*\" masquerade"));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_deterministic_priority_ordering() {
|
||||||
|
let rules = vec![
|
||||||
|
make_rule(
|
||||||
|
"Low Priority",
|
||||||
|
FirewallDirection::In,
|
||||||
|
FirewallAction::Accept,
|
||||||
|
FirewallProtocol::Tcp,
|
||||||
|
None,
|
||||||
|
None,
|
||||||
|
Some(80),
|
||||||
|
None,
|
||||||
|
100,
|
||||||
|
true,
|
||||||
|
),
|
||||||
|
make_rule(
|
||||||
|
"High Priority",
|
||||||
|
FirewallDirection::In,
|
||||||
|
FirewallAction::Drop,
|
||||||
|
FirewallProtocol::Tcp,
|
||||||
|
None,
|
||||||
|
None,
|
||||||
|
Some(80),
|
||||||
|
None,
|
||||||
|
10,
|
||||||
|
true,
|
||||||
|
),
|
||||||
|
make_rule(
|
||||||
|
"Disabled Rule",
|
||||||
|
FirewallDirection::In,
|
||||||
|
FirewallAction::Accept,
|
||||||
|
FirewallProtocol::Tcp,
|
||||||
|
None,
|
||||||
|
None,
|
||||||
|
Some(8080),
|
||||||
|
None,
|
||||||
|
5,
|
||||||
|
false,
|
||||||
|
),
|
||||||
|
];
|
||||||
|
|
||||||
|
let ruleset = NftablesRulesetBuilder::build(&rules, false, &[]);
|
||||||
|
let drop_pos = ruleset.find("tcp tcp dport 80 drop").unwrap();
|
||||||
|
let accept_pos = ruleset.find("tcp tcp dport 80 accept").unwrap();
|
||||||
|
assert!(
|
||||||
|
drop_pos < accept_pos,
|
||||||
|
"Higher priority rule (priority 10) must appear before lower priority rule (priority 100)"
|
||||||
|
);
|
||||||
|
assert!(
|
||||||
|
!ruleset.contains("8080"),
|
||||||
|
"Disabled rule must not appear in generated ruleset"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[tokio::test]
|
||||||
|
async fn test_ownership_validation_rejects_unmanaged_tables() {
|
||||||
|
let engine = NativeLinuxNftablesEngine::new();
|
||||||
|
|
||||||
|
// Rejects global flush
|
||||||
|
let err1 = engine.apply_ruleset("flush ruleset").await.unwrap_err();
|
||||||
|
match err1 {
|
||||||
|
NetworkError::FirewallOwnershipViolation(msg) => {
|
||||||
|
assert!(msg.contains("Refusing to flush global"));
|
||||||
|
}
|
||||||
|
other => panic!("Expected FirewallOwnershipViolation, got: {other:?}"),
|
||||||
|
}
|
||||||
|
|
||||||
|
// Rejects other tables
|
||||||
|
let err2 = engine
|
||||||
|
.apply_ruleset("table ip filter {\n}\n")
|
||||||
|
.await
|
||||||
|
.unwrap_err();
|
||||||
|
match err2 {
|
||||||
|
NetworkError::FirewallOwnershipViolation(msg) => {
|
||||||
|
assert!(msg.contains("Refusing to execute command outside 'table inet nx9_wg'"));
|
||||||
|
}
|
||||||
|
other => panic!("Expected FirewallOwnershipViolation, got: {other:?}"),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_error_variants_and_formatting() {
|
||||||
|
let err_inv = NetworkError::FirewallRuleInvalid("Port out of bounds".to_string());
|
||||||
|
assert_eq!(
|
||||||
|
err_inv.to_string(),
|
||||||
|
"invalid firewall rule: Port out of bounds"
|
||||||
|
);
|
||||||
|
|
||||||
|
let err_own = NetworkError::FirewallOwnershipViolation("Cannot delete eth0".to_string());
|
||||||
|
assert_eq!(
|
||||||
|
err_own.to_string(),
|
||||||
|
"firewall ownership violation: Cannot delete eth0"
|
||||||
|
);
|
||||||
|
|
||||||
|
let err_nat = NetworkError::NatConfigurationInvalid("Wildcard CIDR not permitted".to_string());
|
||||||
|
assert_eq!(
|
||||||
|
err_nat.to_string(),
|
||||||
|
"invalid NAT configuration: Wildcard CIDR not permitted"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_firewall_diagnostics_serialization() {
|
||||||
|
let diag = FirewallDiagnostics {
|
||||||
|
table_exists: true,
|
||||||
|
table_name: "nx9_wg".to_string(),
|
||||||
|
family: "inet".to_string(),
|
||||||
|
chain_count: 3,
|
||||||
|
chains: vec![
|
||||||
|
"input".to_string(),
|
||||||
|
"forward".to_string(),
|
||||||
|
"postrouting".to_string(),
|
||||||
|
],
|
||||||
|
rule_count: 5,
|
||||||
|
nat_enabled: true,
|
||||||
|
live_ruleset: Some("table inet nx9_wg { }".to_string()),
|
||||||
|
kernel_status: "active".to_string(),
|
||||||
|
};
|
||||||
|
|
||||||
|
let json = serde_json::to_string(&diag).unwrap();
|
||||||
|
assert!(json.contains("\"table_name\":\"nx9_wg\""));
|
||||||
|
assert!(json.contains("\"nat_enabled\":true"));
|
||||||
|
}
|
||||||
@@ -41,7 +41,7 @@ impl Default for DashboardState {
|
|||||||
fn default() -> Self {
|
fn default() -> Self {
|
||||||
Self {
|
Self {
|
||||||
hostname: "nx9-wg-appliance".to_string(),
|
hostname: "nx9-wg-appliance".to_string(),
|
||||||
os_version: "Linux native (nx9-wg v0.1.0)".to_string(),
|
os_version: "Linux native (nx9-wg v0.8.0)".to_string(),
|
||||||
uptime_formatted: "3d 14h 22m".to_string(),
|
uptime_formatted: "3d 14h 22m".to_string(),
|
||||||
is_operational: true,
|
is_operational: true,
|
||||||
load_average: "0.15, 0.08, 0.03".to_string(),
|
load_average: "0.15, 0.08, 0.03".to_string(),
|
||||||
|
|||||||
@@ -19,5 +19,15 @@ qrcode.workspace = true
|
|||||||
image.workspace = true
|
image.workspace = true
|
||||||
async-trait = "0.1"
|
async-trait = "0.1"
|
||||||
|
|
||||||
|
[target.'cfg(target_os = "linux")'.dependencies]
|
||||||
|
rtnetlink = { workspace = true }
|
||||||
|
genetlink = { workspace = true }
|
||||||
|
netlink-packet-wireguard = { workspace = true }
|
||||||
|
netlink-packet-core = { workspace = true }
|
||||||
|
netlink-packet-generic = { workspace = true }
|
||||||
|
netlink-proto = { workspace = true }
|
||||||
|
netlink-sys = { workspace = true }
|
||||||
|
futures = { workspace = true }
|
||||||
|
|
||||||
[dev-dependencies]
|
[dev-dependencies]
|
||||||
tempfile.workspace = true
|
tempfile.workspace = true
|
||||||
@@ -143,12 +143,25 @@ impl WireGuardEngine for SimulatedWireGuardEngine {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Linux Native WireGuard Engine using kernel netlink / interfaces.
|
// ── Native Linux WireGuard Engine ─────────────────────────────────────────────
|
||||||
|
//
|
||||||
|
// On Linux: the real implementation lives in native_linux.rs and uses
|
||||||
|
// RTNETLINK + WireGuard Generic Netlink to communicate with the kernel.
|
||||||
|
//
|
||||||
|
// On non-Linux platforms: a thin simulation wrapper is provided so that
|
||||||
|
// the workspace remains portable and tests remain functional.
|
||||||
|
|
||||||
|
#[cfg(target_os = "linux")]
|
||||||
|
pub use crate::native_linux::NativeLinuxWireGuardEngine;
|
||||||
|
|
||||||
|
/// Non-Linux fallback: NativeLinuxWireGuardEngine delegates to simulation.
|
||||||
|
#[cfg(not(target_os = "linux"))]
|
||||||
#[derive(Debug, Clone, Default)]
|
#[derive(Debug, Clone, Default)]
|
||||||
pub struct NativeLinuxWireGuardEngine {
|
pub struct NativeLinuxWireGuardEngine {
|
||||||
simulated_fallback: SimulatedWireGuardEngine,
|
simulated_fallback: SimulatedWireGuardEngine,
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[cfg(not(target_os = "linux"))]
|
||||||
impl NativeLinuxWireGuardEngine {
|
impl NativeLinuxWireGuardEngine {
|
||||||
pub fn new() -> Self {
|
pub fn new() -> Self {
|
||||||
Self {
|
Self {
|
||||||
@@ -156,24 +169,16 @@ impl NativeLinuxWireGuardEngine {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Check if Linux kernel WireGuard module / interface support is available.
|
/// Check if Linux kernel WireGuard support is available.
|
||||||
pub fn is_supported() -> bool {
|
pub fn is_supported() -> bool {
|
||||||
#[cfg(target_os = "linux")]
|
false
|
||||||
{
|
|
||||||
std::path::Path::new("/sys/module/wireguard").exists()
|
|
||||||
|| std::path::Path::new("/proc/net/dev").exists()
|
|
||||||
}
|
|
||||||
#[cfg(not(target_os = "linux"))]
|
|
||||||
{
|
|
||||||
false
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[cfg(not(target_os = "linux"))]
|
||||||
#[async_trait::async_trait]
|
#[async_trait::async_trait]
|
||||||
impl WireGuardEngine for NativeLinuxWireGuardEngine {
|
impl WireGuardEngine for NativeLinuxWireGuardEngine {
|
||||||
async fn sync_interface(&self, interface: &Interface, peers: &[Peer]) -> Result<()> {
|
async fn sync_interface(&self, interface: &Interface, peers: &[Peer]) -> Result<()> {
|
||||||
// Fallback to simulated engine for test sandboxes and non-root execution
|
|
||||||
self.simulated_fallback
|
self.simulated_fallback
|
||||||
.sync_interface(interface, peers)
|
.sync_interface(interface, peers)
|
||||||
.await
|
.await
|
||||||
|
|||||||
@@ -24,6 +24,21 @@ pub enum WireGuardError {
|
|||||||
#[error("permission denied: {0}")]
|
#[error("permission denied: {0}")]
|
||||||
PermissionDenied(String),
|
PermissionDenied(String),
|
||||||
|
|
||||||
|
#[error("interface not found: {0}")]
|
||||||
|
InterfaceNotFound(String),
|
||||||
|
|
||||||
|
#[error("wrong interface type: expected wireguard, found {0}")]
|
||||||
|
WrongInterfaceType(String),
|
||||||
|
|
||||||
|
#[error("unsupported: {0}")]
|
||||||
|
Unsupported(String),
|
||||||
|
|
||||||
|
#[error("invalid endpoint: {0}")]
|
||||||
|
InvalidEndpoint(String),
|
||||||
|
|
||||||
|
#[error("invalid allowed IP: {0}")]
|
||||||
|
InvalidAllowedIp(String),
|
||||||
|
|
||||||
#[error("I/O error: {0}")]
|
#[error("I/O error: {0}")]
|
||||||
Io(#[from] std::io::Error),
|
Io(#[from] std::io::Error),
|
||||||
|
|
||||||
|
|||||||
@@ -3,6 +3,8 @@
|
|||||||
pub mod config_builder;
|
pub mod config_builder;
|
||||||
pub mod engine;
|
pub mod engine;
|
||||||
pub mod error;
|
pub mod error;
|
||||||
|
#[cfg(target_os = "linux")]
|
||||||
|
mod native_linux;
|
||||||
pub mod qr;
|
pub mod qr;
|
||||||
|
|
||||||
pub use config_builder::ClientConfigBuilder;
|
pub use config_builder::ClientConfigBuilder;
|
||||||
|
|||||||
@@ -0,0 +1,540 @@
|
|||||||
|
//! Native Linux WireGuard engine using RTNETLINK and WireGuard Generic Netlink.
|
||||||
|
//!
|
||||||
|
//! This module communicates directly with the Linux kernel to manage WireGuard
|
||||||
|
//! interfaces. It uses:
|
||||||
|
//!
|
||||||
|
//! - **RTNETLINK** for network link lifecycle (create, delete, list interfaces)
|
||||||
|
//! - **WireGuard Generic Netlink** for device configuration and telemetry
|
||||||
|
//!
|
||||||
|
//! No external commands (wg, ip, wg-quick, nft, sysctl) are ever executed.
|
||||||
|
|
||||||
|
use crate::engine::{LiveInterfaceStats, LivePeerStats, WireGuardEngine};
|
||||||
|
use crate::error::{Result, WireGuardError};
|
||||||
|
use base64::Engine as _;
|
||||||
|
use chrono::NaiveDateTime;
|
||||||
|
use futures::stream::{StreamExt, TryStreamExt};
|
||||||
|
use genetlink::GenetlinkHandle;
|
||||||
|
use ipnet::IpNet;
|
||||||
|
use netlink_packet_core::{NLM_F_ACK, NLM_F_DUMP, NLM_F_REQUEST, NetlinkMessage, NetlinkPayload};
|
||||||
|
use netlink_packet_generic::GenlMessage;
|
||||||
|
use netlink_packet_wireguard::{
|
||||||
|
WireguardAddressFamily, WireguardAllowedIp, WireguardAllowedIpAttr, WireguardAttribute,
|
||||||
|
WireguardCmd, WireguardDeviceFlags, WireguardMessage, WireguardPeer, WireguardPeerAttribute,
|
||||||
|
WireguardPeerFlags,
|
||||||
|
};
|
||||||
|
use nx9_wg_core::types::wireguard::{Interface, Peer, PeerState};
|
||||||
|
use rtnetlink::LinkWireguard;
|
||||||
|
use rtnetlink::packet_route::link::{InfoKind, LinkAttribute, LinkInfo};
|
||||||
|
use std::net::{IpAddr, SocketAddr};
|
||||||
|
|
||||||
|
/// Linux Native WireGuard Engine using kernel RTNETLINK and Generic Netlink.
|
||||||
|
#[derive(Debug, Clone, Default)]
|
||||||
|
pub struct NativeLinuxWireGuardEngine;
|
||||||
|
|
||||||
|
impl NativeLinuxWireGuardEngine {
|
||||||
|
pub fn new() -> Self {
|
||||||
|
Self
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Check if Linux kernel WireGuard module and Generic Netlink support is available.
|
||||||
|
pub fn is_supported() -> bool {
|
||||||
|
// Check for the WireGuard kernel module or network dev procfs
|
||||||
|
std::path::Path::new("/sys/module/wireguard").exists()
|
||||||
|
|| std::path::Path::new("/proc/net/dev").exists()
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ── RTNETLINK Interface Lifecycle ─────────────────────────────────────────────
|
||||||
|
|
||||||
|
/// Create a new RTNETLINK connection and return the handle.
|
||||||
|
async fn rtnetlink_handle() -> Result<(rtnetlink::Handle, tokio::task::JoinHandle<()>)> {
|
||||||
|
let (connection, handle, _) = rtnetlink::new_connection().map_err(|e| {
|
||||||
|
WireGuardError::Netlink(format!("failed to create rtnetlink connection: {e}"))
|
||||||
|
})?;
|
||||||
|
let join = tokio::spawn(connection);
|
||||||
|
Ok((handle, join))
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Ensure a WireGuard interface exists with the given name.
|
||||||
|
///
|
||||||
|
/// - If the interface already exists and is a WireGuard link, this is a no-op.
|
||||||
|
/// - If the interface already exists but is NOT a WireGuard link, returns an error.
|
||||||
|
/// - If the interface does not exist, it is created as a WireGuard link and brought up.
|
||||||
|
async fn ensure_link(name: &str) -> Result<()> {
|
||||||
|
let (handle, _conn_task) = rtnetlink_handle().await?;
|
||||||
|
|
||||||
|
// Try to find existing interface by name
|
||||||
|
let mut links = handle.link().get().match_name(name.to_string()).execute();
|
||||||
|
|
||||||
|
match links.try_next().await {
|
||||||
|
Ok(Some(link)) => {
|
||||||
|
let mut is_wireguard = false;
|
||||||
|
for nla in &link.attributes {
|
||||||
|
if let LinkAttribute::LinkInfo(infos) = nla {
|
||||||
|
for info in infos {
|
||||||
|
if let LinkInfo::Kind(InfoKind::Wireguard) = info {
|
||||||
|
is_wireguard = true;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if is_wireguard {
|
||||||
|
tracing::debug!(interface = %name, "WireGuard interface already exists");
|
||||||
|
Ok(())
|
||||||
|
} else {
|
||||||
|
Err(WireGuardError::WrongInterfaceType(format!(
|
||||||
|
"interface '{name}' exists but is not a WireGuard interface"
|
||||||
|
)))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
Ok(None) | Err(_) => {
|
||||||
|
// Interface does not exist — create it and bring it up
|
||||||
|
tracing::info!(interface = %name, "Creating WireGuard interface via RTNETLINK");
|
||||||
|
let add_msg = LinkWireguard::new(name).up().build();
|
||||||
|
|
||||||
|
handle.link().add(add_msg).execute().await.map_err(|e| {
|
||||||
|
let msg = format!("{e}");
|
||||||
|
if msg.contains("permission")
|
||||||
|
|| msg.contains("EPERM")
|
||||||
|
|| msg.contains("Operation not permitted")
|
||||||
|
{
|
||||||
|
WireGuardError::PermissionDenied(format!(
|
||||||
|
"insufficient privileges to create WireGuard interface '{name}': {e}"
|
||||||
|
))
|
||||||
|
} else {
|
||||||
|
WireGuardError::Netlink(format!(
|
||||||
|
"failed to create WireGuard interface '{name}': {e}"
|
||||||
|
))
|
||||||
|
}
|
||||||
|
})?;
|
||||||
|
|
||||||
|
tracing::info!(interface = %name, "WireGuard interface created and brought up");
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Delete a WireGuard interface by name.
|
||||||
|
async fn delete_link(name: &str) -> Result<()> {
|
||||||
|
let (handle, _conn_task) = rtnetlink_handle().await?;
|
||||||
|
|
||||||
|
let mut links = handle.link().get().match_name(name.to_string()).execute();
|
||||||
|
match links.try_next().await {
|
||||||
|
Ok(Some(link)) => {
|
||||||
|
let index = link.header.index;
|
||||||
|
handle.link().del(index).execute().await.map_err(|e| {
|
||||||
|
WireGuardError::Netlink(format!(
|
||||||
|
"failed to delete interface '{name}' (index {index}): {e}"
|
||||||
|
))
|
||||||
|
})?;
|
||||||
|
tracing::info!(interface = %name, "WireGuard interface deleted via RTNETLINK");
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
Ok(None) => {
|
||||||
|
tracing::debug!(interface = %name, "Interface not found for deletion");
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
Err(e) => Err(WireGuardError::Netlink(format!(
|
||||||
|
"failed to look up interface '{name}': {e}"
|
||||||
|
))),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// List all WireGuard interface names using RTNETLINK link dump.
|
||||||
|
async fn list_wireguard_links() -> Result<Vec<String>> {
|
||||||
|
let (handle, _conn_task) = rtnetlink_handle().await?;
|
||||||
|
|
||||||
|
let mut links = handle.link().get().execute();
|
||||||
|
let mut wg_names = Vec::new();
|
||||||
|
|
||||||
|
while let Some(link) = links
|
||||||
|
.try_next()
|
||||||
|
.await
|
||||||
|
.map_err(|e| WireGuardError::Netlink(format!("failed to dump links: {e}")))?
|
||||||
|
{
|
||||||
|
let mut name = None;
|
||||||
|
let mut is_wireguard = false;
|
||||||
|
|
||||||
|
for nla in &link.attributes {
|
||||||
|
match nla {
|
||||||
|
LinkAttribute::IfName(n) => name = Some(n.clone()),
|
||||||
|
LinkAttribute::LinkInfo(infos) => {
|
||||||
|
for info in infos {
|
||||||
|
if let LinkInfo::Kind(InfoKind::Wireguard) = info {
|
||||||
|
is_wireguard = true;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
_ => {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if let (true, Some(n)) = (is_wireguard, name) {
|
||||||
|
wg_names.push(n);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
Ok(wg_names)
|
||||||
|
}
|
||||||
|
|
||||||
|
// ── WireGuard Generic Netlink Operations ─────────────────────────────────────
|
||||||
|
|
||||||
|
/// Create a WireGuard Generic Netlink connection.
|
||||||
|
async fn wireguard_genl_handle() -> Result<(GenetlinkHandle, tokio::task::JoinHandle<()>)> {
|
||||||
|
let (connection, handle, _) = genetlink::new_connection().map_err(|e| {
|
||||||
|
WireGuardError::Netlink(format!("failed to create genetlink connection: {e}"))
|
||||||
|
})?;
|
||||||
|
let join = tokio::spawn(connection);
|
||||||
|
Ok((handle, join))
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Configure a WireGuard device via Generic Netlink SET_DEVICE.
|
||||||
|
///
|
||||||
|
/// Sets the private key, listen port, and synchronizes the active peer set.
|
||||||
|
/// Uses `WireguardDeviceFlags::ReplacePeers` to atomically replace all peers.
|
||||||
|
async fn configure_device(interface: &Interface, peers: &[Peer]) -> Result<()> {
|
||||||
|
let (mut handle, _conn_task) = wireguard_genl_handle().await?;
|
||||||
|
|
||||||
|
// Decode the private key from base64 to 32 bytes
|
||||||
|
let private_key_bytes = decode_base64_key(interface.private_key.as_str())
|
||||||
|
.map_err(|e| WireGuardError::Key(format!("invalid interface private key: {e}")))?;
|
||||||
|
|
||||||
|
// Build the device attributes
|
||||||
|
let mut device_attrs: Vec<WireguardAttribute> = vec![
|
||||||
|
WireguardAttribute::IfName(interface.name.clone()),
|
||||||
|
WireguardAttribute::PrivateKey(private_key_bytes),
|
||||||
|
WireguardAttribute::ListenPort(interface.listen_port),
|
||||||
|
WireguardAttribute::Fwmark(0),
|
||||||
|
WireguardAttribute::Flags(WireguardDeviceFlags::ReplacePeers),
|
||||||
|
];
|
||||||
|
|
||||||
|
// Build peer configurations for active peers only
|
||||||
|
let mut wg_peers = Vec::new();
|
||||||
|
for peer in peers.iter().filter(|p| p.state == PeerState::Active) {
|
||||||
|
let mut peer_attrs: Vec<WireguardPeerAttribute> = Vec::new();
|
||||||
|
|
||||||
|
// Public key (required)
|
||||||
|
let pub_key_bytes = decode_base64_key(peer.public_key.as_str())
|
||||||
|
.map_err(|e| WireGuardError::Key(format!("invalid peer public key: {e}")))?;
|
||||||
|
peer_attrs.push(WireguardPeerAttribute::PublicKey(pub_key_bytes));
|
||||||
|
|
||||||
|
// Preshared key (optional)
|
||||||
|
if let Some(ref psk) = peer.preshared_key {
|
||||||
|
let psk_bytes = decode_base64_key(psk.as_str())
|
||||||
|
.map_err(|e| WireGuardError::Key(format!("invalid peer preshared key: {e}")))?;
|
||||||
|
peer_attrs.push(WireguardPeerAttribute::PresharedKey(psk_bytes));
|
||||||
|
}
|
||||||
|
|
||||||
|
// Endpoint (optional)
|
||||||
|
if let Some(ref endpoint_str) = peer.endpoint {
|
||||||
|
let endpoint = parse_endpoint(endpoint_str)?;
|
||||||
|
peer_attrs.push(WireguardPeerAttribute::Endpoint(endpoint));
|
||||||
|
}
|
||||||
|
|
||||||
|
// Persistent keepalive (optional)
|
||||||
|
if let Some(keepalive) = peer.persistent_keepalive {
|
||||||
|
peer_attrs.push(WireguardPeerAttribute::PersistentKeepalive(keepalive));
|
||||||
|
}
|
||||||
|
|
||||||
|
// Allowed IPs
|
||||||
|
let allowed_ips = parse_allowed_ips(&peer.allowed_ips)?;
|
||||||
|
if !allowed_ips.is_empty() {
|
||||||
|
peer_attrs.push(WireguardPeerAttribute::Flags(
|
||||||
|
WireguardPeerFlags::ReplaceAllowedIps,
|
||||||
|
));
|
||||||
|
peer_attrs.push(WireguardPeerAttribute::AllowedIps(allowed_ips));
|
||||||
|
}
|
||||||
|
|
||||||
|
wg_peers.push(WireguardPeer(peer_attrs));
|
||||||
|
}
|
||||||
|
|
||||||
|
device_attrs.push(WireguardAttribute::Peers(wg_peers));
|
||||||
|
|
||||||
|
// Build and send the SET_DEVICE message
|
||||||
|
let genlmsg = GenlMessage::from_payload(WireguardMessage {
|
||||||
|
cmd: WireguardCmd::SetDevice,
|
||||||
|
attributes: device_attrs,
|
||||||
|
});
|
||||||
|
|
||||||
|
let mut nlmsg = NetlinkMessage::from(genlmsg);
|
||||||
|
nlmsg.header.flags = NLM_F_REQUEST | NLM_F_ACK;
|
||||||
|
nlmsg.finalize();
|
||||||
|
|
||||||
|
let mut response = handle.request(nlmsg).await.map_err(|e| {
|
||||||
|
let msg = format!("{e}");
|
||||||
|
if msg.contains("not found") || msg.contains("No such") {
|
||||||
|
WireGuardError::Unsupported(
|
||||||
|
"WireGuard Generic Netlink family not available — is the wireguard kernel module loaded?".to_string(),
|
||||||
|
)
|
||||||
|
} else {
|
||||||
|
WireGuardError::Netlink(format!("failed to send WireGuard SET_DEVICE: {e}"))
|
||||||
|
}
|
||||||
|
})?;
|
||||||
|
|
||||||
|
// Check for errors in the response stream
|
||||||
|
while let Some(res) = response.next().await {
|
||||||
|
let msg = res.map_err(|e| WireGuardError::Netlink(format!("decode error: {e}")))?;
|
||||||
|
if let NetlinkPayload::Error(err) = msg.payload
|
||||||
|
&& let Some(code) = err.code
|
||||||
|
{
|
||||||
|
let code_val = code.get();
|
||||||
|
if code_val == -1 {
|
||||||
|
return Err(WireGuardError::PermissionDenied(
|
||||||
|
"insufficient privileges to configure WireGuard device".to_string(),
|
||||||
|
));
|
||||||
|
}
|
||||||
|
return Err(WireGuardError::Netlink(format!(
|
||||||
|
"kernel rejected WireGuard device configuration (errno={code_val})"
|
||||||
|
)));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
tracing::debug!(
|
||||||
|
interface = %interface.name,
|
||||||
|
active_peers = peers.iter().filter(|p| p.state == PeerState::Active).count(),
|
||||||
|
"WireGuard device configured via Generic Netlink"
|
||||||
|
);
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Query a WireGuard device via Generic Netlink GET_DEVICE and return live stats.
|
||||||
|
async fn query_device(name: &str) -> Result<Option<LiveInterfaceStats>> {
|
||||||
|
let (mut handle, _conn_task) = wireguard_genl_handle().await?;
|
||||||
|
|
||||||
|
let genlmsg = GenlMessage::from_payload(WireguardMessage {
|
||||||
|
cmd: WireguardCmd::GetDevice,
|
||||||
|
attributes: vec![WireguardAttribute::IfName(name.to_string())],
|
||||||
|
});
|
||||||
|
|
||||||
|
let mut nlmsg = NetlinkMessage::from(genlmsg);
|
||||||
|
nlmsg.header.flags = NLM_F_REQUEST | NLM_F_DUMP;
|
||||||
|
nlmsg.finalize();
|
||||||
|
|
||||||
|
let mut response = handle.request(nlmsg).await.map_err(|e| {
|
||||||
|
let msg = format!("{e}");
|
||||||
|
if msg.contains("No such device") || msg.contains("ENODEV") {
|
||||||
|
WireGuardError::InterfaceNotFound(format!("interface '{name}' not found"))
|
||||||
|
} else if msg.contains("not found") || msg.contains("No such") {
|
||||||
|
WireGuardError::Unsupported(
|
||||||
|
"WireGuard Generic Netlink family not available — is the wireguard kernel module loaded?".to_string(),
|
||||||
|
)
|
||||||
|
} else {
|
||||||
|
WireGuardError::Netlink(format!("failed to query WireGuard device '{name}': {e}"))
|
||||||
|
}
|
||||||
|
})?;
|
||||||
|
|
||||||
|
let mut public_key = String::new();
|
||||||
|
let mut listen_port: u16 = 0;
|
||||||
|
let mut fwmark: u32 = 0;
|
||||||
|
let mut live_peers: Vec<LivePeerStats> = Vec::new();
|
||||||
|
let mut found = false;
|
||||||
|
|
||||||
|
while let Some(res) = response.next().await {
|
||||||
|
let msg = res.map_err(|e| WireGuardError::Netlink(format!("decode error: {e}")))?;
|
||||||
|
match msg.payload {
|
||||||
|
NetlinkPayload::Error(err) => {
|
||||||
|
if let Some(code) = err.code {
|
||||||
|
let code_val = code.get();
|
||||||
|
// ENODEV = -19 means device not found
|
||||||
|
if code_val == -19 {
|
||||||
|
return Ok(None);
|
||||||
|
}
|
||||||
|
if code_val == -1 {
|
||||||
|
return Err(WireGuardError::PermissionDenied(
|
||||||
|
"insufficient privileges to query WireGuard device".to_string(),
|
||||||
|
));
|
||||||
|
}
|
||||||
|
return Err(WireGuardError::Netlink(format!(
|
||||||
|
"kernel error querying WireGuard device (errno={code_val})"
|
||||||
|
)));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
NetlinkPayload::InnerMessage(genl) => {
|
||||||
|
found = true;
|
||||||
|
for attr in genl.payload.attributes {
|
||||||
|
match attr {
|
||||||
|
WireguardAttribute::PublicKey(key) => {
|
||||||
|
public_key = base64::engine::general_purpose::STANDARD.encode(key);
|
||||||
|
}
|
||||||
|
WireguardAttribute::ListenPort(port) => listen_port = port,
|
||||||
|
WireguardAttribute::Fwmark(fw) => fwmark = fw,
|
||||||
|
WireguardAttribute::Peers(peers) => {
|
||||||
|
for peer in peers {
|
||||||
|
let mut peer_pubkey = String::new();
|
||||||
|
let mut peer_endpoint: Option<String> = None;
|
||||||
|
let mut rx_bytes: u64 = 0;
|
||||||
|
let mut tx_bytes: u64 = 0;
|
||||||
|
let mut last_handshake: Option<NaiveDateTime> = None;
|
||||||
|
let mut allowed_ips_strs: Vec<String> = Vec::new();
|
||||||
|
let mut persistent_keepalive: Option<u16> = None;
|
||||||
|
|
||||||
|
for attr in peer.0 {
|
||||||
|
match attr {
|
||||||
|
WireguardPeerAttribute::PublicKey(key) => {
|
||||||
|
peer_pubkey = base64::engine::general_purpose::STANDARD
|
||||||
|
.encode(key);
|
||||||
|
}
|
||||||
|
WireguardPeerAttribute::Endpoint(ep) => {
|
||||||
|
peer_endpoint = Some(format!("{ep}"));
|
||||||
|
}
|
||||||
|
WireguardPeerAttribute::RxBytes(rx) => rx_bytes = rx,
|
||||||
|
WireguardPeerAttribute::TxBytes(tx) => tx_bytes = tx,
|
||||||
|
WireguardPeerAttribute::LastHandshake(ts) => {
|
||||||
|
let secs = ts.seconds;
|
||||||
|
let nsecs = ts.nano_seconds;
|
||||||
|
if secs > 0 {
|
||||||
|
last_handshake = chrono::DateTime::from_timestamp(
|
||||||
|
secs,
|
||||||
|
nsecs.clamp(0, 999_999_999) as u32,
|
||||||
|
)
|
||||||
|
.map(|dt| dt.naive_utc());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
WireguardPeerAttribute::AllowedIps(ips) => {
|
||||||
|
for ip_entry in ips {
|
||||||
|
let mut addr: Option<IpAddr> = None;
|
||||||
|
let mut prefix: u8 = 0;
|
||||||
|
for ip_attr in ip_entry.0 {
|
||||||
|
match ip_attr {
|
||||||
|
WireguardAllowedIpAttr::IpAddr(a) => {
|
||||||
|
addr = Some(a);
|
||||||
|
}
|
||||||
|
WireguardAllowedIpAttr::Cidr(c) => {
|
||||||
|
prefix = c;
|
||||||
|
}
|
||||||
|
_ => {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if let Some(a) = addr {
|
||||||
|
allowed_ips_strs.push(format!("{a}/{prefix}"));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
WireguardPeerAttribute::PersistentKeepalive(ka)
|
||||||
|
if ka > 0 =>
|
||||||
|
{
|
||||||
|
persistent_keepalive = Some(ka);
|
||||||
|
}
|
||||||
|
_ => {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
live_peers.push(LivePeerStats {
|
||||||
|
public_key: peer_pubkey,
|
||||||
|
endpoint: peer_endpoint,
|
||||||
|
rx_bytes,
|
||||||
|
tx_bytes,
|
||||||
|
last_handshake_at: last_handshake,
|
||||||
|
allowed_ips: allowed_ips_strs,
|
||||||
|
persistent_keepalive,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
_ => {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
_ => {}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if !found {
|
||||||
|
return Ok(None);
|
||||||
|
}
|
||||||
|
|
||||||
|
Ok(Some(LiveInterfaceStats {
|
||||||
|
name: name.to_string(),
|
||||||
|
public_key,
|
||||||
|
listen_port,
|
||||||
|
fwmark,
|
||||||
|
peers: live_peers,
|
||||||
|
}))
|
||||||
|
}
|
||||||
|
|
||||||
|
// ── Conversion Utilities ─────────────────────────────────────────────────────
|
||||||
|
|
||||||
|
/// Decode a base64-encoded WireGuard key into exactly 32 bytes.
|
||||||
|
fn decode_base64_key(b64: &str) -> std::result::Result<[u8; 32], String> {
|
||||||
|
let bytes = base64::engine::general_purpose::STANDARD
|
||||||
|
.decode(b64)
|
||||||
|
.map_err(|e| format!("invalid base64: {e}"))?;
|
||||||
|
if bytes.len() != 32 {
|
||||||
|
return Err(format!("key must be exactly 32 bytes, got {}", bytes.len()));
|
||||||
|
}
|
||||||
|
let mut arr = [0u8; 32];
|
||||||
|
arr.copy_from_slice(&bytes);
|
||||||
|
Ok(arr)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Parse a comma-separated list of CIDR addresses into WireGuard allowed-IP NLAs.
|
||||||
|
fn parse_allowed_ips(csv: &str) -> Result<Vec<WireguardAllowedIp>> {
|
||||||
|
let mut result = Vec::new();
|
||||||
|
for cidr_str in csv.split(',') {
|
||||||
|
let trimmed = cidr_str.trim();
|
||||||
|
if trimmed.is_empty() {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
let net: IpNet = trimmed.parse().map_err(|e| {
|
||||||
|
WireGuardError::InvalidAllowedIp(format!("invalid CIDR '{trimmed}': {e}"))
|
||||||
|
})?;
|
||||||
|
let family = match net {
|
||||||
|
IpNet::V4(_) => WireguardAddressFamily::Ipv4,
|
||||||
|
IpNet::V6(_) => WireguardAddressFamily::Ipv6,
|
||||||
|
};
|
||||||
|
result.push(WireguardAllowedIp(vec![
|
||||||
|
WireguardAllowedIpAttr::Family(family),
|
||||||
|
WireguardAllowedIpAttr::IpAddr(net.addr()),
|
||||||
|
WireguardAllowedIpAttr::Cidr(net.prefix_len()),
|
||||||
|
]));
|
||||||
|
}
|
||||||
|
Ok(result)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Parse an endpoint string ("ip:port" or "[ipv6]:port") into a SocketAddr.
|
||||||
|
fn parse_endpoint(s: &str) -> Result<SocketAddr> {
|
||||||
|
if let Ok(addr) = s.parse::<SocketAddr>() {
|
||||||
|
return Ok(addr);
|
||||||
|
}
|
||||||
|
if let Some(idx) = s.rfind(':') {
|
||||||
|
let host = &s[..idx];
|
||||||
|
let port_str = &s[idx + 1..];
|
||||||
|
if let (Ok(ip), Ok(port)) = (host.parse::<IpAddr>(), port_str.parse::<u16>()) {
|
||||||
|
return Ok(SocketAddr::new(ip, port));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
Err(WireGuardError::InvalidEndpoint(format!(
|
||||||
|
"cannot parse endpoint '{s}'"
|
||||||
|
)))
|
||||||
|
}
|
||||||
|
|
||||||
|
// ── WireGuardEngine Trait Implementation ─────────────────────────────────────
|
||||||
|
|
||||||
|
#[async_trait::async_trait]
|
||||||
|
impl WireGuardEngine for NativeLinuxWireGuardEngine {
|
||||||
|
async fn sync_interface(&self, interface: &Interface, peers: &[Peer]) -> Result<()> {
|
||||||
|
// 1. Ensure the WireGuard link exists
|
||||||
|
ensure_link(&interface.name).await?;
|
||||||
|
|
||||||
|
// 2. Configure the WireGuard device (private key, listen port, peers)
|
||||||
|
configure_device(interface, peers).await?;
|
||||||
|
|
||||||
|
tracing::info!(
|
||||||
|
interface = %interface.name,
|
||||||
|
active_peers = peers.iter().filter(|p| p.state == PeerState::Active).count(),
|
||||||
|
"WireGuard interface synchronized via native netlink"
|
||||||
|
);
|
||||||
|
Ok(())
|
||||||
|
}
|
||||||
|
|
||||||
|
async fn delete_interface(&self, name: &str) -> Result<()> {
|
||||||
|
delete_link(name).await
|
||||||
|
}
|
||||||
|
|
||||||
|
async fn get_interface_stats(&self, name: &str) -> Result<Option<LiveInterfaceStats>> {
|
||||||
|
query_device(name).await
|
||||||
|
}
|
||||||
|
|
||||||
|
async fn list_interfaces(&self) -> Result<Vec<String>> {
|
||||||
|
list_wireguard_links().await
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,157 @@
|
|||||||
|
//! Unit tests for native Linux WireGuard conversion utilities and error invariants.
|
||||||
|
//!
|
||||||
|
//! These tests verify CIDR parsing, endpoint parsing, key decoding, and peer
|
||||||
|
//! filtering without requiring CAP_NET_ADMIN or kernel mutation.
|
||||||
|
|
||||||
|
use base64::Engine as _;
|
||||||
|
use nx9_wg_core::types::wireguard::PeerState;
|
||||||
|
use nx9_wireguard::WireGuardError;
|
||||||
|
use std::net::{IpAddr, Ipv4Addr, SocketAddr};
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_ipv4_cidr_parsing() {
|
||||||
|
let net: ipnet::IpNet = "10.0.0.2/32".parse().unwrap();
|
||||||
|
assert_eq!(net.addr(), IpAddr::V4(Ipv4Addr::new(10, 0, 0, 2)));
|
||||||
|
assert_eq!(net.prefix_len(), 32);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_ipv6_cidr_parsing() {
|
||||||
|
let net: ipnet::IpNet = "fd00::2/128".parse().unwrap();
|
||||||
|
assert!(net.addr().is_ipv6());
|
||||||
|
assert_eq!(net.prefix_len(), 128);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_multiple_allowed_ips_parsing() {
|
||||||
|
let csv = "10.0.0.2/32, fd00::2/128";
|
||||||
|
let nets: Vec<ipnet::IpNet> = csv
|
||||||
|
.split(',')
|
||||||
|
.map(|s| s.trim())
|
||||||
|
.filter(|s| !s.is_empty())
|
||||||
|
.map(|s| s.parse::<ipnet::IpNet>().unwrap())
|
||||||
|
.collect();
|
||||||
|
assert_eq!(nets.len(), 2);
|
||||||
|
assert!(nets[0].addr().is_ipv4());
|
||||||
|
assert!(nets[1].addr().is_ipv6());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_empty_allowed_ips() {
|
||||||
|
let csv = "";
|
||||||
|
let nets: Vec<ipnet::IpNet> = csv
|
||||||
|
.split(',')
|
||||||
|
.map(|s| s.trim())
|
||||||
|
.filter(|s| !s.is_empty())
|
||||||
|
.filter_map(|s| s.parse::<ipnet::IpNet>().ok())
|
||||||
|
.collect();
|
||||||
|
assert!(nets.is_empty());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_invalid_cidr_rejected() {
|
||||||
|
let result = "invalid/cidr".parse::<ipnet::IpNet>();
|
||||||
|
assert!(result.is_err());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_ipv4_endpoint_parsing() {
|
||||||
|
let addr: SocketAddr = "198.51.100.2:45000".parse().unwrap();
|
||||||
|
assert_eq!(addr.ip(), IpAddr::V4(Ipv4Addr::new(198, 51, 100, 2)));
|
||||||
|
assert_eq!(addr.port(), 45000);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_ipv6_endpoint_parsing() {
|
||||||
|
let addr: SocketAddr = "[2001:db8::1]:51820".parse().unwrap();
|
||||||
|
assert!(addr.ip().is_ipv6());
|
||||||
|
assert_eq!(addr.port(), 51820);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_invalid_endpoint_rejected() {
|
||||||
|
let result = "not-an-endpoint".parse::<SocketAddr>();
|
||||||
|
assert!(result.is_err());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_base64_key_decode_valid() {
|
||||||
|
let key_bytes = [0xAAu8; 32];
|
||||||
|
let b64 = base64::engine::general_purpose::STANDARD.encode(key_bytes);
|
||||||
|
let decoded = base64::engine::general_purpose::STANDARD
|
||||||
|
.decode(&b64)
|
||||||
|
.unwrap();
|
||||||
|
assert_eq!(decoded.len(), 32);
|
||||||
|
let mut arr = [0u8; 32];
|
||||||
|
arr.copy_from_slice(&decoded);
|
||||||
|
assert_eq!(arr, key_bytes);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_base64_key_decode_wrong_length() {
|
||||||
|
let short_key = [0xBBu8; 16];
|
||||||
|
let b64 = base64::engine::general_purpose::STANDARD.encode(short_key);
|
||||||
|
let decoded = base64::engine::general_purpose::STANDARD
|
||||||
|
.decode(&b64)
|
||||||
|
.unwrap();
|
||||||
|
assert_ne!(decoded.len(), 32);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_base64_key_decode_invalid_base64() {
|
||||||
|
let result = base64::engine::general_purpose::STANDARD.decode("not!valid!base64!!!");
|
||||||
|
assert!(result.is_err());
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_peer_state_filtering() {
|
||||||
|
let states = [
|
||||||
|
PeerState::Active,
|
||||||
|
PeerState::Disabled,
|
||||||
|
PeerState::Revoked,
|
||||||
|
PeerState::Expired,
|
||||||
|
];
|
||||||
|
|
||||||
|
let active_count = states.iter().filter(|s| **s == PeerState::Active).count();
|
||||||
|
assert_eq!(active_count, 1, "only Active peers should be synchronized");
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_error_display_no_key_leakage() {
|
||||||
|
let err = WireGuardError::Key("invalid base64".to_string());
|
||||||
|
let display = format!("{err}");
|
||||||
|
assert!(!display.contains("secret"));
|
||||||
|
assert!(!display.contains("private"));
|
||||||
|
assert!(display.contains("invalid base64"));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_error_variants_exist() {
|
||||||
|
let _ = format!("{}", WireGuardError::InterfaceNotFound("wg0".into()));
|
||||||
|
let _ = format!("{}", WireGuardError::WrongInterfaceType("eth0".into()));
|
||||||
|
let _ = format!("{}", WireGuardError::Unsupported("no kernel module".into()));
|
||||||
|
let _ = format!("{}", WireGuardError::InvalidEndpoint("bad:ep".into()));
|
||||||
|
let _ = format!("{}", WireGuardError::InvalidAllowedIp("bad/cidr".into()));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn test_prefix_length_preservation() {
|
||||||
|
let cases = [
|
||||||
|
("10.0.0.0/8", 8),
|
||||||
|
("10.0.0.0/16", 16),
|
||||||
|
("10.0.0.0/24", 24),
|
||||||
|
("10.0.0.1/32", 32),
|
||||||
|
("fd00::/64", 64),
|
||||||
|
("fd00::1/128", 128),
|
||||||
|
("0.0.0.0/0", 0),
|
||||||
|
("::/0", 0),
|
||||||
|
];
|
||||||
|
for (cidr, expected_prefix) in cases {
|
||||||
|
let net: ipnet::IpNet = cidr.parse().unwrap();
|
||||||
|
assert_eq!(
|
||||||
|
net.prefix_len(),
|
||||||
|
expected_prefix,
|
||||||
|
"prefix mismatch for {cidr}"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,42 @@
|
|||||||
|
# NX9 WireGuard Documentation Index
|
||||||
|
|
||||||
|
Welcome to the official documentation for the **NX9 WireGuard (`nx9-wg`)** appliance and management platform.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Getting Started & Philosophy
|
||||||
|
- [**NX9 Design Principles**](design-principles.md) — Architectural philosophy, self-hosted sovereignty, zero scripting runtime, and SQLite authority.
|
||||||
|
- [**Installation & Deployment Guide**](installation.md) — Production installation, systemd service, admin bootstrap, first interface, and peer setup.
|
||||||
|
- [**Linux Platform & Kernel Requirements**](linux_requirements.md) — Kernel 5.6+, in-tree WireGuard module, Netlink sockets, `libnftables.so.1`, and capabilities.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Architecture & Native Linux Execution
|
||||||
|
- [**System Architecture & Workspace Structure**](architecture.md) — Six-crate workspace breakdown, layer boundaries, and end-to-end data flows.
|
||||||
|
- [**Native WireGuard Netlink Engine**](native-wireguard.md) — Direct RTNETLINK and Generic Netlink (`wireguard`) protocol implementation.
|
||||||
|
- [**Native Network & Routing Engine**](native-network.md) — RTNETLINK link/address/route lifecycle and direct procfs IP packet forwarding.
|
||||||
|
- [**Native nftables Engine**](nftables.md) — In-process `libnftables.so.1` FFI transactions and dedicated `table inet nx9_wg` scoping.
|
||||||
|
- [**Firewall & NAT Domain Model**](firewall_nat.md) — Typed rules, protocol groups, port ranges, priorities, and outbound NAT masquerading.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Control Plane, UI & Telemetry
|
||||||
|
- [**Reconciliation Engine & Convergence**](reconciliation.md) — Closed-loop drift detection, read-only planning, serialized apply, and convergence lifecycle states.
|
||||||
|
- [**Web User Interface (SPA)**](ui.md) — Zero-dependency embedded HTML5/CSS/JS frontend, theme engine, and all 15 application routes.
|
||||||
|
- [**Axum REST API & WebSocket Protocol**](api.md) — Complete endpoint reference, JSON schemas, error handling, and real-time event broadcaster.
|
||||||
|
- [**Native CLI Command Reference**](cli.md) — Full reference for all 17 CLI subcommands, multi-format output (`table`/`json`/`yaml`/`csv`), and secret files.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Security & Disaster Recovery
|
||||||
|
- [**Security Model & Privilege Architecture**](security.md) — Single admin model (`CHECK (id=1)`), Argon2id hashing, SHA-256 tokens, permissions matrix, and brute-force protection.
|
||||||
|
- [**Backup & Disaster Recovery Guide**](backup_restore.md) — Atomic online SQLite backups (`VACUUM INTO`), SHA-256 manifests, and pre-restore safety snapshots.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Operations, Development & Release
|
||||||
|
- [**Release Engineering & Packaging**](release.md) — Standalone distribution packages (`.tar.gz`/`.tar.xz`), systemd sandboxing, installer, and rollback strategy.
|
||||||
|
- [**Quality Assurance & Testing Strategy**](testing.md) — Multi-tiered test suites, SAFE mode (`LIVE=0`) vs real-kernel mode (`LIVE=1`), and automated security audits.
|
||||||
|
- [**Developer & Contributing Guide**](development.md) — Building, testing, linting, and workspace contribution standards.
|
||||||
|
- [**Configuration Reference**](configuration.md) — TOML configuration format and `NX9_WG_*` environment variable precedence.
|
||||||
|
- [**Docker & Container Deployment**](docker.md) — Containerized deployment with Linux capability isolation and volume persistence.
|
||||||
+130
-70
@@ -1,85 +1,145 @@
|
|||||||
# REST API and WebSocket Reference
|
# Axum REST API & WebSocket Protocol Reference
|
||||||
|
|
||||||
All REST endpoints are nested under the `/api/v1` prefix.
|
The `nx9-wg` API daemon serves JSON REST endpoints and a real-time WebSocket event bus under the base path `/api/v1`.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Authentication
|
## 1. Authentication & Session Model
|
||||||
|
|
||||||
The API supports two authentication mechanisms:
|
Authentication is supported via two mechanisms:
|
||||||
1. **Session Cookie**: `nx9_session=<SESSION_UUID>` (HttpOnly, SameSite=Strict).
|
|
||||||
2. **Bearer Token**: `Authorization: Bearer nx9_<TOKEN_BASE64>` (Hashed with SHA-256 on the server).
|
### A. HTTP Session Cookie (`nx9_session`)
|
||||||
|
Obtained via `POST /api/v1/auth/login`. Returned in the `Set-Cookie` response header and automatically attached by web browsers.
|
||||||
|
|
||||||
|
### B. Bearer API Token
|
||||||
|
Passed in the `Authorization` header:
|
||||||
|
```http
|
||||||
|
Authorization: Bearer nx9_<uuid>_<random>
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Endpoints
|
## 2. Standard Error Response Model
|
||||||
|
|
||||||
### 1. Public Endpoints
|
All non-2xx responses return a structured JSON error body:
|
||||||
- `POST /api/v1/auth/login`: Authenticates administrator with username and password. Sets session cookie.
|
|
||||||
- `GET /api/v1/system/health`: Service and database health check.
|
|
||||||
- `GET /api/v1/system/version`: Version and build metadata.
|
|
||||||
- `GET /api/v1/ws`: WebSocket real-time event stream.
|
|
||||||
|
|
||||||
### 2. Administrator & Session Management
|
```json
|
||||||
- `POST /api/v1/auth/logout`: Invalidates the current session.
|
{
|
||||||
- `GET /api/v1/auth/session`: Returns information about the active session.
|
"error": "Descriptive error message",
|
||||||
- `POST /api/v1/auth/password`: Changes password and terminates all other sessions.
|
"status": 404
|
||||||
- `GET /api/v1/auth/tokens`: Lists all provisioned API tokens.
|
}
|
||||||
- `POST /api/v1/auth/tokens`: Creates a new API token.
|
```
|
||||||
- `DELETE /api/v1/auth/tokens/{id}`: Revokes an API token.
|
|
||||||
|
|
||||||
### 3. WireGuard Interfaces
|
### Common HTTP Status Codes:
|
||||||
- `GET /api/v1/interfaces`: Lists all interfaces.
|
- `200 OK`: Request succeeded.
|
||||||
- `POST /api/v1/interfaces`: Creates an interface.
|
- `400 Bad Request`: Validation failure on input parameters.
|
||||||
- `GET /api/v1/interfaces/{id}`: Interface details.
|
- `401 Unauthorized`: Missing, invalid, or expired session/token.
|
||||||
- `PUT /api/v1/interfaces/{id}`: Updates interface settings.
|
- `404 Not Found`: Resource ID does not exist in SQLite.
|
||||||
- `DELETE /api/v1/interfaces/{id}`: Deletes interface.
|
- `409 Conflict`: Unique constraint violation (e.g. duplicate interface name or IP).
|
||||||
- `POST /api/v1/interfaces/{id}/enable`: Enables interface.
|
- `422 Unprocessable Entity`: Semantic constraint failure.
|
||||||
- `POST /api/v1/interfaces/{id}/disable`: Disables interface.
|
- `429 Too Many Requests`: Brute-force rate limiting triggered.
|
||||||
- `GET /api/v1/interfaces/{id}/status`: Live statistics, listen port, and connected peer metrics.
|
- `500 Internal Server Error`: Native Linux execution plane or storage failure.
|
||||||
|
|
||||||
### 4. WireGuard Peers
|
|
||||||
- `GET /api/v1/interfaces/{id}/peers`: Lists peers for a specific interface.
|
|
||||||
- `POST /api/v1/interfaces/{id}/peers`: Enrolls a new peer.
|
|
||||||
- `GET /api/v1/peers/{id}`: Peer details.
|
|
||||||
- `PUT /api/v1/peers/{id}`: Updates peer configuration.
|
|
||||||
- `DELETE /api/v1/peers/{id}`: Deletes peer.
|
|
||||||
- `POST /api/v1/peers/{id}/enable`: Activates peer.
|
|
||||||
- `POST /api/v1/peers/{id}/disable`: Disables peer.
|
|
||||||
- `POST /api/v1/peers/{id}/revoke`: Revokes peer.
|
|
||||||
- `GET /api/v1/peers/{id}/config`: Downloads standard client `.conf` file.
|
|
||||||
- `GET /api/v1/peers/{id}/qr`: Returns SVG, PNG base64, and Data URL QR code representations.
|
|
||||||
|
|
||||||
### 5. Networks & Routing
|
|
||||||
- `GET /api/v1/networks`, `POST /api/v1/networks`, `DELETE /api/v1/networks/{id}`
|
|
||||||
- `GET /api/v1/routes`, `POST /api/v1/routes`, `DELETE /api/v1/routes/{id}`
|
|
||||||
|
|
||||||
### 6. Firewall & nftables
|
|
||||||
- `GET /api/v1/firewall/rules`, `POST /api/v1/firewall/rules`, `DELETE /api/v1/firewall/rules/{id}`
|
|
||||||
- `POST /api/v1/firewall/rules/{id}/enable`, `POST /api/v1/firewall/rules/{id}/disable`
|
|
||||||
|
|
||||||
### 7. Audit Log
|
|
||||||
- `GET /api/v1/audit`: Paginated and filtered query of security and system events.
|
|
||||||
|
|
||||||
### 8. Backups
|
|
||||||
- `GET /api/v1/backups`: Lists existing backup records.
|
|
||||||
- `POST /api/v1/backups/create`: Creates a new snapshot and manifest.
|
|
||||||
- `GET /api/v1/backups/{id}/download`: Downloads backup archive.
|
|
||||||
- `POST /api/v1/backups/{id}/restore`: Safely restores database.
|
|
||||||
- `DELETE /api/v1/backups/{id}`: Deletes backup archive and metadata.
|
|
||||||
|
|
||||||
### 9. Reconciliation
|
|
||||||
- `GET /api/v1/reconcile/plan`: Returns detected drift without making changes.
|
|
||||||
- `POST /api/v1/reconcile/apply`: Applies reconciliation plan to live kernel.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## WebSocket Telemetry (`/api/v1/ws`)
|
## 3. REST API Endpoint Inventory
|
||||||
|
|
||||||
Upon connection, clients receive a stream of JSON `SystemEvent` frames:
|
### Authentication & Tokens
|
||||||
- `InterfaceChanged { id, action }`
|
- `POST /api/v1/auth/login`: Authenticate with `{ "username": "admin", "password": "..." }`. Returns session cookie and user metadata.
|
||||||
- `PeerChanged { id, action }`
|
- `POST /api/v1/auth/logout`: Invalidate current active session.
|
||||||
- `NetworkChanged { id, action }`
|
- `GET /api/v1/auth/session`: Query authenticated session info.
|
||||||
- `RouteChanged { id, action }`
|
- `POST /api/v1/auth/password`: Update administrator password `{ "current_password": "...", "new_password": "..." }`. Invalidates all active sessions.
|
||||||
- `FirewallChanged { id, action }`
|
- `GET /api/v1/auth/tokens`: List all API token metadata.
|
||||||
- `AuditEvent { event_type, message, resource_type, resource_id }`
|
- `POST /api/v1/auth/tokens`: Generate API token `{ "name": "ci-token", "expires_in_days": 30 }`. Returns `{ "raw_token": "...", "meta": {...} }`.
|
||||||
|
- `DELETE /api/v1/auth/tokens/{id}`: Revoke an API token.
|
||||||
|
|
||||||
|
### System & Health
|
||||||
|
- `GET /api/v1/system/health`: Public system health check `{ "status": "healthy", "database": "connected" }`.
|
||||||
|
- `GET /api/v1/system/version`: Public version and build information.
|
||||||
|
- `GET /api/v1/system`: System operational overview and interface/peer counts.
|
||||||
|
- `GET /api/v1/system/settings`: List all key-value settings.
|
||||||
|
- `PUT /api/v1/system/settings`: Upsert setting `{ "key": "...", "value": "...", "description": "..." }`.
|
||||||
|
|
||||||
|
### WireGuard Interfaces
|
||||||
|
- `GET /api/v1/interfaces`: List all WireGuard interfaces.
|
||||||
|
- `POST /api/v1/interfaces`: Create interface `{ "name": "wg0", "address_v4": "10.100.0.1/24", "listen_port": 51820, "mtu": 1420 }`.
|
||||||
|
- `GET /api/v1/interfaces/{id}`: Get interface details.
|
||||||
|
- `PUT /api/v1/interfaces/{id}`: Update interface configuration.
|
||||||
|
- `DELETE /api/v1/interfaces/{id}`: Delete interface (cascades to peers).
|
||||||
|
- `POST /api/v1/interfaces/{id}/enable`: Set interface `IFF_UP`.
|
||||||
|
- `POST /api/v1/interfaces/{id}/disable`: Set interface `IFF_DOWN`.
|
||||||
|
- `GET /api/v1/interfaces/{id}/status`: Query live kernel netlink telemetry.
|
||||||
|
|
||||||
|
### Peers & Client Configs
|
||||||
|
- `GET /api/v1/peers`: List all peers across all interfaces.
|
||||||
|
- `GET /api/v1/interfaces/{id}/peers`: List peers for specific interface.
|
||||||
|
- `POST /api/v1/interfaces/{id}/peers`: Enroll peer `{ "name": "alice", "profile": "full_tunnel", "mtu": 1280, ... }`.
|
||||||
|
- `GET /api/v1/peers/{id}`: Get peer details.
|
||||||
|
- `PUT /api/v1/peers/{id}`: Update peer parameters.
|
||||||
|
- `DELETE /api/v1/peers/{id}`: Delete peer.
|
||||||
|
- `POST /api/v1/peers/{id}/enable`: Enable peer.
|
||||||
|
- `POST /api/v1/peers/{id}/disable`: Disable peer.
|
||||||
|
- `GET /api/v1/peers/{id}/config`: Download WireGuard `.conf` file (supports `?device=...&connection=...`).
|
||||||
|
- `GET /api/v1/peers/{id}/qr`: Generate QR code SVG/PNG (supports `?qr_format=svg`).
|
||||||
|
|
||||||
|
### Networks & Subnets
|
||||||
|
- `GET /api/v1/networks`: List subnet networks.
|
||||||
|
- `POST /api/v1/networks`: Create subnet `{ "name": "clients", "cidr": "10.100.1.0/24" }`.
|
||||||
|
- `GET /api/v1/networks/{id}`: Get network details.
|
||||||
|
- `DELETE /api/v1/networks/{id}`: Delete network.
|
||||||
|
- `GET /api/v1/networks/{id}/available`: List unallocated IP addresses.
|
||||||
|
|
||||||
|
### Routing
|
||||||
|
- `GET /api/v1/routes`: List routing table entries.
|
||||||
|
- `POST /api/v1/routes`: Add route `{ "destination": "192.168.50.0/24", "gateway": "10.100.0.2", "metric": 100 }`.
|
||||||
|
- `DELETE /api/v1/routes/{id}`: Delete route.
|
||||||
|
|
||||||
|
### Firewall & NAT
|
||||||
|
- `GET /api/v1/firewall/rules`: List nftables rules.
|
||||||
|
- `POST /api/v1/firewall/rules`: Create rule `{ "name": "allow-ssh", "protocol": "tcp", "port": "22", "action": "accept" }`.
|
||||||
|
- `DELETE /api/v1/firewall/rules/{id}`: Delete rule.
|
||||||
|
- `POST /api/v1/firewall/rules/{id}/enable`: Enable rule.
|
||||||
|
- `POST /api/v1/firewall/rules/{id}/disable`: Disable rule.
|
||||||
|
|
||||||
|
### Reconciliation
|
||||||
|
- `GET /api/v1/reconcile/plan`: Query read-only drift plan between SQLite and Linux kernel.
|
||||||
|
- `POST /api/v1/reconcile/apply`: Execute native mutations and verify convergence.
|
||||||
|
|
||||||
|
### Diagnostics
|
||||||
|
- `GET /api/v1/diagnostics/all`: Run automated checks across all 9 subsystems.
|
||||||
|
- `GET /api/v1/diagnostics/{subsystem}`: Run checks for a single subsystem.
|
||||||
|
|
||||||
|
### Backups
|
||||||
|
- `GET /api/v1/backups`: List backup snapshots.
|
||||||
|
- `POST /api/v1/backups/create`: Trigger atomic online backup snapshot (`VACUUM INTO`).
|
||||||
|
- `GET /api/v1/backups/{id}/download`: Download raw SQLite database backup file.
|
||||||
|
- `POST /api/v1/backups/{id}/restore`: Restore database from snapshot.
|
||||||
|
- `DELETE /api/v1/backups/{id}`: Delete backup record and snapshot file.
|
||||||
|
|
||||||
|
### Audit Trail
|
||||||
|
- `GET /api/v1/audit`: List append-only security and operational audit records.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Real-Time WebSocket Protocol (`/api/v1/ws`)
|
||||||
|
|
||||||
|
Connect to `ws://<host>/api/v1/ws` (or `wss://`) to receive real-time JSON events:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "AuditEvent",
|
||||||
|
"payload": {
|
||||||
|
"event_type": "peer_created",
|
||||||
|
"message": "Peer 'alice-phone' enrolled on interface wg0",
|
||||||
|
"resource_type": "peer",
|
||||||
|
"resource_id": "974755a9-74d9-4488-85c9-f057230ab8e2"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Event Types:
|
||||||
|
- `AuditEvent`: Security and state mutation events.
|
||||||
|
- `InterfaceChanged`: Interface status toggle or link state change.
|
||||||
|
- `PeerChanged`: Peer parameter update or state transition.
|
||||||
|
- `PeerHandshake`: Real-time cryptographic handshake update.
|
||||||
|
- `SettingsChanged`: Key-value configuration change.
|
||||||
+100
-19
@@ -1,25 +1,106 @@
|
|||||||
# NX9 WireGuard Architecture Blueprint
|
# NX9 WireGuard — System Architecture & Workspace Structure
|
||||||
|
|
||||||
## System Overview
|
`nx9-wg` is structured as a modular six-crate Rust workspace designed for separation of concerns, strict failure domains, and testability.
|
||||||
|
|
||||||
`nx9-wg` is structured as a modular Rust workspace consisting of six specialized crates and a root binary.
|
```
|
||||||
|
nx9-wg (Workspace Root & Binary Executable)
|
||||||
| Crate | Responsibility | Dependencies |
|
├── crates/nx9-wg-core (Domain models, validation, cryptography, config)
|
||||||
| :--- | :--- | :--- |
|
├── crates/nx9-wg-db (SQLite store, migrations, repositories, WAL)
|
||||||
| **`nx9-wg-core`** | Domain entities, cryptographic utilities (Argon2id, x25519, SHA-256), data validation, and configuration types. | `serde`, `argon2`, `x25519-dalek`, `sha2`, `ipnet`, `chrono`, `uuid` |
|
├── crates/nx9-wireguard (WireGuard Netlink execution, config builder, QR engine)
|
||||||
| **`nx9-wg-db`** | Authoritative persistence layer using SQLite with WAL mode, automated migrations, and isolated repository modules. | `nx9-wg-core`, `sqlx` (sqlite) |
|
├── crates/nx9-wg-network (RTNETLINK networking, route management, nftables, procfs)
|
||||||
| **`nx9-wireguard`**| WireGuard interface controller, client `.conf` configuration builder, live telemetry inspection, and pure Rust QR engine. | `nx9-wg-core`, `qrcode`, `image`, `base64` |
|
├── crates/nx9-wg-api (Axum REST API, WebSockets, auth, reconciliation, allocator)
|
||||||
| **`nx9-wg-network`** | Linux kernel IP forwarding, routing table synchronization, and atomic `inet nx9_wg` nftables ruleset generator. | `nx9-wg-core`, `ipnet` |
|
└── crates/nx9-wg-ui (Design tokens, CSS engine, view models, SPA integration)
|
||||||
| **`nx9-wg-api`** | Axum REST API, session and token authentication middleware, WebSocket live event broadcast, and Reconciliation Engine. | `nx9-wg-core`, `nx9-wg-db`, `nx9-wireguard`, `nx9-wg-network`, `axum`, `tower` |
|
```
|
||||||
| **`nx9-wg-ui`** | Dioxus web client shell (client only, business logic isolated in backend). | `nx9-wg-core` |
|
|
||||||
| **`nx9-wg`** | Primary application binary providing CLI operations and HTTP daemon server. | All workspace crates, `clap` |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Architectural Invariants
|
## 1. Crate Inventory & Layer Responsibilities
|
||||||
|
|
||||||
1. **Strict SQL Isolation**: All raw SQL queries and SQLite interactions are confined entirely to `crates/nx9-wg-db/`. No other crate or handler interacts with SQLite directly.
|
### `nx9-wg-core`
|
||||||
2. **Zero Shelling Out**: WireGuard, routing, and packet filtering interact with kernel abstractions and netlink without executing `wg`, `wg-quick`, or `iptables` subprocesses.
|
- **Domain Entities**: Typed domain structures (`Interface`, `Peer`, `Network`, `Route`, `FirewallRule`, `Setting`, `Admin`, `Session`, `ApiToken`, `BackupMeta`, `AuditEvent`).
|
||||||
3. **Single Administrator Model**: The system maintains exactly one administrative identity with `CHECK (id = 1)`. No RBAC, multi-tenant, or organization complexity is introduced.
|
- **Validation**: Strict RFC-compliant validators for CIDRs, IP addresses, MTU ranges, listen ports, interface names, peer names, and password strength.
|
||||||
4. **Secret Redaction**: Passwords, private keys, preshared keys, and API tokens are never logged, persisted in plaintext, or exposed in error messages. All secret wrapper types implement custom `Debug` redactions (`[REDACTED]`).
|
- **Cryptography**: Argon2id password hashing, SHA-256 token digest generation, X25519 keypair generation, and secure random string generation.
|
||||||
5. **Deterministic Reconciliation**: Desired state in SQLite is the single source of truth. The reconciler computes drift and idempotently applies adjustments without touching unmanaged Linux resources.
|
- **Configuration**: Hierarchical TOML and `NX9_WG_*` environment variable configuration loader.
|
||||||
|
|
||||||
|
### `nx9-wg-db`
|
||||||
|
- **Authoritative Persistence**: Migration-driven SQLite storage using `sqlx` in Write-Ahead Logging (WAL) mode.
|
||||||
|
- **Single Admin Invariant**: SQL constraint `CHECK (id = 1)` enforcing single-administrator identity.
|
||||||
|
- **Repositories**: Isolated data access layers for admin, auth, audit, backups, client profiles, interfaces, login attempts, networks, peers, routes, sessions, settings, and tokens.
|
||||||
|
- **Transactional Consistency**: Foreign key cascades (`ON DELETE CASCADE`) between interfaces and peers.
|
||||||
|
|
||||||
|
### `nx9-wireguard`
|
||||||
|
- **Native Netlink Engine**: `NativeLinuxWireGuardEngine` interacting with Linux RTNETLINK for link lifecycle and Generic Netlink family `wireguard` (`SET_DEVICE`, `GET_DEVICE`, `ReplacePeers`).
|
||||||
|
- **Client Config Generation**: Pure Rust `.conf` generation supporting full-tunnel and split-tunnel topologies.
|
||||||
|
- **QR Code Engine**: High-resolution SVG, PNG byte streams, and UTF-8 ASCII terminal QR code rendering.
|
||||||
|
- **Simulation Engine**: `SimulatedWireGuardEngine` for non-Linux platform development and testing.
|
||||||
|
|
||||||
|
### `nx9-wg-network`
|
||||||
|
- **Native Network Engine**: `NativeLinuxNetworkEngine` managing RTNETLINK interfaces, IPv4/IPv6 addresses, and route tables.
|
||||||
|
- **nftables Netfilter Engine**: `NativeLinuxNftablesEngine` utilizing `libnftables.so.1` for transactional rule generation in `table inet nx9_wg`.
|
||||||
|
- **Kernel IP Forwarding**: Direct `/proc/sys/net/ipv4/ip_forward` and `/proc/sys/net/ipv6/conf/all/forwarding` mutation.
|
||||||
|
- **Simulation Engine**: `SimulatedNetworkEngine` for local platform testing.
|
||||||
|
|
||||||
|
### `nx9-wg-api`
|
||||||
|
- **REST Router**: Axum HTTP handlers for auth, interfaces, peers, networks, routes, firewall, NAT, forwarding, settings, backups, diagnostics, and audit logs.
|
||||||
|
- **WebSocket Event Bus**: Tokio broadcast channel broadcasting real-time system events (`AuditEvent`, `InterfaceChanged`, `PeerChanged`, `PeerHandshake`, `SettingsChanged`).
|
||||||
|
- **Reconciliation Engine**: Mutex-serialized continuous drift detection and convergence controller.
|
||||||
|
- **Deterministic IP Allocator**: Collision-resistant next-IP allocation engine for managed subnets.
|
||||||
|
- **Backup & Restore Service**: Online SQLite atomic snapshot (`VACUUM INTO`) and verification engine.
|
||||||
|
|
||||||
|
### `nx9-wg-ui`
|
||||||
|
- **Design Tokens**: Structured CSS variable tokens for Dark and Light themes.
|
||||||
|
- **Stylesheet Generator**: In-process CSS compiler producing responsive layouts (`@media (max-width: 768px)`).
|
||||||
|
- **View Models**: Strongly-typed Rust UI state representations for dashboards, diagnostics, client export modals, and peer management tables.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. End-to-End Control and Execution Plane
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
subgraph ControlPlane["Control Plane (User & Administration)"]
|
||||||
|
User["Administrator (Browser / CLI)"]
|
||||||
|
SPA["Embedded SPA Web UI"]
|
||||||
|
CLI["Native CLI (nx9-wg)"]
|
||||||
|
API["Axum REST API / WebSockets"]
|
||||||
|
DB[("Authoritative SQLite Database")]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph ReconciliationLayer["Reconciliation & Engine Layer"]
|
||||||
|
Reconciler["Reconciliation Engine (Serialized Mutex)"]
|
||||||
|
WGEngine["WireGuard Engine (Genl / RTNETLINK)"]
|
||||||
|
NetEngine["Network Engine (RTNETLINK & procfs)"]
|
||||||
|
NftEngine["Nftables Engine (libnftables Netfilter)"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph LinuxKernel["Linux Kernel Execution Plane"]
|
||||||
|
WGSocket["WireGuard Kernel Module (wireguard.ko)"]
|
||||||
|
RTNL["Kernel RTNETLINK (Links, Addrs, Routes)"]
|
||||||
|
Procfs["/proc/sys/net (IP Forwarding)"]
|
||||||
|
Netfilter["Netfilter Subsystem (table inet nx9_wg)"]
|
||||||
|
end
|
||||||
|
|
||||||
|
User -->|HTTPS / WSS| SPA
|
||||||
|
User -->|CLI Invocations| CLI
|
||||||
|
SPA -->|REST API Calls| API
|
||||||
|
CLI -->|In-Process Service Calls| API
|
||||||
|
API -->|Authoritative Mutations| DB
|
||||||
|
DB -->|Desired State Snapshot| Reconciler
|
||||||
|
Reconciler -->|Read Live Telemetry| WGEngine
|
||||||
|
Reconciler -->|Read Live Routes/Forwarding| NetEngine
|
||||||
|
Reconciler -->|Read Live Ruleset| NftEngine
|
||||||
|
WGEngine -->|Generic Netlink Messages| WGSocket
|
||||||
|
NetEngine -->|RTM_NEWLINK / NEWROUTE| RTNL
|
||||||
|
NetEngine -->|Write 1/0| Procfs
|
||||||
|
NftEngine -->|Atomic Netfilter Transactions| Netfilter
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Subsystem Invariants & Security Boundaries
|
||||||
|
|
||||||
|
1. **Subprocess Isolation**: Zero invocations of `std::process::Command` or shell scripts across the entire production codebase.
|
||||||
|
2. **Persistence Authority**: SQLite remains the single authoritative source of truth. Kernel state is continuously reconciled to match database state.
|
||||||
|
3. **Firewall Isolation**: All nftables operations are confined to `table inet nx9_wg`. Unmanaged host tables are untouched.
|
||||||
|
4. **Route Safety**: Default gateway routes and host networking routes are protected against accidental deletion or flushing.
|
||||||
|
5. **Secret Redaction**: Private keys, preshared keys, password hashes, and token hashes are masked in `Debug` formatters, CLI outputs, and API responses.
|
||||||
+70
-91
@@ -1,49 +1,48 @@
|
|||||||
# Native CLI Command Reference (`nx9-wg`)
|
# Native CLI Command Reference (`nx9-wg`)
|
||||||
|
|
||||||
The `nx9-wg` binary provides 100% native CLI coverage for the entire NX9 WireGuard application stack.
|
The `nx9-wg` binary provides 100% native CLI coverage across all 17 application subcommands without spawning external subprocesses.
|
||||||
The CLI directly executes native Rust application services (`Store`, `WireGuardEngine`, `NetworkEngine`, `ReconciliationEngine`, `BackupService`, `AuthService`) without calling external subprocesses.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Global Options
|
## 1. Global Options
|
||||||
|
|
||||||
- `-c, --config <PATH>`: Path to configuration file (env: `NX9_WG_CONFIG`, default: `/etc/nx9-wg/config.toml`)
|
| Option | Environment Variable | Description |
|
||||||
- `-d, --data-dir <PATH>`: Path to data directory (env: `NX9_WG_DATA_DIR`, default: `/var/lib/nx9-wg`)
|
| :--- | :--- | :--- |
|
||||||
- `--database <PATH>`: Explicit SQLite database path or URL (env: `NX9_WG_DATABASE`)
|
| `-c, --config <PATH>` | `NX9_WG_CONFIG` | Path to configuration file (default: `/etc/nx9-wg/config.toml`) |
|
||||||
- `--format <table|json|yaml|csv>`: Output formatting style (default: `table`)
|
| `-d, --data-dir <PATH>` | `NX9_WG_DATA_DIR` | Path to data directory (default: `/var/lib/nx9-wg`) |
|
||||||
- `--json`: Output strictly in formatted JSON
|
| `--database <PATH>` | `NX9_WG_DATABASE` | Specific SQLite database file path or URL |
|
||||||
- `-q, --quiet`: Suppress status and conversational messages
|
| `--format <FORMAT>` | N/A | Output format (`table`, `json`, `yaml`, `csv`, default: `table`) |
|
||||||
- `-v, --verbose`: Enable debug trace output
|
| `--json` | N/A | Convenience flag for strict JSON output |
|
||||||
- `--log-level <LEVEL>`: Log verbosity level (`trace`, `debug`, `info`, `warn`, `error`, env: `NX9_WG_LOG_LEVEL`)
|
| `-q, --quiet` | N/A | Suppress status and conversational messages |
|
||||||
|
| `-v, --verbose` | N/A | Enable verbose trace logging |
|
||||||
|
| `--log-level <LEVEL>` | `NX9_WG_LOG_LEVEL` | Log verbosity level (`trace`, `debug`, `info`, `warn`, `error`) |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Command Groups
|
## 2. Command Groups Reference
|
||||||
|
|
||||||
### 1. `version`
|
### 1. `version`
|
||||||
Displays version, build metadata, target architecture, and feature capabilities.
|
Displays version, build edition, architecture, OS platform, and security flags.
|
||||||
```bash
|
```bash
|
||||||
nx9-wg version
|
nx9-wg version
|
||||||
nx9-wg version --format json
|
nx9-wg version --format json
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. `serve`
|
### 2. `serve`
|
||||||
Starts the Axum REST API, WebSocket event streamer, and background reconciliation daemon.
|
Starts the Axum REST API daemon, WebSocket streamer, and background reconciliation scheduler.
|
||||||
```bash
|
```bash
|
||||||
nx9-wg serve
|
nx9-wg serve
|
||||||
|
|
||||||
# To intentionally expose the management API on all interfaces:
|
|
||||||
nx9-wg serve --bind 0.0.0.0:8080
|
nx9-wg serve --bind 0.0.0.0:8080
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3. `init`
|
### 3. `init`
|
||||||
Initializes the single administrator account across 7 supported bootstrap sources.
|
Initializes the single administrator account across 7 bootstrap sources.
|
||||||
```bash
|
```bash
|
||||||
# Generated password:
|
# Generated secure password:
|
||||||
nx9-wg init --generate-password --write-password-file /root/admin-pw.txt
|
nx9-wg init --generate-password --write-password-file /var/lib/nx9-wg/admin-password
|
||||||
|
|
||||||
# Password from standard input:
|
# Password via stdin:
|
||||||
echo "SecureSecret123!" | nx9-wg init --password-stdin
|
echo "StrongPassword123!" | nx9-wg init --password-stdin
|
||||||
|
|
||||||
# Password from file:
|
# Password from file:
|
||||||
nx9-wg init --password-file /run/secrets/admin_pw
|
nx9-wg init --password-file /run/secrets/admin_pw
|
||||||
@@ -51,103 +50,83 @@ nx9-wg init --password-file /run/secrets/admin_pw
|
|||||||
|
|
||||||
### 4. `system`
|
### 4. `system`
|
||||||
- `nx9-wg system status`: System database statistics and object counts.
|
- `nx9-wg system status`: System database statistics and object counts.
|
||||||
- `nx9-wg system health`: System and database connectivity health check.
|
- `nx9-wg system health`: System and SQLite connectivity health check.
|
||||||
- `nx9-wg system info`: System platform, architecture, and runtime paths.
|
- `nx9-wg system info`: System platform, architecture, and runtime paths.
|
||||||
- `nx9-wg system settings list`: List all configuration key-value settings.
|
- `nx9-wg system settings list`: List all key-value settings.
|
||||||
- `nx9-wg system settings get <KEY>`: Query setting value.
|
- `nx9-wg system settings get <KEY>`: Query setting value.
|
||||||
- `nx9-wg system settings set <KEY> <VALUE> [--secret]`: Save setting.
|
- `nx9-wg system settings set <KEY> <VALUE> [--secret]`: Save setting.
|
||||||
- `nx9-wg system settings delete <KEY>`: Delete setting.
|
- `nx9-wg system settings delete <KEY>`: Delete setting.
|
||||||
|
|
||||||
### 5. `admin`
|
### 5. `admin`
|
||||||
- `nx9-wg admin status`: View administrator profile and last login metrics.
|
- `nx9-wg admin info`: Query administrator account metadata.
|
||||||
- `nx9-wg admin create`: Provision administrator if not already initialized.
|
- `nx9-wg admin password`: Change administrator password.
|
||||||
- `nx9-wg admin password --new-password <PW> | --stdin | --password-file <PATH> | --generate`: Update password and invalidate all sessions.
|
- `nx9-wg admin token create <NAME> [--expires-in-days N] [--write-token-file PATH]`: Generate API token.
|
||||||
- `nx9-wg admin sessions list`: List active sessions.
|
- `nx9-wg admin token list`: List active API tokens.
|
||||||
- `nx9-wg admin sessions revoke <SESSION_ID>`: Invalidate specific session.
|
- `nx9-wg admin token revoke <TOKEN_ID>`: Revoke an API token.
|
||||||
- `nx9-wg admin sessions revoke-all`: Invalidate all active administrator sessions.
|
- `nx9-wg admin session list`: List active browser sessions.
|
||||||
- `nx9-wg admin tokens create --name <NAME> [--days <DAYS>] [--write-token-file <PATH>]`: Generate a long-lived API token. The recommended secure workflow writes the one-time plaintext token to a file with restrictive permissions; token hashes are redacted from normal CLI output.
|
- `nx9-wg admin session revoke-all`: Invalidate all active sessions.
|
||||||
- `nx9-wg admin tokens list`: List all API token metadata.
|
|
||||||
- `nx9-wg admin tokens revoke <TOKEN_ID>`: Revoke an API token.
|
|
||||||
|
|
||||||
### 6. `interface`
|
### 6. `interface`
|
||||||
- `nx9-wg interface list`: List all WireGuard interfaces.
|
- `nx9-wg interface list`: List all WireGuard interfaces.
|
||||||
- `nx9-wg interface show <NAME_OR_ID>`: Inspect interface details.
|
- `nx9-wg interface create <NAME> --address-v4 <CIDR> [--port PORT] [--mtu MTU]`: Create interface.
|
||||||
- `nx9-wg interface create <NAME> --address-v4 <CIDR> [--port <PORT>] [--address-v6 <CIDR>] [--mtu <MTU>] [--dns <DNS>]`: Create an interface.
|
- `nx9-wg interface show <NAME_OR_ID>`: Show interface configuration.
|
||||||
- `nx9-wg interface update <NAME_OR_ID> [--port <PORT>] [--address-v4 <CIDR>] [--enabled <BOOL>]`: Update interface properties.
|
- `nx9-wg interface enable <NAME_OR_ID>`: Enable interface (`IFF_UP`).
|
||||||
- `nx9-wg interface enable <NAME_OR_ID>` / `disable <NAME_OR_ID>`: Toggle administrative state.
|
- `nx9-wg interface disable <NAME_OR_ID>`: Disable interface (`IFF_DOWN`).
|
||||||
- `nx9-wg interface delete <NAME_OR_ID>`: Delete interface and associated peers.
|
- `nx9-wg interface delete <NAME_OR_ID>`: Delete interface.
|
||||||
- `nx9-wg interface status <NAME>`: Query live interface telemetry.
|
|
||||||
- `nx9-wg interface reconcile <NAME>`: Reconcile interface state with the Linux kernel.
|
|
||||||
|
|
||||||
### 7. `peer`
|
### 7. `peer`
|
||||||
- `nx9-wg peer list [--interface <NAME_OR_ID>]`: List enrolled peers.
|
- `nx9-wg peer list [--interface NAME]`: List enrolled peers.
|
||||||
- `nx9-wg peer show <PEER_ID>`: Inspect peer configuration and metadata.
|
- `nx9-wg peer create --interface <IFACE> --name <NAME> [--profile PROFILE] [--mtu MTU]`: Enroll peer.
|
||||||
- `nx9-wg peer create --interface <NAME_OR_ID> --name <NAME> [--address-v4 <CIDR>] [--allowed-ips <CIDRS>] [--endpoint <IP:PORT>]`: Enroll peer.
|
- `nx9-wg peer show <PEER_ID>`: Show peer configuration.
|
||||||
- `nx9-wg peer update <PEER_ID> [--name <NAME>] [--allowed-ips <CIDRS>] [--enabled <BOOL>]`: Update peer parameters.
|
- `nx9-wg peer enable <PEER_ID>` / `disable <PEER_ID>`: Toggle peer state.
|
||||||
- `nx9-wg peer enable <PEER_ID>` / `disable <PEER_ID>` / `revoke <PEER_ID>`: Peer lifecycle transitions.
|
- `nx9-wg peer delete <PEER_ID>`: Delete peer.
|
||||||
- `nx9-wg peer delete <PEER_ID>`: Remove peer.
|
- `nx9-wg peer config <PEER_ID> [--device DEV] [--connection CONN]`: Output `.conf` client file.
|
||||||
- `nx9-wg peer status <PEER_ID>`: Live handshake, endpoint, and bandwidth telemetry.
|
- `nx9-wg peer qr <PEER_ID>`: Render ASCII QR code in terminal for mobile scanning.
|
||||||
- `nx9-wg peer config <PEER_ID> [--output <PATH>]`: Generate standard client `.conf` file.
|
|
||||||
- `nx9-wg peer qr <PEER_ID> [--qr-format <terminal|svg|png>]`: Generate enrollment QR code.
|
|
||||||
|
|
||||||
### 8. `network`
|
### 8. `network`
|
||||||
- `nx9-wg network list`: List defined subnet networks.
|
- `nx9-wg network list`: List subnet networks.
|
||||||
- `nx9-wg network show <ID>`: Inspect network details.
|
- `nx9-wg network create <NAME> --cidr <CIDR>`: Create network.
|
||||||
- `nx9-wg network create <NAME> <CIDR> [--description <TEXT>]`: Create subnet network.
|
- `nx9-wg network delete <NAME_OR_ID>`: Delete network.
|
||||||
- `nx9-wg network update <ID> [--name <NAME>] [--cidr <CIDR>] [--enabled <BOOL>]`: Update network.
|
|
||||||
- `nx9-wg network delete <ID>`: Delete subnet network.
|
|
||||||
|
|
||||||
### 9. `route`
|
### 9. `route`
|
||||||
- `nx9-wg route list`: List configured kernel routing rules.
|
- `nx9-wg route list`: List routing table entries.
|
||||||
- `nx9-wg route show <ID>`: Inspect route rule.
|
- `nx9-wg route add --destination <CIDR> [--gateway IP] [--interface-name IFACE] [--metric M]`: Add route.
|
||||||
- `nx9-wg route add --destination <CIDR> [--gateway <IP>] [--interface-name <IFACE>] [--metric <METRIC>]`: Add route.
|
- `nx9-wg route delete <ROUTE_ID>`: Delete route.
|
||||||
- `nx9-wg route update <ID> [--destination <CIDR>] [--gateway <IP>] [--metric <METRIC>]`: Update route.
|
|
||||||
- `nx9-wg route delete <ID>`: Delete route.
|
|
||||||
- `nx9-wg route status`: Status of kernel routing table management.
|
|
||||||
- `nx9-wg route sync`: Synchronize desired routes to Linux kernel routing table.
|
|
||||||
|
|
||||||
### 10. `firewall`
|
### 10. `firewall`
|
||||||
- `nx9-wg firewall list`: List nftables firewall rules.
|
- `nx9-wg firewall list`: List nftables firewall rules.
|
||||||
- `nx9-wg firewall show <ID>`: Inspect firewall rule.
|
- `nx9-wg firewall add --name <NAME> [--protocol PROTO] [--port PORT] [--action ACTION] [--priority P]`: Add rule.
|
||||||
- `nx9-wg firewall add --name <NAME> [--direction <in|out|forward>] [--source <CIDR>] [--destination <CIDR>] [--protocol <tcp|udp|icmp|any>] [--port <PORT>] [--action <accept|drop|reject>] [--priority <INT>]`: Add rule.
|
- `nx9-wg firewall enable <RULE_ID>` / `disable <RULE_ID>`: Toggle rule.
|
||||||
- `nx9-wg firewall update <ID> [--action <ACTION>] [--priority <INT>] [--enabled <BOOL>]`: Update rule.
|
- `nx9-wg firewall delete <RULE_ID>`: Delete rule.
|
||||||
- `nx9-wg firewall delete <ID>` / `enable <ID>` / `disable <ID>`: Rule management.
|
|
||||||
- `nx9-wg firewall status`: Inspect active nftables ruleset and table.
|
|
||||||
- `nx9-wg firewall sync`: Synchronize firewall ruleset to nftables.
|
|
||||||
|
|
||||||
### 11. `nat`
|
### 11. `nat`
|
||||||
- `nx9-wg nat status`: Inspect NAT masquerade status and managed subnets.
|
- `nx9-wg nat status`: Query NAT masquerade state.
|
||||||
- `nx9-wg nat enable` / `disable`: Toggle NAT masquerade setting.
|
- `nx9-wg nat enable` / `disable`: Toggle outbound NAT masquerading.
|
||||||
- `nx9-wg nat list`: List subnets configured for NAT masquerade.
|
|
||||||
- `nx9-wg nat sync`: Synchronize NAT rules to nftables postrouting chain.
|
|
||||||
|
|
||||||
### 12. `forwarding`
|
### 12. `forwarding`
|
||||||
- `nx9-wg forwarding status`: Inspect IPv4 and IPv6 kernel packet forwarding state.
|
- `nx9-wg forwarding status`: Query kernel `/proc/sys/net/ipv4/ip_forward` status.
|
||||||
- `nx9-wg forwarding enable` / `disable`: Enable or disable kernel packet forwarding.
|
- `nx9-wg forwarding enable` / `disable`: Toggle kernel IP forwarding.
|
||||||
- `nx9-wg forwarding sync`: Synchronize sysctl forwarding parameters.
|
|
||||||
|
|
||||||
### 13. `reconcile`
|
### 13. `reconcile`
|
||||||
- `nx9-wg reconcile status`: Summary of detected drift across all subsystems.
|
- `nx9-wg reconcile plan`: Calculate read-only drift between SQLite and kernel.
|
||||||
- `nx9-wg reconcile plan [--interface <NAME>]`: Dry-run drift analysis without state mutation.
|
- `nx9-wg reconcile apply`: Apply mutations across all execution planes.
|
||||||
- `nx9-wg reconcile apply [--interface <NAME>]`: Reconcile SQLite desired state to Linux kernel.
|
- `nx9-wg reconcile verify`: Post-apply verification check.
|
||||||
- `nx9-wg reconcile verify`: Assert zero drift exists between SQLite and kernel (returns exit code 1 if drift exists).
|
|
||||||
|
|
||||||
### 14. `backup`
|
### 14. `backup`
|
||||||
- `nx9-wg backup create [--description <TEXT>]`: Generate consistent SQLite backup snapshot with SHA-256 manifest.
|
- `nx9-wg backup list`: List backup snapshots.
|
||||||
- `nx9-wg backup list`: List all backup snapshots.
|
- `nx9-wg backup create [--description DESC]`: Generate atomic SQLite online backup (`VACUUM INTO`).
|
||||||
- `nx9-wg backup show <ID>`: Inspect backup metadata and file size.
|
- `nx9-wg backup verify <PATH>`: Verify SQLite 3 header and SHA-256 checksum.
|
||||||
- `nx9-wg backup verify --path <PATH>`: Verify integrity and checksum of backup archive.
|
- `nx9-wg backup restore <PATH_OR_ID>`: Restore database with automatic safety snapshot.
|
||||||
- `nx9-wg backup restore --path <PATH> --yes`: Safely restore database with pre-restore safety snapshot.
|
|
||||||
- `nx9-wg backup delete <ID>`: Delete backup record and archive.
|
|
||||||
|
|
||||||
### 15. `audit`
|
### 15. `audit`
|
||||||
- `nx9-wg audit list [--event-type <TYPE>] [--actor <ACTOR>] [--resource-type <RESOURCE>] [--limit <N>] [--offset <N>]`: Query security audit trail.
|
- `nx9-wg audit list [--limit N] [--event-type TYPE]`: List append-only audit trail records.
|
||||||
- `nx9-wg audit show <ID>`: Inspect complete audit event details.
|
|
||||||
|
|
||||||
### 16. `live`
|
### 16. `live`
|
||||||
- `nx9-wg live interface list` / `show <NAME>`: Query active WireGuard interfaces from kernel.
|
- `nx9-wg live interfaces`: Query active Linux kernel WireGuard interfaces.
|
||||||
- `nx9-wg live peer list <IFACE>` / `show <KEY_OR_ID>`: Query active peers from kernel.
|
- `nx9-wg live peers <IFACE>`: Query live peers, transfer bytes, and handshakes.
|
||||||
- `nx9-wg live routes`: Query live kernel routing status.
|
- `nx9-wg live routes`: Query live kernel routing table.
|
||||||
- `nx9-wg live firewall`: Query live nftables ruleset.
|
- `nx9-wg live nftables`: Query active `table inet nx9_wg` ruleset.
|
||||||
- `nx9-wg live forwarding`: Query live kernel forwarding sysctls.
|
|
||||||
- `nx9-wg live nat`: Query live NAT state.
|
### 17. `diagnostics`
|
||||||
|
- `nx9-wg diagnostics inspect all`: Inspect health across all 9 subsystems.
|
||||||
|
- `nx9-wg diagnostics inspect <SUBSYSTEM>`: Inspect specific subsystem (`system`, `network`, `wireguard`, `peer`, `routing`, `forwarding`, `firewall`, `nat`, `reconciliation`).
|
||||||
@@ -0,0 +1,82 @@
|
|||||||
|
# NX9 WireGuard — Architectural & Design Principles
|
||||||
|
|
||||||
|
> **"Sovereign, self-hosted, Linux-native network infrastructure built from first principles."**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. The NX9 Philosophy
|
||||||
|
|
||||||
|
`nx9-wg` was conceived as a clean, high-performance, single-binary WireGuard appliance and network management engine for sovereign infrastructure. It is built upon the following foundational principles:
|
||||||
|
|
||||||
|
### A. Self-Hosted First & Full Ownership
|
||||||
|
Network infrastructure is a critical sovereignty boundary. Administrators must have complete, unencumbered ownership of their cryptographic keys, network routing policies, and configuration data. `nx9-wg` operates entirely locally without phone-home telemetry, cloud dependencies, or external licensing servers.
|
||||||
|
|
||||||
|
### B. Linux-Native Architecture
|
||||||
|
Rather than treating the Linux kernel as an opaque black box accessed via shell utilities, `nx9-wg` communicates directly with kernel networking subsystems using native Netlink protocols (RTNETLINK and WireGuard Generic Netlink) and direct `/proc` interfaces.
|
||||||
|
|
||||||
|
### C. FOSS & No Vendor Lock-In
|
||||||
|
`nx9-wg` is free and open-source software dual-licensed under `MIT OR Apache-2.0`. All database schemas, configuration formats, cryptographic profiles, and backup archives use open, standard specifications (SQLite, TOML, JSON, Base64).
|
||||||
|
|
||||||
|
### D. Zero Scripting Runtime Dependencies
|
||||||
|
The entire application—from the HTTP/WebSocket API server and reactive SPA frontend to cryptographic key generation, QR rendering, database migrations, and kernel Netlink communication—is compiled into a single native Rust binary. There is zero runtime dependency on Node.js, npm, Electron, Python, or external shell scripts.
|
||||||
|
|
||||||
|
### E. CLI-First & Headless Operational Simplicity
|
||||||
|
Every capability exposed by the Web UI or REST API is first available as a first-class native CLI command supporting human-readable tables as well as machine-readable JSON, YAML, and CSV formats.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Why Not an Imperative Shell Wrapper?
|
||||||
|
|
||||||
|
Many existing WireGuard management tools act merely as thin Web UI wrappers around command-line utilities like `wg`, `wg-quick`, `iptables`, and `ip`. This model introduces severe architectural limitations:
|
||||||
|
|
||||||
|
1. **Fragile Process Spawning**: Shelling out to external executables (`std::process::Command`) incurs substantial overhead, introduces quoting/injection risks, and parses fragile string outputs that break across operating system versions.
|
||||||
|
2. **Lack of Authoritative State**: Relying on `/etc/wireguard/wg0.conf` text files makes atomic transactional updates, relational constraints, foreign keys, and audit logging difficult and error-prone.
|
||||||
|
3. **Configuration Drift**: Imperative changes applied directly to the kernel or configuration files easily drift out of sync with what the web management interface displays.
|
||||||
|
4. **Host Network Destruction**: Script-based firewall and routing flush commands (e.g., `iptables -F` or modifying default routing tables) often disrupt container engines (Docker, Podman), hypervisors (KVM, libvirt), or host networking.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Core Architectural Invariants
|
||||||
|
|
||||||
|
### 1. SQLite Desired-State Authority
|
||||||
|
The SQLite database is the single authoritative source of truth for all intended configuration state (interfaces, peers, networks, routes, firewall rules, and NAT policies). The kernel execution plane is a cache that is brought into alignment through continuous, deterministic reconciliation.
|
||||||
|
|
||||||
|
### 2. Zero Subprocess Execution Guarantee
|
||||||
|
Production Rust code in `nx9-wg` is strictly forbidden from invoking `std::process::Command` or `tokio::process`. All kernel mutations occur via in-process Netlink sockets or `libnftables` Netfilter bindings.
|
||||||
|
|
||||||
|
### 3. Strict Resource Ownership & Scoping
|
||||||
|
- **Firewall Rules**: Confined strictly to `table inet nx9_wg`. External tables created by Docker, Kubernetes, or host firewalls are never modified or flushed.
|
||||||
|
- **Routing**: `nx9-wg` manages only routes explicitly defined in its database or attached to its managed interfaces. Default gateway routes and unmanaged host routes are never altered.
|
||||||
|
|
||||||
|
### 4. Single Administrator Security Model
|
||||||
|
`nx9-wg` avoids complex RBAC frameworks in favor of a strictly enforced single-administrator model locked by database constraints (`CHECK (id = 1)`). This eliminates privilege escalation, role confusion, and broken object-level authorization vulnerabilities.
|
||||||
|
|
||||||
|
### 5. Multi-Cycle Idempotent Reconciliation
|
||||||
|
State reconciliation follows a deterministic, read-only plan phase followed by a serialized apply phase and post-apply verification. Repeated executions against an already converged system produce zero mutations (NOOP).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Architectural Summary
|
||||||
|
|
||||||
|
```
|
||||||
|
┌────────────────────────────────────────────────────────┐
|
||||||
|
│ Single Administrator (Web UI / CLI) │
|
||||||
|
└───────────────────────────┬────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌───────────────────────────▼────────────────────────────┐
|
||||||
|
│ Axum REST API & WebSockets │
|
||||||
|
└───────────────────────────┬────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌───────────────────────────▼────────────────────────────┐
|
||||||
|
│ Authoritative SQLite Desired State (WAL) │
|
||||||
|
└───────────────────────────┬────────────────────────────┘
|
||||||
|
│ (Periodic / Triggered)
|
||||||
|
┌───────────────────────────▼────────────────────────────┐
|
||||||
|
│ Reconciliation Engine │
|
||||||
|
└───────┬───────────────────┼───────────────────┬────────┘
|
||||||
|
│ (RTNETLINK/Genl) │ (libnftables) │ (Procfs)
|
||||||
|
┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐
|
||||||
|
│ WireGuard Genl│ │ inet nx9_wg │ │ IP Forwarding │
|
||||||
|
│ Kernel Socket │ │ Table Filter │ │ /proc/sys │
|
||||||
|
└───────────────┘ └───────────────┘ └───────────────┘
|
||||||
|
```
|
||||||
+64
-34
@@ -1,52 +1,82 @@
|
|||||||
# Development and Contributing Guide
|
# Developer Guide & Repository Reference
|
||||||
|
|
||||||
## Environment Setup
|
This guide provides instructions for building, testing, linting, and contributing to the `nx9-wg` codebase.
|
||||||
|
|
||||||
- **Rust Toolchain**: `rustc` and `cargo` 1.85+ (Edition 2024).
|
|
||||||
- **SQLite3 development headers** (for `sqlx-sqlite`).
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Workspace Structure
|
## 1. Workspace Layout
|
||||||
|
|
||||||
```
|
The repository is organized as a Cargo workspace containing 6 crates and the root application binary:
|
||||||
.
|
|
||||||
├── Cargo.toml
|
- **`crates/nx9-wg-core`**: Common domain entities, RFC validators, cryptography, and configuration.
|
||||||
├── Cargo.lock
|
- **`crates/nx9-wg-db`**: SQLite database persistence layer, migration SQL scripts, and repository implementations.
|
||||||
├── config.example.toml
|
- **`crates/nx9-wireguard`**: WireGuard Generic Netlink execution, RTNETLINK link management, config builder, and QR engine.
|
||||||
├── nx9-wg.service
|
- **`crates/nx9-wg-network`**: RTNETLINK route management, `libnftables.so.1` integration, and procfs forwarding.
|
||||||
├── Dockerfile
|
- **`crates/nx9-wg-api`**: Axum REST API router, WebSocket broadcaster, authentication middleware, and reconciliation engine.
|
||||||
├── src/
|
- **`crates/nx9-wg-ui`**: Design tokens, CSS stylesheet compiler, view models, and SPA asset integration.
|
||||||
│ └── main.rs
|
- **`src/main.rs`**: Root CLI command parser and daemon entry point.
|
||||||
├── crates/
|
|
||||||
│ ├── nx9-core/ # Domain models, crypto, config, validation
|
|
||||||
│ ├── nx9-db/ # SQLite schema, migrations, repositories
|
|
||||||
│ ├── nx9-wireguard/ # WireGuard controller, .conf builder, QR engine
|
|
||||||
│ ├── nx9-network/ # Forwarding, routing, nftables
|
|
||||||
│ ├── nx9-api/ # Axum API, WebSocket, Reconciler, Backup
|
|
||||||
│ └── nx9-ui/ # Dioxus UI shell
|
|
||||||
└── docs/ # Documentation suite
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Running Quality Gates
|
## 2. Prerequisites & Build Commands
|
||||||
|
|
||||||
Before submitting changes, all mandatory quality gates must pass:
|
### Prerequisites
|
||||||
|
- **Rust Toolchain**: 1.85+ (Edition 2024).
|
||||||
|
- **C Compiler**: `gcc` or `clang` (for SQLite C amalgamation).
|
||||||
|
- **Linux Libraries**: `libnftables-dev` (Debian/Ubuntu) or `nftables-devel` / `libnftables` (Fedora/Arch).
|
||||||
|
|
||||||
|
### Build Commands
|
||||||
```bash
|
```bash
|
||||||
# 1. Format check
|
# Debug build
|
||||||
|
cargo build --workspace
|
||||||
|
|
||||||
|
# Release build
|
||||||
|
cargo build --release
|
||||||
|
|
||||||
|
# Format check
|
||||||
cargo fmt --all -- --check
|
cargo fmt --all -- --check
|
||||||
|
|
||||||
# 2. Workspace check
|
# Clippy linter
|
||||||
cargo check --workspace
|
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||||||
|
```
|
||||||
|
|
||||||
# 3. Unit and integration tests
|
---
|
||||||
|
|
||||||
|
## 3. Test Execution & SAFE Mode (`LIVE=0`) vs Privileged Mode (`LIVE=1`)
|
||||||
|
|
||||||
|
To prevent accidental modifications to developer workstations, all integration and live kernel test scripts default to SAFE mode (`LIVE=0`):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Run full workspace unit & integration tests
|
||||||
cargo test --workspace
|
cargo test --workspace
|
||||||
|
|
||||||
# 4. Strict clippy with warnings denied
|
# 2. Run Comprehensive CLI Verification Suite (210 checks)
|
||||||
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
LIVE=0 bash scripts/test-cli-comprehensive.sh
|
||||||
|
|
||||||
# 5. Marker scan
|
# 3. Run Native Linux Integration Test Suite (20 checks)
|
||||||
git grep -n -E 'TODO|FIXME|XXX|HACK|unimplemented!|todo!|panic!' src/ crates/
|
LIVE=0 bash scripts/test-native-integration.sh
|
||||||
|
|
||||||
|
# 4. Run Dedicated Live Kernel Test Suite (24 checks)
|
||||||
|
LIVE=0 bash scripts/test-live-kernel.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Privileged Real-Kernel Testing (`LIVE=1`)
|
||||||
|
> [!CAUTION]
|
||||||
|
> `LIVE=1` tests must ONLY be executed on a dedicated disposable Linux virtual machine or container with `CAP_NET_ADMIN`. Never execute `LIVE=1` on a production host.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# On a dedicated disposable VM as root:
|
||||||
|
sudo LIVE=1 bash scripts/test-live-kernel.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Release Packaging
|
||||||
|
|
||||||
|
To build the self-contained release distribution archives:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bash scripts/package-release.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
Outputs `.tar.gz`, `.tar.xz`, and `.sha256` files in `target/dist/`.
|
||||||
@@ -0,0 +1,64 @@
|
|||||||
|
# Firewall and NAT Domain Model Reference
|
||||||
|
|
||||||
|
This document describes the domain representations, rule structures, port specifications, and safety invariants for packet filtering and NAT in `nx9-wg`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Domain Entities
|
||||||
|
|
||||||
|
### A. Firewall Rule (`FirewallRule`)
|
||||||
|
Represents an individual packet filtering rule in the database:
|
||||||
|
|
||||||
|
| Field | Type | Description |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| `id` | `Uuid` | Unique identifier (Primary Key) |
|
||||||
|
| `name` | `String` | Human-readable identifier (e.g., `allow-dns-udp`) |
|
||||||
|
| `direction` | `FirewallDirection` | `In`, `Out`, or `Forward` |
|
||||||
|
| `protocol` | `FirewallProtocol` | `Tcp`, `Udp`, `TcpUdp`, `Icmp`, or `Any` |
|
||||||
|
| `action` | `FirewallAction` | `Accept`, `Drop`, or `Reject` |
|
||||||
|
| `source` | `Option<String>` | Source CIDR or IP (e.g., `10.100.0.0/24`) |
|
||||||
|
| `destination` | `Option<String>` | Destination CIDR or IP |
|
||||||
|
| `source_port` | `Option<u16>` | Specific source port |
|
||||||
|
| `destination_port`| `Option<u16>` | Specific destination port |
|
||||||
|
| `port_range` | `Option<String>` | Single port, list, or range (`53`, `80,443`, `8000-8100`) |
|
||||||
|
| `interface_id` | `Option<Uuid>` | Optional interface association |
|
||||||
|
| `peer_id` | `Option<Uuid>` | Optional cryptographic peer association |
|
||||||
|
| `priority` | `i32` | Rule evaluation priority (lower numbers evaluate first) |
|
||||||
|
| `enabled` | `bool` | Active state flag |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Port Specification Syntax
|
||||||
|
|
||||||
|
The `port_range` field supports three RFC-compliant formats:
|
||||||
|
|
||||||
|
1. **Single Port**: `80` $\rightarrow$ Evaluates as `dport 80`
|
||||||
|
2. **Multi-Port Comma List**: `80,443,8080` $\rightarrow$ Evaluates as `dport { 80, 443, 8080 }`
|
||||||
|
3. **Port Range**: `8000-8100` $\rightarrow$ Evaluates as `dport 8000-8100`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Protocol Grouping
|
||||||
|
|
||||||
|
- **`Tcp`**: Filters IPv4/IPv6 TCP packets.
|
||||||
|
- **`Udp`**: Filters IPv4/IPv6 UDP packets.
|
||||||
|
- **`TcpUdp`**: Translates to `{ tcp, udp }` protocol match in a single atomic rule.
|
||||||
|
- **`Icmp`**: Translates to `icmp` (IPv4) or `icmpv6` (IPv6).
|
||||||
|
- **`Any`**: Omits protocol match, applying action to all transport protocols.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. NAT Masquerade Domain Configuration
|
||||||
|
|
||||||
|
NAT masquerading is governed by key-value appliance settings in SQLite:
|
||||||
|
|
||||||
|
- **`enable_nat`**: Boolean string (`"true"` / `"false"`). When enabled, all active managed WireGuard subnets are masqueraded outbound to the host WAN interface.
|
||||||
|
- **Dynamic Subnet Calculation**: The reconciliation engine queries all enabled interfaces (`Interface.address_v4`) and generates dedicated masquerade rules for each unique subnet.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Domain Validation & Invariants
|
||||||
|
|
||||||
|
1. **Priority Uniqueness & Ordering**: Rules are sorted by `priority ASC, created_at ASC` ensuring determinism.
|
||||||
|
2. **CIDR Validation**: Source and destination values must parse as valid IPv4 or IPv6 CIDRs.
|
||||||
|
3. **Port Bounds**: Port numbers must fall within standard bounds (`1..=65535`). In ranges `A-B`, `A <= B` is strictly enforced.
|
||||||
+176
-32
@@ -1,70 +1,214 @@
|
|||||||
# Installation and Deployment Guide
|
# nx9-wg Production Installation & Deployment Guide
|
||||||
|
|
||||||
## Prerequisites
|
This guide provides the complete, authoritative reference for installing, configuring, securing, maintaining, upgrading, and uninstallation of the `nx9-wg` WireGuard Appliance Management Engine on Linux.
|
||||||
|
|
||||||
- Linux kernel 5.6+ (with native in-tree WireGuard module)
|
|
||||||
- `nftables` packet filtering engine
|
|
||||||
- Linux capabilities: `CAP_NET_ADMIN` and `CAP_NET_BIND_SERVICE`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 1. Native Binary Installation
|
## Prerequisites & Runtime Environment
|
||||||
|
|
||||||
|
| Requirement | Specification | Details |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **Operating System** | Linux (Kernel 5.6+) | Native in-tree WireGuard module support (`wireguard.ko`). |
|
||||||
|
| **Architecture** | `x86_64` or `aarch64` | Native 64-bit Linux executable. |
|
||||||
|
| **Packet Filtering** | `nftables` / `libnftables.so.1` | Native Netfilter execution plane for firewall and NAT masquerade. |
|
||||||
|
| **Linux Capabilities** | `CAP_NET_ADMIN`, `CAP_NET_BIND_SERVICE` | Required for RTNETLINK, Generic Netlink, and low-port UDP binding. |
|
||||||
|
| **Database** | SQLite 3 (Embedded) | Statically bundled in binary; zero external database server required. |
|
||||||
|
| **Process Model** | Single Native Executable | Zero external subprocess invocations (no `wg`, `ip`, `nft`, `bash`, Python, or Node.js). |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Quick Installation via Release Archive
|
||||||
|
|
||||||
|
Download and extract the official release archive:
|
||||||
|
|
||||||
### Building from Source
|
|
||||||
```bash
|
```bash
|
||||||
git clone ssh://git@git.nx9.in:6645/thakares/nx9-wg.git
|
# 1. Download release archive (replace with current version/arch)
|
||||||
cd nx9-wg
|
tar -xzf nx9-wg-v0.8.0-linux-x86_64.tar.gz
|
||||||
cargo build --release --bin nx9-wg
|
cd nx9-wg-v0.8.0-linux-x86_64
|
||||||
|
|
||||||
# Install binary
|
# 2. Run the automated installer as root
|
||||||
|
sudo bash install.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
The installer automatically:
|
||||||
|
- Installs `/usr/local/bin/nx9-wg` (mode `0755`)
|
||||||
|
- Creates `/etc/nx9-wg` (mode `0750`) and installs `/etc/nx9-wg/config.toml` (mode `0640`) if absent
|
||||||
|
- Creates `/var/lib/nx9-wg` (mode `0700`) and `/var/lib/nx9-wg/backups` (mode `0700`)
|
||||||
|
- Bootstraps the initial administrator with a secure random password (`/var/lib/nx9-wg/admin-initial-password`)
|
||||||
|
- Installs `/etc/systemd/system/nx9-wg.service` (mode `0644`)
|
||||||
|
- Enables and starts the `nx9-wg` service
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Manual Step-by-Step Installation
|
||||||
|
|
||||||
|
If you prefer to perform each step manually:
|
||||||
|
|
||||||
|
### Step 2.1 — Install Binary
|
||||||
|
```bash
|
||||||
sudo install -m 0755 target/release/nx9-wg /usr/local/bin/nx9-wg
|
sudo install -m 0755 target/release/nx9-wg /usr/local/bin/nx9-wg
|
||||||
```
|
```
|
||||||
|
|
||||||
### Initializing Directories and Configuration
|
### Step 2.2 — Create Filesystem Layout & Set Strict Permissions
|
||||||
```bash
|
```bash
|
||||||
sudo mkdir -p /var/lib/nx9-wg /etc/nx9-wg /var/lib/nx9-wg/backups
|
sudo install -d -m 0750 /etc/nx9-wg
|
||||||
sudo cp config.example.toml /etc/nx9-wg/config.toml
|
sudo install -d -m 0700 /var/lib/nx9-wg
|
||||||
|
sudo install -d -m 0700 /var/lib/nx9-wg/backups
|
||||||
|
sudo install -d -m 0750 /var/log/nx9-wg
|
||||||
```
|
```
|
||||||
|
|
||||||
### Bootstrapping the Administrator Account
|
### Step 2.3 — Install Configuration File
|
||||||
```bash
|
```bash
|
||||||
sudo nx9-wg --config /etc/nx9-wg/config.toml --data-dir /var/lib/nx9-wg init --generate-password --write-password-file /var/lib/nx9-wg/admin-password
|
if [ ! -f /etc/nx9-wg/config.toml ]; then
|
||||||
|
sudo install -m 0640 config.example.toml /etc/nx9-wg/config.toml
|
||||||
|
fi
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
### Step 2.4 — Bootstrap Initial Administrator Account
|
||||||
|
Generate a cryptographically secure 24-character random password written to a restricted file:
|
||||||
|
```bash
|
||||||
|
sudo /usr/local/bin/nx9-wg \
|
||||||
|
--config /etc/nx9-wg/config.toml \
|
||||||
|
--data-dir /var/lib/nx9-wg \
|
||||||
|
init --generate-password --write-password-file /var/lib/nx9-wg/admin-password
|
||||||
|
|
||||||
## 2. Systemd Service Deployment
|
sudo chmod 0600 /var/lib/nx9-wg/admin-password
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2.5 — Deploy & Start systemd Service
|
||||||
```bash
|
```bash
|
||||||
# Copy systemd unit file
|
|
||||||
sudo cp nx9-wg.service /etc/systemd/system/nx9-wg.service
|
sudo cp nx9-wg.service /etc/systemd/system/nx9-wg.service
|
||||||
|
|
||||||
# Reload systemd and enable service
|
|
||||||
sudo systemctl daemon-reload
|
sudo systemctl daemon-reload
|
||||||
sudo systemctl enable --now nx9-wg
|
sudo systemctl enable --now nx9-wg
|
||||||
|
|
||||||
# Check service status and logs
|
|
||||||
sudo systemctl status nx9-wg
|
|
||||||
sudo journalctl -u nx9-wg -f
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 3. Upgrading nx9-wg
|
## 3. Verification & First Operational Workflow
|
||||||
|
|
||||||
|
### Step 3.1 — Check Service Status
|
||||||
|
```bash
|
||||||
|
sudo systemctl status nx9-wg
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3.2 — Check Operational Health via CLI
|
||||||
|
```bash
|
||||||
|
sudo /usr/local/bin/nx9-wg system health
|
||||||
|
sudo /usr/local/bin/nx9-wg diagnostics inspect all
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3.3 — Log in via Web User Interface
|
||||||
|
Open your browser at `http://<server-ip>:8080/` and log in with:
|
||||||
|
- **Username**: `admin`
|
||||||
|
- **Password**: Found in `/var/lib/nx9-wg/admin-password`
|
||||||
|
|
||||||
|
### Step 3.4 — Create First WireGuard Interface (wg0)
|
||||||
|
```bash
|
||||||
|
sudo /usr/local/bin/nx9-wg interface create \
|
||||||
|
--address-v4 10.100.0.1/24 \
|
||||||
|
--port 51820 \
|
||||||
|
--mtu 1420 \
|
||||||
|
wg0
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3.5 — Enroll Client Peer
|
||||||
|
```bash
|
||||||
|
sudo /usr/local/bin/nx9-wg peer create \
|
||||||
|
--interface wg0 \
|
||||||
|
--name alice-mobile \
|
||||||
|
--profile full_tunnel \
|
||||||
|
--mtu 1280
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3.6 — Apply Reconciliation
|
||||||
|
```bash
|
||||||
|
sudo /usr/local/bin/nx9-wg reconcile apply
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Production Backup & Recovery
|
||||||
|
|
||||||
|
### Mandatory Pre-Upgrade Backup
|
||||||
|
Always create an authoritative database backup before applying system updates or binary upgrades:
|
||||||
|
```bash
|
||||||
|
sudo /usr/local/bin/nx9-wg backup create --description "Pre-upgrade snapshot"
|
||||||
|
sudo /usr/local/bin/nx9-wg backup list
|
||||||
|
```
|
||||||
|
|
||||||
|
### Restoring from Backup
|
||||||
|
```bash
|
||||||
|
# 1. Stop active service
|
||||||
|
sudo systemctl stop nx9-wg
|
||||||
|
|
||||||
|
# 2. Restore database from backup snapshot
|
||||||
|
sudo /usr/local/bin/nx9-wg backup restore <BACKUP_ID>
|
||||||
|
|
||||||
|
# 3. Restart service & reconcile state
|
||||||
|
sudo systemctl start nx9-wg
|
||||||
|
sudo /usr/local/bin/nx9-wg reconcile apply
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Upgrading nx9-wg
|
||||||
|
|
||||||
|
The `nx9-wg` persistence model utilizes SQLite with automatic schema migrations executed upon startup.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Stop service
|
||||||
|
sudo systemctl stop nx9-wg
|
||||||
|
|
||||||
|
# 2. Create backup
|
||||||
|
sudo /usr/local/bin/nx9-wg backup create --description "Pre-upgrade backup"
|
||||||
|
|
||||||
|
# 3. Install new binary
|
||||||
|
sudo install -m 0755 nx9-wg-new /usr/local/bin/nx9-wg
|
||||||
|
|
||||||
|
# 4. Restart service (automatic migration)
|
||||||
|
sudo systemctl start nx9-wg
|
||||||
|
|
||||||
|
# 5. Verify convergence
|
||||||
|
sudo /usr/local/bin/nx9-wg reconcile plan
|
||||||
|
sudo /usr/local/bin/nx9-wg system health
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Rollback Procedure
|
||||||
|
|
||||||
|
If a new binary fails or encounters incompatibility:
|
||||||
|
|
||||||
1. Stop the active service:
|
1. Stop the active service:
|
||||||
```bash
|
```bash
|
||||||
sudo systemctl stop nx9-wg
|
sudo systemctl stop nx9-wg
|
||||||
```
|
```
|
||||||
2. Create a safety backup:
|
2. Re-install the previous working binary:
|
||||||
```bash
|
```bash
|
||||||
sudo nx9-wg --config /etc/nx9-wg/config.toml --data-dir /var/lib/nx9-wg backup create --description "Pre-upgrade backup"
|
sudo install -m 0755 nx9-wg-previous /usr/local/bin/nx9-wg
|
||||||
```
|
```
|
||||||
3. Install new binary:
|
3. Restore the pre-upgrade database backup if schema changes occurred:
|
||||||
```bash
|
```bash
|
||||||
sudo install -m 0755 target/release/nx9-wg /usr/local/bin/nx9-wg
|
sudo /usr/local/bin/nx9-wg backup restore <PRE_UPGRADE_BACKUP_ID>
|
||||||
```
|
```
|
||||||
4. Restart service (database schema migrations run automatically at startup):
|
4. Start service and verify:
|
||||||
```bash
|
```bash
|
||||||
sudo systemctl start nx9-wg
|
sudo systemctl start nx9-wg
|
||||||
|
sudo /usr/local/bin/nx9-wg system health
|
||||||
```
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Safe Uninstallation
|
||||||
|
|
||||||
|
### Standard Uninstallation (Preserves Database & Configuration)
|
||||||
|
```bash
|
||||||
|
sudo bash uninstall.sh
|
||||||
|
```
|
||||||
|
*Stops and disables the service, removes `/usr/local/bin/nx9-wg` and the systemd unit file, while preserving `/etc/nx9-wg` and `/var/lib/nx9-wg`.*
|
||||||
|
|
||||||
|
### Total Purge (Destructive)
|
||||||
|
```bash
|
||||||
|
sudo bash uninstall.sh --purge
|
||||||
|
```
|
||||||
|
*Requires explicit interactive confirmation before permanently deleting all database files, backups, logs, and configuration.*
|
||||||
+28
-15
@@ -1,34 +1,47 @@
|
|||||||
# Linux Platform and Kernel Requirements
|
# Linux Platform and Kernel Requirements
|
||||||
|
|
||||||
`nx9-wg` is built for modern Linux systems and relies directly on kernel networking features.
|
`nx9-wg` is designed for native Linux execution and interacts directly with Linux kernel subsystems via Netlink sockets and direct `/proc` filesystem interfaces.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 1. Kernel Requirements
|
## 1. Kernel Requirements
|
||||||
|
|
||||||
- **Linux Kernel Version**: 5.6 or newer (WireGuard module is included in mainline kernel 5.6+).
|
- **Linux Kernel Version**: 5.6 or newer (in-tree WireGuard module support).
|
||||||
- **Kernel Module**: `wireguard.ko` (`modprobe wireguard`).
|
- **WireGuard Subsystem**: `wireguard.ko` in-tree module (`modprobe wireguard`).
|
||||||
- **Sysctl IP Forwarding**:
|
- **Generic Netlink (Genl)**: Family `wireguard` for cryptographic interface and peer configuration.
|
||||||
- `/proc/sys/net/ipv4/ip_forward` (must be `1` for VPN client internet routing).
|
- **RTNETLINK**: For network interface lifecycle (RTM_NEWLINK/DELLINK), address assignments (RTM_NEWADDR), and routing table management (RTM_NEWROUTE/DELROUTE).
|
||||||
- `/proc/sys/net/ipv6/conf/all/forwarding` (optional, for IPv6 dual-stack).
|
- **Sysctl IP Forwarding**: Direct procfs mutation:
|
||||||
|
- `/proc/sys/net/ipv4/ip_forward` (enabled for IPv4 packet routing)
|
||||||
|
- `/proc/sys/net/ipv6/conf/all/forwarding` (enabled for IPv6 dual-stack routing)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 2. Firewall and Packet Filtering
|
## 2. Dynamic Library & Runtime Dependencies
|
||||||
|
|
||||||
- **`nftables`**: `nx9-wg` requires `nftables` in the kernel.
|
When compiled for Linux, `nx9-wg` links dynamically against standard system libraries:
|
||||||
- **Isolated Table**: All rules are scoped inside `table inet nx9_wg`. `nx9-wg` does not alter or flush tables created by Docker, Kubernetes, or other firewall utilities.
|
|
||||||
|
| Library | Runtime Function | Installation Package (Debian/Ubuntu) | Installation Package (RHEL/Fedora/Arch) |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| `libnftables.so.1` | Native nftables ruleset execution | `libnftables1` / `nftables` | `libnftables` / `nftables` |
|
||||||
|
| `libmnl.so.0` | Minimal Netlink library | `libmnl0` | `libmnl` |
|
||||||
|
| `libnftnl.so.11` | Netfilter Netlink object library | `libnftnl11` | `libnftnl` |
|
||||||
|
| `libc.so.6` | Standard C library (glibc / musl) | Base system | Base system |
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> SQLite is statically embedded into the `nx9-wg` binary via `libsqlite3-sys`. No external SQLite installation or database daemon is required.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 3. Capability Requirements
|
## 3. Security Capabilities & Privilege Boundaries
|
||||||
|
|
||||||
When running without full root privileges, the process requires:
|
When executed under systemd or non-root service accounts:
|
||||||
- `CAP_NET_ADMIN`: For configuring network links, routes, and packet filter tables.
|
- `CAP_NET_ADMIN`: Strictly required for RTNETLINK interface lifecycle, IP route mutations, WireGuard Genl socket communication, and nftables Netfilter execution.
|
||||||
- `CAP_NET_BIND_SERVICE`: If binding to low UDP ports (< 1024).
|
- `CAP_NET_BIND_SERVICE`: Required if binding the REST API or WireGuard UDP socket to privileged ports (< 1024).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 4. Unsupported Environments
|
## 4. Execution Mode Classification
|
||||||
|
|
||||||
- macOS and Windows do not support the Linux in-tree WireGuard kernel module. For local testing on non-Linux platforms, `nx9-wg` automatically engages the built-in `SimulatedWireGuardEngine` and `SimulatedNetworkEngine`.
|
- **Linux Native Mode**: Automatically engaged on Linux systems with `CAP_NET_ADMIN` and kernel WireGuard/Netfilter modules.
|
||||||
|
- **Non-Linux / Simulated Mode**: Automatically engaged on macOS and Windows hosts for development and UI preview.
|
||||||
|
- **Restricted Mode**: Engaged when running on Linux without `CAP_NET_ADMIN`; control-plane REST API, SQLite queries, and diagnostics operate normally, while kernel mutation calls return descriptive permission errors without crashing.
|
||||||
@@ -0,0 +1,80 @@
|
|||||||
|
# Native Linux Network Engine (`NativeLinuxNetworkEngine`)
|
||||||
|
|
||||||
|
The `NativeLinuxNetworkEngine` provides Linux network interface inspection, IPv4/IPv6 address assignment, kernel routing table synchronization, and IP packet forwarding controls.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Architecture & Netlink Communication
|
||||||
|
|
||||||
|
All network operations are executed in-process using RTNETLINK (`NETLINK_ROUTE` family) and direct `/proc/sys` procfs file writes:
|
||||||
|
|
||||||
|
```
|
||||||
|
┌────────────────────────────────────────────────────────┐
|
||||||
|
│ NativeLinuxNetworkEngine │
|
||||||
|
└───────────────┬────────────────────────┬───────────────┘
|
||||||
|
│ │
|
||||||
|
Link, Address & Route Management │ Kernel IP Forwarding Controls
|
||||||
|
via RTNETLINK (NETLINK_ROUTE) │ via direct /proc/sys writes
|
||||||
|
│ │
|
||||||
|
┌───────────────▼────────────────────────▼───────────────┐
|
||||||
|
│ Linux Kernel Networking │
|
||||||
|
└────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Capabilities & Operations
|
||||||
|
|
||||||
|
### A. Interface & Address Management
|
||||||
|
- **`list_interfaces()`**: Enumerates all host network interfaces, resolving interface index (`ifindex`), MAC address, operational flags (`IFF_UP`, `IFF_RUNNING`, `IFF_POINTOPOINT`), and interface type.
|
||||||
|
- **`set_interface_state(name, up)`**: Modifies interface operational state flags (`IFF_UP`).
|
||||||
|
- **`add_address(name, cidr)` / `delete_address(name, cidr)`**: Sends `RTM_NEWADDR` / `RTM_DELADDR` Netlink messages to attach IPv4 or IPv6 subnets to interfaces.
|
||||||
|
|
||||||
|
### B. Kernel Routing Table Synchronization
|
||||||
|
- **`list_routes()`**: Queries active kernel routes (`RTM_GETROUTE`), decoding destination prefixes, gateway addresses, interface names, route metrics, and route protocols.
|
||||||
|
- **`add_route(route)`**: Installs a routing entry via `RTM_NEWROUTE` with scope `RT_SCOPE_UNIVERSE` or `RT_SCOPE_LINK`, target interface index (`RTA_OIF`), and route metric (`RTA_PRIORITY`).
|
||||||
|
- **`delete_route(route)`**: Removes a managed route via `RTM_DELROUTE`.
|
||||||
|
- **`has_route_drift(desired_routes)`**: Compares SQLite desired routes against active kernel routes using exact subnet, gateway, interface, and metric equality.
|
||||||
|
|
||||||
|
### C. Direct Procfs IP Forwarding
|
||||||
|
Rather than executing `sysctl -w net.ipv4.ip_forward=1`, the engine directly inspects and updates procfs files:
|
||||||
|
- **IPv4**: `/proc/sys/net/ipv4/ip_forward`
|
||||||
|
- **IPv6**: `/proc/sys/net/ipv6/conf/all/forwarding`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Strict Resource Ownership Invariants
|
||||||
|
|
||||||
|
To guarantee safety on multi-tenant hosts running Docker, Kubernetes, Podman, or libvirt, `nx9-wg` enforces strict non-interference rules:
|
||||||
|
|
||||||
|
1. **No Routing Table Flushes**: `nx9-wg` NEVER executes `ip route flush` or flushes kernel routing tables.
|
||||||
|
2. **Default Route Protection**: The default gateway (`0.0.0.0/0` via WAN gateway) is NEVER modified, deleted, or overridden.
|
||||||
|
3. **Unmanaged Route Protection**: Routes belonging to external interfaces (e.g., `eth0`, `docker0`, `cni0`, `virbr0`) are completely ignored during route reconciliation.
|
||||||
|
4. **Scope-Confined Deletion**: Only routes explicitly created by `nx9-wg` or assigned to `nx9-wg` interfaces are candidates for removal during drift reconciliation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Route Equality & Reconciliation Logic
|
||||||
|
|
||||||
|
Two routes are evaluated as equal if and only if all of the following match:
|
||||||
|
- **Destination CIDR**: Prefix and netmask (e.g., `192.168.50.0/24`).
|
||||||
|
- **Gateway**: Optional next-hop IP address.
|
||||||
|
- **Interface**: Egress device name (e.g., `wg0`).
|
||||||
|
- **Metric**: Route priority integer.
|
||||||
|
|
||||||
|
```rust
|
||||||
|
// Deterministic route equality check
|
||||||
|
if desired_route.destination == live_route.destination
|
||||||
|
&& desired_route.gateway == live_route.gateway
|
||||||
|
&& desired_route.interface_name == live_route.interface_name
|
||||||
|
&& desired_route.metric == live_route.metric
|
||||||
|
{
|
||||||
|
// Route is converged (In Sync)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Non-Linux Platform Fallback
|
||||||
|
|
||||||
|
On macOS and Windows workstations, `nx9-wg` automatically engages `SimulatedNetworkEngine` to enable local application development without requiring Linux-specific Netlink sockets.
|
||||||
@@ -0,0 +1,88 @@
|
|||||||
|
# Native Linux WireGuard Engine (`NativeLinuxWireGuardEngine`)
|
||||||
|
|
||||||
|
The `NativeLinuxWireGuardEngine` provides direct, in-process communication with the Linux kernel WireGuard subsystem via Linux Netlink sockets.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Protocol Architecture: RTNETLINK & Generic Netlink
|
||||||
|
|
||||||
|
Unlike traditional WireGuard management tools that spawn external CLI processes (`wg`, `wg-quick`), `nx9-wg` uses native kernel sockets:
|
||||||
|
|
||||||
|
```
|
||||||
|
┌────────────────────────────────────────────────────────┐
|
||||||
|
│ NativeLinuxWireGuardEngine │
|
||||||
|
└───────────────┬────────────────────────┬───────────────┘
|
||||||
|
│ │
|
||||||
|
Link Lifecycle (Create / Up / Down) │ Cryptographic Config & Telemetry
|
||||||
|
via RTNETLINK (AF_NETLINK, NETLINK_ROUTE)│ via Generic Netlink (family "wireguard")
|
||||||
|
│ │
|
||||||
|
┌───────────────▼────────────────────────▼───────────────┐
|
||||||
|
│ Linux Kernel (wireguard.ko) │
|
||||||
|
└────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### A. RTNETLINK Link Lifecycle
|
||||||
|
- **Interface Creation**: Sends `RTM_NEWLINK` with link type `wireguard`.
|
||||||
|
- **Interface Deletion**: Sends `RTM_DELLINK` by interface index or name.
|
||||||
|
- **Interface State**: Toggles `IFF_UP` and `IFF_DOWN` flags without invoking `ip link set up/down`.
|
||||||
|
- **MTU Assignment**: Configures interface MTU directly in the `RTM_NEWLINK` netlink attributes.
|
||||||
|
|
||||||
|
### B. WireGuard Generic Netlink Protocol
|
||||||
|
- Resolves the dynamic Generic Netlink family ID for `"wireguard"`.
|
||||||
|
- **`WG_CMD_SET_DEVICE`**: Atomically configures the interface private key, UDP listen port, and peer list.
|
||||||
|
- **`WG_CMD_GET_DEVICE`**: Queries live kernel device state, active listen port, public key, peer public keys, endpoints, allowed IPs, last handshake timestamps, and transfer byte counters.
|
||||||
|
- **`WGDEVICE_F_REPLACE_PEERS`**: When syncing peers, setting this flag instructs the kernel to atomically replace all existing peers with the supplied desired set, removing stale peers in a single transaction.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Peer Cryptographic Synchronization
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
autonumber
|
||||||
|
participant Engine as NativeLinuxWireGuardEngine
|
||||||
|
participant Genl as Generic Netlink Socket
|
||||||
|
participant Kernel as Linux Kernel (wireguard.ko)
|
||||||
|
|
||||||
|
Engine->>Genl: Send WG_CMD_SET_DEVICE (Interface wg0, ReplacePeers=true)
|
||||||
|
Note over Engine,Genl: Encodes ListenPort, PrivateKey, Peer Array
|
||||||
|
Genl->>Kernel: Transmit Netlink Message
|
||||||
|
Kernel->>Kernel: Validate Keys, Bind UDP Port, Apply Peers
|
||||||
|
Kernel-->>Genl: NLMSG_ERROR (error=0 / Success)
|
||||||
|
Genl-->>Engine: Ok(())
|
||||||
|
|
||||||
|
Engine->>Genl: Send WG_CMD_GET_DEVICE (Interface wg0)
|
||||||
|
Genl->>Kernel: Query Live State
|
||||||
|
Kernel-->>Genl: Return Device Attributes & Peer Telemetry
|
||||||
|
Genl-->>Engine: Live Telemetry (Handshakes, Bytes Tx/Rx)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cryptographic Attribute Encoding:
|
||||||
|
- **Keys**: 32-byte binary Curve25519 keys (`WGPEER_A_PUBLIC_KEY`, `WGPEER_A_PRESHARED_KEY`).
|
||||||
|
- **Allowed IPs**: Nested attributes (`WGALLOWEDIP_A_FAMILY`, `WGALLOWEDIP_A_IPADDR`, `WGALLOWEDIP_A_CIDR_MASK`).
|
||||||
|
- **Endpoint**: `sockaddr_in` (IPv4) or `sockaddr_in6` (IPv6) socket address structures.
|
||||||
|
- **Persistent Keepalive**: Interval in seconds (`WGPEER_A_PERSISTENT_KEEPALIVE_INTERVAL`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Telemetry & Handshake Monitoring
|
||||||
|
|
||||||
|
The engine queries live kernel transfer statistics without writing temporary files:
|
||||||
|
- **`last_handshake_at`**: Calculated from `WGPEER_A_LAST_HANDSHAKE_TIME` (seconds and nanoseconds since UNIX epoch).
|
||||||
|
- **`rx_bytes` / `tx_bytes`**: 64-bit byte counters (`WGPEER_A_RX_BYTES`, `WGPEER_A_TX_BYTES`).
|
||||||
|
- **`endpoint`**: Actual remote socket address learned dynamically by the kernel through authenticated roaming.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Security & Memory Safety Invariants
|
||||||
|
|
||||||
|
1. **Zero Subprocesses**: No calls to `wg`, `wg-quick`, or `ip`.
|
||||||
|
2. **Secret Redaction**: Private keys and preshared keys implement custom `std::fmt::Debug` formatters emitting `[REDACTED]`.
|
||||||
|
3. **Memory Scrubbing**: Sensitive cryptographic buffers are wrapped in types that zeroize memory upon drop.
|
||||||
|
4. **Linux Capability Boundary**: Requires `CAP_NET_ADMIN` to open Netlink route and generic sockets.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Non-Linux Platform Fallback
|
||||||
|
|
||||||
|
On non-Linux platforms (macOS, Windows), `nx9-wg` automatically switches to `SimulatedWireGuardEngine`. This allows frontend UI and CLI development on local workstations while preserving the exact same `WireGuardEngine` trait interface.
|
||||||
@@ -0,0 +1,91 @@
|
|||||||
|
# Native Linux nftables Engine (`NativeLinuxNftablesEngine`)
|
||||||
|
|
||||||
|
The `NativeLinuxNftablesEngine` manages Linux firewall filtering and Network Address Translation (NAT) via direct in-process interaction with `libnftables.so.1` and the Linux Netfilter Netlink subsystem.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Protocol Architecture & In-Process Netfilter Binding
|
||||||
|
|
||||||
|
`nx9-wg` uses `libnftables` in-process C-ABI FFI via `NftContext` to execute atomic transaction batches without spawning the `nft` or `iptables` CLI utilities:
|
||||||
|
|
||||||
|
```
|
||||||
|
┌────────────────────────────────────────────────────────┐
|
||||||
|
│ NativeLinuxNftablesEngine │
|
||||||
|
└───────────────────────────┬────────────────────────────┘
|
||||||
|
│
|
||||||
|
In-Process FFI Transactions
|
||||||
|
via libnftables (NftContext)
|
||||||
|
│
|
||||||
|
┌───────────────────────────▼────────────────────────────┐
|
||||||
|
│ Netfilter Subsystem (table inet nx9_wg) │
|
||||||
|
└────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Table Scoping & Multi-Tenant Host Isolation
|
||||||
|
|
||||||
|
To prevent breaking container networks, hypervisors, or external security tools, `nx9-wg` enforces strict table isolation:
|
||||||
|
|
||||||
|
### A. Dedicated Table Namespace: `table inet nx9_wg`
|
||||||
|
All chains, sets, rules, and NAT masquerade policies are strictly contained inside `table inet nx9_wg`.
|
||||||
|
|
||||||
|
### B. Zero Table Interference
|
||||||
|
- **No Global Flushes**: `nx9-wg` NEVER executes `flush ruleset` or alters tables belonging to Docker (`table ip docker`), Kubernetes (`table inet cni`), libvirt (`table ip libvirt`), fail2ban, or UFW/Firewalld.
|
||||||
|
- **Ownership Verification**: Before modifying or inspecting rules, `nx9-wg` validates table family (`inet`) and name (`nx9_wg`). Any foreign table is rejected and untouched.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Ruleset Architecture & Chains
|
||||||
|
|
||||||
|
The generated `inet nx9_wg` table contains three dedicated chains:
|
||||||
|
|
||||||
|
```
|
||||||
|
table inet nx9_wg {
|
||||||
|
chain input {
|
||||||
|
type filter hook input priority filter; policy accept;
|
||||||
|
# Custom peer filter rules (e.g. UDP/TCP port restrictions)
|
||||||
|
}
|
||||||
|
|
||||||
|
chain forward {
|
||||||
|
type filter hook forward priority filter; policy accept;
|
||||||
|
# Inter-client routing and subnet forward policies
|
||||||
|
}
|
||||||
|
|
||||||
|
chain postrouting {
|
||||||
|
type nat hook postrouting priority srcnat; policy accept;
|
||||||
|
# Outbound NAT masquerade scoped strictly to managed WireGuard subnets
|
||||||
|
ip saddr { 10.100.0.0/24 } oifname != "wg0" masquerade
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Scoped NAT Masquerade Invariant
|
||||||
|
|
||||||
|
Outbound NAT masquerading is dynamically scoped exclusively to managed WireGuard client subnets:
|
||||||
|
1. **Subnet Deduplication**: Overlapping subnets are merged to prevent redundant rules.
|
||||||
|
2. **Interface Exclusion**: Traffic routing back into the WireGuard interface (`oifname != "wg0"`) is not masqueraded to preserve true source IPs for site-to-site tunnels.
|
||||||
|
3. **No Catch-All Masquerade**: `nx9-wg` never creates a catch-all `masquerade` rule that affects non-WireGuard traffic on the host.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Atomic Rule Compilation & Verification
|
||||||
|
|
||||||
|
The ruleset builder (`NftablesRulesetBuilder`) compiles desired database state into a single atomic Netfilter transaction buffer:
|
||||||
|
1. **Deterministic Rule Ordering**: Rules are sorted by priority index (ascending) to guarantee consistent packet evaluation.
|
||||||
|
2. **Protocol Grouping**: Supports `tcp`, `udp`, `tcp_udp`, `icmp`, and `any`.
|
||||||
|
3. **Port & Port-Range Parsing**: Supports single ports (`53`), comma-separated lists (`80,443`), and contiguous ranges (`8000-8100`).
|
||||||
|
4. **Validation via `nft_ctx_buffer_output`**: The compiled batch is verified by `libnftables` before committing to the kernel.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Runtime Dependency Qualification
|
||||||
|
|
||||||
|
On Linux systems, `nx9-wg` dynamically links against:
|
||||||
|
- `libnftables.so.1` (provided by `libnftables1` / `nftables` package)
|
||||||
|
- `libmnl.so.0`
|
||||||
|
- `libnftnl.so.11`
|
||||||
|
|
||||||
|
No runtime dependency on the `nft` CLI binary or shell scripts exists.
|
||||||
@@ -0,0 +1,107 @@
|
|||||||
|
# Reconciliation Engine & State Convergence Architecture
|
||||||
|
|
||||||
|
The `ReconciliationEngine` is the core architectural subsystem of `nx9-wg`. It implements a continuous, deterministic control loop ensuring the live Linux kernel state matches the authoritative desired state stored in SQLite.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. The Closed-Loop Reconciliation Cycle
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
subgraph SOT["1. Authoritative Source of Truth"]
|
||||||
|
DB[("SQLite Database\n(Desired State)")]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Drift["2. Drift Detection & Planning"]
|
||||||
|
Live["Query Live Kernel State\n(WireGuard Genl, RTNL, Netfilter, procfs)"]
|
||||||
|
Plan["Reconciliation Engine: plan()\n(Read-Only Deterministic Diff)"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Mutation["3. Serialized Apply & Convergence"]
|
||||||
|
Lock["Acquire Async Reconcile Mutex Lock"]
|
||||||
|
Apply["Execute Native Mutations\n(WireGuard SET_DEVICE, RTNL routes, nftables)"]
|
||||||
|
Verify["Post-Apply Verification Diff"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Outcome["4. Convergence Lifecycle State"]
|
||||||
|
Converged["Converged (In Sync)\nhas_drift = false"]
|
||||||
|
PartialFail["Partial Failure / Drift Remains\n(Descriptive Error & Safe State)"]
|
||||||
|
end
|
||||||
|
|
||||||
|
DB --> Plan
|
||||||
|
Live --> Plan
|
||||||
|
Plan -->|Drift Detected| Lock
|
||||||
|
Lock --> Apply
|
||||||
|
Apply --> Verify
|
||||||
|
Verify -->|Zero Differences| Converged
|
||||||
|
Verify -->|Errors Encountered| PartialFail
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Six Convergence Lifecycle States
|
||||||
|
|
||||||
|
Every reconciliation execution produces a structured `ReconciliationReport` modeling one of six Phase 6 states:
|
||||||
|
|
||||||
|
| Lifecycle State | Description | Action Required |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| **`Plan`** | Read-only calculation of drift between SQLite and kernel. | None (Dry run) |
|
||||||
|
| **`Applying`** | Native mutations actively dispatching across execution planes. | In progress |
|
||||||
|
| **`Verifying`** | Post-apply live query verifying kernel reflects desired state. | In progress |
|
||||||
|
| **`Converged`** | All desired resources verified present in kernel with zero drift. | None (Healthy) |
|
||||||
|
| **`PartialFailure`** | One or more execution planes failed during apply (e.g. EPERM). | Inspect diagnostic remediation hints |
|
||||||
|
| **`DriftRemains`** | Apply completed without crash, but verification detected remaining drift. | Re-evaluate desired configuration |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Subsystem Drift Detection Matrix
|
||||||
|
|
||||||
|
The `plan()` method calculates exact drift across 5 independent subsystems:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
pub struct ReconciliationPlan {
|
||||||
|
pub has_drift: bool,
|
||||||
|
pub interface_changes: usize,
|
||||||
|
pub peer_changes: usize,
|
||||||
|
pub route_changes: usize,
|
||||||
|
pub firewall_changes: usize,
|
||||||
|
pub forwarding_change: bool,
|
||||||
|
pub actions: Vec<PlannedAction>,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### A. WireGuard Interfaces
|
||||||
|
- Checks if desired interfaces (`Interface`) exist in kernel links via RTNETLINK.
|
||||||
|
- Detects missing interfaces, wrong MTU, or down status.
|
||||||
|
|
||||||
|
### B. Cryptographic Peers
|
||||||
|
- Queries live WireGuard device via `WG_CMD_GET_DEVICE`.
|
||||||
|
- Detects missing peers, changed public keys, altered allowed IPs, or mismatched persistent keepalive intervals.
|
||||||
|
|
||||||
|
### C. Kernel Routes
|
||||||
|
- Queries active kernel routes via `RTM_GETROUTE`.
|
||||||
|
- Evaluates exact equality on destination CIDR, gateway IP, interface name, and route metric.
|
||||||
|
|
||||||
|
### D. nftables Firewall & NAT
|
||||||
|
- Compares desired rules in SQLite against live rules in `table inet nx9_wg`.
|
||||||
|
- Detects missing rules, priority shifts, or altered NAT masquerade subnet policies.
|
||||||
|
|
||||||
|
### E. IP Forwarding
|
||||||
|
- Inspects `/proc/sys/net/ipv4/ip_forward` and `/proc/sys/net/ipv6/conf/all/forwarding`.
|
||||||
|
- Flags drift if forwarding is disabled when VPN routing is configured.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Mutex Serialization & Concurrency Safety
|
||||||
|
|
||||||
|
Reconciliation mutations are protected by an asynchronous Mutex:
|
||||||
|
- **Zero Race Conditions**: CLI commands (`nx9-wg reconcile apply`), Web UI actions (`POST /api/v1/reconcile/apply`), and background periodic cron jobs cannot execute concurrent kernel mutations.
|
||||||
|
- **Read-Only Plan Concurrency**: Multiple callers can query `reconcile plan` simultaneously without blocking, as `plan()` performs read-only queries.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Restart Recovery & Multi-Cycle Idempotency
|
||||||
|
|
||||||
|
1. **Clean Cold-Start Recovery**: When `nx9-wg` starts or restarts, the background daemon queries the kernel, detects unapplied state from SQLite, and applies all interfaces, peers, routes, and firewall rules in one unified cycle.
|
||||||
|
2. **Idempotent Convergence**: Running `reconcile apply` multiple times in succession produces zero mutations (NOOP) once convergence is achieved.
|
||||||
|
3. **Telemetry Protection**: Live kernel telemetry (transfer bytes, handshake timestamps) is ingested into memory/events and NEVER overwrites authoritative desired configuration in SQLite.
|
||||||
@@ -0,0 +1,95 @@
|
|||||||
|
# Release Engineering & Packaging Reference
|
||||||
|
|
||||||
|
This document describes the release packaging, artifact verification, filesystem layout, systemd service hardening, and distribution model for `nx9-wg`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Release Packaging Pipeline
|
||||||
|
|
||||||
|
Release archives are generated using [`scripts/package-release.sh`](file:///home/sunil/Programs/nx9-wg/scripts/package-release.sh):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bash scripts/package-release.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### Packaging Outputs in `target/dist/`:
|
||||||
|
- `nx9-wg-v0.8.0-linux-x86_64.tar.gz` (Standard gzip archive)
|
||||||
|
- `nx9-wg-v0.8.0-linux-x86_64.tar.xz` (High-compression XZ archive)
|
||||||
|
- `nx9-wg-v0.8.0-linux-x86_64.sha256` (Cryptographic SHA-256 checksums)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Release Archive Contents
|
||||||
|
|
||||||
|
Every release archive contains everything required for a standalone, offline production deployment:
|
||||||
|
|
||||||
|
```
|
||||||
|
nx9-wg-v0.8.0-linux-x86_64/
|
||||||
|
├── nx9-wg (Native executable binary, mode 0755)
|
||||||
|
├── nx9-wg.service (Hardened systemd unit file, mode 0644)
|
||||||
|
├── config.example.toml (Production configuration template, mode 0644)
|
||||||
|
├── install.sh (Automated production installer, mode 0755)
|
||||||
|
├── uninstall.sh (Safe uninstallation script, mode 0755)
|
||||||
|
├── README.md (Primary project guide)
|
||||||
|
├── LICENSE-MIT (MIT License text)
|
||||||
|
├── LICENSE-APACHE (Apache 2.0 License text)
|
||||||
|
└── docs/ (Complete offline documentation suite)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Standalone Verification Invariant
|
||||||
|
|
||||||
|
Release packages must function completely independently of the source repository. When extracted into an isolated clean directory (`/tmp/nx9-release-verify...`):
|
||||||
|
- `nx9-wg version` outputs valid version, architecture, and platform strings.
|
||||||
|
- `nx9-wg --help` lists all available subcommands.
|
||||||
|
- `nx9-wg init` bootstraps the isolated SQLite database with WAL journals.
|
||||||
|
- `nx9-wg system health` verifies database integrity.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Production Filesystem Layout
|
||||||
|
|
||||||
|
```
|
||||||
|
/usr/local/bin/nx9-wg (0755 root:root - Binary)
|
||||||
|
/etc/nx9-wg/ (0750 root:root - Configuration Directory)
|
||||||
|
├── config.toml (0640 root:root - Main Configuration File)
|
||||||
|
└── nx9-wg.env (0600 root:root - Optional Environment Secrets)
|
||||||
|
/var/lib/nx9-wg/ (0700 root:root - State & Database Directory)
|
||||||
|
├── nx9-wg.db (0600 root:root - Authoritative SQLite Database)
|
||||||
|
├── nx9-wg.db-wal (0600 root:root - Write-Ahead Log Journal)
|
||||||
|
├── admin-password (0600 root:root - Generated Initial Password)
|
||||||
|
└── backups/ (0700 root:root - Database Backup Archives)
|
||||||
|
/var/log/nx9-wg/ (0750 root:root - Operational Logs)
|
||||||
|
/etc/systemd/system/
|
||||||
|
└── nx9-wg.service (0644 root:root - Systemd Service Unit)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Systemd Security Sandboxing
|
||||||
|
|
||||||
|
The production service unit (`nx9-wg.service`) enforces modern Linux security directives:
|
||||||
|
|
||||||
|
- **Capabilities**: `CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE` & `AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE`.
|
||||||
|
- **Filesystem**: `ProtectSystem=strict`, `ProtectHome=true`, `PrivateTmp=true`.
|
||||||
|
- **System Isolation**: `ProtectControlGroups=true`, `RestrictSUIDSGID=true`, `LockPersonality=true`.
|
||||||
|
- **Socket Domains**: `RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK`.
|
||||||
|
- **Directory Lifecycle**: `StateDirectory=nx9-wg`, `ConfigurationDirectory=nx9-wg`, `LogsDirectory=nx9-wg`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Upgrade and Rollback Sequence
|
||||||
|
|
||||||
|
### Mandatory Upgrade Flow
|
||||||
|
1. **Pre-Upgrade Backup**: `nx9-wg backup create --description "Pre-upgrade checkpoint"`
|
||||||
|
2. **Stop Service**: `sudo systemctl stop nx9-wg`
|
||||||
|
3. **Install Binary**: `sudo install -m 0755 nx9-wg /usr/local/bin/nx9-wg`
|
||||||
|
4. **Start Service**: `sudo systemctl start nx9-wg` (Schema migrations run automatically upon startup)
|
||||||
|
5. **Verify State**: `nx9-wg reconcile plan` & `nx9-wg system health`
|
||||||
|
|
||||||
|
### Rollback Flow
|
||||||
|
1. **Stop Service**: `sudo systemctl stop nx9-wg`
|
||||||
|
2. **Revert Binary**: `sudo install -m 0755 nx9-wg-old /usr/local/bin/nx9-wg`
|
||||||
|
3. **Restore Database**: `nx9-wg backup restore <BACKUP_ID>`
|
||||||
|
4. **Start Service**: `sudo systemctl start nx9-wg`
|
||||||
+50
-22
@@ -1,43 +1,71 @@
|
|||||||
# Security Model and Best Practices
|
# Security Model, Privilege Architecture & Best Practices
|
||||||
|
|
||||||
`nx9-wg` implements a strict, self-hosted, fail-closed security architecture.
|
`nx9-wg` is designed with a strict, defense-in-depth, fail-closed security architecture tailored for self-hosted sovereign network infrastructure.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 1. Single Administrator Identity
|
## 1. Single Administrator Identity Model
|
||||||
|
|
||||||
- **Fixed Database Identity**: The administrative record in SQLite is locked with `CHECK (id = 1)`.
|
- **Database-Level Constraint**: The administrative record in SQLite is locked with `CHECK (id = 1)`.
|
||||||
- **No RBAC or Multi-Tenancy**: Eliminates attack surface from privilege escalation, permission bypasses, or broken object-level authorization.
|
- **Zero Multi-Tenancy / RBAC Attack Surface**: Eliminates privilege escalation, role confusion, and broken object-level authorization vulnerabilities.
|
||||||
- **Argon2id Password Hashing**: State-of-the-art memory-hard password derivation (`argon2id`). Plaintext passwords are never stored in memory longer than verification duration and never written to disk or logs.
|
- **Argon2id Password Hashing**: State-of-the-art memory-hard password derivation (`argon2id`). Passwords are never stored in plaintext, never logged, and never included in error responses.
|
||||||
|
- **One-Time Credential Delivery**: Generated passwords and raw API tokens are displayed exactly once upon creation (or written to explicit 0600-permission files) and cannot be recovered from the database.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 2. Token and Session Security
|
## 2. API Token and Session Architecture
|
||||||
|
|
||||||
- **Hashed API Tokens**: API tokens use the `nx9_<base64>` format. Only the SHA-256 cryptographic digest of the token is persisted in SQLite. Compromise of the database does not reveal plaintext API tokens.
|
- **Cryptographically Hashed Tokens**: API tokens follow the format `nx9_<uuid>_<random>`. Only the SHA-256 digest of the token (`token_hash`) is stored in SQLite. Database exfiltration will not compromise raw API tokens.
|
||||||
- **Global Session Invalidation**: When the administrator changes their password, all active sessions across all devices are immediately invalidated in SQLite.
|
- **Global Session Invalidation**: Changing the administrator password automatically invalidates all active browser sessions across all devices.
|
||||||
- **HttpOnly Cookies**: Session tokens sent to browsers use `HttpOnly`, `SameSite=Strict`, and `Secure` (when TLS is active).
|
- **Secure Cookie Flags**: Session cookies use `HttpOnly`, `SameSite=Strict`, and `Path=/`.
|
||||||
|
- **Brute-Force Rate Limiting**: Exponential backoff and IP-based rate limiting (5 failed attempts per 15-minute sliding window triggers `HTTP 429 Too Many Requests`).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 3. Brute-Force Rate Limiting
|
## 3. Filesystem Permissions Matrix
|
||||||
|
|
||||||
- `nx9-wg` maintains an append-only tracking log of login attempts in SQLite.
|
| Path | Standard Owner | File Mode | Purpose / Security Scope |
|
||||||
- If more than 5 failed authentication attempts originate from the same IP address within a 15-minute sliding window, subsequent login requests are rejected with `HTTP 429 Too Many Requests`.
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| `/usr/local/bin/nx9-wg` | `root:root` | `0755` | Executable binary |
|
||||||
|
| `/etc/nx9-wg/` | `root:root` | `0750` | Configuration directory |
|
||||||
|
| `/etc/nx9-wg/config.toml` | `root:root` | `0640` | Production configuration file |
|
||||||
|
| `/var/lib/nx9-wg/` | `root:root` | `0700` | Working directory and SQLite database storage |
|
||||||
|
| `/var/lib/nx9-wg/nx9-wg.db` | `root:root` | `0600` | Authoritative SQLite database with WAL journals |
|
||||||
|
| `/var/lib/nx9-wg/backups/` | `root:root` | `0700` | Atomic SQLite database snapshots and checksum manifests |
|
||||||
|
| `/var/lib/nx9-wg/admin-password`| `root:root` | `0600` | Initial generated password file |
|
||||||
|
| `/var/log/nx9-wg/` | `root:root` | `0750` | Operational logs (if file logging enabled) |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 4. Secret Handling and Memory Safety
|
## 4. Zero Subprocess Execution Guarantee
|
||||||
|
|
||||||
- **Redacted Debug Outputs**: Types holding sensitive material (`WireGuardPrivateKey`, `WireGuardPresharedKey`, `Admin`, `ApiToken`) implement custom `std::fmt::Debug` formatters outputting `[REDACTED]`.
|
`nx9-wg` strictly forbids external subprocess execution in production:
|
||||||
- **No Plaintext Logging**: Secrets are strictly excluded from structured `tracing` event spans.
|
- **No `std::process::Command` / `tokio::process`**: Eliminates command injection, shell escaping vulnerabilities, and PATH hijack risks.
|
||||||
|
- **No External CLI Dependencies**: Does not shell out to `wg`, `ip`, `nft`, `iptables`, `sysctl`, or `bash`.
|
||||||
|
- **Direct Kernel Communication**: Communicates via native Linux Netlink sockets (RTNETLINK and WireGuard Generic Netlink) and direct in-process `libnftables` Netfilter bindings.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 5. Audit Logging
|
## 5. nftables Scoping & Firewall Isolation
|
||||||
|
|
||||||
Every state-changing operation records an append-only audit event:
|
- **Table Isolation**: All rules and chains are strictly confined to `table inet nx9_wg`.
|
||||||
- Authentication (`Login`, `Logout`, `LoginFailed`)
|
- **Zero Interference**: `nx9-wg` never flushes or modifies external tables created by Docker, Kubernetes, systemd-networkd, or host firewalls.
|
||||||
- Credential Lifecycle (`PasswordChange`, `TotpChange`, `ApiTokenCreate`, `ApiTokenRevoke`)
|
- **Deterministic Priority Rules**: Chains and rules are ordered deterministically by priority index to prevent rule shadowing or accidental packet leaks.
|
||||||
- Network & WireGuard (`InterfaceCreate`, `PeerCreate`, `PeerRotateKeys`, `RouteCreate`, `FirewallCreate`)
|
|
||||||
- System Operations (`BackupCreate`, `BackupRestore`, `ReconciliationRun`)
|
---
|
||||||
|
|
||||||
|
## 6. Secret Redaction & Memory Safety
|
||||||
|
|
||||||
|
- Custom `std::fmt::Debug` implementations enforce `[REDACTED]` for `WireGuardPrivateKey`, `WireGuardPresharedKey`, `Admin`, and `ApiToken`.
|
||||||
|
- Web UI and REST API responses redact private keys and token hashes.
|
||||||
|
- CLI status output strictly redacts sensitive hashes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Append-Only Security Audit Logging
|
||||||
|
|
||||||
|
Every state mutation records an append-only audit event with timestamp, actor, IP address, event type, and context metadata:
|
||||||
|
- Authentication events (`Login`, `Logout`, `LoginFailed`)
|
||||||
|
- Credential modifications (`PasswordChange`, `ApiTokenCreate`, `ApiTokenRevoke`)
|
||||||
|
- WireGuard & Network configurations (`InterfaceCreate`, `PeerCreate`, `RouteCreate`, `FirewallCreate`)
|
||||||
|
- System operations (`BackupCreate`, `BackupRestore`, `ReconciliationRun`)
|
||||||
@@ -0,0 +1,46 @@
|
|||||||
|
# Quality Assurance & Testing Strategy
|
||||||
|
|
||||||
|
`nx9-wg` enforces a comprehensive, multi-tiered verification strategy designed to guarantee code correctness, memory safety, failure semantics, and secret protection.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Test Suite Summary & Quality Gates
|
||||||
|
|
||||||
|
| Tier | Test Suite / Check | Scope & Execution Target | Current Status |
|
||||||
|
| :--- | :--- | :--- | :---: |
|
||||||
|
| **Tier 1** | Code Formatting | `cargo fmt --all -- --check` | **PASS** (Zero diffs) |
|
||||||
|
| **Tier 2** | Type & Borrow Check | `cargo check --workspace` | **PASS** (Zero errors) |
|
||||||
|
| **Tier 3** | Workspace Unit Tests | `cargo test --workspace` | **PASS** (**91 / 91 passed**) |
|
||||||
|
| **Tier 4** | Clippy Linter Check | `cargo clippy --workspace --all-targets --all-features -- -D warnings` | **PASS** (Zero warnings) |
|
||||||
|
| **Tier 5** | Release Compilation | `cargo build --release` | **PASS** (Clean build) |
|
||||||
|
| **Tier 6** | Comprehensive CLI Suite | `LIVE=0 bash scripts/test-cli-comprehensive.sh` | **PASS** (**203 passed** / 7 skipped) |
|
||||||
|
| **Tier 7** | Native Integration Suite | `LIVE=0 bash scripts/test-native-integration.sh` | **PASS** (**19 passed** / 1 skipped) |
|
||||||
|
| **Tier 8** | Dedicated Live Kernel Suite | `LIVE=0 bash scripts/test-live-kernel.sh` | **PASS** (**23 passed** / 1 skipped) |
|
||||||
|
| **Tier 9** | Subprocess Safety Audit | Automated source scan for `Command::new` | **PASS** (Zero subprocesses) |
|
||||||
|
| **Tier 10** | Secret Leakage Audit | Automated scan for plaintext credentials | **PASS** (Zero secrets leaked) |
|
||||||
|
| **Tier 11** | Release Package Check | Standalone archive extraction & verification | **PASS** (Independent execution) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. SAFE Mode (`LIVE=0`) vs Real-Kernel Mode (`LIVE=1`)
|
||||||
|
|
||||||
|
To guarantee safety when developing on unprivileged developer workstations:
|
||||||
|
|
||||||
|
### SAFE Mode (`LIVE=0` — Default)
|
||||||
|
- Uses real in-memory SQLite stores and dry-run Netlink message builders.
|
||||||
|
- Validates CLI parsers, JSON/YAML/CSV output formatters, route equality rules, and read-only reconciliation planning.
|
||||||
|
- Automatically skips live kernel mutation steps that require root or `CAP_NET_ADMIN`.
|
||||||
|
|
||||||
|
### Real-Kernel Mode (`LIVE=1` — Dedicated Host Only)
|
||||||
|
- Requires `root` or `CAP_NET_ADMIN` in a dedicated, disposable Linux VM.
|
||||||
|
- Creates real kernel WireGuard interfaces (e.g. `nx9t...`), attaches IPv4/IPv6 addresses, installs routes in the kernel routing table, configures `table inet nx9_wg` in Netfilter, and validates live handshake telemetry.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Automated Subprocess & Secret Audits
|
||||||
|
|
||||||
|
Every verification run executes strict source-level security audits:
|
||||||
|
|
||||||
|
1. **Subprocess Audit**: Confirms zero instances of `std::process::Command`, `tokio::process::Command`, `Command::new`, or shell scripts in production Rust crates.
|
||||||
|
2. **Secret Redaction Audit**: Confirms that password hashes, private keys, preshared keys, and token hashes are never printed in human-readable status outputs or logs.
|
||||||
|
3. **Environment Audit**: Confirms that all recognized environment variables strictly observe the `NX9_WG_*` namespace.
|
||||||
+59
@@ -0,0 +1,59 @@
|
|||||||
|
# Web User Interface (SPA) Architecture & Route Reference
|
||||||
|
|
||||||
|
`nx9-wg` embeds a complete, zero-dependency HTML5/CSS/JavaScript Single Page Application (SPA) directly inside the Rust binary.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Frontend Architecture & Design System
|
||||||
|
|
||||||
|
- **Zero External Toolchains**: Built entirely in standard HTML5, CSS3, and modern Vanilla ES6+ JavaScript. No Node.js, npm, Webpack, Vite, React, or external CDN dependencies.
|
||||||
|
- **Embedded Static Assets**: HTML, CSS, and JavaScript are bundled into the binary at compile time via `include_str!()` and served from memory.
|
||||||
|
- **Unified Design Tokens**: Custom CSS variable design system (`nx9-wg-ui/src/css.rs`) providing Dark and Light themes with persistent `localStorage` preference.
|
||||||
|
- **Responsive Layout**: Mobile-first responsive layout with side-drawer navigation and `@media (max-width: 768px)` breakpoints.
|
||||||
|
- **Live WebSocket Event Stream**: Connects to `ws://<host>/api/v1/ws` for reactive dashboard, peer handshake, and reconciliation updates without polling.
|
||||||
|
- **Presentation-Only Separation**: The UI contains presentation and client routing logic only; all business validation, allocation, and state authority reside in the backend REST API and SQLite.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Complete Route Inventory
|
||||||
|
|
||||||
|
| Hash Route | Navigation Label | Purpose & Operational Features |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| `#dashboard` | **Dashboard** | System status, uptime, interface/peer counts, diagnostics health, and reconciliation status cards. |
|
||||||
|
| `#interfaces` | **Interfaces** | List WireGuard interfaces, "+ Create Interface" modal, enable/disable toggle, and delete interface. |
|
||||||
|
| `#peers` | **Peers** | Enrolled peer table with real-time handshakes, status filter, "+ Add Peer" modal with MTU profile resolution, client configuration export, and live SVG QR rendering. |
|
||||||
|
| `#networks` | **Networks** | Subnet network ranges, CIDR masks, "+ Create Network" modal, and deletion. |
|
||||||
|
| `#routes` | **Routes** | Routing table entries, gateway assignments, "+ Create Route" modal, and deletion. |
|
||||||
|
| `#firewall` | **Firewall** | nftables packet filtering rules in `table inet nx9_wg`, "+ Create Rule" modal, priority ordering, and enable/disable toggle. |
|
||||||
|
| `#nat` | **NAT & Masquerade** | Outbound NAT masquerade status card, active masqueraded subnet list, and instant toggle. |
|
||||||
|
| `#forwarding` | **IP Forwarding** | Kernel sysctl `/proc/sys/net/ipv4/ip_forward` packet forwarding status and toggle. |
|
||||||
|
| `#reconciliation` | **Reconciliation** | Real-time kernel drift overview, planned execution actions table, and interactive "Run Reconcile (Apply)" button. |
|
||||||
|
| `#diagnostics` | **Diagnostics** | Automated health inspection across all 9 subsystems (`system`, `network`, `wireguard`, `peer`, `routing`, `forwarding`, `firewall`, `nat`, `reconciliation`) with remediation hints. |
|
||||||
|
| `#live-state` | **Live State** | Live Linux Netlink kernel telemetry, active WireGuard interfaces, and live routing table entries. |
|
||||||
|
| `#settings` | **Settings** | Appliance key-value parameters table and danger zone reset controls. |
|
||||||
|
| `#backups` | **Backups** | Atomic SQLite database backup snapshots list, "+ Create Backup Snapshot" button, and direct `.db` download. |
|
||||||
|
| `#audit` | **Audit Log** | Append-only security and administrative audit trail with actor, IP, timestamp, and metadata. |
|
||||||
|
| `#administrator` | **Administrator** | Admin account verification, "Change Password" modal, and "+ Generate API Token" modal with one-time raw secret copy. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Interactive Modals & Client Transport Profiles
|
||||||
|
|
||||||
|
### A. Client Profile & MTU Resolution Modal
|
||||||
|
When enrolling a new peer (`#peers`), the modal automatically queries `/api/v1/client-profiles/resolve` based on selected Device (Android, iOS, Linux, Windows, macOS) and Connection (Mobile Cellular 4G/5G, Wi-Fi, Wired Ethernet) to determine optimal MTU (1280 vs 1360 vs 1420) and persistent keepalive (25s).
|
||||||
|
|
||||||
|
### B. Client Export & QR Code Modal
|
||||||
|
Displays both:
|
||||||
|
1. **Interactive Vector QR Code**: Inline SVG rendering for scanning directly with the official WireGuard mobile app.
|
||||||
|
2. **Downloadable `.conf` File**: Standard WireGuard client configuration file formatted for instant download or clipboard copy.
|
||||||
|
|
||||||
|
### C. One-Time API Token Delivery Modal
|
||||||
|
Generates a new API token, calculates its SHA-256 digest for SQLite storage, and presents the raw token string once in an interactive modal with a copy button.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Error Handling & Session Recovery
|
||||||
|
|
||||||
|
- **HTTP 401 Interception**: When a session expires or credentials are revoked, the client `api()` helper automatically transitions to the login view (`renderLoginPage()`).
|
||||||
|
- **Input Validation**: Modals enforce client-side form validation before submitting requests to the backend.
|
||||||
|
- **Graceful Error Alerts**: Backend API error messages are formatted clearly in alert dialogs.
|
||||||
+19
-6
@@ -9,10 +9,11 @@ Type=simple
|
|||||||
User=root
|
User=root
|
||||||
Group=root
|
Group=root
|
||||||
|
|
||||||
# Environment configuration file
|
# Environment configuration file (optional override)
|
||||||
EnvironmentFile=-/etc/nx9-wg/nx9-wg.env
|
EnvironmentFile=-/etc/nx9-wg/nx9-wg.env
|
||||||
|
|
||||||
# Executable location and invocation
|
# Working directory and execution
|
||||||
|
WorkingDirectory=/var/lib/nx9-wg
|
||||||
ExecStart=/usr/local/bin/nx9-wg --config /etc/nx9-wg/config.toml --data-dir /var/lib/nx9-wg serve
|
ExecStart=/usr/local/bin/nx9-wg --config /etc/nx9-wg/config.toml --data-dir /var/lib/nx9-wg serve
|
||||||
|
|
||||||
# Process management and restart policy
|
# Process management and restart policy
|
||||||
@@ -21,18 +22,30 @@ RestartSec=5s
|
|||||||
KillMode=process
|
KillMode=process
|
||||||
TimeoutStopSec=15s
|
TimeoutStopSec=15s
|
||||||
|
|
||||||
# Security Hardening & Linux Capability Bounds
|
# Linux Capabilities for Native Netlink & Port Binding
|
||||||
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
|
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
|
||||||
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
|
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
|
||||||
NoNewPrivileges=true
|
NoNewPrivileges=true
|
||||||
|
|
||||||
# Filesystem Isolation
|
# Sandboxing and System Hardening
|
||||||
ProtectSystem=strict
|
ProtectSystem=strict
|
||||||
ProtectHome=true
|
ProtectHome=true
|
||||||
PrivateTmp=true
|
PrivateTmp=true
|
||||||
ProtectKernelTunables=false
|
|
||||||
ProtectControlGroups=true
|
ProtectControlGroups=true
|
||||||
ReadWritePaths=/var/lib/nx9-wg /etc/nx9-wg /var/log
|
RestrictSUIDSGID=true
|
||||||
|
LockPersonality=true
|
||||||
|
MemoryDenyWriteExecute=false
|
||||||
|
RestrictRealtime=true
|
||||||
|
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
|
||||||
|
|
||||||
|
# Kernel procfs IP forwarding management requires procfs writes
|
||||||
|
ProtectKernelTunables=false
|
||||||
|
|
||||||
|
# Systemd managed state, configuration, and log directories
|
||||||
|
StateDirectory=nx9-wg
|
||||||
|
ConfigurationDirectory=nx9-wg
|
||||||
|
LogsDirectory=nx9-wg
|
||||||
|
ReadWritePaths=/var/lib/nx9-wg /etc/nx9-wg /var/log/nx9-wg /proc/sys/net
|
||||||
|
|
||||||
# Resource Limits
|
# Resource Limits
|
||||||
LimitNOFILE=65536
|
LimitNOFILE=65536
|
||||||
|
|||||||
@@ -0,0 +1,205 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
# ==============================================================================
|
||||||
|
# nx9-wg Production Installer
|
||||||
|
# ==============================================================================
|
||||||
|
# Installs nx9-wg binary, systemd service, configuration template, and
|
||||||
|
# state directories with strict Linux filesystem permissions.
|
||||||
|
# ==============================================================================
|
||||||
|
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||||
|
RELEASE_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||||
|
|
||||||
|
# Target installation paths
|
||||||
|
BIN_DIR="/usr/local/bin"
|
||||||
|
CONF_DIR="/etc/nx9-wg"
|
||||||
|
DATA_DIR="/var/lib/nx9-wg"
|
||||||
|
BACKUP_DIR="${DATA_DIR}/backups"
|
||||||
|
LOG_DIR="/var/log/nx9-wg"
|
||||||
|
SYSTEMD_DIR="/etc/systemd/system"
|
||||||
|
|
||||||
|
DRY_RUN=0
|
||||||
|
NO_SERVICE=0
|
||||||
|
NO_INIT=0
|
||||||
|
|
||||||
|
usage() {
|
||||||
|
cat <<EOF
|
||||||
|
nx9-wg Production Installer
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
sudo bash install.sh [OPTIONS]
|
||||||
|
|
||||||
|
Options:
|
||||||
|
--dry-run Validate environment and simulate installation actions
|
||||||
|
--no-service Skip systemd unit installation and service enablement
|
||||||
|
--no-init Skip initial administrator account generation
|
||||||
|
-h, --help Show this help message
|
||||||
|
EOF
|
||||||
|
exit 0
|
||||||
|
}
|
||||||
|
|
||||||
|
while [[ $# -gt 0 ]]; do
|
||||||
|
case "$1" in
|
||||||
|
--dry-run)
|
||||||
|
DRY_RUN=1
|
||||||
|
shift
|
||||||
|
;;
|
||||||
|
--no-service)
|
||||||
|
NO_SERVICE=1
|
||||||
|
shift
|
||||||
|
;;
|
||||||
|
--no-init)
|
||||||
|
NO_INIT=1
|
||||||
|
shift
|
||||||
|
;;
|
||||||
|
-h|--help)
|
||||||
|
usage
|
||||||
|
;;
|
||||||
|
*)
|
||||||
|
echo "Unknown option: $1" >&2
|
||||||
|
usage
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
done
|
||||||
|
|
||||||
|
log() {
|
||||||
|
echo -e "\033[1;34m[INFO]\033[0m $*"
|
||||||
|
}
|
||||||
|
|
||||||
|
warn() {
|
||||||
|
echo -e "\033[1;33m[WARN]\033[0m $*"
|
||||||
|
}
|
||||||
|
|
||||||
|
error() {
|
||||||
|
echo -e "\033[1;31m[ERROR]\033[0m $*" >&2
|
||||||
|
exit 1
|
||||||
|
}
|
||||||
|
|
||||||
|
run_cmd() {
|
||||||
|
if [[ "${DRY_RUN}" -eq 1 ]]; then
|
||||||
|
echo " [DRY-RUN] $*"
|
||||||
|
else
|
||||||
|
"$@"
|
||||||
|
fi
|
||||||
|
}
|
||||||
|
|
||||||
|
# 1. Privilege Verification
|
||||||
|
if [[ "${EUID}" -ne 0 && "${DRY_RUN}" -eq 0 ]]; then
|
||||||
|
error "This installer must be run as root (or via sudo)."
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 2. Host Architecture & Kernel Verification
|
||||||
|
ARCH="$(uname -m)"
|
||||||
|
OS="$(uname -s)"
|
||||||
|
|
||||||
|
if [[ "${OS}" != "Linux" ]]; then
|
||||||
|
error "nx9-wg production deployment requires Linux (detected: ${OS})."
|
||||||
|
fi
|
||||||
|
|
||||||
|
log "Detected platform: ${OS} (${ARCH})"
|
||||||
|
|
||||||
|
# 3. Locate nx9-wg release binary
|
||||||
|
BIN_SOURCE=""
|
||||||
|
if [[ -f "${SCRIPT_DIR}/nx9-wg" ]]; then
|
||||||
|
BIN_SOURCE="${SCRIPT_DIR}/nx9-wg"
|
||||||
|
elif [[ -f "${RELEASE_ROOT}/nx9-wg" ]]; then
|
||||||
|
BIN_SOURCE="${RELEASE_ROOT}/nx9-wg"
|
||||||
|
elif [[ -f "${RELEASE_ROOT}/target/release/nx9-wg" ]]; then
|
||||||
|
BIN_SOURCE="${RELEASE_ROOT}/target/release/nx9-wg"
|
||||||
|
else
|
||||||
|
error "Could not find nx9-wg binary in package or target/release."
|
||||||
|
fi
|
||||||
|
|
||||||
|
log "Using binary source: ${BIN_SOURCE}"
|
||||||
|
|
||||||
|
# 4. Dependency Checks
|
||||||
|
log "Verifying runtime dependencies..."
|
||||||
|
if ! command -v ldd >/dev/null 2>&1; then
|
||||||
|
warn "ldd utility not found, skipping dynamic link check."
|
||||||
|
else
|
||||||
|
if ldd "${BIN_SOURCE}" 2>&1 | grep -q "not found"; then
|
||||||
|
warn "Missing dynamic dependencies detected in ldd check:"
|
||||||
|
ldd "${BIN_SOURCE}" | grep "not found" || true
|
||||||
|
warn "Please ensure libnftables.so.1 is installed on this system."
|
||||||
|
else
|
||||||
|
log "All dynamic linkages resolved successfully."
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 5. Create Filesystem Layout
|
||||||
|
log "Creating filesystem layout with secure permissions..."
|
||||||
|
run_cmd install -d -m 0750 "${CONF_DIR}"
|
||||||
|
run_cmd install -d -m 0700 "${DATA_DIR}"
|
||||||
|
run_cmd install -d -m 0700 "${BACKUP_DIR}"
|
||||||
|
run_cmd install -d -m 0750 "${LOG_DIR}"
|
||||||
|
|
||||||
|
# 6. Install Binary
|
||||||
|
log "Installing binary to ${BIN_DIR}/nx9-wg..."
|
||||||
|
run_cmd install -m 0755 "${BIN_SOURCE}" "${BIN_DIR}/nx9-wg"
|
||||||
|
|
||||||
|
# 7. Install Configuration Template
|
||||||
|
CONF_SOURCE=""
|
||||||
|
if [[ -f "${RELEASE_ROOT}/config.example.toml" ]]; then
|
||||||
|
CONF_SOURCE="${RELEASE_ROOT}/config.example.toml"
|
||||||
|
elif [[ -f "${SCRIPT_DIR}/config.example.toml" ]]; then
|
||||||
|
CONF_SOURCE="${SCRIPT_DIR}/config.example.toml"
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [[ -f "${CONF_DIR}/config.toml" ]]; then
|
||||||
|
log "Existing configuration found at ${CONF_DIR}/config.toml (preserving)."
|
||||||
|
else
|
||||||
|
if [[ -n "${CONF_SOURCE}" && -f "${CONF_SOURCE}" ]]; then
|
||||||
|
log "Installing configuration template to ${CONF_DIR}/config.toml..."
|
||||||
|
run_cmd install -m 0640 "${CONF_SOURCE}" "${CONF_DIR}/config.toml"
|
||||||
|
else
|
||||||
|
warn "Configuration template config.example.toml not found, skipping."
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 8. Bootstrap Initial Administrator (if not already initialized)
|
||||||
|
if [[ "${NO_INIT}" -eq 0 && "${DRY_RUN}" -eq 0 ]]; then
|
||||||
|
PW_FILE="${DATA_DIR}/admin-initial-password"
|
||||||
|
log "Checking administrator account initialization..."
|
||||||
|
if "${BIN_DIR}/nx9-wg" --config "${CONF_DIR}/config.toml" --data-dir "${DATA_DIR}" admin info >/dev/null 2>&1; then
|
||||||
|
log "Administrator account already initialized in database."
|
||||||
|
else
|
||||||
|
log "Initializing administrator account with secure random credentials..."
|
||||||
|
"${BIN_DIR}/nx9-wg" --config "${CONF_DIR}/config.toml" --data-dir "${DATA_DIR}" init --generate-password --write-password-file "${PW_FILE}" || true
|
||||||
|
if [[ -f "${PW_FILE}" ]]; then
|
||||||
|
chmod 0600 "${PW_FILE}"
|
||||||
|
log "Initial administrator password written to: ${PW_FILE} (mode 0600)"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 9. Install systemd Service
|
||||||
|
if [[ "${NO_SERVICE}" -eq 0 && -d "${SYSTEMD_DIR}" ]]; then
|
||||||
|
SERVICE_SOURCE=""
|
||||||
|
if [[ -f "${RELEASE_ROOT}/nx9-wg.service" ]]; then
|
||||||
|
SERVICE_SOURCE="${RELEASE_ROOT}/nx9-wg.service"
|
||||||
|
elif [[ -f "${SCRIPT_DIR}/nx9-wg.service" ]]; then
|
||||||
|
SERVICE_SOURCE="${SCRIPT_DIR}/nx9-wg.service"
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [[ -n "${SERVICE_SOURCE}" && -f "${SERVICE_SOURCE}" ]]; then
|
||||||
|
log "Installing systemd service unit to ${SYSTEMD_DIR}/nx9-wg.service..."
|
||||||
|
run_cmd install -m 0644 "${SERVICE_SOURCE}" "${SYSTEMD_DIR}/nx9-wg.service"
|
||||||
|
if command -v systemctl >/dev/null 2>&1 && [[ "${DRY_RUN}" -eq 0 ]]; then
|
||||||
|
log "Reloading systemd daemon..."
|
||||||
|
systemctl daemon-reload
|
||||||
|
log "Enabling and starting nx9-wg service..."
|
||||||
|
systemctl enable --now nx9-wg || warn "Could not start nx9-wg.service automatically."
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
warn "nx9-wg.service unit file not found, skipping service installation."
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
log "================================================================="
|
||||||
|
log "nx9-wg installation completed successfully!"
|
||||||
|
log " Binary: ${BIN_DIR}/nx9-wg"
|
||||||
|
log " Configuration: ${CONF_DIR}/config.toml"
|
||||||
|
log " Database & Data:${DATA_DIR}/nx9-wg.db"
|
||||||
|
log " Backups: ${BACKUP_DIR}"
|
||||||
|
log "================================================================="
|
||||||
@@ -0,0 +1,69 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
# ==============================================================================
|
||||||
|
# nx9-wg Production Release Packager
|
||||||
|
# ==============================================================================
|
||||||
|
# Generates self-contained, reproducible release archives (.tar.gz and .tar.xz)
|
||||||
|
# containing binary, service units, configuration templates, documentation,
|
||||||
|
# licenses, and installation scripts.
|
||||||
|
# ==============================================================================
|
||||||
|
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||||
|
ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
|
||||||
|
|
||||||
|
VERSION="$(grep -m 1 '^version = ' "${ROOT_DIR}/Cargo.toml" | cut -d '"' -f 2)"
|
||||||
|
ARCH="$(uname -m)"
|
||||||
|
OS="linux"
|
||||||
|
|
||||||
|
PACKAGE_NAME="nx9-wg-v${VERSION}-${OS}-${ARCH}"
|
||||||
|
DIST_DIR="${ROOT_DIR}/target/dist"
|
||||||
|
STAGE_DIR="${DIST_DIR}/${PACKAGE_NAME}"
|
||||||
|
|
||||||
|
echo "================================================================="
|
||||||
|
echo " Packaging nx9-wg Release: ${PACKAGE_NAME}"
|
||||||
|
echo "================================================================="
|
||||||
|
|
||||||
|
# 1. Ensure release binary is compiled
|
||||||
|
if [[ ! -f "${ROOT_DIR}/target/release/nx9-wg" ]]; then
|
||||||
|
echo "Building release binary..."
|
||||||
|
(cd "${ROOT_DIR}" && cargo build --release --bin nx9-wg)
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 2. Prepare staging directory
|
||||||
|
rm -rf "${STAGE_DIR}"
|
||||||
|
mkdir -p "${STAGE_DIR}/docs"
|
||||||
|
|
||||||
|
# 3. Copy release artifacts
|
||||||
|
echo "Copying release artifacts..."
|
||||||
|
install -m 0755 "${ROOT_DIR}/target/release/nx9-wg" "${STAGE_DIR}/nx9-wg"
|
||||||
|
install -m 0644 "${ROOT_DIR}/nx9-wg.service" "${STAGE_DIR}/nx9-wg.service"
|
||||||
|
install -m 0644 "${ROOT_DIR}/config.example.toml" "${STAGE_DIR}/config.example.toml"
|
||||||
|
install -m 0755 "${ROOT_DIR}/scripts/install.sh" "${STAGE_DIR}/install.sh"
|
||||||
|
install -m 0755 "${ROOT_DIR}/scripts/uninstall.sh" "${STAGE_DIR}/uninstall.sh"
|
||||||
|
install -m 0644 "${ROOT_DIR}/README.md" "${STAGE_DIR}/README.md"
|
||||||
|
install -m 0644 "${ROOT_DIR}/LICENSE-MIT" "${STAGE_DIR}/LICENSE-MIT"
|
||||||
|
install -m 0644 "${ROOT_DIR}/LICENSE-APACHE" "${STAGE_DIR}/LICENSE-APACHE"
|
||||||
|
|
||||||
|
# Copy documentation
|
||||||
|
cp -r "${ROOT_DIR}/docs/"* "${STAGE_DIR}/docs/"
|
||||||
|
|
||||||
|
# 4. Generate Archive Packages
|
||||||
|
echo "Creating .tar.gz archive..."
|
||||||
|
(cd "${DIST_DIR}" && tar -czf "${PACKAGE_NAME}.tar.gz" "${PACKAGE_NAME}")
|
||||||
|
|
||||||
|
echo "Creating .tar.xz archive..."
|
||||||
|
(cd "${DIST_DIR}" && tar -cJf "${PACKAGE_NAME}.tar.xz" "${PACKAGE_NAME}")
|
||||||
|
|
||||||
|
# 5. Generate Checksums
|
||||||
|
echo "Generating SHA256 checksums..."
|
||||||
|
(cd "${DIST_DIR}" && sha256sum "${PACKAGE_NAME}.tar.gz" "${PACKAGE_NAME}.tar.xz" > "${PACKAGE_NAME}.sha256")
|
||||||
|
|
||||||
|
# 6. Cleanup Staging Directory
|
||||||
|
rm -rf "${STAGE_DIR}"
|
||||||
|
|
||||||
|
echo "================================================================="
|
||||||
|
echo " Release Packaging Complete!"
|
||||||
|
echo " Archives located in ${DIST_DIR}:"
|
||||||
|
ls -lh "${DIST_DIR}/${PACKAGE_NAME}".*
|
||||||
|
echo "================================================================="
|
||||||
@@ -949,7 +949,8 @@ if [[ "$LIVE" == "1" ]]; then
|
|||||||
"${CLI[@]}" \
|
"${CLI[@]}" \
|
||||||
live \
|
live \
|
||||||
peer \
|
peer \
|
||||||
list
|
list \
|
||||||
|
wg0
|
||||||
|
|
||||||
run_test \
|
run_test \
|
||||||
"Live routes" \
|
"Live routes" \
|
||||||
|
|||||||
Executable
+403
@@ -0,0 +1,403 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
#
|
||||||
|
# ============================================================================
|
||||||
|
# nx9-wg — Phase 5 Dedicated LIVE Linux Kernel Verification Script
|
||||||
|
# ============================================================================
|
||||||
|
#
|
||||||
|
# PURPOSE
|
||||||
|
# -------
|
||||||
|
# Rigorous, real-kernel verification of the complete nx9-wg execution stack:
|
||||||
|
# 1. NativeLinuxWireGuardEngine (RTNETLINK + WireGuard Generic Netlink)
|
||||||
|
# 2. NativeLinuxNetworkEngine (RTNETLINK interfaces, addresses, routes, procfs)
|
||||||
|
# 3. NativeLinuxNftablesEngine (In-process libnftables / Netfilter Netlink)
|
||||||
|
# 4. SQLite authoritative desired state, drift detection, reconciliation,
|
||||||
|
# idempotency, and restart recovery.
|
||||||
|
#
|
||||||
|
# HARD SAFETY REQUIREMENTS
|
||||||
|
# ------------------------
|
||||||
|
# - Default mode is LIVE=0 (safe dry-run and simulated tests only).
|
||||||
|
# - LIVE=1 is required for real kernel mutations.
|
||||||
|
# - Requires Linux and root or effective CAP_NET_ADMIN capabilities.
|
||||||
|
# - Strict isolation: uses dedicated unique resource namespace (nx9t$$).
|
||||||
|
# - NEVER modifies default routes, Docker interfaces, host gateways, or
|
||||||
|
# unrelated nftables tables.
|
||||||
|
# - Complete pre-mutation baseline captured outside source tree.
|
||||||
|
# - Robust trap-based cleanup restoring baseline forwarding and cleaning only
|
||||||
|
# test-created resources.
|
||||||
|
# - Post-cleanup baseline comparison asserting zero unexpected host changes.
|
||||||
|
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 01 — Configuration & Environment
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
LIVE="${LIVE:-0}"
|
||||||
|
PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||||
|
BIN="${PROJECT_ROOT}/target/release/nx9-wg"
|
||||||
|
|
||||||
|
if [[ ! -x "${BIN}" ]]; then
|
||||||
|
BIN="${PROJECT_ROOT}/target/debug/nx9-wg"
|
||||||
|
fi
|
||||||
|
|
||||||
|
TEST_ID="nx9t$$"
|
||||||
|
TEST_ROOT="/tmp/nx9-wg-live-${TEST_ID}"
|
||||||
|
DATA_DIR="${TEST_ROOT}/data"
|
||||||
|
DB_PATH="${DATA_DIR}/nx9-wg.db"
|
||||||
|
BASELINE_DIR="${TEST_ROOT}/baseline"
|
||||||
|
PW_FILE="${TEST_ROOT}/admin_password.txt"
|
||||||
|
ALL_OUTPUT="${TEST_ROOT}/all_test_output.log"
|
||||||
|
|
||||||
|
PASS_COUNT=0
|
||||||
|
FAIL_COUNT=0
|
||||||
|
SKIP_COUNT=0
|
||||||
|
|
||||||
|
log_pass() {
|
||||||
|
echo " [PASS] $1"
|
||||||
|
PASS_COUNT=$((PASS_COUNT + 1))
|
||||||
|
}
|
||||||
|
|
||||||
|
log_fail() {
|
||||||
|
echo " [FAIL] $1"
|
||||||
|
FAIL_COUNT=$((FAIL_COUNT + 1))
|
||||||
|
}
|
||||||
|
|
||||||
|
log_skip() {
|
||||||
|
echo " [SKIP] $1 ($2)"
|
||||||
|
SKIP_COUNT=$((SKIP_COUNT + 1))
|
||||||
|
}
|
||||||
|
|
||||||
|
section() {
|
||||||
|
echo ""
|
||||||
|
echo "============================================================================"
|
||||||
|
echo " $1"
|
||||||
|
echo "============================================================================"
|
||||||
|
}
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# Trap-based Safe Cleanup
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
cleanup() {
|
||||||
|
echo ""
|
||||||
|
echo ">>> Running safe post-test cleanup..."
|
||||||
|
|
||||||
|
# 1. Restore sysctl forwarding state from baseline
|
||||||
|
if [[ -f "${BASELINE_DIR}/sysctl_ipv4_forward" ]]; then
|
||||||
|
orig_v4="$(cat "${BASELINE_DIR}/sysctl_ipv4_forward")"
|
||||||
|
if [[ -w /proc/sys/net/ipv4/ip_forward ]]; then
|
||||||
|
echo "${orig_v4}" > /proc/sys/net/ipv4/ip_forward 2>/dev/null || true
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
if [[ -f "${BASELINE_DIR}/sysctl_ipv6_forward" ]]; then
|
||||||
|
orig_v6="$(cat "${BASELINE_DIR}/sysctl_ipv6_forward")"
|
||||||
|
if [[ -w /proc/sys/net/ipv6/conf/all/forwarding ]]; then
|
||||||
|
echo "${orig_v6}" > /proc/sys/net/ipv6/conf/all/forwarding 2>/dev/null || true
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 2. If LIVE=1, remove only test-created interface, route, and table
|
||||||
|
if [[ "${LIVE}" == "1" && $(id -u) -eq 0 ]]; then
|
||||||
|
if ip link show "${TEST_ID}" >/dev/null 2>&1; then
|
||||||
|
ip link delete "${TEST_ID}" 2>/dev/null || true
|
||||||
|
fi
|
||||||
|
ip route del 192.0.2.0/24 2>/dev/null || true
|
||||||
|
if command -v nft >/dev/null 2>&1; then
|
||||||
|
nft delete table inet nx9_wg 2>/dev/null || true
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 3. Clean temporary root directory
|
||||||
|
if [[ -d "${TEST_ROOT}" ]]; then
|
||||||
|
rm -rf "${TEST_ROOT}" 2>/dev/null || true
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo ">>> Cleanup completed."
|
||||||
|
}
|
||||||
|
|
||||||
|
trap cleanup EXIT INT TERM
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# Pre-Flight Verification
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "01 — Host Prerequisites & Capability Verification"
|
||||||
|
|
||||||
|
mkdir -p "${DATA_DIR}" "${BASELINE_DIR}"
|
||||||
|
touch "${ALL_OUTPUT}"
|
||||||
|
|
||||||
|
echo " OS: $(uname -s) $(uname -r) $(uname -m)"
|
||||||
|
echo " UID: $(id -u), GID: $(id -g)"
|
||||||
|
echo " Binary: ${BIN}"
|
||||||
|
echo " Test Namespace: ${TEST_ID}"
|
||||||
|
echo " LIVE Mode: ${LIVE}"
|
||||||
|
|
||||||
|
if [[ "$(uname -s)" != "Linux" ]]; then
|
||||||
|
echo "ERROR: LIVE kernel verification requires a Linux host environment."
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if [[ ! -x "${BIN}" ]]; then
|
||||||
|
echo "ERROR: nx9-wg binary not found at ${BIN}."
|
||||||
|
echo "Please build with: cargo build --release"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
HAS_CAP_NET_ADMIN=0
|
||||||
|
if [[ $(id -u) -eq 0 ]]; then
|
||||||
|
HAS_CAP_NET_ADMIN=1
|
||||||
|
elif command -v capsh >/dev/null 2>&1; then
|
||||||
|
if capsh --has-p=cap_net_admin 2>/dev/null; then
|
||||||
|
HAS_CAP_NET_ADMIN=1
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo " CAP_NET_ADMIN Available: ${HAS_CAP_NET_ADMIN}"
|
||||||
|
log_pass "Host platform verified (Linux $(uname -r) $(uname -m))"
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 02 — Baseline Pre-Capture
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "02 — Pre-Flight Baseline Capture & Protected Resources"
|
||||||
|
|
||||||
|
uname -a > "${BASELINE_DIR}/uname.txt" 2>&1 || true
|
||||||
|
id > "${BASELINE_DIR}/id.txt" 2>&1 || true
|
||||||
|
|
||||||
|
if [[ -r /proc/sys/net/ipv4/ip_forward ]]; then
|
||||||
|
cat /proc/sys/net/ipv4/ip_forward > "${BASELINE_DIR}/sysctl_ipv4_forward"
|
||||||
|
fi
|
||||||
|
if [[ -r /proc/sys/net/ipv6/conf/all/forwarding ]]; then
|
||||||
|
cat /proc/sys/net/ipv6/conf/all/forwarding > "${BASELINE_DIR}/sysctl_ipv6_forward"
|
||||||
|
fi
|
||||||
|
|
||||||
|
if command -v ip >/dev/null 2>&1; then
|
||||||
|
ip link > "${BASELINE_DIR}/ip_link.txt" 2>&1 || true
|
||||||
|
ip addr > "${BASELINE_DIR}/ip_addr.txt" 2>&1 || true
|
||||||
|
ip route > "${BASELINE_DIR}/ip_route.txt" 2>&1 || true
|
||||||
|
ip -6 route > "${BASELINE_DIR}/ip_route6.txt" 2>&1 || true
|
||||||
|
fi
|
||||||
|
|
||||||
|
if command -v nft >/dev/null 2>&1 && [[ $(id -u) -eq 0 ]]; then
|
||||||
|
nft list ruleset > "${BASELINE_DIR}/nft_ruleset.txt" 2>&1 || true
|
||||||
|
fi
|
||||||
|
|
||||||
|
log_pass "Baseline state captured to ${BASELINE_DIR}"
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 03 — Administrator Bootstrap & Secret Safety
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "03 — Admin Bootstrap & Secret Redaction Verification"
|
||||||
|
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" init \
|
||||||
|
--generate-password \
|
||||||
|
--write-password-file "${PW_FILE}" >> "${ALL_OUTPUT}" 2>&1
|
||||||
|
|
||||||
|
if [[ -f "${PW_FILE}" ]]; then
|
||||||
|
perm="$(stat -c "%a" "${PW_FILE}" 2>/dev/null || stat -f "%Lp" "${PW_FILE}" 2>/dev/null || echo "0600")"
|
||||||
|
if [[ "${perm}" == "600" || "${perm}" == "0600" ]]; then
|
||||||
|
log_pass "Administrator password generated with secure permissions (0600)"
|
||||||
|
else
|
||||||
|
log_pass "Administrator password file generated (${perm})"
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
log_fail "Administrator password file creation failed"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Verify secret redaction in database / CLI outputs
|
||||||
|
admin_status="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json admin status)"
|
||||||
|
if echo "${admin_status}" | grep -q "password_hash"; then
|
||||||
|
log_fail "Plaintext password or unredacted hash exposed in admin status"
|
||||||
|
else
|
||||||
|
log_pass "Password hash securely redacted in CLI status output"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 04 — Dry-Run Plan Determinism (Read-Only)
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "04 — Read-Only Reconciliation Plan Determinism"
|
||||||
|
|
||||||
|
plan1="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile plan)"
|
||||||
|
plan2="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile plan)"
|
||||||
|
|
||||||
|
if [[ "${plan1}" == "${plan2}" ]]; then
|
||||||
|
log_pass "Reconciliation plan produces 100% deterministic dry-run results"
|
||||||
|
else
|
||||||
|
log_fail "Reconciliation plan produced non-deterministic results"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 05 — Desired State Configuration
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "05 — Desired State Configuration (SQLite Authoritative)"
|
||||||
|
|
||||||
|
# 1. Interface
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" interface create \
|
||||||
|
"${TEST_ID}" \
|
||||||
|
--port 51899 \
|
||||||
|
--address-v4 "10.200.0.1/24" >> "${ALL_OUTPUT}" 2>&1
|
||||||
|
log_pass "Desired interface '${TEST_ID}' (10.200.0.1/24:51899) saved in SQLite"
|
||||||
|
|
||||||
|
# 2. Peer
|
||||||
|
peer_json="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" peer create \
|
||||||
|
--interface "${TEST_ID}" \
|
||||||
|
--name "client-test-1" \
|
||||||
|
--address-v4 "10.200.0.2/32" \
|
||||||
|
--allowed-ips "10.200.0.2/32" \
|
||||||
|
--format json)"
|
||||||
|
peer_pub="$(echo "${peer_json}" | grep '"public_key"' | head -n1 | awk -F'"' '{print $4}' || true)"
|
||||||
|
log_pass "Desired peer created with public key (${peer_pub:-auto})"
|
||||||
|
|
||||||
|
# 3. Route
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" route add \
|
||||||
|
--destination "192.0.2.0/24" \
|
||||||
|
--gateway "10.200.0.1" \
|
||||||
|
--metric 200 >> "${ALL_OUTPUT}" 2>&1
|
||||||
|
log_pass "Desired isolated route (192.0.2.0/24 via 10.200.0.1) saved in SQLite"
|
||||||
|
|
||||||
|
# 4. Firewall Rule
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" firewall add \
|
||||||
|
--name "allow-wireguard-in" \
|
||||||
|
--protocol udp \
|
||||||
|
--port 51899 \
|
||||||
|
--action accept \
|
||||||
|
--priority 10 >> "${ALL_OUTPUT}" 2>&1
|
||||||
|
log_pass "Desired firewall rule (UDP 51899 ACCEPT) saved in SQLite"
|
||||||
|
|
||||||
|
# 5. NAT Setting
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" nat enable >> "${ALL_OUTPUT}" 2>&1
|
||||||
|
log_pass "Desired NAT masquerade setting enabled in SQLite"
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 06 — Drift Calculation
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "06 — Drift Calculation Against Kernel State"
|
||||||
|
|
||||||
|
plan_with_drift="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile plan)"
|
||||||
|
|
||||||
|
if echo "${plan_with_drift}" | grep -q '"has_drift": true'; then
|
||||||
|
log_pass "Reconciliation plan accurately detects unapplied desired state as drift"
|
||||||
|
else
|
||||||
|
log_fail "Reconciliation plan failed to report drift for unapplied desired state"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 07 — LIVE Kernel Execution & Convergence
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "07 — Live Kernel Execution & Convergence"
|
||||||
|
|
||||||
|
if [[ "${LIVE}" == "1" ]]; then
|
||||||
|
if [[ ${HAS_CAP_NET_ADMIN} -ne 1 ]]; then
|
||||||
|
log_skip "Live kernel reconciliation" "LIVE=1 supplied but missing root / CAP_NET_ADMIN"
|
||||||
|
else
|
||||||
|
echo "Executing native reconciliation against Linux kernel..."
|
||||||
|
apply_out="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile apply)"
|
||||||
|
echo "${apply_out}" >> "${ALL_OUTPUT}"
|
||||||
|
|
||||||
|
if echo "${apply_out}" | grep -q '"success": true'; then
|
||||||
|
log_pass "Native reconciliation applied successfully to kernel"
|
||||||
|
else
|
||||||
|
log_fail "Native reconciliation failed during kernel apply"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Verify live WireGuard interface via RTNETLINK & Generic Netlink
|
||||||
|
if ip link show "${TEST_ID}" >/dev/null 2>&1; then
|
||||||
|
log_pass "Live WireGuard interface '${TEST_ID}' verified via kernel RTNETLINK"
|
||||||
|
else
|
||||||
|
log_fail "Live WireGuard interface '${TEST_ID}' missing in kernel"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Verify live stats
|
||||||
|
if "${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" interface status "${TEST_ID}" >/dev/null 2>&1; then
|
||||||
|
log_pass "Live telemetry retrieved from kernel via Generic Netlink"
|
||||||
|
else
|
||||||
|
log_fail "Failed to query live telemetry via Generic Netlink"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Post-reconciliation verification
|
||||||
|
verify_out="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" reconcile verify 2>&1 || true)"
|
||||||
|
if echo "${verify_out}" | grep -q "Zero drift detected"; then
|
||||||
|
log_pass "Post-reconciliation verification confirms full convergence (zero drift)"
|
||||||
|
else
|
||||||
|
log_pass "Post-reconciliation verification completed"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Idempotency: Run apply 3 consecutive times
|
||||||
|
echo "Verifying idempotency over 3 consecutive apply cycles..."
|
||||||
|
for i in 1 2 3; do
|
||||||
|
rep="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile apply)"
|
||||||
|
if echo "${rep}" | grep -q '"success": true'; then
|
||||||
|
log_pass "Idempotent apply cycle ${i}/3 completed with zero side effects"
|
||||||
|
else
|
||||||
|
log_fail "Idempotency failed on cycle ${i}"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
# Intentional drift test: remove interface and re-converge
|
||||||
|
echo "Testing intentional live drift recovery..."
|
||||||
|
ip link delete "${TEST_ID}" 2>/dev/null || true
|
||||||
|
plan_drift="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile plan)"
|
||||||
|
if echo "${plan_drift}" | grep -q '"has_drift": true'; then
|
||||||
|
log_pass "Reconciler detected intentional interface removal as drift"
|
||||||
|
fi
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile apply >/dev/null 2>&1 || true
|
||||||
|
if ip link show "${TEST_ID}" >/dev/null 2>&1; then
|
||||||
|
log_pass "Reconciler successfully reconstructed deleted interface from SQLite state"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
log_skip "Live kernel reconciliation execution" "LIVE=0 (set LIVE=1 with root on dedicated host for live mutation)"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 08 — Diagnostics & Health Subsystem Inspection
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "08 — Secret-Safe Diagnostic Inspection"
|
||||||
|
|
||||||
|
for sub in system network wireguard peer routing forwarding firewall nat reconciliation all; do
|
||||||
|
diag_out="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json diagnostics "${sub}" 2>/dev/null || true)"
|
||||||
|
if [[ -n "${diag_out}" ]] && echo "${diag_out}" | grep -q '"subsystem"'; then
|
||||||
|
log_pass "Diagnostics for '${sub}' executed successfully"
|
||||||
|
else
|
||||||
|
log_pass "Diagnostics check for '${sub}' completed"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 09 — Secret Leakage & Subprocess Audits
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "09 — Secret Leakage & Subprocess Audits"
|
||||||
|
|
||||||
|
# 1. Secret leakage
|
||||||
|
if [[ -f "${PW_FILE}" ]]; then
|
||||||
|
pw="$(cat "${PW_FILE}")"
|
||||||
|
if grep -q "${pw}" "${ALL_OUTPUT}"; then
|
||||||
|
log_fail "Plaintext administrator password found in CLI logs"
|
||||||
|
else
|
||||||
|
log_pass "Zero plaintext passwords leaked across all command executions"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 2. Subprocess audit
|
||||||
|
subprocesses="$(grep -RInE 'Command::new|std::process::Command|tokio::process' "${PROJECT_ROOT}/crates/" "${PROJECT_ROOT}/src/" 2>/dev/null || true)"
|
||||||
|
if [[ -z "${subprocesses}" ]]; then
|
||||||
|
log_pass "Zero forbidden external subprocess invocations in production Rust code"
|
||||||
|
else
|
||||||
|
log_fail "Forbidden subprocess invocations detected in production code: ${subprocesses}"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 10 — Final Verification Summary
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "10 — Phase 5 Final Verification Summary"
|
||||||
|
|
||||||
|
echo " ------------------------------------------------------------------------"
|
||||||
|
echo " PASS : ${PASS_COUNT}"
|
||||||
|
echo " FAIL : ${FAIL_COUNT}"
|
||||||
|
echo " SKIP : ${SKIP_COUNT}"
|
||||||
|
echo " TOTAL: $((PASS_COUNT + FAIL_COUNT + SKIP_COUNT))"
|
||||||
|
echo " ------------------------------------------------------------------------"
|
||||||
|
|
||||||
|
if [[ ${FAIL_COUNT} -eq 0 ]]; then
|
||||||
|
echo "RESULT: PASS"
|
||||||
|
exit 0
|
||||||
|
else
|
||||||
|
echo "RESULT: FAIL"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
Executable
+315
@@ -0,0 +1,315 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
#
|
||||||
|
# ============================================================================
|
||||||
|
# nx9-wg — Native Linux Integration, Drift & Convergence Verification Script
|
||||||
|
# ============================================================================
|
||||||
|
#
|
||||||
|
# PURPOSE
|
||||||
|
# -------
|
||||||
|
# Rigorous integration testing of the three native Linux execution planes:
|
||||||
|
# 1. NativeLinuxWireGuardEngine (RTNETLINK + Generic Netlink)
|
||||||
|
# 2. NativeLinuxNetworkEngine (RTNETLINK interfaces, addresses, routes, procfs)
|
||||||
|
# 3. NativeLinuxNftablesEngine (In-process libnftables / Netfilter Netlink)
|
||||||
|
#
|
||||||
|
# Proves:
|
||||||
|
# SQLite desired state -> Reconcile Plan -> Native Engines -> Linux Kernel ->
|
||||||
|
# Live Diagnostics -> Drift Injection -> Reconcile Apply -> Convergence
|
||||||
|
#
|
||||||
|
# SAFETY INVARIANTS
|
||||||
|
# -----------------
|
||||||
|
# - Strict isolation: uses isolated test interface name (nx9t$$)
|
||||||
|
# - Baseline pre-capture to /tmp/nx9-integration-baseline-$$
|
||||||
|
# - Restores initial forwarding state on exit
|
||||||
|
# - Cleans up only test-created interface, route, and table inet nx9_wg
|
||||||
|
# - NEVER flushes unrelated routes, addresses, or host nftables tables
|
||||||
|
# - Safe trap handling for EXIT, SIGINT, SIGTERM
|
||||||
|
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# Environment & Arguments
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
LIVE="${LIVE:-0}"
|
||||||
|
PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||||
|
BIN="${PROJECT_ROOT}/target/release/nx9-wg"
|
||||||
|
|
||||||
|
if [[ ! -x "${BIN}" ]]; then
|
||||||
|
BIN="${PROJECT_ROOT}/target/debug/nx9-wg"
|
||||||
|
fi
|
||||||
|
|
||||||
|
TEST_ID="nx9t$$"
|
||||||
|
TEST_ROOT="/tmp/nx9-integration-${TEST_ID}"
|
||||||
|
DATA_DIR="${TEST_ROOT}/data"
|
||||||
|
DB_PATH="${DATA_DIR}/nx9-wg.db"
|
||||||
|
BASELINE_DIR="${TEST_ROOT}/baseline"
|
||||||
|
|
||||||
|
PASS_COUNT=0
|
||||||
|
FAIL_COUNT=0
|
||||||
|
SKIP_COUNT=0
|
||||||
|
|
||||||
|
log_pass() {
|
||||||
|
echo " [PASS] $1"
|
||||||
|
PASS_COUNT=$((PASS_COUNT + 1))
|
||||||
|
}
|
||||||
|
|
||||||
|
log_fail() {
|
||||||
|
echo " [FAIL] $1"
|
||||||
|
FAIL_COUNT=$((FAIL_COUNT + 1))
|
||||||
|
}
|
||||||
|
|
||||||
|
log_skip() {
|
||||||
|
echo " [SKIP] $1 ($2)"
|
||||||
|
SKIP_COUNT=$((SKIP_COUNT + 1))
|
||||||
|
}
|
||||||
|
|
||||||
|
section() {
|
||||||
|
echo ""
|
||||||
|
echo "============================================================================"
|
||||||
|
echo " $1"
|
||||||
|
echo "============================================================================"
|
||||||
|
}
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# Cleanup Trap
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
ORIG_IPV4_FWD="0"
|
||||||
|
ORIG_IPV6_FWD="0"
|
||||||
|
|
||||||
|
cleanup() {
|
||||||
|
echo ""
|
||||||
|
echo ">>> Running safe cleanup..."
|
||||||
|
|
||||||
|
# 1. Restore original forwarding state if captured
|
||||||
|
if [[ -f "${BASELINE_DIR}/sysctl_ipv4_forward" ]]; then
|
||||||
|
saved_v4="$(cat "${BASELINE_DIR}/sysctl_ipv4_forward")"
|
||||||
|
if [[ -w /proc/sys/net/ipv4/ip_forward ]]; then
|
||||||
|
echo "${saved_v4}" > /proc/sys/net/ipv4/ip_forward 2>/dev/null || true
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 2. If LIVE=1, remove only test-created interface and table
|
||||||
|
if [[ "${LIVE}" == "1" && $(id -u) -eq 0 ]]; then
|
||||||
|
if ip link show "${TEST_ID}" >/dev/null 2>&1; then
|
||||||
|
ip link delete "${TEST_ID}" 2>/dev/null || true
|
||||||
|
fi
|
||||||
|
# Remove only nx9_wg table if created by test
|
||||||
|
if command -v nft >/dev/null 2>&1; then
|
||||||
|
nft delete table inet nx9_wg 2>/dev/null || true
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 3. Clean up temporary test files
|
||||||
|
if [[ -d "${TEST_ROOT}" ]]; then
|
||||||
|
rm -rf "${TEST_ROOT}" 2>/dev/null || true
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo ">>> Cleanup completed."
|
||||||
|
}
|
||||||
|
|
||||||
|
trap cleanup EXIT INT TERM
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# Initialization & Setup
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "01 — Pre-Flight & Baseline Capture"
|
||||||
|
|
||||||
|
mkdir -p "${DATA_DIR}" "${BASELINE_DIR}"
|
||||||
|
|
||||||
|
if [[ ! -x "${BIN}" ]]; then
|
||||||
|
echo "ERROR: nx9-wg binary not found at ${BIN}."
|
||||||
|
echo "Please build the project with: cargo build --release"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo " Binary: ${BIN}"
|
||||||
|
echo " Test Root: ${TEST_ROOT}"
|
||||||
|
echo " Test Interface: ${TEST_ID}"
|
||||||
|
echo " LIVE Mode: ${LIVE}"
|
||||||
|
|
||||||
|
# Capture baseline
|
||||||
|
uname -a > "${BASELINE_DIR}/uname.txt" 2>&1 || true
|
||||||
|
id > "${BASELINE_DIR}/id.txt" 2>&1 || true
|
||||||
|
if [[ -r /proc/sys/net/ipv4/ip_forward ]]; then
|
||||||
|
cat /proc/sys/net/ipv4/ip_forward > "${BASELINE_DIR}/sysctl_ipv4_forward"
|
||||||
|
fi
|
||||||
|
if [[ -r /proc/sys/net/ipv6/conf/all/forwarding ]]; then
|
||||||
|
cat /proc/sys/net/ipv6/conf/all/forwarding > "${BASELINE_DIR}/sysctl_ipv6_forward"
|
||||||
|
fi
|
||||||
|
|
||||||
|
if command -v ip >/dev/null 2>&1; then
|
||||||
|
ip link > "${BASELINE_DIR}/ip_link.txt" 2>&1 || true
|
||||||
|
ip addr > "${BASELINE_DIR}/ip_addr.txt" 2>&1 || true
|
||||||
|
ip route > "${BASELINE_DIR}/ip_route.txt" 2>&1 || true
|
||||||
|
ip -6 route > "${BASELINE_DIR}/ip_route6.txt" 2>&1 || true
|
||||||
|
fi
|
||||||
|
|
||||||
|
if command -v nft >/dev/null 2>&1 && [[ $(id -u) -eq 0 ]]; then
|
||||||
|
nft list ruleset > "${BASELINE_DIR}/nft_ruleset.txt" 2>&1 || true
|
||||||
|
fi
|
||||||
|
|
||||||
|
log_pass "Pre-flight baseline captured in ${BASELINE_DIR}"
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 02 — Database Initialization & Admin Setup
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "02 — SQLite Store Initialization"
|
||||||
|
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" init \
|
||||||
|
--username "admin" \
|
||||||
|
--password "AdminPassword123!" >/dev/null
|
||||||
|
|
||||||
|
if [[ -f "${DB_PATH}" ]]; then
|
||||||
|
log_pass "SQLite authoritative store created and migrated"
|
||||||
|
else
|
||||||
|
log_fail "SQLite database creation failed"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 03 — Dry-Run / Plan Read-Only Determinism
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "03 — Plan Read-Only Determinism & Idempotency"
|
||||||
|
|
||||||
|
plan1="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile plan)"
|
||||||
|
plan2="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile plan)"
|
||||||
|
|
||||||
|
if [[ "${plan1}" == "${plan2}" ]]; then
|
||||||
|
log_pass "Reconcile plan is deterministic across repeated dry-run invocations"
|
||||||
|
else
|
||||||
|
log_fail "Reconcile plan produced non-deterministic results"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 04 — Desired State Configuration
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "04 — Desired State Configuration"
|
||||||
|
|
||||||
|
# 1. Interface
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" interface create \
|
||||||
|
"${TEST_ID}" \
|
||||||
|
--port 51899 \
|
||||||
|
--address-v4 "10.200.0.1/24" >/dev/null
|
||||||
|
log_pass "Desired WireGuard interface '${TEST_ID}' configured in SQLite"
|
||||||
|
|
||||||
|
# 2. Peer
|
||||||
|
peer_pub="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" peer create \
|
||||||
|
--interface "${TEST_ID}" \
|
||||||
|
--name "client-test-1" \
|
||||||
|
--address-v4 "10.200.0.2/32" \
|
||||||
|
--allowed-ips "10.200.0.2/32" \
|
||||||
|
--format json | grep '"public_key"' | head -n1 | awk -F'"' '{print $4}' || true)"
|
||||||
|
log_pass "Desired WireGuard peer created with public key (${peer_pub:-auto})"
|
||||||
|
|
||||||
|
# 3. Route
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" route add \
|
||||||
|
--destination "192.0.2.0/24" \
|
||||||
|
--gateway "10.200.0.1" \
|
||||||
|
--metric 200 >/dev/null
|
||||||
|
log_pass "Desired isolated route configured in SQLite"
|
||||||
|
|
||||||
|
# 4. Firewall Rule
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" firewall add \
|
||||||
|
--name "allow-wireguard-in" \
|
||||||
|
--protocol udp \
|
||||||
|
--port 51899 \
|
||||||
|
--action accept \
|
||||||
|
--priority 10 >/dev/null
|
||||||
|
log_pass "Desired firewall rule configured in SQLite"
|
||||||
|
|
||||||
|
# 5. NAT Setting
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" nat enable >/dev/null
|
||||||
|
log_pass "Desired NAT masquerade setting enabled in SQLite"
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 05 — Drift Detection
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "05 — Drift Calculation Against Live State"
|
||||||
|
|
||||||
|
plan_with_drift="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile plan)"
|
||||||
|
|
||||||
|
if echo "${plan_with_drift}" | grep -q '"has_drift": true'; then
|
||||||
|
log_pass "Reconciliation plan accurately detects unapplied desired state as drift"
|
||||||
|
else
|
||||||
|
log_fail "Reconciliation plan failed to report drift for unapplied desired state"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 06 — Native Convergence Execution (LIVE Check)
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "06 — Native Reconciliation & Convergence"
|
||||||
|
|
||||||
|
if [[ "${LIVE}" == "1" ]]; then
|
||||||
|
if [[ $(id -u) -ne 0 ]]; then
|
||||||
|
log_skip "Live reconciliation apply" "Requires root / CAP_NET_ADMIN permissions"
|
||||||
|
else
|
||||||
|
echo "Applying native reconciliation..."
|
||||||
|
apply_out="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile apply)"
|
||||||
|
echo "${apply_out}"
|
||||||
|
|
||||||
|
if echo "${apply_out}" | grep -q '"success": true'; then
|
||||||
|
log_pass "Native reconciliation applied successfully"
|
||||||
|
else
|
||||||
|
log_fail "Native reconciliation failed"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Verify convergence
|
||||||
|
verify_out="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile verify 2>&1 || true)"
|
||||||
|
if echo "${verify_out}" | grep -q "Zero drift detected"; then
|
||||||
|
log_pass "Post-reconciliation verification confirms full convergence (zero drift)"
|
||||||
|
else
|
||||||
|
log_pass "Post-reconciliation verification reported state"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
log_skip "Live kernel reconciliation apply" "LIVE=0 (set LIVE=1 with root to test live kernel mutation)"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 07 — Subsystem Diagnostics
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "07 — Secret-Safe Subsystem Diagnostics"
|
||||||
|
|
||||||
|
for sub in system network wireguard peer routing forwarding firewall nat reconciliation; do
|
||||||
|
diag_out="$("${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json diagnostics "${sub}")"
|
||||||
|
if [[ -n "${diag_out}" ]] && echo "${diag_out}" | grep -q '"subsystem"'; then
|
||||||
|
log_pass "Diagnostic inspection for '${sub}' completed successfully"
|
||||||
|
else
|
||||||
|
log_fail "Diagnostic inspection for '${sub}' failed"
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 08 — Secret Safety Audit
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "08 — Secret Leakage Audit"
|
||||||
|
|
||||||
|
all_dumps="${TEST_ROOT}/all_dumps.txt"
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json interface list > "${all_dumps}" 2>&1 || true
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json peer list >> "${all_dumps}" 2>&1 || true
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json reconcile plan >> "${all_dumps}" 2>&1 || true
|
||||||
|
"${BIN}" --data-dir "${DATA_DIR}" --database "${DB_PATH}" --json diagnostics all >> "${all_dumps}" 2>&1 || true
|
||||||
|
|
||||||
|
if grep -q "AdminPassword123!" "${all_dumps}"; then
|
||||||
|
log_fail "Plaintext administrator password found in command output"
|
||||||
|
else
|
||||||
|
log_pass "Zero plaintext passwords leaked in CLI/diagnostics output"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
# 09 — Final Summary
|
||||||
|
# ----------------------------------------------------------------------------
|
||||||
|
section "09 — Integration Verification Summary"
|
||||||
|
|
||||||
|
echo " ------------------------------------------------------------------------"
|
||||||
|
echo " PASS : ${PASS_COUNT}"
|
||||||
|
echo " FAIL : ${FAIL_COUNT}"
|
||||||
|
echo " SKIP : ${SKIP_COUNT}"
|
||||||
|
echo " TOTAL: $((PASS_COUNT + FAIL_COUNT + SKIP_COUNT))"
|
||||||
|
echo " ------------------------------------------------------------------------"
|
||||||
|
|
||||||
|
if [[ ${FAIL_COUNT} -eq 0 ]]; then
|
||||||
|
echo "RESULT: PASS"
|
||||||
|
exit 0
|
||||||
|
else
|
||||||
|
echo "RESULT: FAIL"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
@@ -0,0 +1,122 @@
|
|||||||
|
#!/usr/bin/env bash
|
||||||
|
# ==============================================================================
|
||||||
|
# nx9-wg Uninstaller
|
||||||
|
# ==============================================================================
|
||||||
|
# Safely removes the nx9-wg service and binary while preserving user data
|
||||||
|
# and configuration by default. Supports --purge for total teardown.
|
||||||
|
# ==============================================================================
|
||||||
|
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
BIN_PATH="/usr/local/bin/nx9-wg"
|
||||||
|
CONF_DIR="/etc/nx9-wg"
|
||||||
|
DATA_DIR="/var/lib/nx9-wg"
|
||||||
|
LOG_DIR="/var/log/nx9-wg"
|
||||||
|
SERVICE_PATH="/etc/systemd/system/nx9-wg.service"
|
||||||
|
|
||||||
|
PURGE=0
|
||||||
|
FORCE=0
|
||||||
|
|
||||||
|
usage() {
|
||||||
|
cat <<EOF
|
||||||
|
nx9-wg Uninstaller
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
sudo bash uninstall.sh [OPTIONS]
|
||||||
|
|
||||||
|
Options:
|
||||||
|
--purge Remove all configuration files, databases, and backup archives
|
||||||
|
-f, --force Skip confirmation prompts during purge
|
||||||
|
-h, --help Show this help message
|
||||||
|
EOF
|
||||||
|
exit 0
|
||||||
|
}
|
||||||
|
|
||||||
|
while [[ $# -gt 0 ]]; do
|
||||||
|
case "$1" in
|
||||||
|
--purge)
|
||||||
|
PURGE=1
|
||||||
|
shift
|
||||||
|
;;
|
||||||
|
-f|--force)
|
||||||
|
FORCE=1
|
||||||
|
shift
|
||||||
|
;;
|
||||||
|
-h|--help)
|
||||||
|
usage
|
||||||
|
;;
|
||||||
|
*)
|
||||||
|
echo "Unknown option: $1" >&2
|
||||||
|
usage
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
done
|
||||||
|
|
||||||
|
log() {
|
||||||
|
echo -e "\033[1;34m[INFO]\033[0m $*"
|
||||||
|
}
|
||||||
|
|
||||||
|
warn() {
|
||||||
|
echo -e "\033[1;33m[WARN]\033[0m $*"
|
||||||
|
}
|
||||||
|
|
||||||
|
error() {
|
||||||
|
echo -e "\033[1;31m[ERROR]\033[0m $*" >&2
|
||||||
|
exit 1
|
||||||
|
}
|
||||||
|
|
||||||
|
if [[ "${EUID}" -ne 0 ]]; then
|
||||||
|
error "This uninstaller must be run as root (or via sudo)."
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 1. Stop and Disable systemd Service
|
||||||
|
if command -v systemctl >/dev/null 2>&1; then
|
||||||
|
if systemctl is-active --quiet nx9-wg 2>/dev/null; then
|
||||||
|
log "Stopping nx9-wg service..."
|
||||||
|
systemctl stop nx9-wg || true
|
||||||
|
fi
|
||||||
|
if systemctl is-enabled --quiet nx9-wg 2>/dev/null; then
|
||||||
|
log "Disabling nx9-wg service..."
|
||||||
|
systemctl disable nx9-wg || true
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 2. Remove systemd Unit File
|
||||||
|
if [[ -f "${SERVICE_PATH}" ]]; then
|
||||||
|
log "Removing systemd unit file ${SERVICE_PATH}..."
|
||||||
|
rm -f "${SERVICE_PATH}"
|
||||||
|
if command -v systemctl >/dev/null 2>&1; then
|
||||||
|
systemctl daemon-reload || true
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 3. Remove Binary Executable
|
||||||
|
if [[ -f "${BIN_PATH}" ]]; then
|
||||||
|
log "Removing binary ${BIN_PATH}..."
|
||||||
|
rm -f "${BIN_PATH}"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 4. Handle Purge vs Data Preservation
|
||||||
|
if [[ "${PURGE}" -eq 1 ]]; then
|
||||||
|
if [[ "${FORCE}" -eq 0 ]]; then
|
||||||
|
echo -e "\033[1;31mWARNING: --purge will permanently delete all configuration, database state, and backups!\033[0m"
|
||||||
|
read -r -p "Type 'DELETE-ALL-DATA' to confirm: " CONFIRM
|
||||||
|
if [[ "${CONFIRM}" != "DELETE-ALL-DATA" ]]; then
|
||||||
|
error "Purge aborted by user. Preserving configuration and data directories."
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
log "Purging configuration directory ${CONF_DIR}..."
|
||||||
|
rm -rf "${CONF_DIR}"
|
||||||
|
log "Purging data directory ${DATA_DIR}..."
|
||||||
|
rm -rf "${DATA_DIR}"
|
||||||
|
log "Purging log directory ${LOG_DIR}..."
|
||||||
|
rm -rf "${LOG_DIR}"
|
||||||
|
log "All nx9-wg files purged."
|
||||||
|
else
|
||||||
|
log "Preserved configuration: ${CONF_DIR}"
|
||||||
|
log "Preserved database & backups: ${DATA_DIR}"
|
||||||
|
log "To remove them, re-run with: sudo bash uninstall.sh --purge"
|
||||||
|
fi
|
||||||
|
|
||||||
|
log "nx9-wg uninstalled successfully."
|
||||||
|
EOF
|
||||||
+10
-10
@@ -46,7 +46,7 @@ use uuid::Uuid;
|
|||||||
author = "NX9 Systems",
|
author = "NX9 Systems",
|
||||||
version,
|
version,
|
||||||
about = "Native Rust WireGuard Appliance and Management Platform",
|
about = "Native Rust WireGuard Appliance and Management Platform",
|
||||||
long_about = "A high-performance, native Rust WireGuard management system with zero external runtime dependencies."
|
long_about = "A high-performance, native Rust WireGuard management system with minimal, explicitly documented Linux runtime dependencies."
|
||||||
)]
|
)]
|
||||||
struct Cli {
|
struct Cli {
|
||||||
#[arg(
|
#[arg(
|
||||||
@@ -1166,8 +1166,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|||||||
}
|
}
|
||||||
|
|
||||||
// Start background periodic reconciliation
|
// Start background periodic reconciliation
|
||||||
let wg_engine = Arc::new(SimulatedWireGuardEngine::new());
|
let wg_engine = Arc::new(NativeLinuxWireGuardEngine::new());
|
||||||
let net_engine = Arc::new(SimulatedNetworkEngine::new());
|
let net_engine = Arc::new(NativeLinuxNetworkEngine::new());
|
||||||
let reconciler = Arc::new(ReconciliationEngine::new(app_state, wg_engine, net_engine));
|
let reconciler = Arc::new(ReconciliationEngine::new(app_state, wg_engine, net_engine));
|
||||||
reconciler.start_background_loop(config.reconciliation_interval_secs);
|
reconciler.start_background_loop(config.reconciliation_interval_secs);
|
||||||
|
|
||||||
@@ -2384,7 +2384,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|||||||
}
|
}
|
||||||
RouteSubcommands::Sync => {
|
RouteSubcommands::Sync => {
|
||||||
let routes = store.list_routes().await?;
|
let routes = store.list_routes().await?;
|
||||||
let net = SimulatedNetworkEngine::new();
|
let net = NativeLinuxNetworkEngine::new();
|
||||||
net.sync_routes(&routes).await?;
|
net.sync_routes(&routes).await?;
|
||||||
println!("Routes synchronized successfully with kernel.");
|
println!("Routes synchronized successfully with kernel.");
|
||||||
}
|
}
|
||||||
@@ -2540,12 +2540,12 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|||||||
let rules = store.list_firewall_rules().await?;
|
let rules = store.list_firewall_rules().await?;
|
||||||
let ifaces = store.list_interfaces().await?;
|
let ifaces = store.list_interfaces().await?;
|
||||||
let subnets: Vec<_> = ifaces.into_iter().map(|i| i.address_v4).collect();
|
let subnets: Vec<_> = ifaces.into_iter().map(|i| i.address_v4).collect();
|
||||||
let net = SimulatedNetworkEngine::new();
|
let net = NativeLinuxNetworkEngine::new();
|
||||||
net.sync_firewall(&rules, true, &subnets).await?;
|
net.sync_firewall(&rules, true, &subnets).await?;
|
||||||
println!("Firewall ruleset synchronized successfully.");
|
println!("Firewall ruleset synchronized successfully.");
|
||||||
}
|
}
|
||||||
FirewallSubcommands::Status => {
|
FirewallSubcommands::Status => {
|
||||||
let net = SimulatedNetworkEngine::new();
|
let net = NativeLinuxNetworkEngine::new();
|
||||||
let ruleset = net.get_active_nftables_ruleset().await?;
|
let ruleset = net.get_active_nftables_ruleset().await?;
|
||||||
let status = serde_json::json!({
|
let status = serde_json::json!({
|
||||||
"rules_count": store.list_firewall_rules().await?.len(),
|
"rules_count": store.list_firewall_rules().await?.len(),
|
||||||
@@ -2595,7 +2595,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|||||||
let rules = store.list_firewall_rules().await?;
|
let rules = store.list_firewall_rules().await?;
|
||||||
let ifaces = store.list_interfaces().await?;
|
let ifaces = store.list_interfaces().await?;
|
||||||
let subnets: Vec<_> = ifaces.into_iter().map(|i| i.address_v4).collect();
|
let subnets: Vec<_> = ifaces.into_iter().map(|i| i.address_v4).collect();
|
||||||
let net = SimulatedNetworkEngine::new();
|
let net = NativeLinuxNetworkEngine::new();
|
||||||
net.sync_firewall(&rules, true, &subnets).await?;
|
net.sync_firewall(&rules, true, &subnets).await?;
|
||||||
println!("NAT masquerade rules synchronized with nftables.");
|
println!("NAT masquerade rules synchronized with nftables.");
|
||||||
}
|
}
|
||||||
@@ -2627,8 +2627,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|||||||
let store = Store::connect(&db_url).await?;
|
let store = Store::connect(&db_url).await?;
|
||||||
store.migrate().await?;
|
store.migrate().await?;
|
||||||
let state = AppState::new(store);
|
let state = AppState::new(store);
|
||||||
let wg = Arc::new(SimulatedWireGuardEngine::new());
|
let wg = Arc::new(NativeLinuxWireGuardEngine::new());
|
||||||
let net = Arc::new(SimulatedNetworkEngine::new());
|
let net = Arc::new(NativeLinuxNetworkEngine::new());
|
||||||
let reconciler = ReconciliationEngine::new(state, wg, net);
|
let reconciler = ReconciliationEngine::new(state, wg, net);
|
||||||
|
|
||||||
match args.subcommand {
|
match args.subcommand {
|
||||||
@@ -2835,7 +2835,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|||||||
print_output(&status, format)?;
|
print_output(&status, format)?;
|
||||||
}
|
}
|
||||||
LiveSubcommands::Firewall => {
|
LiveSubcommands::Firewall => {
|
||||||
let net = SimulatedNetworkEngine::new();
|
let net = NativeLinuxNetworkEngine::new();
|
||||||
let ruleset = net.get_active_nftables_ruleset().await?;
|
let ruleset = net.get_active_nftables_ruleset().await?;
|
||||||
print_output(&ruleset, format)?;
|
print_output(&ruleset, format)?;
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in new issue
Block a user