# RustProxy OPNsense packaging repository

Docker-only build pipeline for RustProxy on Debian. No FreeBSD VM is required.

RustProxy itself is not stored here. Every scheduled run fetches it independently from:

`https://git.linuxiarz.pl/gru/RustProxy`

## Flow

```text
rustproxy-opnsense-repo             RustProxy upstream
          |                              |
          +--------------+---------------+
                         v
                  Debian cron hourly
                         |
                         v
              Docker cross-build image
       Rust 1.88 + clang/lld + FreeBSD 15.1 sysroot
                         |
                         v
             x86_64-unknown-freebsd binary
                         |
                         v
              Linux-side .pkg assembly
                         |
                         v
        dist/os-rustproxy-latest.pkg
                         |
                         v
              pkg add -f on OPNsense
```

The Docker container does not emulate FreeBSD. It runs on the Linux kernel and uses the FreeBSD 15.1 headers/libraries only as a cross-compilation sysroot.

## Repository contents

- `opnsense-plugin/www/rustproxy/` - OPNsense plugin source.
- `builder/docker/Dockerfile` - Rust/Clang FreeBSD 15.1 cross toolchain.
- `builder/debian/hourly-build.sh` - fetch/change detection scheduler.
- `builder/debian/build-docker-release.sh` - Docker build orchestration.
- `builder/debian/package-freebsd.sh` - creates a FreeBSD `.pkg` archive on Linux.
- `ci/build-release.sh` - build/publish/test-deploy entrypoint.
- `deploy/opnsense/install-direct.sh` - direct package installer for OPNsense.
- `docs/FIRST_RUN.md` - exact first-run commands.

## Build trigger

A build starts when either:

- this packaging repository changes, or
- the fetched RustProxy commit changes.

`APP_REPO_REF=HEAD` follows the current default branch. A tag or branch can be pinned in `/etc/rustproxy-opnsense-builder.env`.

## Output

After a successful run:

```text
dist/
├── BUILD-INFO.txt
├── SHA256
├── os-rustproxy-latest.pkg
├── docker-build/rust-proxy
└── packages/26.7/amd64/os-rustproxy-<version>_<revision>.pkg
```

This version intentionally produces an installable `.pkg`, not a full `pkg repo` catalogue. Installation/update is currently done with `pkg add -f`.

The Linux-side package builder validates the FreeBSD package payload before publishing it: payload paths must be absolute (`/usr/local/...`), no undeclared directory entries are archived, and every payload file must have an identical entry in `+MANIFEST`.

## OPNsense UI

The OPNsense page **Services -> RustProxy** exposes enable/disable plus separate bind-address and port settings for HTTP, HTTPS/TLS and administration. On OPNsense/FreeBSD RustProxy runs as `root`.

## Validation

```sh
./scripts/check.sh
```

See `docs/FIRST_RUN.md` for Debian setup.

## OPNsense listener settings

The OPNsense page **Services -> RustProxy** exposes the runtime listeners used by the rc.d service:

- HTTP bind address + port: `0.0.0.0` / `8080`
- HTTPS/TLS bind address + port: `0.0.0.0` / `8181` (toggleable)
- Admin bind address + port: `0.0.0.0` / `9090`
- Allow remote admin: on by default so the RustProxy panel can be reached from other hosts; OPNsense firewall rules still decide which networks can connect

On OPNsense/FreeBSD the service runs as `root` and keeps `/var/db/rustproxy` mode `0700`. This avoids startup/access failures seen after privilege dropping with `daemon -u rustproxy`. Package installation restarts `configd` so `configctl rustproxy ...` actions are immediately available even after direct `pkg add`. When RustProxy is enabled, the package post-install hook also restarts it after `pkg upgrade`/`pkg add -f`, so an upgrade does not leave the service stopped.

Allocator tuning is platform-native: Linux packages use `MALLOC_ARENA_MAX=2` for glibc, while this FreeBSD/OPNsense service exports `MALLOC_CONF=narenas:2` for jemalloc. Override it with `rustproxy_malloc_conf` in rc.conf, or set the value empty to disable the tuning.

## FreeBSD/OPNsense-only RustProxy patches

Version-specific application patches live under `builder/freebsd/patches/<RustProxy-version>/`.
They are **not** applied to `/opt/opn-rustproxy/source/RustProxy` and are never pushed back to the RustProxy repository.
`builder/debian/build-docker-release.sh` creates an isolated source copy under `dist/.build-source/`, runs `builder/freebsd/apply-patches.sh` there, and mounts only that patched copy into the Docker build container.

For RustProxy `0.20.0` the patch set is:

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

Set `APPLY_FREEBSD_PATCHES=0` in `/etc/rustproxy-opnsense-builder.env` only when you explicitly want to test the unpatched upstream source.

### Runtime PID directory

The OPNsense rc.d service creates `/var/run/rustproxy` as `root:wheel` (0750) on every start. Both supervisor and child PID files live there. The runtime is kept as root on OPNsense/FreeBSD because privilege dropping caused real-world startup and data/certificate access failures.

### Listener compatibility note

Plugin model 1.3 stores bind addresses and ports separately. This prevents malformed rendered arguments such as `--tls-listen 0.0.0.0:`. Existing 1.2.x combined `proxyListen`, `tlsListen` and `adminListen` values remain accepted by rc.d during upgrades. If a legacy value is malformed, rc.d falls back to the documented default instead of passing an invalid listener to RustProxy.