v0.35.1: performance, AGPL licensing and documentation overhaul
- Web Server reads static files inline; proxy middleware chain flattened - About window with license summary and project links; AGPL-3.0-or-later - Rewritten documentation: feature list, screenshots, performance guide - Fix false spikes in per-Vhost request-rate charts Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MMsgSXoK4Bph2vU6fSBkAH
This commit is contained in:
135 files changed
+1425
-1064
No files matched your search
+5
-6
@@ -2,8 +2,7 @@
|
||||
|
||||
Access control can be configured globally, on a Vhost and on selected Custom locations. Policies are **cumulative**: a more specific allow rule does not cancel a denial at a broader level. Changes should be tested with both an allowed and a denied client.
|
||||
|
||||
## Global block / allow policy (0.34.13)
|
||||
|
||||
## Global block / allow policy
|
||||
**Settings → Rules & headers → Global block / allow** applies to public HTTP traffic across all vhosts, redirects and not-found hosts before upstream access. In addition to the existing User-Agent deny patterns, use the global country block/allow list (ISO two-letter codes), client IP/CIDR and allow-only DNS ACL, HTTP method policy, request Content-Type denylist and shared per-IP rate limit. All are disabled by default except previously configured User-Agent blocking. An explicit IP allow does **not** bypass the country policy: both must permit a request. Missing GeoIP country is allowed for country block mode and denied for country allow mode.
|
||||
|
||||
Global restrictions add to per-vhost and path rules. Rate-limit requests are counted for each client IP **across** vhosts. Prefer a conservative shared ceiling to avoid blocking shared NAT clients. A global method denial returns 405, the content-type/ACL/UA policy returns 403, and the shared rate limiter returns 429 with `Retry-After`. Admin and TCP/UDP stream listeners are outside this HTTP scope. For global response headers, use the adjacent **Security headers** subtab; see [Security](SECURITY.md).
|
||||
@@ -39,11 +38,11 @@ New Vhosts store an explicit `authentication` choice; old Vhosts with only `tiny
|
||||
|
||||
- **Basic Auth:** protect selected Vhosts with configured credentials. Use HTTPS so credentials are not sent over plaintext.
|
||||
- **Tinyauth:** add a verification URL and an HTTPS login URL. RustProxy makes a bounded, body-free authorization request and can pass specifically allowed identity headers upstream. An origin URL automatically uses `/api/auth/nginx` (or set that path explicitly). This Nginx auth-request integration sends `X-Original-URL` and `X-Original-Method`, with a validated `X-Forwarded-For` and `X-Real-IP` for Tinyauth IP ACLs. It does **not** send `X-Forwarded-Host` or `X-Forwarded-URI` to the verifier, avoiding the `conflicting auth module headers` rejection introduced in Tinyauth 5.2.0 while keeping compatibility with earlier versions that implement the Nginx endpoint. Tinyauth has its own timeout and private-backend policy.
|
||||
- **Provider-neutral gateway error pages (0.34.15):** One embedded `src/admin/web/error_auth_provider.html` template renders a self-contained HTML page for **Tinyauth, Authelia, authentik, and future providers**, using only the safe provider display name and the failure category. It replaces the three vendor-specific `error_tinyauth_*.html` source files while preserving the familiar Tinyauth response titles and statuses. For example: `502 Tinyauth connection error` if its HTTP client cannot reach Tinyauth (DNS/TCP/TLS/transport), `504 Tinyauth timeout` if the auth deadline expires, or `502 Tinyauth verification error` for unexpected verifier status or invalid/oversized data. The page always retains the HTTP error status, `Content-Type: text/html; charset=utf-8`, `Cache-Control: private, no-store` and `X-Content-Type-Options: nosniff`. Backend URLs, protocol errors and identity data are not shown to visitors. All of these cases **deny access** to the protected origin. HTTP `401`/`403` and configured login redirects remain unchanged. These auth-specific pages take precedence over custom Vhost/general HTTP error pages so the failure remains distinguishable. The generic failure marker also protects Basic Auth denials and provider login redirects from being replaced by Vhost pages. HTTPS-verifier transport errors are classified as connection failures, truncated/oversized/invalid verifier responses as verification failures, and verification deadlines as timeouts.
|
||||
- **Provider-neutral gateway error pages:** One embedded `src/admin/web/error_auth_provider.html` template renders a self-contained HTML page for **Tinyauth, Authelia, authentik, and future providers**, using only the safe provider display name and the failure category. It replaces the three vendor-specific `error_tinyauth_*.html` source files while preserving the familiar Tinyauth response titles and statuses. For example: `502 Tinyauth connection error` if its HTTP client cannot reach Tinyauth (DNS/TCP/TLS/transport), `504 Tinyauth timeout` if the auth deadline expires, or `502 Tinyauth verification error` for unexpected verifier status or invalid/oversized data. The page always retains the HTTP error status, `Content-Type: text/html; charset=utf-8`, `Cache-Control: private, no-store` and `X-Content-Type-Options: nosniff`. Backend URLs, protocol errors and identity data are not shown to visitors. All of these cases **deny access** to the protected origin. HTTP `401`/`403` and configured login redirects remain unchanged. These auth-specific pages take precedence over custom Vhost/general HTTP error pages so the failure remains distinguishable. The generic failure marker also protects Basic Auth denials and provider login redirects from being replaced by Vhost pages. HTTPS-verifier transport errors are classified as connection failures, truncated/oversized/invalid verifier responses as verification failures, and verification deadlines as timeouts.
|
||||
- Point the verifier URL **directly** at the private Tinyauth service (for example `http://tinyauth:3000/api/auth/nginx`), rather than routing it through a second public proxy that might inject conflicting headers. Do not disable Tinyauth's header-spoofing protections. Confirm that Tinyauth trusts only the actual RustProxy address/network when enabling Tinyauth IP-based access controls (`TINYAUTH_AUTH_TRUSTEDPROXIES`).
|
||||
- **Authelia (0.34.15):** select **Authelia → Forward Auth** under **Vhost → Authentication**. Enter the internal service origin (for example `http://authelia:9091`) and the public HTTPS login portal (for example `https://auth.example.com`); RustProxy calls `/api/authz/forward-auth`. It forwards trusted `X-Forwarded-*`, `X-Original-URL` and `X-Original-Method` metadata, verifies the provider result, returns provider-approved `302/303` login redirects only to the configured portal origin, and forwards configured `Remote-*` identity headers after stripping client-forged values. A `200` verifier response alone grants access. `401`/`403` deny; transport failures return 502 and timeouts 504. The Authelia `session.cookies` domains and `authelia_url` are defined in Authelia itself: protecting **unrelated registered domains** generally requires a login URL/cookie configuration within each domain, not one cookie from a single unrelated site.
|
||||
- **authentik (0.34.15):** select **authentik → Forward Auth** and enter the private outpost origin (for example `http://authentik:9000`), not an `/if/flow` login URL. RustProxy calls `/outpost.goauthentik.io/auth/nginx`, forwards verified `X-Authentik-*` identity headers, and responds to a `401` with a same-origin login start at `/outpost.goauthentik.io/start?rd=...`. RustProxy reserves `/outpost.goauthentik.io` (and descendants) on the protected application hostname and forwards them to the configured outpost **without checking authentication again**, after ordinary global/Vhost IP/country/rate rules. No manual Custom Location is needed for that path. In authentik create a separate **Proxy Provider → Forward auth (single application)** for each protected external application URL, assign it to the serving outpost, then enable that Vhost's integration. Multiple unrelated domains can share the same authentik installation; they do **not** share a browser cookie across domains.
|
||||
- **OIDC (0.34.16, opt-in):** choose **Authelia → OIDC**, **authentik → OIDC**, **Pocket ID → OIDC** or **Other OIDC provider → OIDC** for the protected Vhost. This switches to the shared OIDC implementation instead of the vendor's Forward Auth adapter. Provide the exact HTTPS **Issuer**, Client ID and confidential Client Secret, a strong unique Session Secret (`openssl rand -hex 32`), and `https://YOUR-EXACT-APP-HOST/_rustproxy/oidc/callback` as the **Redirect URL**. Register that exact callback as an allowed redirect URI in the identity provider. The issuer can be `https://auth.example.com.cc` while the protected hostname is `app.linuxiarz.pl`; browser cookies do not cross between them. The issuer's discovery `/.well-known/openid-configuration`, authorization, token and JWKS endpoints must resolve from RustProxy and use the issuer's HTTPS origin with trusted TLS. Use split DNS or the private-address opt-in if the issuer resolves to internal addresses; do not disable HTTPS certificate validation. OIDC currently requires a confidential client using `client_secret_basic`, authorization-code flow, and an RS256 or ES256 signing key. Public PKCE-only clients are not supported.
|
||||
- **Authelia:** select **Authelia → Forward Auth** under **Vhost → Authentication**. Enter the internal service origin (for example `http://authelia:9091`) and the public HTTPS login portal (for example `https://auth.example.com`); RustProxy calls `/api/authz/forward-auth`. It forwards trusted `X-Forwarded-*`, `X-Original-URL` and `X-Original-Method` metadata, verifies the provider result, returns provider-approved `302/303` login redirects only to the configured portal origin, and forwards configured `Remote-*` identity headers after stripping client-forged values. A `200` verifier response alone grants access. `401`/`403` deny; transport failures return 502 and timeouts 504. The Authelia `session.cookies` domains and `authelia_url` are defined in Authelia itself: protecting **unrelated registered domains** generally requires a login URL/cookie configuration within each domain, not one cookie from a single unrelated site.
|
||||
- **authentik:** select **authentik → Forward Auth** and enter the private outpost origin (for example `http://authentik:9000`), not an `/if/flow` login URL. RustProxy calls `/outpost.goauthentik.io/auth/nginx`, forwards verified `X-Authentik-*` identity headers, and responds to a `401` with a same-origin login start at `/outpost.goauthentik.io/start?rd=...`. RustProxy reserves `/outpost.goauthentik.io` (and descendants) on the protected application hostname and forwards them to the configured outpost **without checking authentication again**, after ordinary global/Vhost IP/country/rate rules. No manual Custom Location is needed for that path. In authentik create a separate **Proxy Provider → Forward auth (single application)** for each protected external application URL, assign it to the serving outpost, then enable that Vhost's integration. Multiple unrelated domains can share the same authentik installation; they do **not** share a browser cookie across domains.
|
||||
- **OIDC (opt-in):** choose **Authelia → OIDC**, **authentik → OIDC**, **Pocket ID → OIDC** or **Other OIDC provider → OIDC** for the protected Vhost. This switches to the shared OIDC implementation instead of the vendor's Forward Auth adapter. Provide the exact HTTPS **Issuer**, Client ID and confidential Client Secret, a strong unique Session Secret (`openssl rand -hex 32`), and `https://YOUR-EXACT-APP-HOST/_rustproxy/oidc/callback` as the **Redirect URL**. Register that exact callback as an allowed redirect URI in the identity provider. The issuer can be `https://auth.example.com.cc` while the protected hostname is `app.linuxiarz.pl`; browser cookies do not cross between them. The issuer's discovery `/.well-known/openid-configuration`, authorization, token and JWKS endpoints must resolve from RustProxy and use the issuer's HTTPS origin with trusted TLS. Use split DNS or the private-address opt-in if the issuer resolves to internal addresses; do not disable HTTPS certificate validation. OIDC currently requires a confidential client using `client_secret_basic`, authorization-code flow, and an RS256 or ES256 signing key. Public PKCE-only clients are not supported.
|
||||
- **OIDC session and identity:** RustProxy generates short-lived transaction state with S256 PKCE and nonce; requires a signed ID token with exact issuer, audience, validity and nonce; and encrypts a separate `__Host-` session cookie for the application host (default 3600 seconds, max 86400). The session is **not continuously revalidated with the issuer**; removing a user at the issuer does not invalidate an already-issued RustProxy session before its expiry or local logout (`/_rustproxy/oidc/logout`). Successful login injects `Remote-Sub`, `Remote-Issuer`, `Remote-User` and optional `Remote-Email`, `Remote-Name`, `Remote-Groups`; use `(Remote-Issuer, Remote-Sub)` for stable account identity and do not auto-link accounts solely by email or username. The backend must not be directly accessible from untrusted clients. Non-GET/HEAD requests without a valid session receive 401, and authentication endpoint failures return 502/504. The provider URL must not itself be protected by this Vhost's OIDC integration. For Authelia, enabling its Forward Auth portal alone is insufficient: also configure Authelia as an OIDC issuer under `identity_providers.oidc`, with at least one signing key, and register a confidential client for every callback URL (or separate clients per application). OIDC does not require any special support from the application being proxied, only from the remote identity provider.
|
||||
|
||||
- **Adding another provider:** Register the vendor and supported methods in `auth_provider::choice::IdentityProvider` and in the Vhost editor. OIDC-compatible vendors reuse the shared `oidc` integration and may need no new Rust transport adapter. New Forward Auth adapters belong in `src/<provider>/mod.rs` with tests and may reuse `forward_auth::Adapter`; their compiled implementation implements the object-safe `auth_provider::Provider` trait. Runtime request handling continues through one `CompiledFrontend.auth_provider` slot and provider-neutral `error_auth_provider.html`. Preserve legacy Vhost configuration keys; add new providers without copying OIDC protocol code or HTML error templates.
|
||||
|
||||
+23
-2
@@ -37,6 +37,27 @@ Some paths have additional DELETE/PATCH operations, job-status resources, query
|
||||
|
||||
Certificate inspection accepts `{ "cert_file": "filename.pem" }` for a managed file or an absolute external path and returns `{ "cert_file": "...", "covered_hosts": ["example.com"] }`. It applies the existing certificate-file trust and size checks and reads no private key. It makes no configuration or permission changes. This POST requires the signed-in administrator's normal Origin, request-marker and CSRF checks; general RO/RW API tokens and certificate-only credentials cannot call it.
|
||||
|
||||
## Access and authentication
|
||||
|
||||
The administration listener is HTTP on loopback (`127.0.0.1:9090`) by default and is separate from the public Vhost listeners. No administrator password is bundled: complete first-time setup with the local CLI (`admin setup-token` or `admin init`). For remote access prefer an SSH tunnel; for direct access enable administration HTTPS with a trusted certificate and restrict the network before binding outside loopback.
|
||||
|
||||
| Credential | Scope |
|
||||
|---|---|
|
||||
| Browser session | Full administration. HttpOnly, SameSite=Strict cookie (Secure on HTTPS), absolute lifetime 7–30 days. Writes require matching Origin, `X-CSRF-Token` and `X-RustProxy-Request: 1`. |
|
||||
| General API token (`ro` / `rw`) | Created in **Settings → Security → API tokens**. Displayed once, stored as a hash, bound to a mandatory IP/CIDR allowlist. Sent as `Authorization: Bearer <token>`. `ro` reads resources and sections; `rw` also writes configuration sections and selected operations. Cannot manage authentication, backups, tokens or certificate credentials. |
|
||||
| Certificate API key | Key ID + Bearer token limited to specific certificate IDs and actions (reload by default, deploy opt-in). |
|
||||
| Prometheus token | Scrape-only credential for the separate exporter; see [Monitoring](MONITORING.md). |
|
||||
|
||||
IP checks use the transport peer, never forwarded headers. Outside loopback, Bearer credentials require administration HTTPS.
|
||||
|
||||
### `/docs` Reader and Swagger
|
||||
|
||||
The authenticated `/docs` page has two tabs: **Reader** with the guides embedded at build time, and **API** with the bundled OpenAPI schema rendered by Swagger UI. All assets are served locally; no CDN is used. Swagger uses the current session, executes read calls directly and asks for confirmation before any write.
|
||||
|
||||
### Publishing the panel behind a reverse proxy
|
||||
|
||||
This is a special-risk topology. Configure a fixed HTTPS public origin, an allowed hostname and a trusted forwarding boundary. Ordinary public Vhosts never forward administration cookies to an upstream. Re-test CSRF/Origin validation and cookie security after any topology change.
|
||||
|
||||
## Authentication and safe writes
|
||||
|
||||
- Ordinary API calls require an administrator browser/session cookie on the admin listener, or a scoped general API Bearer token for explicitly allowlisted API methods/paths. Browser-session writes require the matching Origin, `X-CSRF-Token` and `X-RustProxy-Request: 1`, in addition to Host validation. Scoped Bearer-token requests are exempt from browser CSRF requirements; the server enforces the token permission, source IP allowlist and HTTPS for non-loopback access instead.
|
||||
@@ -79,7 +100,7 @@ The section name in the URL and its corresponding JSON member in a full configur
|
||||
| `logging` | `logging`, `error_log` |
|
||||
| `global-security` | `global_security`, including `user_agent_blocking` |
|
||||
|
||||
Every GET returns a `value` object or array whose shape can be sent unchanged to the matching PUT. For the three grouped sections the `value` contains exactly the named members; for the other sections it is the serialized value of the matching configuration member. Saving does not alter unrelated sections. In 0.34.16 an ordinary Vhost may configure mutually exclusive `oidc`, `authelia` and `authentik` objects alongside existing `tinyauth`/`basic_auth` settings; every optional provider defaults to disabled. OIDC uses `/_rustproxy/oidc/callback` on an exact Vhost HTTPS hostname and requires issuer/client/session secrets. See [Access](ACCESS.md).
|
||||
Every GET returns a `value` object or array whose shape can be sent unchanged to the matching PUT. For the three grouped sections the `value` contains exactly the named members; for the other sections it is the serialized value of the matching configuration member. Saving does not alter unrelated sections. An ordinary Vhost may configure mutually exclusive `oidc`, `authelia` and `authentik` objects alongside existing `tinyauth`/`basic_auth` settings; every optional provider defaults to disabled. OIDC uses `/_rustproxy/oidc/callback` on an exact Vhost HTTPS hostname and requires issuer/client/session secrets. See [Access](ACCESS.md).
|
||||
|
||||
### Complete section-update example
|
||||
|
||||
@@ -130,4 +151,4 @@ Authorization: Bearer <secret>
|
||||
X-RustProxy-Certificate-Key: <key-id>
|
||||
```
|
||||
|
||||
The credential can be used only for allowed certificate reload/deploy operations, not configuration, users, metrics or secret management. Non-loopback use requires the appropriate administration HTTPS security boundary. Rotate broad or legacy credentials. See [API access](API_ACCESS.md) and [Certificates](ACME_PROVIDERS.md).
|
||||
The credential can be used only for allowed certificate reload/deploy operations, not configuration, users, metrics or secret management. Non-loopback use requires the appropriate administration HTTPS security boundary. Rotate broad or legacy credentials. See [Certificates](CERTIFICATES.md).
|
||||
@@ -1,35 +0,0 @@
|
||||
# Administration authentication and API access
|
||||
|
||||
## Default exposure and setup
|
||||
|
||||
The administration listener uses **HTTP loopback (`127.0.0.1:9090`) by default** and is separate from normal Vhost listeners. No administrator password is bundled. Use the local CLI `admin setup-token` or `admin init` to complete first-time setup. For access from another workstation, prefer an SSH tunnel; for direct remote operation, enable **administration HTTPS**, configure a trusted certificate and narrow network access before binding outside loopback.
|
||||
|
||||
## Session security
|
||||
|
||||
Administrator sessions use an HttpOnly, SameSite=Strict cookie, with Secure on HTTPS. Expiry is bounded by the configured absolute lifetime (7–30 days, default 30). Logout, password changes and revoke-all terminate sessions. API mutations are validated for Host/Origin, CSRF token and request marker; a cookie copied into automation is not an approved general-purpose API token.
|
||||
|
||||
Unauthenticated endpoints intentionally expose only minimal setup/sign-in and health behavior. Configuration, operational status, dashboard assets, file logs, the API specification and the documentation Reader require authentication. Admin responses use no-store and security headers, and the browser does not expose the full application state before sign-in.
|
||||
|
||||
## `/docs` Reader and Swagger
|
||||
|
||||
The authenticated documentation page has two tabs: **Reader**, embedding the registered Markdown guides at compile time, and **API**, displaying the bundled OpenAPI schema. Both are local assets; no runtime CDN access is required for viewing the reference. A document edit affects the shipped reader **only after rebuilding** RustProxy.
|
||||
|
||||
Swagger uses the current signed-in session, not a new broad credential. It requires explicit confirmation for write operations. Treat the OpenAPI schema as a request guide and RustProxy's field/authorization validation as the final authority.
|
||||
|
||||
## Publishing the panel behind a reverse proxy
|
||||
|
||||
This is a **special-risk topology**, not the default. Configure a fixed HTTPS public origin/allowed hostname and a trusted forwarding boundary. RustProxy has an explicit narrowly constrained local-listener exception, but a normal public Vhost must not pass administration cookies to an ordinary upstream. Forwarded Host/Proto values are trusted only when the direct peer satisfies the configured trust rules. Test CSRF/Origin validation and cookie security after a topology change.
|
||||
|
||||
## General administration API tokens (0.34.1 DEV)
|
||||
|
||||
Settings → **Security → API tokens (RO/RW)** generates a one-time-displayed opaque Bearer credential, with `ro` (read) or `rw` (read/write) permission and a **mandatory allowlist of client IPs or CIDRs**. The token is stored only as a hash; save it securely at creation or generate a replacement. Deleting a token revokes it immediately. The existing browser session workflow is unchanged; this is not a browser login/password substitute.
|
||||
|
||||
Send `Authorization: Bearer <token>` to the administration listener over HTTPS outside loopback. IP checks use the transport peer, not spoofable forwarded headers. Only the narrowly allowlisted `/api/*` resource routes are usable: RO is read-only, RW adds selected configuration and operational operations. Tokens cannot access authentication, backups, documentation, other token creation/revocation, certificate API management, or unrestricted administrator endpoints. The separate certificate-only API credentials work independently. The **Settings → Administration** page includes a direct link to token management.
|
||||
|
||||
## Certificate-only credentials
|
||||
|
||||
Certificate API Key ID + Bearer credentials are limited by certificate ID and by allowed action (reload by default; deploy opt-in). They do not grant login or administrative configuration access. Revocation/rotation are administrator-only actions. Keep tokens out of logs and pass them over HTTPS outside loopback.
|
||||
|
||||
## Offline build assets
|
||||
|
||||
Swagger JavaScript/stylesheets are prepared by the build and embedded behind authentication. If compilation fails during Swagger asset preparation, inspect `build.rs` and `scripts/build/swagger_assets.py` and ensure the required checked/downloaded asset inputs are available. Do not replace these authenticated assets with an unaudited public CDN workaround.
|
||||
+4
-7
@@ -2,8 +2,7 @@
|
||||
|
||||
RustProxy provides an optional shared HTTP response cache with a bounded in-memory **HOT** tier and optional persistent-disk **COLD** tier. Both the global cache and a Vhost's effective policy must permit caching. **COLD storage is disabled by default**, and newly created Vhosts do not automatically cache dynamic content.
|
||||
|
||||
### Cache controls in Settings (0.34.13)
|
||||
|
||||
### Cache controls in Settings
|
||||
The static-extension cookie-bypass warning sits with its extension list, separate from **Cache response headers** options. Only enable this optimization for files whose bytes do not depend on the user's session. `Cookie` can then be omitted from the shared cache key for the configured extensions; responses with `Set-Cookie`, `private`, `no-store` or `Vary: Cookie` remain uncacheable.
|
||||
|
||||
## Enable caching safely
|
||||
@@ -14,8 +13,7 @@ The static-extension cookie-bypass warning sits with its extension list, separat
|
||||
4. Optionally enable HIT-only diagnostics. Send repeated identical requests using `curl`, then inspect **Cache → Domains / Stored objects** for `MISS → HIT`.
|
||||
5. Review **Varnish-compatible cache policy**, enabled by default, then check TTL, revalidation and invalidation after updating the origin's content or configuration.
|
||||
|
||||
## Varnish-compatible cache policy (0.34.7)
|
||||
|
||||
## Varnish-compatible cache policy
|
||||
**Settings → Cache → Varnish-compatible cache policy** (`cache.varnish_compatible`, **enabled by default**) avoids needless cache replacement on browser hard reloads. On a fresh object it ignores only the client's `Cache-Control: no-cache`, `max-age=0` and `Pragma: no-cache` for cache **lookup/freshness**. It does not remove or modify these request headers when fetching from the origin, and it does not alter cache identity or request conditionals.
|
||||
|
||||
Set **Default grace (seconds)** in Settings → Cache (default **60**, range 0..604800). This affects only eligible objects in compatibility mode and never overwrites explicit origin `stale-while-revalidate`, including `=0`. Use the adjacent **i** information icon for the short operator explanation (PL/EN). Disabling the option restores the original strict client reload semantics. Changing modes invalidates currently stored representations across HOT/COLD so they are refilled under one consistent policy; no process restart is needed. Existing JSON configurations with no field inherit `true`. The setting also applies to eligible resources of the embedded Web Server.
|
||||
@@ -84,8 +82,7 @@ done
|
||||
|
||||
Look for cache reason labels including `request_cookie`, `request_authorization`, `response_cache_control`, `route_disabled` and `cache_hit` when diagnostic headers are enabled. A `MISS` alone does not prove the object was admitted to HOT/COLD.
|
||||
|
||||
## Cache response headers and upstream diagnostics (0.34.12)
|
||||
|
||||
## Cache response headers and upstream diagnostics
|
||||
**RFC 9211:** `Cache-Status` is a structured list of cache hops, ordered from the origin-side cache toward the client. RustProxy **does not replace or suppress** an upstream `Cache-Status`. When **Settings → Cache → Expose Cache-Status** is enabled and RustProxy makes a cache decision, it appends its own `RustProxy` member to the existing list; multiple HTTP header fields are an equivalent wire representation of the same list. There is no `backend=hit/miss` parameter: the upstream's own members already describe its cache decisions.
|
||||
|
||||
For example, with an upstream HIT and a RustProxy HIT:
|
||||
@@ -134,7 +131,7 @@ The initial request can show `RustProxy; fwd=miss`; an eligible repeat should sh
|
||||
|
||||
Authenticated Cache page/API operations can purge selected entries, domains or larger scopes. The optional public HTTP `PURGE`/`BAN` interface is **disabled by default**. Enable it only by listing trusted client IPs/CIDRs under **Settings → Cache → HTTP BAN / PURGE IP allowlist**; operations are additionally subject to Vhost binding and normal access controls. `PURGE` addresses an exact URL; `BAN` applies the supported bounded matching rules. Never allow untrusted Internet clients to purge all tenants' objects.
|
||||
|
||||
In 0.34.0, changing operational Vhost settings is intended to preserve compatible HOT/COLD objects; content-affecting changes invalidate affected scopes and COLD carries an additional fingerprint against stale resurrection. **This new behavior still needs release-level verification**, so validate cache after configuration edits and during upgrades. Earlier persistent cache entries may need refilling following format/compatibility transitions.
|
||||
Changing operational Vhost settings is intended to preserve compatible HOT/COLD objects; content-affecting changes invalidate affected scopes and COLD carries an additional fingerprint against stale resurrection. **This new behavior still needs release-level verification**, so validate cache after configuration edits and during upgrades. Earlier persistent cache entries may need refilling following format/compatibility transitions.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
||||
@@ -11,8 +11,7 @@ ancestor even though it can host a Web Server document root. See
|
||||
[Installation: external paths](INSTALL.md#linux-debrpm-read-only-access-to-external-paths)
|
||||
for scoped ACLs and Certbot renewal handling.
|
||||
|
||||
### Certificate file permission command preview (0.34.13)
|
||||
|
||||
### Certificate file permission command preview
|
||||
The permissions explanation now appears next to generated read/traversal ACL commands, rather than alongside the path inputs. The **Copy commands** action is offered only after a valid path selection produces a command preview. These commands grant read access to the certificate/private key and traversal of parent directories; they do not grant write permission.
|
||||
|
||||
## Supported certificate methods
|
||||
@@ -37,7 +36,7 @@ HTTP-01 cannot create wildcard certificates; use DNS-01. A staging certificate i
|
||||
5. Wait for the job result; inspect errors under Certificates and the service logs.
|
||||
6. Assign the issued/imported certificate to the intended Vhost/listener and verify a real TLS handshake with the public hostname.
|
||||
|
||||
In 0.34.1 DEV, expand a certificate in the Certificates inventory and use **Assign Vhosts** to check/uncheck multiple Vhosts before applying one revisioned Vhost-section save. This updates Vhost certificate mappings, not the PEM files themselves. Verify frontend listener and certificate hostname coverage separately.
|
||||
Expand a certificate in the Certificates inventory and use **Assign Vhosts** to check/uncheck multiple Vhosts before applying one revisioned Vhost-section save. This updates Vhost certificate mappings, not the PEM files themselves. Verify frontend listener and certificate hostname coverage separately.
|
||||
|
||||
The reserved HTTP-01 challenge path is available only during eligible issuance/renewal work. It is not a generic public file server and does not bypass authentication for unrelated URLs.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Most settings are managed in the authenticated panel. Save changes after validation; use **Configuration history** to compare or restore an earlier revision. Some listeners are process-owned and require restart to change. Configuration updates are not a replacement for encrypted full backups.
|
||||
|
||||
> Cache compatibility: **Settings → Cache → Varnish-compatible cache policy** (`cache.varnish_compatible`) defaults to `true` in 0.34.7, also for configs without the field. Turning it off restores legacy client freshness handling. Implicit grace defaults to **60 seconds** (`cache.varnish_grace_seconds`, editable in Settings → Cache). See [HTTP cache](CACHE.md#varnish-compatible-cache-policy-0347) for semantics and safety exceptions.
|
||||
> Cache compatibility: **Settings → Cache → Varnish-compatible cache policy** (`cache.varnish_compatible`) defaults to `true`, also for configurations without the field. Turning it off restores legacy client freshness handling. Implicit grace defaults to **60 seconds** (`cache.varnish_grace_seconds`, editable in Settings → Cache). See [HTTP cache](CACHE.md#varnish-compatible-cache-policy) for semantics and safety exceptions.
|
||||
|
||||
## Configuration storage: SQLite or JSON file
|
||||
|
||||
@@ -64,13 +64,12 @@ ACLs support IP/CIDR and **allow-only** DNS/DDNS hostname rules, plus reusable p
|
||||
|
||||
Global response headers, per-Vhost rules and Web Service-specific headers are distinct scopes. Security and proxy-protocol headers may be protected from rewriting. Compression supports eligible response encodings; availability is still constrained by global limits and the requesting client.
|
||||
|
||||
### Global HTTP block / allow and security headers (0.34.13)
|
||||
|
||||
### Global HTTP block / allow and security headers
|
||||
Under **Settings → Rules & headers**, choose **Global block / allow** to configure rules applying to every public HTTP vhost, redirect and 404 host. Independent controls cover **country block/allow**, global **User-Agent deny patterns**, **IP/CIDR and allow-only DNS ACL**, **HTTP method allow/block**, **request Content-Type denylist** and a **shared per-client-IP rate limit**. Disabled policies are neutral. If country allow mode is selected, an unknown GeoIP country is denied; block mode permits unknown countries. Global IP and country checks are cumulative, as are global rules and more restrictive per-vhost policies. Verify the trusted client-IP and GeoIP configuration before enabling country or rate controls. The global rate limit uses the same bucket for a given client across all public vhosts. It does not affect TCP/UDP streams or the separate administration listener.
|
||||
|
||||
The adjacent **Security headers** subtab applies a global response baseline: **HSTS** (HTTPS only), **nosniff**, **X-Frame-Options**, **Referrer-Policy**, **Content-Security-Policy** and **Permissions-Policy**. Explicit per-vhost security-header values take precedence; absence of a vhost value does not cancel a global header. Test HSTS and CSP against all sites before enabling. **Global custom headers** remains a distinct subtab for arbitrary request/response header rules.
|
||||
|
||||
In the updated **0.34.13** API, global User-Agent blocking is nested at `config.global_security.user_agent_blocking`; it is no longer a separate root-level setting. Example (only the relevant fragment):
|
||||
Global User-Agent blocking is nested at `config.global_security.user_agent_blocking`; it is no longer a separate root-level setting. Example (only the relevant fragment):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -87,7 +86,7 @@ On upgrade, older JSON, database rows, backups and revision history containing a
|
||||
|
||||
## Cache and transforms
|
||||
|
||||
Caching is opt-in. HOT holds bounded memory entries; COLD is an optional disk tier (off by default). Freshness follows eligible HTTP policy and `Vary`; private/no-store responses and protected requests are not shared. Configuration saves can selectively invalidate affected cached responses; 0.34.0 behavior needs production validation. HTTP BAN/PURGE is **disabled by default** and uses an explicit source-IP allowlist. See [Cache](CACHE.md).
|
||||
Caching is opt-in. HOT holds bounded memory entries; COLD is an optional disk tier (off by default). Freshness follows eligible HTTP policy and `Vary`; private/no-store responses and protected requests are not shared. Configuration saves selectively invalidate only the affected cached responses. HTTP BAN/PURGE is **disabled by default** and uses an explicit source-IP allowlist. See [Cache](CACHE.md).
|
||||
|
||||
Response transformations are optional and apply only to configured eligible MIME types and scopes. See [Response delivery](RESPONSE_DELIVERY.md) for codec defaults, transformation limits and header precedence. Content rewriting can affect validators, compression and cache entries; test actual representations after configuration changes.
|
||||
|
||||
|
||||
@@ -1,38 +0,0 @@
|
||||
# Docker / OCI deployment
|
||||
|
||||
The included `Dockerfile` compiles RustProxy with a **Rust 1.99** build image and runs it on Debian as an unprivileged `rustproxy` account (UID 10001). It includes Python, Certbot and DNS-plugin packages for certificate handling. The main container does **not** need the Docker socket.
|
||||
|
||||
## Build and start
|
||||
|
||||
Run from the repository root:
|
||||
|
||||
```bash
|
||||
docker build -t rustproxy:0.34.2 .
|
||||
docker volume create rustproxy-data
|
||||
docker run -d --name rustproxy \
|
||||
-p 8080:8080 \
|
||||
-v rustproxy-data:/var/lib/rustproxy \
|
||||
rustproxy:0.34.2
|
||||
```
|
||||
|
||||
In the image, the default HTTP frontend binds `0.0.0.0:8080`. The admin listener defaults to `127.0.0.1:9090` **inside the container**. Simply publishing container port 9090 does not make that loopback listener reachable from a remote host. Initialize the administrator from a local container shell:
|
||||
|
||||
```bash
|
||||
docker exec rustproxy rust-proxy admin setup-token
|
||||
```
|
||||
|
||||
Provide a secure, private path for first-time panel access. If remote administration is required, configure its own HTTPS mode, certificate and an intentional non-loopback listener before mapping the port publicly; restrict it with firewall policy. Never expose plain HTTP administration as a convenience.
|
||||
|
||||
## Persistent data and ports
|
||||
|
||||
- Mount `/var/lib/rustproxy` persistently for SQLite, private keys, certificate profiles and optional COLD cache. Back it up securely and keep volume ownership correct.
|
||||
- Map the chosen HTTP and HTTPS TCP ports. If enabling HTTP/3, publish the corresponding **UDP** port too, and allow it through the host firewall.
|
||||
- If you need low-numbered **container** ports, use host-port forwarding or deliberate capability settings; the image runs without root privileges.
|
||||
- Store file access logs under a writable location/volume if enabled. The built-in on-disk access-log sink is not necessarily on by default.
|
||||
- Managed ACME material in the persisted volume survives container replacement. DNS credentials and external mounts must be protected and carried over separately.
|
||||
|
||||
For Docker-based application discovery, install the **separate Docker agent** on each target host and connect it over the supported restricted interface. See [Docker discovery](DOCKER_DISCOVERY.md).
|
||||
|
||||
## Upgrade and validate
|
||||
|
||||
Build a reviewed new image, preserve the volume, make an encrypted application backup and deploy with a maintenance window. Verify configuration compatibility, listener reachability, frontend certificates, backup/restore and live traffic. The supplied 0.34.2 development source candidate is not itself a production-tested OCI image.
|
||||
+1
-1
@@ -14,7 +14,7 @@ page has its own stylesheet.
|
||||
|
||||
The Overview contains live counters, charts and optional backend, cache, PHP, Docker and Stream cards. Under **Settings → Appearance → Dashboard layout** or the Overview editor, configure visibility, order, card width, density and the number of history samples. A hidden card stops consuming its optional browser-side visualization work but does not turn off its underlying proxy feature.
|
||||
|
||||
In 0.34.1, the unlocked Overview layout exposes a single **Save and lock** action (plus Cancel), removing the redundant lock-and-save button.
|
||||
The unlocked Overview layout exposes a single **Save and lock** action (plus Cancel), removing the redundant lock-and-save button.
|
||||
|
||||
**Dashboard Presets** supports up to **16 named layouts per administrator**. Save, load, rename, overwrite and delete presets; a factory layout can be restored. Presets preserve the dashboard arrangement, not the live traffic values. Interface theme, scale and other display settings are also account-scoped and do not alter proxy routing or rewrite shared configuration.
|
||||
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
# Feature list
|
||||
|
||||
RustProxy is a single service that combines a reverse proxy, a static/PHP web server, certificate management, an HTTP cache and traffic monitoring, all managed from a browser panel or an API. Optional features are disabled by default; enable only what you need.
|
||||
|
||||
|
||||
|
||||
## Reverse proxy
|
||||
|
||||
| Feature | Details |
|
||||
|---|---|
|
||||
| Vhosts | Exact and wildcard hostnames, aliases, several listeners per Vhost, per-Vhost HTTP/2 and HTTP/3 switches |
|
||||
| Backends | HTTP and HTTPS origins, HTTP/1.1, automatic ALPN (H2/H1), strict HTTP/2 and H2C, optional upstream certificate verification with custom CA and server name |
|
||||
| Load balancing | Least connections (default), round robin, least traffic, adaptive and IP hash; member weights, backup and draining members, sticky cookie or IP affinity |
|
||||
| Health checks | Active TCP or HTTP probes with thresholds and live health status per member |
|
||||
| Connection reuse | Bounded keep-alive pools with idle and age limits, pool recycling and protocol telemetry |
|
||||
| Custom locations | Prefix, exact and regex paths, path rewriting, per-location backends, Web Services, local responses, redirects and internal error fallbacks |
|
||||
| WebSockets | HTTP/1.1 Upgrade, RFC 8441 (HTTP/2) and RFC 9220 (HTTP/3) Extended CONNECT |
|
||||
| Forwarding headers | `X-Forwarded-*`, `Forwarded`, `X-Real-IP`, trusted proxy ranges, Cloudflare client IP and country |
|
||||
| Redirects and pages | Redirect hosts, canonical host and HTTPS redirects, 404 hosts, custom error pages and direct-IP pages |
|
||||
| TCP/UDP Streams | Layer-4 forwarding with backend pools, health checks, session limits and idle timeouts |
|
||||
|
||||
## Frontends and TLS
|
||||
|
||||
- HTTP/1.1, HTTPS with HTTP/2, optional HTTP/3 (QUIC) with `Alt-Svc` management and configurable UDP buffers.
|
||||
- Named listeners with per-listener protocols; Vhosts bind to listener IDs.
|
||||
- TLS 1.2/1.3 policy with cipher-suite allowlist and per-Vhost overrides.
|
||||
- Optional hybrid post-quantum key exchange (X25519MLKEM768).
|
||||
- SNI certificate selection, hot certificate reload without restart.
|
||||
|
||||
## Web Server
|
||||
|
||||
- Static sites and downloads served from reusable **Web Services** shared by several Vhosts.
|
||||
- Index files, optional directory listing, MIME mapping and attachment extensions.
|
||||
- `try_files`, regex rewrites and a safe subset of Apache `.htaccess` rules.
|
||||
- Conditional requests (`ETag`, `Last-Modified`), byte ranges, precompressed `.br`/`.gz` sidecars and optional Linux `sendfile`.
|
||||
- Symlink policy, attack-probe blocking and header hardening presets.
|
||||
- PHP through external PHP-FPM with shared profiles, per-application pools and resource limits.
|
||||
- Presets for single-page apps, WordPress and Roundcube.
|
||||
|
||||
|
||||
|
||||
## Certificates
|
||||
|
||||
- Self-signed certificates, PEM import and externally managed certificate paths (for example Certbot).
|
||||
- Managed ACME with HTTP-01 and DNS-01 (Cloudflare, OVH, RFC 2136), automatic renewal and job history.
|
||||
- Certificate inventory with expiry, coverage check and bulk assignment to Vhosts.
|
||||
- Restricted certificate API keys for deploy/reload from external systems such as OPNsense.
|
||||
|
||||
|
||||
|
||||
## Access and security
|
||||
|
||||
- IP/CIDR and DNS/DDNS allow/deny rules, reusable ACL profiles (up to eight per Vhost).
|
||||
- Country allow/deny lists with automatic GeoIP database updates.
|
||||
- Request rate limiting per Vhost and globally, with burst and `Retry-After`.
|
||||
- HTTP method policy, request Content-Type denylist and User-Agent blocking.
|
||||
- Security headers: HSTS, CSP, X-Frame-Options, Referrer-Policy, Permissions-Policy, `nosniff`.
|
||||
- HTTP Basic authentication with Argon2 hashes and brute-force limits.
|
||||
- Forward Auth with Tinyauth, Authelia and authentik; OIDC (Authorization Code + PKCE) with Authelia, authentik, Pocket ID and compatible providers.
|
||||
- Fail-closed authentication errors, identity header stripping and private/no-store responses for authenticated content.
|
||||
- Protection against private/loopback/control-plane upstream destinations unless explicitly allowed.
|
||||
|
||||
## Cache and delivery
|
||||
|
||||
- Shared HTTP cache with a memory tier (HOT) and an optional disk tier (COLD).
|
||||
- RFC 9111 freshness, validators and `Vary`; stale-while-revalidate, stale-if-error and request coalescing.
|
||||
- Varnish-compatible policy option, forced caching rules and per-location cache switches.
|
||||
- RFC 9211 `Cache-Status` and optional `X-Cache` diagnostics.
|
||||
- Purge and ban from the panel, the API or HTTP PURGE/BAN from allowlisted addresses.
|
||||
- Live compression with gzip, Brotli, Zstandard and deflate.
|
||||
- Optional minification of JavaScript, CSS, HTML, SVG and JSON with memory budgets.
|
||||
|
||||
|
||||
|
||||
## Monitoring and logs
|
||||
|
||||
- Overview dashboard with requests per second, bandwidth, status codes, cache hit ratio, protocol mix, system load and backend health.
|
||||
- Customizable dashboard layouts and saved presets.
|
||||
- Per-Vhost, per-backend, per-Web-Service and per-Stream statistics.
|
||||
- Live request log in the browser and in the terminal (`--livelogs`).
|
||||
- Stored JSON access logs with search syntax, per-Vhost log files and an error log.
|
||||
- Prometheus exporter with token/CIDR protection, JSON metrics and a compact summary endpoint.
|
||||
- Grafana dashboard and Nagios checks included.
|
||||
|
||||
|
||||
|
||||
## Operations
|
||||
|
||||
- Configuration stored in SQLite or in a JSON file, with validation before activation and hot reload.
|
||||
- Revision history with diff and one-click restore.
|
||||
- Encrypted full backups and validated offline restore; encrypted Secret Store for credentials.
|
||||
- Docker discovery through a separate agent: publish containers as Vhosts with one switch.
|
||||
- Nginx Proxy Manager import with a dry-run plan.
|
||||
- Managed install/update scripts with rollback, DEB/RPM packages, Docker image and an OPNsense plugin.
|
||||
- Panel in English and Polish, light and dark themes, adjustable density and corner style.
|
||||
|
||||
## Administration and API
|
||||
|
||||
- Panel served on a separate, loopback-only listener by default; optional HTTPS for remote administration.
|
||||
- Single administrator with Argon2 password, session revocation and CSRF/Origin protection.
|
||||
- Complete REST API described by a bundled OpenAPI schema with Swagger UI at `/docs`.
|
||||
- Scoped `ro`/`rw` API tokens bound to IP allowlists.
|
||||
- Command-line tools for setup, configuration, certificates, backups and live logs.
|
||||
|
||||
See the [screenshots](SCREENSHOTS.md) for a visual tour and the [documentation index](README.md) for detailed guides.
|
||||
+29
-10
@@ -11,7 +11,7 @@ Use maintained packages whenever possible. For custom installations, use the scr
|
||||
| OPNsense plugin | https://rustproxy-opn.linuxiarz.pl/ |
|
||||
| Debian 13+ source bootstrap | `install-debian13.sh` from the project repository |
|
||||
| Manual Linux/systemd install | Compile the application; use `install.sh` and `update.sh` |
|
||||
| OCI container | Included `Dockerfile`; see [Container](CONTAINER.md) |
|
||||
| OCI container | Included `Dockerfile`; see [Docker / OCI container](#docker--oci-container) |
|
||||
|
||||
Package/plugin instructions and maintenance policies are maintained separately from the source archive. The optional Docker agent is packaged independently of RustProxy's main service for **Linux amd64/x86_64 only**, not FreeBSD pkg. On a Docker host, the agent can also be installed manually from `docker-agent/install.sh`; the installer and packages preserve existing tokens and TLS keys. See [Docker discovery](DOCKER_DISCOVERY.md) and [agent operations](../docker-agent/README.md).
|
||||
|
||||
@@ -31,7 +31,7 @@ The script installs dependencies, builds with `cargo build --release --locked` a
|
||||
|
||||
## Build from the source
|
||||
|
||||
The current `Cargo.toml` declares **Rust 1.99 minimum**, with a `stable` toolchain in `rust-toolchain.toml`. Use Cargo, a C compiler/linker, Bash and Python 3 (Python 3.11+ is advisable for project checks). Run as a normal build user:
|
||||
The minimum Rust version is declared in `Cargo.toml` (`rust-version`); `rust-toolchain.toml` selects the `stable` channel. Use Cargo, a C compiler/linker, Bash and Python 3 (Python 3.11+ is advisable for project checks). Run as a normal build user:
|
||||
|
||||
```bash
|
||||
bash dev.sh doctor
|
||||
@@ -89,8 +89,7 @@ Then visit `http://127.0.0.1:9090` on your workstation. For a directly reachable
|
||||
|
||||
## Linux DEB/RPM: read-only access to external paths
|
||||
|
||||
New Linux packages (package-builder filesystem-access policy, revision 5) and
|
||||
the maintained manual service template use `ProtectHome=read-only` rather than
|
||||
Linux packages and the maintained manual service template use `ProtectHome=read-only` rather than
|
||||
`ProtectHome=true`. This makes document roots under `/home`, `/var/www` and
|
||||
`/srv` readable if the service account has **ordinary Unix group or ACL
|
||||
permissions**. `ProtectSystem=strict` remains enabled: the service cannot
|
||||
@@ -98,7 +97,7 @@ modify these files merely because a group or ACL permits it. No systemd
|
||||
drop-in or extra `ReadOnlyPaths=` entry is needed to **read** site content or
|
||||
an external certificate. This also applies when paths are stored in the panel.
|
||||
|
||||
In **0.34.10**, the panel generates Linux permission commands from the actual
|
||||
The panel generates Linux permission commands from the actual
|
||||
paths you enter: below the two external certificate/key fields, and directly
|
||||
below a Web Server's document root. The commands target the standard
|
||||
`rustproxy` account and resolve symlink targets when run. Review them and run
|
||||
@@ -160,7 +159,7 @@ After granting certificate read access, return to the form and use
|
||||
**Read names from certificate**. The editor reads the public certificate's
|
||||
DNS SAN entries into the legacy SNI field; this does not read the private key
|
||||
or save the certificate. Manual name edits are preserved by background reads.
|
||||
See [Certificates](ACME_PROVIDERS.md#permission-commands-and-automatic-sni-names).
|
||||
See [Certificates](CERTIFICATES.md#permission-commands-and-automatic-sni-names).
|
||||
|
||||
To diagnose unresolved errors, run `systemctl cat rustproxy` and
|
||||
`systemctl show rustproxy -p ProtectHome -p ProtectSystem -p User -p Group`,
|
||||
@@ -170,7 +169,7 @@ check parent permissions with `namei -l /path/to/file`, and examine
|
||||
unit and is **not** automatically removed by an upgrade. On SELinux/AppArmor
|
||||
hosts, additional mandatory access-control policy may be required; POSIX ACLs
|
||||
cannot bypass it. See [Web Server](WEB_SERVER.md) and
|
||||
[Certificates](ACME_PROVIDERS.md).
|
||||
[Certificates](CERTIFICATES.md).
|
||||
|
||||
**Write access is intentionally different.** An app that needs to upload or
|
||||
modify files under an arbitrary document root needs a separately planned
|
||||
@@ -233,6 +232,28 @@ This is **optional**. Without `--config`, RustProxy keeps its active configurati
|
||||
|
||||
For the alternate environment-variable method, set `RUST_PROXY_CONFIG=/etc/rustproxy/config.json` in the service's protected EnvironmentFile. Do not set **both** unrelated config paths. See [Configuration](CONFIGURATION.md) and the [deployment example](../deploy/README.md).
|
||||
|
||||
## Docker / OCI container
|
||||
|
||||
The included `Dockerfile` compiles RustProxy in a Rust build image and runs it on Debian as the unprivileged `rustproxy` account (UID 10001). The image contains Python, Certbot and DNS plugins for certificate automation. The main container does **not** need the Docker socket.
|
||||
|
||||
```bash
|
||||
docker build -t rustproxy:latest .
|
||||
docker volume create rustproxy-data
|
||||
docker run -d --name rustproxy \
|
||||
-p 8080:8080 \
|
||||
-v rustproxy-data:/var/lib/rustproxy \
|
||||
rustproxy:latest
|
||||
docker exec rustproxy rust-proxy admin setup-token
|
||||
```
|
||||
|
||||
Inside the image the HTTP frontend binds `0.0.0.0:8080` and administration binds `127.0.0.1:9090`, so publishing port 9090 alone does not expose the panel. For remote administration, enable administration HTTPS with a certificate and an explicit non-loopback listener first, and restrict access with firewall rules.
|
||||
|
||||
- Mount `/var/lib/rustproxy` persistently: it holds SQLite, private keys, certificate profiles and the optional COLD cache.
|
||||
- Publish the HTTP/HTTPS TCP ports you use, and the matching **UDP** port when HTTP/3 is enabled.
|
||||
- The image runs without root; map low host ports with port forwarding or deliberate capabilities.
|
||||
- To discover containers on other hosts, install the separate [Docker agent](DOCKER_DISCOVERY.md).
|
||||
- Upgrade by building a new image, keeping the volume and taking an encrypted backup first.
|
||||
|
||||
## Managed update
|
||||
|
||||
Test the new build first. Then execute:
|
||||
@@ -246,10 +267,8 @@ Managed updates preserve the saved configuration, create a private backup, switc
|
||||
|
||||
## ACME prerequisites
|
||||
|
||||
The managed certificate service can create a private Python/Certbot environment in the data directory; a usable system Certbot may be used as fallback. DNS-01 providers need credentials and appropriate permissions. HTTP-01 needs incoming public TCP `80`. On systems without an available Python/Certbot runtime, PEM import and external certificate references can still be used. See [Certificates](ACME_PROVIDERS.md).
|
||||
The managed certificate service can create a private Python/Certbot environment in the data directory; a usable system Certbot may be used as fallback. DNS-01 providers need credentials and appropriate permissions. HTTP-01 needs incoming public TCP `80`. On systems without an available Python/Certbot runtime, PEM import and external certificate references can still be used. See [Certificates](CERTIFICATES.md).
|
||||
|
||||
## After installation
|
||||
|
||||
Verify `systemctl status rustproxy` and `journalctl -u rustproxy` (managed systemd), the panel login, frontend certificates, first Vhost, real backend response, access policies, optional QUIC, current logs and a full backup/restore test. For error diagnosis, consult [Troubleshooting](TROUBLESHOOTING.md).
|
||||
|
||||
**Release verification:** RustProxy 0.34.2 is a source package; complete a Rust 1.99+ build and target-platform HTTP/systemd/security acceptance tests before Internet-facing production use.
|
||||
@@ -1,24 +0,0 @@
|
||||
# Integrations overview
|
||||
|
||||
RustProxy offers built-in integrations and optional helper components. Each has its own permissions and network requirements; enabling an integration does not automatically configure its external service.
|
||||
|
||||
| Integration | Purpose | Setup and limits |
|
||||
|---|---|---|
|
||||
| **Docker agent** | Discover running Docker services and publish generated Vhosts | Install separate agent on Docker host; use Bearer token and TLS certificate pin. [Guide](DOCKER_DISCOVERY.md). |
|
||||
| **Tinyauth** | Delegate authentication for selected Vhosts | Existing Nginx auth-request support remains unchanged, with fail-closed 502/504 errors. [Access](ACCESS.md). |
|
||||
| **Authelia** | Forward auth for selected Vhosts | Select it in Vhost Authentication, set internal service origin and trusted public HTTPS login URL, and configure the portal's per-domain cookie rules. [Access](ACCESS.md). |
|
||||
| **OIDC integration method (Authelia, Pocket ID, authentik and compatible issuers)** | Central OAuth/OIDC login for protected apps across different parent domains | Select the identity provider, then OIDC. Set HTTPS issuer discovery, Client ID/Secret, explicit app callback and encrypted local session. Requires an OIDC client on the chosen provider. [Access](ACCESS.md). |
|
||||
| **authentik** | Forward auth for selected Vhosts, including unrelated application domains | Configure one authentik single-application proxy provider per public application and its serving outpost; enter the outpost's internal origin. RustProxy handles the reserved outpost path automatically. [Access](ACCESS.md). |
|
||||
| **ACME / Certbot** | Issue/renew HTTPS certificates | HTTP-01 or DNS-01 via Cloudflare, OVH or RFC2136; protect credentials. [Certificates](ACME_PROVIDERS.md). |
|
||||
| **Prometheus** | Scrape operational metrics | Separate endpoint/token/CIDR rules. [Monitoring](MONITORING.md). |
|
||||
| **Grafana** | Visualize Prometheus results | Example dashboard under `grafana/README.md`. |
|
||||
| **Nagios** | External service checks | Sample checks under `nagios/README.md`; configure authorized network/API access. |
|
||||
| **Nginx Proxy Manager** | Import existing NPM proxy hosts | Included Python dry-run migration, without importing all NPM settings or private certificates. [Migration](MIGRATION.md). |
|
||||
| **OPNsense certificate deploy** | Deploy certificates from OPNsense ACME plugin | Review `integrations/opnsense-acme/README.md` and use scoped certificate credentials. |
|
||||
| **RouterOS OCI packaging** | Build an image suited to RouterOS-container environments | Separate experimental packaging under `integrations/routeros-oci-build/README.md`; test the host architecture/network constraints. |
|
||||
|
||||
## Rules of thumb
|
||||
|
||||
Use API credentials with the smallest allowed action/scope and terminate TLS on sensitive network links. The Docker socket must remain confined to the Docker agent host, not the main proxy. Certificate deploy/reload tokens are **not** general administrator API tokens. For imported NPM services, revisit backend TLS verification, frontend certificate assignment, access rules and special Nginx directives manually.
|
||||
|
||||
External compatibility depends on the versions and settings of those external products; this source archive cannot establish acceptance against a live provider or CA.
|
||||
+3
-3
@@ -1,6 +1,6 @@
|
||||
# Upgrades and migration
|
||||
|
||||
This guide covers changes that need operator action when moving to RustProxy 0.34.0 and the included Nginx Proxy Manager importer. For ordinary package upgrades, first follow [Installation and updates](INSTALL.md).
|
||||
This guide covers upgrades that need operator action and the included Nginx Proxy Manager importer. For ordinary package upgrades, first follow [Installation and updates](INSTALL.md).
|
||||
|
||||
## Before changing versions
|
||||
|
||||
@@ -16,8 +16,8 @@ A managed install uses `update.sh`; an unmanaged source-tree install must follow
|
||||
|
||||
| Change area | What to review |
|
||||
|---|---|
|
||||
| **0.34.0 cache** | Operational Vhost saves aim to retain compatible HOT/COLD cache. Content-affecting changes invalidate a scope; older disk cache objects can require refilling. Validate actual behavior before rollout. |
|
||||
| **0.34.0 Web Server** | `sendfile=auto` is an optional Linux cleartext HTTP/1.1 path; default is `off`. No existing service needs to enable it. |
|
||||
| **Cache** | Operational Vhost saves aim to retain compatible HOT/COLD cache. Content-affecting changes invalidate a scope; older disk cache objects can require refilling. Validate actual behavior before rollout. |
|
||||
| **Web Server** | `sendfile=auto` is an optional Linux cleartext HTTP/1.1 path; default is `off`. No existing service needs to enable it. |
|
||||
| **0.32.x origin protocols** | Legacy backend `http2` remains compatible on TLS (H2/H1) and H2C for plain HTTP. New strict `h2` must be set explicitly. |
|
||||
| **0.33.x Overview** | Dashboard presets/layouts are per administrator, independent from Vhost configuration; existing preferences should be retained and new widgets may remain hidden. |
|
||||
| **Certificate API grants** | Older broad/reload-only credentials can exist after additive migration; replace them with explicit certificate-ID allowlists and least privilege. |
|
||||
|
||||
+1
-1
@@ -24,7 +24,7 @@ Overview allows account-specific card layout and history controls; see [Dashboar
|
||||
|
||||
The exporter is **disabled by default** and uses a separate HTTP listener, normally `127.0.0.1:9191`, at `/metrics`. It is not protected by the admin browser cookie; it has its **own** client-network and bearer-token policy. In **Settings → Prometheus** enable the endpoint and configure:
|
||||
|
||||
In 0.34.1, use the separate **Prometheus token** controls in Settings to generate, rotate or revoke a 32+ character Bearer credential. Its clear value appears only once; copy it directly into your monitoring secrets store. The database keeps only its hash, and rotation/revocation takes effect without reprinting the previous secret. The older environment-variable credential remains supported as a fallback *only until* a generated credential or explicit revocation entry exists. Setting a new token does not reconfigure the exporter listener or its enable switch.
|
||||
Use the separate **Prometheus token** controls in Settings to generate, rotate or revoke a 32+ character Bearer credential. Its clear value appears only once; copy it directly into your monitoring secrets store. The database keeps only its hash, and rotation/revocation takes effect without reprinting the previous secret. The older environment-variable credential remains supported as a fallback *only until* a generated credential or explicit revocation entry exists. Setting a new token does not reconfigure the exporter listener or its enable switch.
|
||||
|
||||
|
||||
- `listen`, `path`, `allowed_cidrs` and an optional environment-variable **name** `bearer_token_env` (the secret value is supplied separately to the service).
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
# Performance
|
||||
|
||||
RustProxy runs on Tokio and Hyper with an asynchronous, streaming request path. This guide describes how performance is measured, where RustProxy stands compared with a similarly configured Nginx, and which settings matter in production.
|
||||
|
||||
## What is measured
|
||||
|
||||
Results are only comparable when both servers do the same work. A stock Nginx installation does very little per request, while RustProxy always records request statistics, traffic analytics and access logs and adds forwarding headers. The comparison therefore uses an Nginx configuration with a similar feature set:
|
||||
|
||||
| Feature | Nginx | RustProxy |
|
||||
|---|---|---|
|
||||
| Access log | `log_format` with timing fields, 64 KiB buffer | Built-in access log and live statistics (default) |
|
||||
| Forwarding headers | `Host`, `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Real-IP` | `Forwarded`, `X-Forwarded-*`, `X-Real-IP`, `X-Request-Id` (default) |
|
||||
| Response headers | `X-Request-ID`, `X-Content-Type-Options` | Request ID and default security headers |
|
||||
| Upstream keep-alive | `keepalive 64`, HTTP/1.1 | Connection pool (default) |
|
||||
| Cache | `proxy_cache` with `proxy_cache_lock` | HOT memory cache with request collapsing |
|
||||
| Compression | `gzip on` | gzip/Brotli/Zstandard negotiation (default) |
|
||||
| Static files | `root`, `etag on` | Web Service with validators (default) |
|
||||
|
||||
## Method
|
||||
|
||||
- Machine: 2 vCPU virtual machine, Linux 6.18, loopback networking.
|
||||
- Each server is pinned to one CPU core (`worker_processes 1` for Nginx, `taskset` for RustProxy). The load generator and the origin share the second core.
|
||||
- Load: `wrk -t1 -c50 -d8s`, HTTP/1.1 keep-alive, two runs per scenario, average reported.
|
||||
- Origin: Nginx serving static files with `Cache-Control: public, max-age=600`.
|
||||
- Nginx 1.24 and RustProxy release builds (`lto = "thin"`, `codegen-units = 1`).
|
||||
|
||||
## Results
|
||||
|
||||
Requests per second on one CPU core (higher is better):
|
||||
|
||||
| Scenario | Nginx | RustProxy 0.35.0 | RustProxy 0.35.1 | 0.35.1 vs 0.35.0 |
|
||||
|---|---:|---:|---:|---:|
|
||||
| Reverse proxy, 1 KiB response | 54,700 | 12,700 | 14,200 | +12% |
|
||||
| Reverse proxy, 100 KiB response | 9,600 | 11,400 | 13,600 | +19% |
|
||||
| Cache hit, 1 KiB response | 51,000 | 19,500 | 23,600 | +21% |
|
||||
| Web Server, 1 KiB file | 78,500 | 13,400 | 23,900 | +78% |
|
||||
| Web Server, 100 KiB file | 22,500 | 8,000 | 14,900 | +86% |
|
||||
|
||||
Reading the results:
|
||||
|
||||
- **Large proxied responses:** RustProxy streams the body directly between connections and is faster than Nginx in its default buffering mode, which spools larger upstream responses to temporary files.
|
||||
- **Small requests:** Nginx remains ahead, because its fixed per-request cost is lower. In RustProxy this cost is dominated by per-request accounting (live statistics, traffic analytics, request IDs and logs) and by the asynchronous runtime. For most deployments it is far below the capacity of the backends behind the proxy.
|
||||
- **Static files:** 0.35.1 reads files directly on the request task instead of a background thread pool, which nearly doubles static throughput.
|
||||
- **CPU per request:** at the 1 KiB proxy scenario RustProxy uses about 70 µs of CPU time per request on the test machine, Nginx about 17 µs. A single core therefore sustains well over 10,000 proxied requests per second.
|
||||
|
||||
Throughput scales with additional CPU cores; RustProxy uses all available cores automatically.
|
||||
|
||||
## Production tuning
|
||||
|
||||
| Setting | Recommendation |
|
||||
|---|---|
|
||||
| Cache | Enable the HOT cache for cacheable content; hits avoid the backend completely. |
|
||||
| Compression | Keep it enabled for text content. Use precompressed `.br`/`.gz` files for static sites. |
|
||||
| Upstream protocol | Prefer HTTP/1.1 keep-alive or HTTP/2 to backends; avoid backends that close every connection. |
|
||||
| Health checks | Use intervals of several seconds; frequent probes consume capacity on large installations. |
|
||||
| Logging | Keep stored log files on fast local storage and use retention limits on busy servers. |
|
||||
| Limits | `--max-connections` (default 512) and `--max-inflight` (default 256) cap concurrency. Raise them on busy servers with enough memory. |
|
||||
| `sendfile` | Optional for large cleartext static files on Linux. On the test machine it gave no measurable gain, so keep `off` unless your own measurements show otherwise. |
|
||||
| TLS | TLS 1.3 with session resumption keeps handshake cost low; HTTP/2 or HTTP/3 reduce connection setup for browsers. |
|
||||
|
||||
## Reproducing the test
|
||||
|
||||
1. Start an origin (any static HTTP server) with a 1 KiB and a 100 KiB file.
|
||||
2. Configure RustProxy with one Vhost pointing to the origin and one Web Service serving the same directory.
|
||||
3. Configure Nginx with the equivalent features from the table above.
|
||||
4. Pin each server to the same number of cores and run `wrk` from a different core:
|
||||
|
||||
```bash
|
||||
taskset -c 1 wrk -t1 -c50 -d8s -H "Host: proxy.example" http://127.0.0.1:8080/1k.txt
|
||||
```
|
||||
|
||||
Always compare matched configurations on the same machine, and repeat each run. Results on physical hardware and real networks differ from loopback measurements.
|
||||
+52
-29
@@ -1,44 +1,67 @@
|
||||
# RustProxy documentation
|
||||
|
||||
Practical guides for **RustProxy 0.35.0**. This index and the listed pages are also available in the authenticated panel at **`/docs → Reader`**. The adjacent **API** tab provides the embedded OpenAPI reference. Paths below are links to actual files in the source archive.
|
||||
Guides for operating RustProxy: installation, publishing services, security, certificates, monitoring and automation. The same pages are available in the administration panel under **`/docs → Reader`**, next to the interactive **API** reference.
|
||||
|
||||
- Project website and packages: [rustproxy.linuxiarz.pl](https://rustproxy.linuxiarz.pl/)
|
||||
- Source code: [git.linuxiarz.pl/gru/RustProxy](https://git.linuxiarz.pl/gru/RustProxy)
|
||||
- License: [GNU AGPL v3.0 or later](../LICENSE)
|
||||
|
||||
## Overview
|
||||
|
||||
- [Feature list](FEATURES.md) — everything RustProxy can do, grouped by area.
|
||||
- [Screenshots](SCREENSHOTS.md) — a tour of the administration panel.
|
||||
- [Performance](PERFORMANCE.md) — benchmark method, comparison with Nginx and tuning.
|
||||
|
||||
## Getting started
|
||||
|
||||
- [Installation and updates](INSTALL.md) — packages, build, first administrator, optional JSON/systemd permissions and updates.
|
||||
- [Container deployment](CONTAINER.md) — image, persistent state, ports and isolation.
|
||||
- [Settings and configuration](CONFIGURATION.md) — active SQLite/file storage source and which changes need restart.
|
||||
- [Troubleshooting](TROUBLESHOOTING.md) — symptom-based checks and release validation.
|
||||
- [Installation and updates](INSTALL.md) — packages, source build, Docker image, first administrator, systemd and updates.
|
||||
- [Configuration](CONFIGURATION.md) — SQLite or JSON configuration source, configuration map and changes that need a restart.
|
||||
- [Troubleshooting](TROUBLESHOOTING.md) — symptom-based checks and a rollout checklist.
|
||||
|
||||
## Publishing services
|
||||
|
||||
- [Vhosts and backends](VHOSTS.md) — domains, listener bindings, request Content-Type filtering, balancing, health and redirects.
|
||||
- [Vhosts and backends](VHOSTS.md) — domains, listeners, backends, balancing, health checks and redirects.
|
||||
- [Custom locations](CUSTOM_LOCATIONS.md) — path routing, rewrites, local responses and error fallbacks.
|
||||
- [Access and authentication](ACCESS.md) — ACL, country/DDNS, Basic Auth, Tinyauth, Authelia, authentik and rate limits.
|
||||
- [Static Web Server](WEB_SERVER.md) — document roots, generated filesystem permission commands, downloads, rules, built-in error pages and file delivery.
|
||||
- [PHP-FPM](PHP_FPM.md) — PHP service profiles, security and application examples.
|
||||
- [Cache](CACHE.md) — HOT/COLD storage, privacy, TTL, RFC 9211 `Cache-Status`, origin diagnostic headers and invalidation.
|
||||
- [Response delivery](RESPONSE_DELIVERY.md) — compression, static transformations and response headers.
|
||||
- [HTTP transport](TRANSPORT.md) — HTTPS/H2/H3, WebSockets, origin protocols and timeouts.
|
||||
- [Experimental TLS post-quantum key exchange](TLS_POST_QUANTUM.md) — opt-in X25519MLKEM768, compatibility, rollback and validation.
|
||||
- [TCP/UDP Streams](STREAMS.md) — non-HTTP forwarding and its security boundaries.
|
||||
- [Web Server](WEB_SERVER.md) — static sites, downloads, `try_files`, rewrites, `.htaccess` subset and error pages.
|
||||
- [PHP-FPM](PHP_FPM.md) — PHP profiles, pool isolation and application examples.
|
||||
- [HTTP transport and TLS](TRANSPORT.md) — HTTPS, HTTP/2, HTTP/3, WebSockets, backend protocols and post-quantum key exchange.
|
||||
- [TCP/UDP Streams](STREAMS.md) — non-HTTP forwarding.
|
||||
|
||||
The Vhosts and Docker discovery guides include the shared adaptive request-rate chart scale introduced in 0.34.11. Version 0.34.12 preserves that adaptive range and adds a disabled-by-default X/Y scale display option under **Settings → Appearance → Charts**. Release 0.34.13 adds global HTTP security policies and UI layout improvements, groups the global User-Agent policy under `global_security`, provides consistent section-based GET/PUT APIs, and moves manual GeoIP refresh to `POST /api/config/geoip/update`. See [Dashboard](DASHBOARD.md). Release 0.34.14 keeps the Tinyauth Nginx-header compatibility patch and dedicated fail-closed 502/504 pages. Release 0.34.15 adds optional Authelia and authentik forward-auth integrations, a shared provider runtime and a single provider-neutral HTML error template. Release 0.34.16 adds optional OIDC central login across unrelated domains. Release 0.35.0 accepts encoded `/` (`%2F` / `%2f`) in proxied paths while keeping normalized routing/security decisions separate from the original Preserve-mode upstream request target. See [Access](ACCESS.md) and [Troubleshooting](TROUBLESHOOTING.md).
|
||||
## Security and access
|
||||
|
||||
## Integrations and operations
|
||||
- [Access and authentication](ACCESS.md) — ACLs, countries, rate limits, Basic Auth, Forward Auth and OIDC.
|
||||
- [Certificates](CERTIFICATES.md) — PEM import, ACME HTTP-01/DNS-01, external Certbot files and automatic renewal.
|
||||
- [Security model](SECURITY.md) — trust boundaries and deployment recommendations.
|
||||
|
||||
- [Certificates and automatic renewal](ACME_PROVIDERS.md) — PEM, automatic SNI names, path permission commands, HTTP-01, DNS-01, Certbot and external certificates.
|
||||
- [Docker discovery](DOCKER_DISCOVERY.md) — optional Linux agent DEB/RPM or manual installation, TLS/token CLI, networking, generated Vhosts and their per-service live HTTP logs.
|
||||
- [Other integrations](INTEGRATIONS.md) — Tinyauth, NPM migration, OPNsense and monitoring tools.
|
||||
- [Dashboard](DASHBOARD.md) — metrics panels, HIT/MISS/BYPASS/OTHER request mix, presets, configuration history and applying stylesheet updates.
|
||||
- [Monitoring](MONITORING.md) — Prometheus, full JSON and compact `summary` API, traffic, backend and cache observations.
|
||||
- [Logs](LOGS.md) — live logs, stored logs, error logs and searches.
|
||||
- [Backups and recovery](BACKUP.md) — encrypted backups, restore and Secret Store.
|
||||
- [Migration](MIGRATION.md) — managed upgrades and Nginx Proxy Manager import.
|
||||
- [Security](SECURITY.md) — important trust boundaries and limitations.
|
||||
- [Administration API](API.md) and [API access](API_ACCESS.md) — endpoints, sessions and restricted certificate credentials.
|
||||
## Performance and delivery
|
||||
|
||||
## Release information
|
||||
- [Cache](CACHE.md) — HOT (memory) and COLD (disk) cache, freshness, `Cache-Status` and invalidation.
|
||||
- [Response delivery](RESPONSE_DELIVERY.md) — compression, transformations and response headers.
|
||||
|
||||
[Changelog](../CHANGELOG.md) tracks user/operator-visible technical changes; [Roadmap](../ROADMAP.md) separates current verification work from future ideas. Historical low-level investigations, audits and benchmarks are not part of the live Reader. Keep them separately if you need an audit trail.
|
||||
## Operations
|
||||
|
||||
When changing functionality, update the appropriate guide, this index, the registered Reader documents and any OpenAPI/schema references together. Describe actual code behavior, not unimplemented plans.
|
||||
- [Dashboard](DASHBOARD.md) — Overview cards, layouts, presets and configuration history.
|
||||
- [Monitoring](MONITORING.md) — Prometheus exporter, JSON metrics, Grafana and Nagios.
|
||||
- [Logs](LOGS.md) — live, stored and error logs.
|
||||
- [Backup and recovery](BACKUP.md) — encrypted backups, restore and the Secret Store.
|
||||
- [Migration](MIGRATION.md) — upgrades and Nginx Proxy Manager import.
|
||||
- [Docker discovery](DOCKER_DISCOVERY.md) — Docker agent and generated Vhosts.
|
||||
- [Administration API](API.md) — authentication, tokens, endpoints and configuration sections.
|
||||
|
||||
## Integrations
|
||||
|
||||
| Integration | Purpose | Guide |
|
||||
|---|---|---|
|
||||
| Docker agent | Discover containers on Docker hosts and publish them as Vhosts | [Docker discovery](DOCKER_DISCOVERY.md) |
|
||||
| Tinyauth, Authelia, authentik | Forward Auth for selected Vhosts | [Access](ACCESS.md) |
|
||||
| OIDC (Authelia, authentik, Pocket ID, others) | Central login across unrelated domains | [Access](ACCESS.md) |
|
||||
| ACME / Certbot | Certificates via HTTP-01 or DNS-01 (Cloudflare, OVH, RFC 2136) | [Certificates](CERTIFICATES.md) |
|
||||
| Prometheus and Grafana | Metrics scraping and a ready dashboard | [Monitoring](MONITORING.md) |
|
||||
| Nagios | Service checks for API, backends, latency and queues | [Monitoring](MONITORING.md) |
|
||||
| Nginx Proxy Manager | Import of existing proxy hosts | [Migration](MIGRATION.md) |
|
||||
| OPNsense | Certificate deployment from the os-acme-client plugin | `integrations/opnsense-acme/README.md` |
|
||||
| MikroTik RouterOS | OCI image build for RouterOS containers | `integrations/routeros-oci-build/README.md` |
|
||||
|
||||
## Release notes
|
||||
|
||||
See the [changelog](../CHANGELOG.md).
|
||||
@@ -0,0 +1,73 @@
|
||||
# Screenshots
|
||||
|
||||
A tour of the RustProxy administration panel. The panel runs on the separate administration listener (by default `http://127.0.0.1:9090`) and is available in English and Polish, with light and dark themes.
|
||||
|
||||
## Sign-in
|
||||
|
||||
Local administrator sign-in. The first account is created with a one-time setup token; there is no default password.
|
||||
|
||||
|
||||
|
||||
## Overview dashboard
|
||||
|
||||
Live requests per second, bandwidth, status codes, cache hit ratio, protocol mix, system resources and backend health. Cards can be rearranged, resized, hidden and saved as presets.
|
||||
|
||||
|
||||
|
||||
## Vhosts
|
||||
|
||||
Every published domain with its listeners, backends, health, request rate and security options. The editor groups frontend, backends, balancing, security, cache and custom locations.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Web Server
|
||||
|
||||
Reusable Web Services for static sites and PHP applications, with presets, delivery options and generated filesystem permission commands.
|
||||
|
||||
|
||||
|
||||
## Certificates
|
||||
|
||||
Certificate inventory with expiry, covered hostnames, assigned Vhosts and managed ACME renewal.
|
||||
|
||||
|
||||
|
||||
## Traffic
|
||||
|
||||
Per-Vhost traffic analytics: top paths, clients, user agents, countries, methods and status codes.
|
||||
|
||||
|
||||
|
||||
## Cache
|
||||
|
||||
HOT and COLD cache usage, hit ratio, stored objects and purge/ban tools.
|
||||
|
||||
|
||||
|
||||
## Logs
|
||||
|
||||
Live and stored request logs with filters, search syntax and record details.
|
||||
|
||||
|
||||
|
||||
## Settings
|
||||
|
||||
Listeners, TLS policy, security, logging, cache, compression, monitoring, administration and appearance.
|
||||
|
||||
|
||||
|
||||
## Documentation and API
|
||||
|
||||
The built-in Reader with all guides, and an interactive OpenAPI reference powered by Swagger UI. Both work offline and use the administrator session.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## About
|
||||
|
||||
Version, author, license summary and project links.
|
||||
|
||||
|
||||
+1
-1
@@ -45,4 +45,4 @@ The **Security headers** subtab controls an HTTPS HSTS policy and optional globa
|
||||
|
||||
## Release and operational validation
|
||||
|
||||
The provided 0.34.0 source includes changes without completed native compilation, all-protocol regression or production performance measurement. Do **not** treat source-code inspection as proof of security or performance. Before using it at an Internet edge, test on the target OS, run the automated suite, verify TLS/H2/H3/WebSocket handling, access and cache privacy, backup/restore, logging and failure recovery. Keep monitored off-host backups and a rollback plan.
|
||||
Before exposing a new version at an Internet edge, test it on the target OS with your own configuration: TLS/H2/H3/WebSocket handling, access rules and cache privacy, backup/restore, logging and failure recovery. Keep monitored off-host backups and a rollback plan.
|
||||
@@ -1,51 +0,0 @@
|
||||
# Experimental post-quantum TLS key exchange (PQC)
|
||||
|
||||
## What it does
|
||||
|
||||
Post-quantum cryptography (PQC) aims to protect key exchange from attackers with future quantum computing capabilities. **X25519MLKEM768** combines a conventional X25519 ephemeral key agreement with post-quantum **ML-KEM-768** in one TLS 1.3 *hybrid key-exchange group*. Both contributions protect the derived traffic secret. This is **not a TLS cipher suite**: AES-GCM or ChaCha20-Poly1305 and ordinary X.509 RSA/ECDSA certificates remain in use. It does not change certificate signatures to post-quantum algorithms, and does not make all parts of TLS quantum-safe.
|
||||
|
||||
When enabled, RustProxy uses the `aws-lc-rs` cryptography provider for selected incoming TLS policies, offering X25519MLKEM768 first and classical key-exchange groups as fallback. When disabled it keeps the existing `ring` TLS provider. The selected key exchange depends on client support and negotiation; turning the switch on does not imply every connection uses PQC. It does **not** change outbound/backend, update-check, certificate-automation or other HTTP client TLS settings.
|
||||
|
||||
For implementation details see [rustls defaults and PQC](https://rustls.dev/docs/rustls/manual/_05_defaults/index.html) and [X25519MLKEM768 rustls API](https://docs.rs/rustls/0.23.45/rustls/crypto/aws_lc_rs/kx_group/static.X25519MLKEM768.html).
|
||||
|
||||
## Enable
|
||||
|
||||
1. Make a configuration backup; ensure that **TLS 1.3** is enabled.
|
||||
2. Open **Settings → TLS policy** and enable **Experimental post-quantum key exchange (PQC)**. Keep your current **cipher suite** list unless you have a specific reason to change it. The KEX group is enabled by the switch, **not** by adding X25519MLKEM768 to the cipher-suite textarea.
|
||||
3. Select **Validate, save and apply**. The TLS status reports the configured key-exchange groups, not the group used by each individual connection.
|
||||
4. Test HTTPS, HTTP/1.1, HTTP/2 and (if enabled) HTTP/3 on staging with a client that supports hybrid KEX, and with older clients that use classical KEX.
|
||||
|
||||
`post_quantum` is stored on the global policy (the default is false):
|
||||
|
||||
```json
|
||||
{"tls": {"policy": {"tls12": true, "tls13": true, "cipher_suites": [], "post_quantum": true}}}
|
||||
```
|
||||
|
||||
This fragment illustrates the `tls` field; do not replace your full configuration with it.
|
||||
|
||||
### Per-vhost behavior
|
||||
|
||||
A Vhost **inherits** the global TLS policy by default. If it has an explicit `tls_policy` override, the override may disable PQC, but it cannot enable PQC while the global setting is disabled. Existing overrides that do not contain `post_quantum` are treated as `false`, even after you enable PQC globally. HTTP/3 Vhosts require their override, if any, to match the global TLS policy exactly, including PQC. Update or remove conflicting overrides before enabling PQC on H3.
|
||||
|
||||
The administration TLS listener also uses the global policy when administration HTTPS is enabled. Open connections keep their negotiated keys; only **new handshakes** use the updated policy.
|
||||
|
||||
## Test negotiated group
|
||||
|
||||
Requires **OpenSSL 3.5+** with `X25519MLKEM768` support:
|
||||
|
||||
```bash
|
||||
openssl s_client -connect example.com:443 -servername example.com \
|
||||
-tls1_3 -groups X25519MLKEM768 -brief
|
||||
```
|
||||
|
||||
Check for `Protocol version: TLSv1.3` and `Negotiated TLS1.3 group: X25519MLKEM768` (format depends on OpenSSL). Compare with a classic-only client using `-groups X25519` and test TLS 1.2 if it is enabled. For HTTP/3, also use an actual QUIC/H3 client and test with UDP blocked to verify fallback to H2/H1; `openssl s_client` does not test QUIC.
|
||||
|
||||
If your TLS connection ends at a CDN, load balancer or TLS-terminating proxy, the test shows **that intermediary**, not RustProxy. To check RustProxy, connect to its listener directly while preserving SNI, and verify its actual certificate.
|
||||
|
||||
## Caveats and rollback
|
||||
|
||||
- Hybrid handshakes are larger and can hit MTU/middlebox limits, especially over QUIC. Measure connection errors, handshake latency, memory and CPU under expected load. Some legacy clients and devices may reject hybrid negotiation.
|
||||
- Enabling the switch changes the incoming TLS cryptographic provider to `aws-lc-rs`; some uncommon certificates, algorithms or hardware platforms may behave differently. `aws-lc-rs` requires a native C/C++ build toolchain; CMake may be needed for some build modes (non-FIPS commonly does not require it). The `ring` provider remains used where the switch is off and for existing outbound integrations.
|
||||
- A non-empty cipher-suite allowlist must contain suites supported by the selected provider; invalid combinations are rejected. PQC requires TLS 1.3.
|
||||
- For immediate rollback, **uncheck PQC in Settings → TLS policy and save**, and if necessary remove per-Vhost overrides that require PQC. Confirm new connections negotiate classic X25519. Existing sessions cannot renegotiate in place; close/reconnect them to retest. Keep the prior binary and backups available for a full rollback.
|
||||
- **Release verification:** the PQC implementation inherited from 0.34.9 still requires native Cargo build, TLS handshake, QUIC interoperability and production load acceptance. Verify the provisionally updated `Cargo.lock` with `cargo metadata --locked` (and refresh it with Cargo if needed), then run `cargo check --all-targets`, `cargo test --all-targets`, `cargo build --release`, and protocol tests before deployment. See the release changelog and source verification notes.
|
||||
+23
-5
@@ -18,8 +18,7 @@ Transport settings attach to **named listeners**, and a Vhost must select the ap
|
||||
- **For new QUIC connections only:** updates to `max_concurrent_bidistream`, `max_concurrent_unistream`, `max_idle_timeout` and reductions to `max_concurrent_connections` are applied without restart. Existing QUIC connections keep their negotiated limits. If no existing UDP socket matches the saved listener address, no H3 is advertised or accepted on the old address.
|
||||
- **Restart needed:** UDP listener enable/disable, changing IP/port/TLS properties, UDP socket buffer sizes, changes to H1/H2 listener settings and increasing `max_concurrent_connections` above the startup bound. The live listener status continues to show `restart_required` for these cases. After a restart, the new connection cap can take effect.
|
||||
|
||||
|
||||
### QUIC UDP socket buffers (0.34.3)
|
||||
### QUIC UDP socket buffers
|
||||
|
||||
The HTTP/3 settings of each TLS listener include:
|
||||
|
||||
@@ -41,7 +40,6 @@ sudo ss -uapm | grep -A1 rust-proxy
|
||||
|
||||
Read the `HTTP/3 UDP effective socket buffers` startup log message. `ss` should show approximately `rb4194304,tb4194304` (or larger if the OS adjusts values) when the requested size is granted. Changes to the OS maxima alone do not resize an existing socket; the configured buffer size is applied when a QUIC listener starts. High default/maxima for every program are not recommended as a substitute for explicit per-socket configuration. No specific throughput gain is guaranteed; compare H2/H3 at matched traffic before/after.
|
||||
|
||||
|
||||
## Backend protocol selection
|
||||
|
||||
| Backend mode | HTTPS origin | Plain HTTP origin |
|
||||
@@ -55,10 +53,30 @@ WebSockets normally use HTTP/1.1 Upgrade. HTTP/2/HTTP/3 client requests can stil
|
||||
|
||||
## TLS and trust
|
||||
|
||||
**Experimental (0.34.9):** Settings → TLS policy has a disabled-by-default **Post-quantum key exchange (PQC)** switch for hybrid TLS 1.3 X25519MLKEM768. This is a TLS key-exchange group, not a cipher suite. See [Post-quantum TLS](TLS_POST_QUANTUM.md) for prerequisites, fallback, HTTP/3 and rollback.
|
||||
|
||||
Public HTTPS requires a correct certificate with hostname coverage. Administration TLS is separate. Backend `https://` encrypts traffic, but **upstream certificate verification is opt-in by default** in the current backend model; enable it and specify CA/name where needed. Private/loopback addresses and routing to a local RustProxy listener require explicit risk overrides.
|
||||
|
||||
## Post-quantum TLS key exchange (optional)
|
||||
|
||||
**Settings → TLS policy → Post-quantum key exchange** enables the hybrid TLS 1.3 group **X25519MLKEM768** (X25519 combined with ML-KEM-768) for incoming TLS. It is a key-exchange group, not a cipher suite: certificates and AES-GCM/ChaCha20-Poly1305 ciphers stay unchanged, and classic groups remain available as a fallback. The setting is off by default and requires TLS 1.3.
|
||||
|
||||
When enabled, incoming TLS uses the `aws-lc-rs` provider; otherwise `ring` is used. Outbound connections (backends, ACME, update checks) are not affected. The setting is stored as `tls.policy.post_quantum`:
|
||||
|
||||
```json
|
||||
{"tls": {"policy": {"tls12": true, "tls13": true, "cipher_suites": [], "post_quantum": true}}}
|
||||
```
|
||||
|
||||
- Vhosts inherit the global policy. A per-Vhost `tls_policy` override can disable PQC but cannot enable it when the global switch is off. HTTP/3 Vhosts need an override that matches the global policy exactly.
|
||||
- Only new handshakes use the updated policy; open connections keep their keys.
|
||||
- Hybrid handshakes are larger and may hit MTU or middlebox limits, especially over QUIC; some legacy clients reject them.
|
||||
- Roll back by unchecking the switch and saving.
|
||||
|
||||
Verify the negotiated group with OpenSSL 3.5 or newer, directly against the RustProxy listener (not a CDN in front of it):
|
||||
|
||||
```bash
|
||||
openssl s_client -connect example.com:443 -servername example.com \
|
||||
-tls1_3 -groups X25519MLKEM768 -brief
|
||||
```
|
||||
|
||||
## Timeouts, request bodies and streaming
|
||||
|
||||
Idle/read/connect/response-header timeouts and backend connection pools are configurable. A response may stream after its headers have arrived; response-header metrics are not full-body duration. WebSockets and Streams have separate idle lifetimes and should be tested with the actual application. RustProxy rejects suspicious ambiguous request targets rather than normalizing them into potentially unsafe backend paths.
|
||||
|
||||
+11
-16
@@ -54,8 +54,7 @@ rust-proxy --data-dir /var/lib/rustproxy config validate config.json
|
||||
|
||||
Use **Logs → Live Logs** or the `--livelogs` CLI mode to correlate request IDs, Vhost/route/backend and status. Inspect **Stored Logs** for previously saved JSONL and selected low-level protocol failures.
|
||||
|
||||
## HTTP/3 throughput and CPU diagnostics (0.34.3 source candidate)
|
||||
|
||||
## HTTP/3 throughput and CPU diagnostics
|
||||
Do not assume that low H3 throughput is a CPU bottleneck from the overall VM percentage alone. A 50% VM reading can mean one saturated vCPU on a 2-vCPU machine. Quinn uses UDP datagrams, per-packet QUIC/TLS, congestion control and OS/virtual NIC offloads; H1/H2 over TCP can behave differently under the same load. Quinn enables UDP GSO by default when the platform supports it, but some VM/network stacks fall back to per-datagram sends.
|
||||
|
||||
1. Run **four matched tests** against the same OpenSpeedTest/large streaming endpoint: direct backend H1, proxied HTTPS H2, proxied HTTPS H3 download, proxied H3 upload. Record client speed, per-process CPU, **per-thread** CPU, and whether the problem persists with a larger number of simultaneous clients.
|
||||
@@ -69,27 +68,23 @@ Do not assume that low H3 throughput is a CPU bottleneck from the overall VM per
|
||||
```
|
||||
|
||||
3. If available, use `perf top -p "$(pidof rust-proxy)"` briefly during the benchmark, and inspect `%sys` / `%soft` in `mpstat -P ALL 1`. Check whether guest CPU has `aes` instruction support with `lscpu`.
|
||||
4. For the 0.34.3 source candidate, set `RUST_LOG=rust_proxy::http3=debug` in a **test** deployment and inspect `HTTP/3 bulk transfer transport snapshot` logs: `quic_lost_packets`, `quic_congestion_events`, `quic_rtt_ms`, `quic_cwnd_bytes`, `quic_path_mtu`, `quic_udp_tx_datagrams` and `quic_udp_tx_ios`. Those Quinn counters are **connection-wide cumulative snapshots**, not stream-specific deltas; compare differences for one isolated connection or across successive samples.
|
||||
4. Set `RUST_LOG=rust_proxy::http3=debug` in a **test** deployment and inspect `HTTP/3 bulk transfer transport snapshot` logs: `quic_lost_packets`, `quic_congestion_events`, `quic_rtt_ms`, `quic_cwnd_bytes`, `quic_path_mtu`, `quic_udp_tx_datagrams` and `quic_udp_tx_ios`. Those Quinn counters are **connection-wide cumulative snapshots**, not stream-specific deltas; compare differences for one isolated connection or across successive samples.
|
||||
|
||||
5. Run `ss -uapm | grep -A1 rust-proxy` during a transfer; check `skmem rb`, `tb` and whether dropped-datagram `d` increments. RustProxy 0.34.3 defaults to 4 MiB per direction and logs the actual SO_RCVBUF/SO_SNDBUF effective values on bind. If Linux clamps them, inspect `sysctl net.core.rmem_max net.core.wmem_max`; saving new socket buffer targets in the panel requires a listener restart. See [HTTP transport](TRANSPORT.md#quic-udp-socket-buffers-0343).
|
||||
5. Run `ss -uapm | grep -A1 rust-proxy` during a transfer; check `skmem rb`, `tb` and whether dropped-datagram `d` increments. RustProxy defaults to 4 MiB per direction and logs the actual SO_RCVBUF/SO_SNDBUF effective values on bind. If Linux clamps them, inspect `sysctl net.core.rmem_max net.core.wmem_max`; saving new socket buffer targets in the panel requires a listener restart. See [HTTP transport](TRANSPORT.md#quic-udp-socket-buffers).
|
||||
|
||||
A rising loss/retransmission count or shrinking congestion window with low CPU suggests packet pacing, network path, UDP buffer/offload or VM issues. With negligible loss and one saturated worker thread, investigate QUIC encryption, UDP send/receive and application streaming costs using `perf` before changing window sizes. HTTP/3 overhead can also affect large file transfers, uploads and long-lived H3 streams; speedtest is only one way to expose it. No throughput improvement is claimed without a production-equivalent QUIC benchmark.
|
||||
|
||||
## Rollout gate for RustProxy 0.34.0
|
||||
## Release rollout checklist
|
||||
|
||||
The latest source optimizations were **not all compiled or performance-tested** in the evidence supplied with this release. Before deploying:
|
||||
1. Verify HTTP/1.1, HTTPS, HTTP/2, HTTP/3 (if enabled), WebSockets and multi-backend failover against a real origin.
|
||||
2. Test private origin constraints, ACL/authentication, rate limits and protected cache content.
|
||||
3. Test Web Server static files, PHP-FPM, cache revalidation/invalidation and `sendfile=auto` if enabled.
|
||||
4. Exercise certificate renewal/reload and a backup **restore** on staging.
|
||||
5. Compare performance only with matched configurations and repeatable traffic; see [Performance](PERFORMANCE.md).
|
||||
|
||||
1. Build using the declared Rust toolchain and run the project's available regression suite on the target platform.
|
||||
2. Verify HTTP/1.1, HTTPS, HTTP/2, HTTP/3 (if enabled), WebSockets and multi-backend failover with a real origin.
|
||||
3. Test private origin constraints, ACL/auth/CSRF, rate limits and protected cache content.
|
||||
4. Test Web Server static files, PHP-FPM, cache revalidation/invalidation and optional `sendfile=auto` only if enabled.
|
||||
5. Exercise certificate renewal/reload and backup **restore** on isolated staging.
|
||||
6. Compare performance only under matched configurations with controlled repeatable traffic; do **not** label 0.34.0 as faster merely because its source reduces internal work.
|
||||
|
||||
For persistent problems, use the feature-specific guide in [Documentation](README.md) and preserve a redacted error example with environment/version and request ID.
|
||||
|
||||
## OIDC central login (0.34.16)
|
||||
For persistent problems, use the feature-specific guide in [Documentation](README.md) and keep a redacted error example with the version and request ID.
|
||||
|
||||
## OIDC central login
|
||||
- **Login does not start / 502:** verify that the HTTPS Issuer URL is the exact `issuer` from `/.well-known/openid-configuration`, including any path or trailing slash. RustProxy must resolve that address and connect to it with a trusted certificate, or you must configure an explicit internal backend origin for server-side OIDC requests. Discovery, authorization, token, UserInfo and JWKS endpoints must have the same HTTPS origin as the issuer.
|
||||
- **Redirect URI mismatch:** register the exact `https://APP-HOST/_rustproxy/oidc/callback` value with the identity provider. The callback hostname must be explicitly listed in the protected Vhost hosts and be accessed over HTTPS. Don't protect the IdP's own login Vhost using this OIDC setting.
|
||||
- **Invalid code, nonce or signature:** ensure that the provider issues an `id_token` using RS256 or ES256 and that a confidential client uses `client_secret_basic` with authorization code and PKCE S256. Repeated callback requests or overwritten browser transaction cookies are refused. A single browser login flow per protected host avoids cookie conflicts.
|
||||
|
||||
+1
-1
@@ -58,7 +58,7 @@ Sample documents in `examples/vhosts-private.json` and `examples/vhosts-balanced
|
||||
|
||||
A backend's `preserve_host` option can retain the frontend authority when appropriate. HTTPS encryption alone does not guarantee verified backend identity: `tls_verify` is **false by default**. Enable verification and configure trusted CA/name for sensitive connections. Private, loopback and RustProxy-local listener targets require explicit security exceptions; do not point a public route to the admin listener. Read [Security](SECURITY.md).
|
||||
|
||||
Connection reuse is bounded by configured idle-pool/recycle limits. 0.34.0 changes the default H1 upstream idle pool for newly configured Vhosts; previously saved explicit values remain. Configure timeouts to suit expected request and upload behavior; a slow origin may need more than the default response-header timeout.
|
||||
Connection reuse is bounded by configured idle-pool/recycle limits. The default H1 upstream idle pool applies to newly configured Vhosts; previously saved explicit values remain. Configure timeouts to suit expected request and upload behavior; a slow origin may need more than the default response-header timeout.
|
||||
|
||||
## Load balancing and health
|
||||
|
||||
|
||||
+2
-3
@@ -46,9 +46,8 @@ For PHP applications, the separate **PHP-FPM pool user** needs its own access to
|
||||
| **Symlinks** | `deny` by default; `inside_root` is an explicit less restrictive policy. |
|
||||
| **Hardening** | Optional checks for common sensitive/attack paths and removal of selected server-identifying headers; not a full WAF. |
|
||||
|
||||
### Static delivery (`sendfile`) — 0.34.0
|
||||
|
||||
In **Web Server → Edit service → Delivery**, `sendfile` supports `off` (default) and `auto`. On **Linux**, eligible full static **GET** responses of at least **64 KiB** over **unencrypted HTTP/1.1** may use a kernel file-transfer path. TLS, HTTP/2, HTTP/3, ranged or transformed content, compressed responses and active object-cache responses keep the normal streaming path. This transport choice should not invalidate otherwise compatible cached objects. It is an **unverified source candidate** in the provided archive: test it on the actual server before use and do not assume a measured speedup.
|
||||
### Static delivery (`sendfile`)
|
||||
In **Web Server → Edit service → Delivery**, `sendfile` supports `off` (default) and `auto`. On **Linux**, eligible full static **GET** responses of at least **64 KiB** over **unencrypted HTTP/1.1** may use a kernel file-transfer path. TLS, HTTP/2, HTTP/3, ranged or transformed content, compressed responses and active object-cache responses keep the normal streaming path. This transport choice should not invalidate otherwise compatible cached objects. Measure on your own hardware before enabling it; see [Performance](PERFORMANCE.md).
|
||||
|
||||
## Rewrites and application presets
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 292 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 125 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 149 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 149 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 221 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 305 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 208 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 153 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 141 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 220 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 178 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 124 KiB |
Reference in new issue
Block a user