NGRProxy

NGRProxy is an OpenWrt/LuCI app that manages nginx reverse-proxy configuration through UCI with hardened defaults, DHCP-aware upstream selection, and transactional config publishing.

Highlights

• UCI-first OpenWrt model (/etc/config/ngrproxy).
• Per-host classes:
  • http_host for HTTP/TLS reverse proxies.
  • stream_host for encrypted TCP passthrough (mail and similar protocols).
• Secure HTTPS upstream handling:
  • requires SNI (upstream_sni),
  • requires trusted CA bundle (upstream_ca),
  • enforces verification for HTTPS backends.
• Upstream host dropdown populated from:
  • static DHCP leases (/etc/config/dhcp),
  • dynamic leases (/tmp/dhcp.leases).
• LuCI preview helper with upstream URL + favicon thumbnail fallback.
• Optional screenshot thumbnail endpoint integration via LuCI controller redirect.
• Per-host ACL controls for HTTP and stream hosts.
• Optional PROXY protocol support for stream listeners/upstreams.
• Legacy config migration utility (/usr/libexec/ngrproxy/migrate.sh).
• Transactional renderer rollback if nginx -t fails.

Package layout

• luci-app-ngrproxy/Makefile
• luci-app-ngrproxy/luasrc/controller/ngrproxy.lua
• luci-app-ngrproxy/luasrc/model/cbi/ngrproxy.lua
• luci-app-ngrproxy/root/etc/config/ngrproxy
• luci-app-ngrproxy/root/etc/init.d/ngrproxy
• luci-app-ngrproxy/root/usr/libexec/ngrproxy/migrate.sh
• luci-app-ngrproxy/root/usr/libexec/ngrproxy/render.sh
• luci-app-ngrproxy/root/usr/share/rpcd/acl.d/luci-app-ngrproxy.json
• scripts/run-sdk-package-tests.sh

Deploy (OpenWrt buildroot or SDK)

1. Add/copy luci-app-ngrproxy into your OpenWrt feed tree.
2. Run:
   • ./scripts/feeds update -a
   • ./scripts/feeds install luci-app-ngrproxy
3. Enable package in make menuconfig.
4. Build and install package.

For SDK compile checks from this repository, run:

scripts/run-sdk-package-tests.sh /path/to/openwrt-sdk [more-sdk-paths...]

The SDK helper installs LuCI feed dependencies, copies the app into package/feeds/luci/applications/luci-app-ngrproxy, and builds there so the package Makefile can resolve ../../luci.mk in the standard LuCI feed layout.

Runtime notes

1. Ensure nginx includes:
   • include /etc/nginx/conf.d/*.conf; in http {}
   • include /etc/nginx/stream.d/*.conf; in stream {}
2. Configure hosts in LuCI and apply/reload the ngrproxy service.
3. Generated config files:
   • /tmp/ngrproxy/generated.http.conf
   • /tmp/ngrproxy/generated.stream.conf
4. Generated symlinks:
   • /etc/nginx/conf.d/zz-ngrproxy-generated.conf
   • /etc/nginx/stream.d/zz-ngrproxy-generated.conf
5. The renderer creates /tmp/ngrproxy on first run before writing generated output.
6. The renderer validates the candidate config with nginx -t and writes details to /tmp/ngrproxy.nginx-test.log.
7. If nginx -t fails, NGRProxy restores the previous generated files when present, or removes newly-created generated files/symlinks when no previous files existed.

Configuration notes

• For http_host, enable at least one of listen_http or listen_https.
• HTTPS listeners require tls_cert and tls_key files.
• HTTPS upstreams require upstream_sni and upstream_ca; nginx upstream certificate verification remains enabled.
• acl_allow can be used on HTTP and stream hosts; acl_deny_all=1 denies clients not explicitly allowed.
• Stream hosts can set:
  • listen_proxy_protocol=1 to expect PROXY protocol from downstream clients/load balancers,
  • send_proxy_protocol=1 to forward PROXY metadata to upstream.
• Optional global screenshot endpoint:
  • Set settings.thumbnail_endpoint with a %s placeholder; the URL-encoded upstream URL is substituted.

Migration behavior

Legacy migration is intentionally conservative:

• /usr/libexec/ngrproxy/migrate.sh converts legacy host / proxy sections into http_host sections.
• The service runs migration during start_service() only when settings.enabled=1.
• Migration is guarded by /etc/ngrproxy/.migrated-v1 to avoid repeated rewrites.
• If you need migration before enabling the service, run /usr/libexec/ngrproxy/migrate.sh manually on the router, then review and commit UCI state as needed.