rustproxy-opnsense-repo/docs/FIRST_RUN.md

First run on Debian

Everything below assumes the working root is /opt/opn-rustproxy.

1. Checkout

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

RustProxy is intentionally not cloned manually. The scheduler fetches it to /opt/opn-rustproxy/source/RustProxy.

2. Install Debian dependencies

sudo bash builder/debian/install.sh

This installs Docker, cron, Git, zstd and the scheduler, then starts docker and cron.

3. Configure

sudo editor /etc/rustproxy-opnsense-builder.env

For the basic local build, use:

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

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=

4. Validate repository scripts

cd /opt/opn-rustproxy/packaging
./scripts/check.sh

5. First build

sudo /usr/local/sbin/rustproxy-opnsense-hourly 2>&1 | sudo tee -a /var/log/rustproxy-opnsense-builder.log

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:

sudo tail -f /var/log/rustproxy-opnsense-builder.log

6. Verify output

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 package payload should contain files such as /usr/local/sbin/rust-proxy and must not contain directory entries such as /usr/ or /usr/local/. The build fails automatically when payload paths differ from +MANIFEST.

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:

scp dist/os-rustproxy-latest.pkg root@OPNSENSE_IP:/tmp/
scp deploy/opnsense/install-direct.sh root@OPNSENSE_IP:/tmp/

Then:

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:

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:

17 * * * * root /usr/local/sbin/rustproxy-opnsense-hourly >> /var/log/rustproxy-opnsense-builder.log 2>&1

No rebuild occurs when both Git SHAs are unchanged. A failed build does not advance the successful-state marker and will be retried later.

9. Optional test-firewall auto deploy

Only for explicitly named test firewalls:

AUTO_DEPLOY_HOSTS="root@10.0.0.10"
AUTO_DEPLOY_SSH_KEY=/root/.ssh/opnsense_test

Leave both empty for manual deployment.

OPNsense runtime settings

After installation open Services -> RustProxy. Defaults are:

• HTTP bind address / port: 0.0.0.0 / 8080
• HTTPS/TLS enabled: yes
• HTTPS/TLS bind address / port: 0.0.0.0 / 8181
• Admin bind address / port: 0.0.0.0 / 9090
• Allow remote admin: yes

The RustProxy administration UI is reachable from other hosts by default on port 9090, subject to OPNsense firewall rules. Use Open RustProxy Admin after Apply to open the panel in a new browser tab. If the admin bind address is 0.0.0.0, the button uses the hostname or IP address through which you opened OPNsense.

Direct pkg add is supported: the package post-install script restarts OPNsense configd, flushes the plugin cache and renders /usr/local/etc/rustproxy/opnsense.conf so configctl rustproxy status/start/stop is available immediately. If Enabled is set, the post-install hook also restarts RustProxy automatically after pkg upgrade or pkg add -f.

FreeBSD uses jemalloc, so the OPNsense rc.d service sets MALLOC_CONF=narenas:2. This is the FreeBSD equivalent of the low-arena intent behind Linux MALLOC_ARENA_MAX=2; the glibc variable is intentionally not exported on OPNsense. Set rustproxy_malloc_conf in rc.conf to override or disable it.

RustProxy requires its data directory to be private. On OPNsense/FreeBSD the plugin runs the service as root and enforces owner root:wheel with mode 0700 on /var/db/rustproxy before every start.

FreeBSD patch set

The OPNsense builder automatically applies version-specific RustProxy patches to a temporary build copy only. The application checkout remains clean:

cd /opt/opn-rustproxy/source/RustProxy
git status

For RustProxy 0.20.0 the builder uses:

builder/freebsd/patches/0.20.0/0001-opnsense-build.patch

The normal setting is:

APPLY_FREEBSD_PATCHES=1

During a build you should see:

Applying FreeBSD/OPNsense patch set for RustProxy 0.20.0 to isolated build source...
  applied: 0001-opnsense-build.patch

Runtime directory

/var/run/rustproxy is created automatically as root:wheel with mode 0750 during package installation and before each service start. PID files are daemon.pid and rustproxy.pid inside that directory.