# 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 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. |
| **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](VHOSTS.md), [Cache](CACHE.md), [Web Server](WEB_SERVER.md), [Monitoring](MONITORING.md), [Security](SECURITY.md).

## 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. 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](ACCESS.md).

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](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.

## 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.