[ OPERATOR GUIDE 02 ]
DECLARATIVE VIRTUAL HOSTS (VHOSTS.D)
Hackergate manages routing through independent YAML files placed in /etc/hackergate/vhosts.d/. The dataplane automatically detects updates and performs atomic pointer swaps without terminating in-flight client TLS connections.
Directory Hierarchy & Schema Autocomplete
/etc/hackergate DIRECTORY STRUCTURE
/etc/hackergate/
gateway.toml # Main daemon settings (listeners, logging, metrics)
vhosts.d/ # Virtual hosts directory (one YAML file per domain)
api.example.com.yaml # API Gateway routing with WAF & Rate Limiting
payments.example.com.yaml # Fintech endpoint with strict mTLS & PL3 WAF
static.example.com.yaml # Static assets served from local filesystem
old-domain.com.yaml # 301 domain migration redirect
schemas/
vhost.schema.json # JSON Schema for VSCode / IDE autocomplete
Production Virtual Host Example
Below is a complete enterprise virtual host YAML demonstrating upstream proxying, automated Let's Encrypt TLS, token bucket rate limiting, and mutual TLS:
/etc/hackergate/vhosts.d/api.example.com.yaml
domain: api.example.com
domainAliases:
- api-eu.example.com
- api-staging.example.com
wildcard: false
# Backend driver: proxy | loadbalancer | static | grpc
backend: proxy
upstream: http://10.244.0.15:8080
# Automated Let's Encrypt TLS or Static Certificates
acme: true
acmeEmail: secops@example.com
httpToHttps: true
httpEnabled: true
# Security profiles evaluated for this domain
securityProfiles: [baseline, api-strict]
# WAF Engine Specific Configuration
waf:
enabled: true
paranoiaLevel: 2
inboundAnomalyThreshold: 5
outboundAnomalyThreshold: 4
# Token Bucket Rate Limiting (per client IP)
ratelimit:
enabled: true
requestsPerSecond: 150
burstSize: 300
# Mutual TLS (mTLS) Client Certificate Verification
mtls:
enabled: false
clientCertCA: /etc/hackergate/pki/client-ca.pem
requestCert: true
# Distributed Tracing & Observability
tracing:
enabled: true
Upstream Pools & Active Health Checking
When backend: loadbalancer is configured, Hackergate distributes traffic across multiple origin backends with continuous background health checking:
/etc/hackergate/vhosts.d/cluster.example.com.yaml
domain: cluster.example.com
backend: loadbalancer
loadbalancer:
algorithm: least-conn # round-robin | least-conn | ip-hash
targets:
- url: http://app-worker-01:8080
weight: 1
- url: http://app-worker-02:8080
weight: 1
- url: http://app-worker-03:8080
weight: 2
healthCheck:
path: /healthz
interval: 5s
timeout: 2s
unhealthyThreshold: 3
healthyThreshold: 2
Unmatched Host & Scanner Containment (RFC 9110)
Automated Internet scanners frequently target raw server IP addresses or send malformed Host: headers. Rather than leaking stack traces or 502 errors, Hackergate intercepts them at the listener layer:
| Fallback Directive | Recommended | Behavior |
|---|---|---|
fallback.mode | "reject" | Answers with an instant HTTP 421 or 444 before any backend connection is opened. |
fallback.status | 421 | RFC 9110 Misdirected Request. Use 444 to terminate TCP socket with zero bytes. |
fallback.profile | "unknown-host" | Evaluates anti-scanner heuristics; repeat probe offenders are banned across the gossip mesh. |