RustProxy/docs/CONFIGURATION.md

Configuration and settings

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 for semantics and safety exceptions.

Configuration storage: SQLite or JSON file

Settings → Manual config shows the active storage mode and path, sourced from the read-only storage member of the authenticated GET /api/config response (revision, config, storage). With no --config, the authoritative configuration is in <data-dir>/config.sqlite3 (normally /var/lib/rustproxy/config.sqlite3). With --config, that JSON file is authoritative, while SQLite still stores revision history, accounts and audit records. Switching modes requires a service restart; the panel does not change the startup argument.

Optional JSON configuration source

Start the process with an existing, absolute JSON config filename, for example:

rust-proxy --data-dir /var/lib/rustproxy --config /etc/rustproxy/config.json serve

RUST_PROXY_CONFIG=/etc/rustproxy/config.json is an equivalent global setting. The file must be a regular file (not a symlink) within the configuration size limit and readable/writable by the service account; its parent directory must permit creation/renaming for atomic updates. The file is the canonical desired configuration. Panel and API edits, including history restore, rewrite it; SQLite retains revisions and audit. RustProxy rejects panel saves after an unimported external file edit rather than clobbering it. Use rust-proxy reload or rust-proxy config reload to import such edits after validation. No --config flag keeps the original SQLite-owned configuration behavior.

For a systemd deployment, use systemctl edit rustproxy to add --config /etc/rustproxy/config.json to ExecStart (with a reset line ExecStart=), or supply RUST_PROXY_CONFIG through the unit's private EnvironmentFile. Use an exported, complete JSON document before enabling the flag; an absent/empty file prevents startup. The example below is in Installation — optional systemd JSON file. It includes chown, POSIX ACLs on both file and parent directory, and ReadWritePaths= for hardened services: RustProxy atomically replaces the JSON and therefore needs write plus traversal permissions on the directory, not merely a writable file. The resulting file will normally be owned by rustproxy with mode 0600 after its first panel save.

Check the effective unit with systemctl cat rustproxy, paths/ACLs with getfacl, and storage mode under Settings → Manual config. Manual file edits require systemctl reload rustproxy to import changes; a successful panel save already updates the file. Listener binds/ALPN still require a restart. Back up both the JSON source and the SQLite database/other private state; history is not a complete backup.

Configuration map

Panel area	Main settings	Operational note
Settings → Listeners	Named HTTP/HTTPS frontends, addresses, HTTP/2, H2C, HTTP/3, transport limits	The selected Vhost must bind the correct listener. Binding changes may require restart.
Settings → Administration	Dedicated admin address, HTTPS/certificate, accepted hostnames/public origin	Local HTTP by default. Remote admin requires deliberate security configuration.
Settings → Security	Admin sessions, passwords, RO/RW API token creation and revocation, host policies	Administration includes a shortcut to API tokens here; token secret is displayed only once.
Vhosts	Domains, certificates, source, backends, health, load balancing, custom locations	The primary place to publish a service.
Web Server	Document roots, static delivery, rewrites, PHP-FPM, cache headers	Attach a Web Service to a Vhost as its source.
Access / ACL profiles	IP/CIDR, DNS/DDNS allow rules, country policy, HTTP methods, rate limits	Access decisions combine across applicable levels.
Settings → Cache	HOT/COLD budgets, TTL, exclusions, diagnostics, invalidation	Global and Vhost permissions must both allow caching.
Settings → Compression / Transform / Headers	Response codecs, content modification, headers and security settings	Avoid changing personalized content in a shared cache.
Certificates	PEM import, managed ACME issuance, renewal and assignment	Issuing a certificate does not automatically publish a Vhost.
Docker / Streams	Docker agent hosts and published services; TCP/UDP forwarding	Streams bypass HTTP Vhost policy.
Overview / Appearance	Dashboard cards, presets, layout, charts and theme	Account-specific display preferences do not change proxy behavior.
Logs / Monitoring	Live/stored logs, error logs, analytics, Prometheus, GeoIP updates	Logs and metrics may need dedicated limits/network permissions.

Read the dedicated guide before enabling advanced options: Vhosts, Cache, Web Server, Monitoring, Security.

