Hub configuration
The hub block defines the one client ingress. Changes to endpoint, key, client network, DNS address, or AWG parameters require profile reissue because those values are embedded in client profiles.
hub.endpoint
- Type
string host:port- Required
- Yes
- Default
- None
- Validation
- Non-empty host and numeric port 1–65535; control characters are rejected.
- Secret classification
- No; public endpoint.
- Side effects
- Sets the profile endpoint and AmneziaWG listen port.
- Minimal example
vpn.example.com:51820
hub.server_public_key
- Type
base64 string- Required
- Yes
- Default
- None
- Validation
- Must decode to a 32-byte X25519 public key.
- Secret classification
- No; keep the matching private key secret.
- Side effects
- Identifies the hub in every client profile.
- Minimal example
W/kKaUP1n48AgIzxs8po0HKV+UEk1vMcTuBW648atSE=
hub.client_cidr
- Type
CIDR string- Required
- Yes
- Default
- None
- Validation
- Must parse as a network and must not overlap the internal 10.90.0.0/16 egress-link range.
- Secret classification
- No; topology metadata.
- Side effects
- Defines ingress addressing, firewall scopes, and device allocation.
- Minimal example
10.80.0.0/24
hub.dns_address
- Type
IP string- Required
- Yes
- Default
- None
- Validation
- Must be an address inside client_cidr and cannot be assigned to a device.
- Secret classification
- No.
- Side effects
- Becomes the client-facing DNS and gateway address.
- Minimal example
10.80.0.1
hub.awg_interface
- Type
map of string to numeric string- Required
- No
- Default
- Empty map
- Validation
- Keys are Jc, Jmin, Jmax, S1, S2, H1, H2, H3, or H4, case-insensitive; values are unsigned 32-bit decimal numbers.
- Secret classification
- No; obfuscation parameters are not credentials.
- Side effects
- Rendered into the ingress and every issued AmneziaWG profile.
- Minimal example
{ Jc: 4, Jmin: 64, Jmax: 256 }
hub.fallback
- Type
object- Required
- No
- Default
- Both fallback paths disabled
- Validation
- Nested fallback settings are validated only when enabled where stated.
- Secret classification
- No, but enabling listeners changes attack surface.
- Side effects
- May accept ingress on UDP/443 and TCP/443.
- Minimal example
fallback: { udp443: false }
hub.fallback.udp443
- Type
boolean- Required
- No
- Default
- false
- Validation
- Cannot be true when endpoint already listens on port 443.
- Secret classification
- No.
- Side effects
- Redirects uplink UDP/443 to the configured AmneziaWG ingress port.
- Minimal example
udp443: true
hub.fallback.reality
- Type
object- Required
- No
- Default
- Disabled object
- Validation
- server_name becomes required when enabled is true.
- Secret classification
- No; keep the matching REALITY private key secret.
- Side effects
- Controls the optional TCP/443 VLESS/REALITY listener.
- Minimal example
reality: { enabled: false }
hub.fallback.reality.enabled
- Type
boolean- Required
- No
- Default
- false
- Validation
- When true, a valid server_name and /etc/vpn-hub/reality.key are needed.
- Secret classification
- No.
- Side effects
- Opens TCP/443 in the host rules only when the listener can be compiled.
- Minimal example
enabled: true
hub.fallback.reality.server_name
- Type
hostname string- Required
- When REALITY is enabled
- Default
- Empty
- Validation
- Bare multi-label hostname, max 253 characters; cannot equal the hub endpoint host.
- Secret classification
- No.
- Side effects
- Selects the real TLS 1.3 site mimicked and used for unauthenticated handoff.
- Minimal example
www.example.com
The outer Terraform firewall exposes 22/TCP only to ssh_allowed_cidrs, 51820/UDP globally, optional fallback transports 443/TCP and 443/UDP, and ICMP. It intentionally leaves both 443 rules present; hub.fallback is the authoritative host-level switch.
Generate keys rather than inventing them:
sudo hubctl keygen --output /etc/vpn-hub/server.keysudo hubctl keygen --reality --output /etc/vpn-hub/reality.keyNext: Fallback and firewall semantics and Devices.