Configuration overview

VPN Hub accepts one strict YAML document or a directory layout. Unknown keys fail decoding. In a directory, hub.yaml holds the base configuration, optional devices.yaml adds devices, and each YAML file under tunnels/ contributes a tunnels: list.

/etc/vpn-hub/
├── hub.yaml
├── devices.yaml
├── tunnels/
│   ├── office.yaml
│   └── edge.yaml
└── secrets/

Relative source.value paths resolve below /etc/vpn-hub by default. Keep the directory 0700, ordinary configuration 0600, and secret-bearing provider material SOPS-encrypted.

`hub`

Type: object
Required: Yes
Default: None
Validation: Must contain endpoint, server_public_key, client_cidr, and dns_address.
Secret classification: Contains public control settings; endpoint and topology may still be sensitive.
Side effects: Defines ingress, resolver, fallback listeners, and generated profiles.
Minimal example: hub: { endpoint: vpn.example.com:51820, ... }

`devices[]`

Type: array of Device
Required: No
Default: Empty array
Validation: IDs, addresses, and public keys must be unique; every entry is validated as a whole.
Secret classification: Public keys are not private keys; the list reveals enrolled topology.
Side effects: Creates ingress peers and assigns each source address to an Internet egress.
Minimal example: devices: []

`tunnels[]`

Type: array of Tunnel
Required: No
Default: Empty array
Validation: IDs are unique; routes and DNS zones cannot overlap across tunnels.
Secret classification: Metadata is not a credential, but source values may be secret.
Side effects: Creates isolated namespaces, routes, resolvers, and provider processes.
Minimal example: tunnels: []

`client_acls[]`

Type: array of ClientACL
Required: No
Default: Empty array
Validation: Each source, target, protocol, and port tuple must be valid and unique.
Secret classification: No; it exposes policy relationships.
Side effects: Adds narrow exceptions to default client-to-client isolation.
Minimal example: client_acls: []

Validate after every edit:

sudo hubctl --config /etc/vpn-hub validate
sudo hubctl --config /etc/vpn-hub deploy --dry-run

Next: Hub fields and Tunnel fields.