v0.24.5

docs/MANAGEMENT.md

@@ -0,0 +1,134 @@
+# Vhost management (updated for 0.4.0)
+
+This guide describes implemented source behavior. Read TEST_REPORT.md before
+acceptance: the packaging environment did not compile or run the Rust backend.
+
+## Compact operations
+
+Vhosts opens a compact list with domains, bound sockets, backend count and live
+health/latency. Edit opens a modal with Details, Backends, Health, SSL, Cache,
+Security, Pages, Authentication and Advanced tabs. Existing source/ACL JSON remains available.
+The structure is inspired by proxy-host managers, not a claim of full feature
+parity with nginx-proxy-manager. Density is configured in Settings and stored only
+as a browser preference. Logo and favicon have not been redesigned.
+
+## Optional certificate upload
+
+In Certificates, upload certificate/full chain PEM and an unencrypted private-key
+PEM. The pair is cryptographically validated and written to private immutable files;
+the form then saves inventory metadata through revision CAS. No vhost or DNS name
+is required just to import a certificate. In a separate vhost save, choose its ID
+in SSL; validation checks that it covers the host's configured DNS names.
+The file inputs clear after the request. Failed/stale inventory saves can leave
+unbound staged files; no key bytes are returned by the API or stored in the config.
+Clear/inherit uses the global SNI/default behavior.
+
+Limits: 128 KiB per file, 300 KiB JSON request, up to 16 supplied DNS names, two concurrent
+upload workers, 64 configured certificate inventory entries and 128 staged/upload
+pairs on disk. Canceled uploads remain staged; no automatic deletion of potentially
+active keys is attempted. New uploads eventually stop at that limit. Perform
+manual cleanup only after backup and confirmation that neither the saved
+configuration nor the serving snapshot references those files, preferably stopped.
+The configured-certificate backup does not collect unused staging files.
+
+Certificates must cover the configured DNS names. This does not prove browser trust,
+chain completeness, revocation status or remaining lifetime. ACME-issued certificates
+are shown as managed/read-only inventory entries; they are renewed through the ACME
+workflow rather than edited as uploaded custom PEM files. New issuance selects the
+production CA environment by default but still requires explicit production confirmation;
+staging remains available for testing. A certificate can be deleted only after it has
+been unassigned and saved everywhere, including vhosts, redirects, 404 hosts, the
+default TLS certificate and the administration panel. Encrypted-key password prompts
+are not supported. The single SNI resolver rejects different selected certificates for
+one DNS name on different IP bindings. Socket changes still require restart; changing
+a certificate for an existing listener uses hot snapshot publication after Save.
+Requests already in flight are not interrupted.
+
+## Cache and response headers
+
+Cache selectors distinguish inheritance, on and off. Blank numeric fields inherit.
+TTL/object limits, query/path exclusions and optional diagnostics are configurable
+per host. The memory/entry ceilings are shared globally; one host cannot increase
+its object ceiling above the global limit. Explicit per-vhost enable is permitted
+when the global cache is explicitly disabled. Cookie-affine pools and path cache=false still
+bypass. Purge on a host clears its entries and invalidates its in-progress fills,
+without rewriting configuration or evicting other hosts. Changing configuration
+still performs a full invalidation.
+
+Security includes visual rules for headers sent to the backend and to the client,
+and per-vhost HSTS/nosniff/frame/referrer/CSP/permissions policies. Advanced JSON
+edits update the visual rows. Global, vhost and path header rules run in order;
+existing final Server/security/protocol safeguards retain precedence. In
+particular, a hidden Server cannot be restored by an ordinary header rule. An
+explicit per-vhost Server override can replace the inherited global Server policy.
+
+## Custom pages
+
+Global Settings / Pages supplies error defaults, direct-IP and unknown-host
+responses. Vhost / Pages supplies an optional static response, a missing-path
+fallback and error overrides. Modes are inheritance, built-in congratulations,
+empty and administrator HTML (typed or loaded from an HTML file).
+
+Supported error keys: 400, 401, 403, 404, 408, 413, 429, 500, 502, 503 and 504.
+Keep the original status by leaving status unset; an explicit status is allowed
+from 200, 204, 400, 401, 403, 404, 408, 410, 413, 429, 500, 502, 503 or 504. Only empty
+mode permits 204. HTML is at most 32 KiB UTF-8 per page and the complete serialized
+configuration remains bounded to 256 KiB. No CSS/image asset hosting or directory
+serving is provided; use self-contained HTML or an upstream for multi-file sites.
+The built-in congratulations text is English; replace it with your own HTML for
+other languages. RustProxy-generated 503 and 504 failures use matching built-in dark
+HTML pages when no administrator override is configured; vhost/global custom error
+pages still take precedence. An origin's own 503/504 response is not rewritten unless
+a custom error override is configured. Admin interface translations still come from
+language packs.
+
+Request behavior:
+
+1. Validate authority/path and real local binding; check applicable host/path ACLs
+   and enabled Tinyauth authentication before serving any content.
+2. Use the explicit direct-IP page for a literal IPv4/IPv6 authority, if enabled.
+3. Otherwise use the matching vhost's static response, if configured.
+4. If no path is selected, use that vhost's missing-path fallback; if there is no
+   matching vhost, use the global unknown-host fallback. Otherwise keep normal 404.
+5. Forward normally when a route exists, then replace a configured error with its
+   vhost override or global default. Apply the normal response/security policy.
+
+Static/fallback endpoints accept GET/HEAD; other methods get 405 with Allow.
+HEAD has the selected response headers and no body. Default status for a static
+vhost/direct-IP page is 200; a missing-path/unknown-host fallback retains 404 unless
+explicitly changed. Error responses retain their original status by default.
+Already-authored pages are not rewritten a second time by error rules. Replacement
+drops old encoding, length, cookies and other representation metadata, while
+preserving authentication challenges, Retry-After and Allow. Pages use no-store.
+
+ACL denial always prevents upstream access, even when its 403 page is configured
+to return 200. A success status for an authentication/server error can mislead
+clients and monitoring. Prefer preserving original statuses. Direct-IP HTTPS
+must still finish TLS; this HTTP feature cannot bypass certificate validation.
+
+HTML is not previewed in the admin DOM. It is trusted administrator content and
+may execute scripts when served to visitors. Never import untrusted HTML.
+
+## Separate live-log window
+
+Use Live logs in the toolbar or a host's Logs button. Choose modal or docked mode;
+filters remain above a scrollable table. Filters combine vhost, method, status
+family, cache/error outcome and text (host, path, method, vhost, backend). Pause
+freezes the displayed bounded snapshot, not collection. Resume uses the latest
+snapshot. Export contains exactly the selected rows. Closing/reopening keeps
+filters; signing out clears viewer state.
+
+The source is a 256-entry in-memory access ring refreshed through SSE/polling.
+It is not an unbounded tail, durable file, guaranteed replay or audit store. The
+vhost field comes from the actual selected frontend and remains available for
+cache/static responses, without fabricating a backend request. Pool health data
+are live observations, not settings; disabled checks are not proof of liveness.
+
+## Additional 0.4.0 controls
+
+The Authentication tab enables Tinyauth. Security includes inherited/per-vhost
+Server and diagnostic header settings. Details selects named listeners shared
+with other vhosts; inline listeners are not part of the current configuration model. Certificates are managed in
+the separate inventory rather than uploading keys from each vhost editor.
+The toast moves into the active dialog/top layer so its message and action remain
+visible and interactive above the backdrop. See INTEGRATIONS_040.md for contracts.