rustproxy-opnsense-repo/docs/ARCHITECTURE.md

Architecture

Components

1. Debian host - Git polling, Docker engine, package assembly and optional publication.
2. Docker builder - Rust 1.88, Clang/LLD and a verified FreeBSD 15.1 sysroot extracted from official base.txz.
3. OPNsense package - os-rustproxy-*.pkg, installed directly with pkg add -f.

No FreeBSD VM is used.

Why the sysroot is enough for the binary build

Rust provides x86_64-unknown-freebsd. Clang receives --target=x86_64-unknown-freebsd15.1 and --sysroot=/opt/freebsd-sysroot, so Rust and C/assembly dependencies such as ring link against FreeBSD headers and libraries instead of Debian ones.

The container is still Linux. It cannot execute the generated FreeBSD binary, so the pipeline performs Linux tests before cross-compilation and ELF inspection after cross-compilation. Runtime validation must happen on an OPNsense/FreeBSD test firewall.

Package construction

FreeBSD pkg archives are compressed tar archives with metadata files beginning with + before package data. The Linux packager creates:

+COMPACT_MANIFEST
+MANIFEST
usr/local/...

and compresses it with zstd to .pkg.

Source isolation

/opt/opn-rustproxy/packaging          packaging repository
/opt/opn-rustproxy/source/RustProxy  dynamically fetched application
/opt/opn-rustproxy/cache             Docker/Cargo cache

The exact RustProxy SHA and package version are written to dist/BUILD-INFO.txt.