glm-5.1
fecc385d75
- ADR-020: Document defense-in-depth rationale for running in a minimal Docker container (memory-safe language + container isolation), flexible upstream addressing (Docker DNS, loopback, LAN, tunnel endpoints), file-primary logging for fail2ban, and volume mount strategy - ADR-016: Add allow_wildcard_bind override for container deployments where 0.0.0.0 is correct inside the container network namespace - operations.md: Add container deployment section with Docker Compose example, networking table, volume mounts, and health check integration; flip logging to file-primary for fail2ban reliability; note systemd as alternative to container deployment - config.md: Restructure logging fields into nested LoggingConfig (matching TOML [logging] section), add allow_wildcard_bind, shutdown_timeout_secs, and log_file_path fields; clarify upstream addressing supports Docker DNS and tunnel endpoints; update validation rule for 0.0.0.0 override - overview.md: Update architecture diagram for container model with Docker networking and volume mounts; add ADR-020 reference - proxy.md: Clarify X-Forwarded-Proto is determined by listener port, not hardcoded 80/443 - ADR-013: Fix health_check_port default contradiction (default is 9900, not 0/disabled as previously stated)
2.7 KiB
ADR-016: Explicit Bind Address Requirement
Status
Accepted
Context
The proxy's bind_addr configuration field specifies the IP address to bind
to. The default for most network services is 0.0.0.0 (bind all interfaces),
which means the service is accessible on every network interface, including
public-facing ones.
For a reverse proxy that terminates TLS and handles security-sensitive traffic, binding to all interfaces is risky. The proxy should only listen on the intended interface(s) — typically a specific public IP for a single-server deployment.
Decision
The bind_addr field on each [[listeners]] entry must be an explicit IP
address. 0.0.0.0 is rejected during config validation unless explicitly
overridden. The proxy will not start if any listener's bind_addr is
0.0.0.0 and the override is not enabled.
Override mechanism: allow_wildcard_bind = true in the config file, or
--allow-wildcard-bind on the command line. This flag permits 0.0.0.0 as a
valid bind address. It is intended for container deployments where the
container's network namespace is isolated and 0.0.0.0 is the correct address
(Docker publishes only the explicitly mapped ports).
Rationale
- A reverse proxy terminating TLS is a security boundary — it should not be accidentally exposed on unintended interfaces
- Single-server deployments have a specific public IP; binding to it deliberately is the correct operational practice
0.0.0.0is often a default in example configurations and can be deployed without the operator realizing the service is accessible on all interfaces- Rejecting it at validation time prevents this common mistake
- In a container,
0.0.0.0is correct and safe because the container's network namespace isolates it — only Docker-published ports are reachable from outside the container - The override is opt-in so it must be a deliberate choice, not an accident
- This matches the principle of explicit over implicit for security-sensitive configuration
Consequences
Positive:
- Prevents accidental exposure on unintended network interfaces in bare-metal deployments
- Forces operators to be deliberate about which interface the proxy serves
- Config validation catches the mistake before deployment
- Container deployments work correctly with
0.0.0.0when the override is explicitly enabled
Negative:
- Container deployments require one extra config flag (
allow_wildcard_bind = true) — a minor operational step - Slightly more configuration required for bare-metal (operator must know their public IP)