Config schema
Every top-level block of the YAML/JSON config file. The only accepted schema version is v1. Most fields are optional; the minimal config in examples/edge-minimal.yaml shows the smallest valid file. The full example with comments lives at examples/edge-full.yaml.
version
Schema version. The only accepted value today is "v1". Empty defaults to "v1". A future v2 will be a hard break.
mode
Top-level role selector:
""(default) — auto. SBI on unless Diameter is enabled with no SBI workload.sbi— SBI listener only.diameter— Diameter listener only.both— both protocols.
server (SBI HTTP/2 listener)
Inbound transport is HTTPS+HTTP/2 when server.tls is set, h2c (HTTP/2 cleartext) otherwise. There is no HTTP/1.1 fallback — 3GPP SBI mandates HTTP/2.
| Field | Type | Default | Description |
|---|---|---|---|
listen | string | :8090 | Listen address. |
tls.cert_file | string | — | Server certificate. Required when tls is set. |
tls.key_file | string | — | Server private key. Required when tls is set. |
tls.ca_file | string | — | CA bundle. Required when require_client_cert: true. |
tls.insecure | bool | false | Disable cert verification on the server side. Rare. |
require_client_cert | bool | false | Enforce mTLS. |
timeouts.read_timeout | duration | 30s | |
timeouts.read_header_timeout | duration | 10s | |
timeouts.write_timeout | duration | 60s | |
timeouts.idle_timeout | duration | 120s | |
timeouts.max_header_bytes | int | 1048576 | 1 MiB. |
max_request_body_size | int | 1048576 | 1 MiB. |
diameter (relay)
See Diameter peering for the full connection-mode model.
| Field | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Enable the Diameter relay. |
listen_addr | string | — | Listen address. Required when any peer is responder or both. |
transport | string | tcp | tcp or sctp. |
origin_host | string | — | Origin-Host AVP value. |
origin_realm | string | — | Single Origin-Realm form. Ignored when origin_realms is non-empty. |
origin_realms | []string | — | All realms this node is authoritative for; first entry is primary (RFC 6733 §6.3 requires one per message). |
vendor_id | uint32 | 0 | Vendor-Id AVP. |
accept_undefined_peer | bool | false | Accept CER from peers not listed in peers[]. |
product_name | string | Edgeguard | Product-Name AVP in CER/CEA. |
host_ip_addresses | []string | library-derived | Host-IP-Address AVPs. |
timers.cea_timeout | duration | 10s | CER/CEA capabilities-exchange timeout. |
timers.dwa_timeout | duration | 10s | DWR/DWA watchdog answer timeout. |
timers.dpa_timeout | duration | 5s | DPR/DPA disconnect timeout. |
timers.stop_timeout | duration | 10s | Graceful-shutdown bound. Caller deadlines win. |
duplicate_protection | bool | false | Enable RFC 6733 §6.3.4 duplicate detection. |
duplicate_timer | duration | 240s | Per-entry TTL when protection is on. |
watchdog_interval | duration | library default | DWR send cadence. |
reconnect_interval | duration | library default | Delay before reconnecting a dropped peer. |
request_timeout | duration | 10s | Upper bound on how long the relay waits for an upstream answer. |
max_missed_watchdogs | int | library default | Close the peer after this many missed DWA answers. |
applications[] | list | — | Each entry: app_id, vendor_id, app_type (auth/acct). |
peers[] | list | — | Each entry: address, connection_mode (initiator/responder/both), optional name, realm, rating. |
routes[] | list | — | Realm-based routes: realm, application_ids, peers, local_action. |
sctp | object | — | SCTP tuning (used only when transport: sctp). |
tls | object | — | TLS configuration (used only when transport: tcp). |
Duration format
Every
duration field below — across server, diameter,
process, admin, and the rest — uses the same encoding. YAML accepts
Go duration strings (10s, 250ms). JSON requires nanoseconds as an
integer (10000000000 for 10s).process
| Field | Type | Default | Description |
|---|---|---|---|
drain_delay | duration | 0s | Lame-duck pause after readiness flips to draining. Set ~2× your probe interval in a cluster; leave 0 on a laptop. |
shutdown_timeout | duration | 15s | Graceful-shutdown bound after the drain delay. |
store_watch_interval | duration | 5s | Control-plane store poll cadence. |
storage
See Using PostgreSQL for the production patterns.
| Field | Type | Default | Description |
|---|---|---|---|
control_plane_db.driver | string | sqlite | sqlite or postgres. |
control_plane_db.dsn | string | in-memory shared-cache sqlite | Connection string. |
admin
| Field | Type | Default | Description |
|---|---|---|---|
grpc_listen | string | — | EdgeControl gRPC listen address. Empty leaves the admin surface down. Set 127.0.0.1:9091 or :9091 to match the port d3x-edgectl targets by default. The legacy admin.listen field is not used. |
default_action | string | deny | allow or deny. Seeded into the policy store on first run. |
allow_anonymous | bool | false | Must be true if auth is empty, otherwise the proxy refuses to start. |
allow_insecure | bool | false | Opt into cleartext gRPC. Production should use TLS. |
auth.users[] | list | — | Operator roster for the Login RPC. Each entry: username, password_hash (bcrypt), role (admin/operator/viewer). Empty disables login. |
auth.login_token_ttl | duration | 1h | Validity window of a JWT issued by Login. The shipped examples/edge-minimal.yaml sets 24h. |
auth.api_key | string | — | Legacy single key. Prefer api_key_file. |
auth.api_key_file | string | — | Path to a file holding the API key. |
auth.jwt_secret | string | — | HMAC secret used to validate (and, for the login form, issue) JWTs. Prefer jwt_secret_file. |
auth.jwt_secret_file | string | — | Path to a file holding the HMAC secret. |
auth.jwt_public_key | string | — | Path to RSA/ECDSA public key for JWT verification. |
tls | object | — | TLS material. Configuring this lets you drop allow_insecure. |
require_client_cert | bool | false | mTLS on the admin listener. |
observability
| Field | Type | Default | Description |
|---|---|---|---|
service_name | string | edge | Canonical identity stamped on logs as service and used as OTel service.name when tracing.service_name is empty. |
metrics_listen | string | — | Dedicated HTTP listener for /metrics, /health, and /ready. Empty disables it. Required for Diameter-only scrapes (CLI: -metrics :9100). The SBI listener still serves the same paths when SBI is on. |
logging.level | string | info | trace | debug | info | warn | error. |
logging.format | string | console | console or json. |
logging.logfile | string | stderr | Append log output here instead of stderr. |
logging.caller | bool | false | Include file:line on every line. |
logging.db_query_log | bool | false | Log every SQL query (debug; warn for slow > 200 ms). |
pprof.enabled | bool | false | Expose net/http/pprof on the SBI listener. |
tracing.endpoint | string | — | OTLP gRPC endpoint. |
tracing.service_name | string | observability.service_name | OTLP service.name. Empty falls back to observability.service_name (edge). |
tracing.sample_rate | float | 1.0 | 0.0 to 1.0. |
tracing.insecure | bool | false | Disable TLS on the OTLP connection. |
nrf
| Field | Type | Default | Description |
|---|---|---|---|
urls | []string | — | Ordered NRF URLs, primary first. Empty disables NRF. |
heartbeat_interval | duration | 60s | How often to heartbeat the registered profile. |
discover_producers | bool | false | Discover downstream producers from the NRF. |
outbound_h2c | bool | false | Use HTTP/2 cleartext for outbound NRF / producer calls. |
callback_base_url | string | — | Externally-reachable base URL for NRF subscription notifications. |
register_max_attempts | int | 5 | Retries on initial register. |
register_backoff | duration | 2s | Backoff between register attempts. |
profiles | list | — | NF profiles this proxy registers as. |
producers | list | — | Static producer endpoints. |
response_policy
| Field | Type | Default | Description |
|---|---|---|---|
strip_headers | []string | — | Headers to remove from every response. |
topology_hiding.enabled | bool | false | Rewrite producer-side hostnames in responses. |
topology_hiding.external_address | string | — | Hostname or URL to substitute. |
defaults
| Field | Type | Default | Description |
|---|---|---|---|
producer.retry.max_attempts | int | 0 (one attempt, no retry) | Set > 0 to enable retries. examples/edge-full.yaml sets 3. |
producer.retry.base_delay | duration | 100ms when retry is on | |
producer.retry.max_delay | duration | 2s when retry is on | |
producer.circuit_breaker.threshold | int | 5 | Consecutive failures before opening. |
producer.circuit_breaker.timeout | duration | 30s | Open-state cool-down. |
producer.timeout | duration | 30s | Per-request producer timeout. |
producer.redirect | bool | false | 307 redirect to producer instead of proxying. |
request_signing / request_verification
Optional message-level signing for outbound requests, and verification for inbound. When both sides of a proxy chain use signing, you can confirm that an in-flight message hasn't been tampered with by an intermediate.
| Field | Type | Default | Description |
|---|---|---|---|
request_signing.enabled | bool | false | |
request_signing.private_key_file | string | — | PEM-encoded private key. |
request_signing.key_id | string | — | Carried in the signature header for the verifier. |
request_signing.algorithm | string | rsa-pss-sha256 | rsa-pss-sha256 or ecdsa-p256-sha256. |
request_verification.enabled | bool | false | |
request_verification.public_key_file | string | — | PEM-encoded public key. |
Examples
Minimal — the smallest valid file:
YAML
Full — see examples/edge-full.yaml in the repo for the canonical commented example.