gru/rustproxy-opnsense-repo
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

push

Browse Source
This commit is contained in:
Mateusz Gruszczyński committed 2026-09-29 14:07:21 +02:00
1 parent 093e6a7c14
commit 1a2a5f0faf
24 files changed
+578 -537
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/ARCHITECTURE.md
+24 -33
View File
@@ -1,46 +1,37 @@
# Architecture
## Release path
## Components
1. Debian cron runs once per hour.
2. It refreshes the packaging repository containing this plugin/build logic.
3. Independently, it fetches `APP_REPO_REF` from `https://git.linuxiarz.pl/gru/RustProxy` into `APP_WORKDIR`.
4. It compares both current commits with the last successful build state.
5. If either commit changed, Debian rsyncs the packaging tree and the RustProxy checkout separately to a FreeBSD 15.1 amd64 builder.
6. FreeBSD reads the application version from the downloaded `Cargo.toml`, runs Cargo tests and a release build.
7. The binary is injected into `opnsense-plugin/www/rustproxy/src/sbin/rust-proxy` inside a clean checkout of the official OPNsense plugins tree.
8. `make package` creates `os-rustproxy-<version>_<revision>.pkg`.
9. `pkg repo` creates a signed package repository.
10. Debian downloads `dist/` and optionally publishes it over rsync/SSH.
11. OPNsense consumes only the custom RustProxy package repository.
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`.
The packaging repository deliberately contains no `app/` directory. This prevents stale application code from accidentally being packaged.
No FreeBSD VM is used.
## Upstream selection
## Why the sysroot is enough for the binary build
Default configuration:
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:
```text
APP_REPO_URL=https://git.linuxiarz.pl/gru/RustProxy
APP_REPO_REF=HEAD
+COMPACT_MANIFEST
+MANIFEST
usr/local/...
```
`HEAD` follows the repository's default branch. To freeze releases, set `APP_REPO_REF` to a branch, tag or other fetchable ref. The exact commit used for each package is written to `dist/BUILD-INFO.txt`.
and compresses it with zstd to `.pkg`.
## Why native FreeBSD for releases
## Source isolation
Rust can cross-compile to `x86_64-unknown-freebsd`, but a release also needs the target ABI and FreeBSD/OPNsense packaging behavior. A native FreeBSD builder makes both the Rust link step and `pkg` metadata/catalog generation match the target platform. The Docker/cross path is intended for fast developer validation only.
```text
/opt/opn-rustproxy/packaging packaging repository
/opt/opn-rustproxy/source/RustProxy dynamically fetched application
/opt/opn-rustproxy/cache Docker/Cargo cache
```
## OPNsense plugin behavior
The first UI version exposes only `general.enabled`.
- Enabled: the service controller renders configuration and starts RustProxy through configd.
- Disabled: the service controller stops RustProxy.
- Boot: an OPNsense syshook regenerates configuration and starts the service only when enabled.
RustProxy runs as the unprivileged `rustproxy` user. Its data is stored in `/var/db/rustproxy` and logs in `/var/log/rustproxy/rustproxy.log`.
## Ports 80 and 443
The MVP does not run RustProxy as root. Keep initial listeners above port 1023. If public 80/443 is required later, prefer an explicit PF redirect from 80/443 to high RustProxy listener ports instead of running the whole proxy as root.
The exact RustProxy SHA and package version are written to `dist/BUILD-INFO.txt`.
docs/FIRST_RUN.md
+101 -72
View File
@@ -1,109 +1,138 @@
# First run
# First run on Debian
## 1. Push this packaging repository
Everything below assumes the working root is `/opt/opn-rustproxy`.
Create a repository for the generated OPNsense plugin/build files and push this tree there. RustProxy itself must not be copied into this repository; it will be fetched dynamically from:
```text
https://git.linuxiarz.pl/gru/RustProxy
```
After pushing, set that new repository address as `PACKAGING_REPO_URL` in the Debian configuration.
## 2. Prepare the FreeBSD release builder
Use FreeBSD 15.1 amd64.
## 1. Checkout
```sh
sudo sh builder/freebsd/bootstrap.sh builder
sudo -u builder sh builder/freebsd/create-repo-key.sh
sudo mkdir -p /opt/opn-rustproxy
sudo chown -R "$USER:$USER" /opt/opn-rustproxy
cd /opt/opn-rustproxy
git clone https://git.linuxiarz.pl/gru/rustproxy-opnsense-repo packaging
cd packaging
```
The bootstrap creates a non-root `builder` account and gives it `/usr/local/rustproxy-build`.
RustProxy is intentionally not cloned manually. The scheduler fetches it to `/opt/opn-rustproxy/source/RustProxy`.
## 3. Prepare Debian
From a checkout of this packaging repository:
## 2. Install Debian dependencies
```sh
sudo bash builder/debian/install.sh
```
This installs Docker, cron, Git, zstd and the scheduler, then starts `docker` and `cron`.
## 3. Configure
```sh
sudo editor /etc/rustproxy-opnsense-builder.env
```
At minimum configure:
For the basic local build, use:
```text
PACKAGING_REPO_URL=<URL of this new packaging repository>
PACKAGING_REPO_REF=main
PACKAGING_REPO_URL=https://git.linuxiarz.pl/gru/rustproxy-opnsense-repo
PACKAGING_REPO_REF=HEAD
PACKAGING_WORKDIR=/opt/opn-rustproxy/packaging
APP_REPO_URL=https://git.linuxiarz.pl/gru/RustProxy
APP_REPO_REF=HEAD
APP_WORKDIR=/opt/opn-rustproxy/source/RustProxy
FREEBSD_HOST=<FreeBSD builder>
FREEBSD_USER=builder
FREEBSD_REMOTE_DIR=/usr/local/rustproxy-build/project
STATE_DIR=/var/lib/rustproxy-opnsense-builder
DOCKER_CACHE_DIR=/opt/opn-rustproxy/cache
BUILD_MODE=docker-freebsd
FREEBSD_RELEASE=15.1-RELEASE
FREEBSD_ABI=FreeBSD:15:amd64
FREEBSD_ARCH=freebsd:15:x86:64
OPNSENSE_ABI=26.7
DOCKER_IMAGE=rustproxy-freebsd15-builder:15.1-rust1.88
RUN_LINUX_TESTS=1
PUBLISH_TARGET=
PUBLISH_SSH_KEY=
AUTO_DEPLOY_HOSTS=
AUTO_DEPLOY_SSH_KEY=
```
`APP_REPO_REF=HEAD` means "build the current default branch". If you want controlled releases, change it to a specific branch or tag.
Run the first cycle manually:
## 4. Validate repository scripts
```sh
sudo /usr/local/sbin/rustproxy-opnsense-hourly
cd /opt/opn-rustproxy/packaging
./scripts/check.sh
```
Cron runs at minute 17 of every hour. Each run fetches the RustProxy upstream. A new build starts when either the upstream RustProxy commit or this packaging repository commit changed. A failed build does not update `last-successful-build`, so it is retried on the next run.
## 5. First build
## 4. Build state
```sh
sudo /usr/local/sbin/rustproxy-opnsense-hourly 2>&1 | sudo tee -a /var/log/rustproxy-opnsense-builder.log
```
Debian stores checkouts separately:
The first run downloads the RustProxy Git checkout and the FreeBSD 15.1 sysroot, then builds the Docker image. Later runs reuse Docker/Cargo caches. RustProxy's build also downloads crates and pinned Swagger UI assets, so the builder needs outbound HTTPS access.
Follow the log with:
```sh
sudo tail -f /var/log/rustproxy-opnsense-builder.log
```
## 6. Verify output
```sh
cd /opt/opn-rustproxy/packaging
cat dist/BUILD-INFO.txt
cat dist/SHA256
file dist/docker-build/rust-proxy
zstd -dc dist/os-rustproxy-latest.pkg | tar -tf - | head -50
```
The binary should identify as an x86-64 FreeBSD ELF executable, not a Linux executable.
## 7. Install on a test OPNsense
Copy the package and installer:
```sh
scp dist/os-rustproxy-latest.pkg root@OPNSENSE_IP:/tmp/
scp deploy/opnsense/install-direct.sh root@OPNSENSE_IP:/tmp/
```
Then:
```sh
ssh root@OPNSENSE_IP
sh /tmp/install-direct.sh /tmp/os-rustproxy-latest.pkg
```
Open **Services -> RustProxy**, enable it and click **Apply**.
Useful checks on OPNsense:
```sh
pkg info os-rustproxy
file /usr/local/sbin/rust-proxy
service rustproxy status
tail -f /var/log/rustproxy/rustproxy.log
```
## 8. Hourly scheduler
`/etc/cron.d/rustproxy-opnsense` runs at minute 17 each hour:
```text
/srv/rustproxy-opnsense/packaging/ # this repository
/srv/rustproxy-opnsense/source/RustProxy # dynamically fetched app
/var/lib/rustproxy-opnsense-builder/ # lock + last successful commit pair
17 * * * * root /usr/local/sbin/rustproxy-opnsense-hourly >> /var/log/rustproxy-opnsense-builder.log 2>&1
```
The FreeBSD build machine receives the two trees separately. Its temporary `$FREEBSD_REMOTE_DIR/app/` always comes from the upstream checkout, never from the packaging repository.
No rebuild occurs when both Git SHAs are unchanged. A failed build does not advance the successful-state marker and will be retried later.
## 5. Publish `dist/`
## 9. Optional test-firewall auto deploy
Set `PUBLISH_TARGET`. The published layout is similar to:
Only for explicitly named test firewalls:
```text
/rustproxy/
BUILD-INFO.txt
SHA256
rustproxy-repo.pub
repository/
26.7/
amd64/
os-rustproxy-<Cargo-version>_<revision>.pkg
meta.conf
data.pkg
packagesite.pkg
AUTO_DEPLOY_HOSTS="root@10.0.0.10"
AUTO_DEPLOY_SSH_KEY=/root/.ssh/opnsense_test
```
`BUILD-INFO.txt` contains the RustProxy source URL, ref and exact commit used to create the package.
## 6. Install on OPNsense
Copy `rustproxy-repo.pub` to the firewall and run:
```sh
sh deploy/opnsense/install-repo.sh \
https://packages.example.net/rustproxy/repository/26.7/amd64 \
/tmp/rustproxy-repo.pub
```
Then open `Services -> RustProxy`, enable it and click Apply.
## 7. Update
Publishing a new package does not automatically upgrade production firewalls. Run:
```sh
sh deploy/opnsense/update.sh
```
`AUTO_DEPLOY_HOSTS` exists only for explicitly listed test firewalls and is empty by default.
Leave both empty for manual deployment.