# Vhost management - historical 0.4-era implementation record

> Historical context. This document is retained for implementation traceability and must not
> be used as the current vhost/operator guide. Use [VHOSTS.md](VHOSTS.md),
> [CUSTOM_LOCATIONS.md](CUSTOM_LOCATIONS.md), [VHOST_ACCESS.md](VHOST_ACCESS.md) and
> [WEB_SERVER.md](WEB_SERVER.md) for current behavior.

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.