Listener and domain setup

1. Create or review a named HTTP/HTTPS listener in Settings → Listeners.
2. For HTTPS, choose the certificate and protocol capabilities. HTTP/3 is optional and requires UDP access.
3. In a Vhost, set exact domains or supported leading wildcards (*.example.com), select listener IDs and certificate.
4. Set the source: HTTP reverse proxy or an existing Web Service. Test DNS, TLS and backend health.
5. Add HTTP → HTTPS (308) or www/non-www redirection if needed. Check routing before turning on caching or restrictions.

Listener bindings set by startup CLI/systemd cannot be removed, disabled or modified through saved configuration. Saved settings may therefore be valid but not active until a service restart. For H3, the Alt-Svc lifetime and reductions in runtime transport limits update for new requests/connections without restart; changed UDP binds, protocol toggles and H3 connection-capacity increases still need restart. See HTTP transport. Administration and public frontends use different security boundaries.

Backend protocols

http1 uses HTTP/1.1. auto selects H2/H1 over HTTPS and ordinary HTTP/1.1 over plaintext. The legacy http2 value retains compatible HTTPS negotiation and H2C for HTTP. Explicit h2 requires H2/H2C; do not use it with an origin that only supports HTTP/1.1. Backend TLS certificate verification is off by default in the source model; enable it deliberately for trusted origin identity. A private origin, loopback origin or origin on a local RustProxy listener also requires an appropriate explicit exception.

Access and header policies

ACLs support IP/CIDR and allow-only DNS/DDNS hostname rules, plus reusable profiles and country rules. Host, Vhost and Custom-location checks are cumulative: an allowed location does not undo a host denial. Configure forwarding identity only behind an explicit trusted proxy. Optional Basic Auth or Tinyauth is attached to Vhosts; WebSockets should be enabled only where used. See Access.

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)

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_security": {
    "user_agent_blocking": {"enabled": true, "patterns": ["bad-bot"]},
    "country_access": {"mode": "off", "countries": []}
  }
}

GET /api/config/global-security returns {revision, section, value} where value is the entire global_security object. To update it, send PUT /api/config/global-security with { "expected_revision": <current-revision>, "value": <complete-global_security-object> }; the User-Agent member is required in the section PUT. Both Global block / allow and Security headers forms save this complete object, preserving unchanged controls from the current revision. Validation and persistence are atomic. The formerly separate PUT /api/config/user-agent-blocking is no longer supported.

On upgrade, older JSON, database rows, backups and revision history containing a root-level user_agent_blocking are migrated at validation/compilation to the nested policy. If both old and new keys are supplied with differing values, validation fails instead of choosing one. Old configurations without global_security retain disabled defaults for all newly added policies. See Administration API, Access and Security.

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.

Response transformations are optional and apply only to configured eligible MIME types and scopes. See Response delivery for codec defaults, transformation limits and header precedence. Content rewriting can affect validators, compression and cache entries; test actual representations after configuration changes.

Administration preferences

Appearance settings, Dashboard Presets and Overview cards belong to the administrator profile. Settings → Appearance → Data refresh keeps the automatic-refresh toggle separate from four intervals arranged in two equal columns (one on narrow screens). The saved corner style (Square, Subtle, Rounded or Extra) applies to controls and surfaces in the main panel and the authenticated Reader/OpenAPI page. Original keeps the legacy appearance. Up to 16 named presets can store card visibility, order, widths, density and sample count. Changing the dashboard does not restart proxy listeners or rewrite routing rules. Source sections under config have a revision guard to prevent accidental overwrite by a stale editor.

Sample files and safe changes

Example JSON is in examples/. Treat it as a starting point: addresses, certificates, paths, backend health endpoints and service IDs must match your installation. The API uses full validated settings and rejects unknown fields; it is not a generic patch store. Use the current authenticated /docs → API OpenAPI reference to inspect field schemas.

For planned changes, export configuration, create an encrypted backup, make one logical change, save, verify real traffic and confirm metrics/logs. Revert via configuration history only when rollback of the config (not filesystem/secrets) is sufficient.