140 lines
8.5 KiB
Markdown
140 lines
8.5 KiB
Markdown
# 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.
|