9.3 KiB
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.
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
- Create or review a named HTTP/HTTPS listener in Settings → Listeners.
- For HTTPS, choose the certificate and protocol capabilities. HTTP/3 is optional and requires UDP access.
- In a Vhost, set exact domains or supported leading wildcards (
*.example.com), select listener IDs and certificate. - Set the source: HTTP reverse proxy or an existing Web Service. Test DNS, TLS and backend health.
- 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.
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. 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.