Configuration¶
The YAML file is the single source of truth for the DNS. The API writes it, the DNS reads it, and SQLite only stores statistics and history.
One zone¶
The lot 1 shape, still the normal one for a single-zone deployment:
zone: app.example.com. # trailing dot optional
ttl: 30
default_pool: central
health:
interval: 5
timeout: 2
fail_threshold: 2
success_threshold: 1
soa:
mname: ns1.app.example.com.
rname: hostmaster.app.example.com.
refresh: 3600
retry: 600
expire: 86400
minimum: 60
pools:
central:
- name: central-1
ip: 192.0.2.10
healthcheck_url: https://192.0.2.10/health
verify_tls: false
- name: central-2
ip: 192.0.2.11
healthcheck_url: https://192.0.2.11/health
paris:
- name: paris-1
ip: 192.0.2.20
ipv6: 2001:db8::20
healthcheck_url: https://192.0.2.20/health
weight: 2
network_rules:
- name: Paris office
cidr: 10.10.0.0/16
pool: paris
network_rules is a top-level key, not a pool key. Rules are matched by longest
prefix; ties are broken deterministically (not by YAML order). A rule may carry
a name, which is metadata only: routing keys on cidr and pool.
Several zones¶
health: {interval: 5, timeout: 2, fail_threshold: 2, success_threshold: 1}
zones:
app.example.com.:
ttl: 30
default_pool: central
pools: {central: [...]}
network_rules: [{cidr: 10.10.0.0/16, pool: central}]
api.example.com.:
ttl: 60
default_pool: api
pools: {api: [...]}
network_rules: []
Pools, rules and counters are isolated per zone; the same pool name may exist in
two zones without merging. health stays global. See Several zones.
Top-level keys¶
| Key | Default | Meaning |
|---|---|---|
zone |
required (or zones) |
Served apex; the A/AAAA record is the apex |
ttl |
30 |
Answer TTL, per zone |
default_pool |
required | Pool used when no rule matches or the matched pool is down |
health |
see below | Probe cadence and thresholds |
soa |
derived | Authority for NXDOMAIN answers |
pools |
required | Pool name → list of backends |
network_rules |
[] |
{cidr, pool, name?}, longest prefix wins |
zones |
— | Several zones in one file (lot 3+) |
circuit_breaker |
off | Per-zone spike protection (lot 3+) |
Backends¶
| Key | Default | Meaning |
|---|---|---|
name |
required | Unique label, shown everywhere |
ip |
required | IPv4 address served in A |
ipv6 |
empty | IPv6 address served in AAAA; absent means not served in AAAA |
healthcheck_url |
— | Lot 1 probe: HTTP GET, 2xx means up |
verify_tls |
true |
false also silences the TLS warning |
weight |
1 |
Smooth weighted round-robin; 0 never serves |
maintenance |
false |
Configured and probed, never answered, no DOWN event |
probe |
— | Typed probe block; mutually exclusive with healthcheck_url |
proactive |
— | Advisory indicators, degraded before DOWN |
remove_when_degraded |
false |
Withdraw a degraded backend from rotation |
Health¶
health:
interval: 5 # seconds between probe rounds
timeout: 2 # per-probe timeout
fail_threshold: 2 # consecutive failures before DOWN
success_threshold: 1 # must stay 1
Two failures mark a backend down; one success restores it and resets the counter. The asymmetry is intentional: fail slowly to tolerate a false positive, recover fast to restore capacity. New backends start healthy, so a restart serves immediately.
SOA¶
Used only in the authority section of NXDOMAIN answers. Defaults:
ns1.<zone>, hostmaster.<zone>, 3600/600/86400/60. The serial is fixed to 0:
the zone content is computed, never transferred (no AXFR/IXFR).
Circuit breaker¶
Opt-in, per zone:
circuit_breaker: {factor: 3, window: 60, cooldown: 120}
Each pool counts the queries routed to it during one window. When it closes,
the count is compared with the exponential moving average of the previous
windows; above factor times that reference the pool is skipped for cooldown
seconds and queries answer from default_pool with reason circuit_open. The
first window only seeds the reference, and a trip does not raise it, so
sustained abnormal traffic trips again after each cooldown. Absent or
enabled: false means off.
DNS semantics¶
- The apex carries the A/AAAA record; any other name inside the zone is NXDOMAIN with the SOA in the authority section.
- A name outside every zone is refused.
_whoami.<zone>TXT returns the caller address as seen by the server: the operator's diagnostic for "which address do my clients arrive from".heartbeat.<zone>TXT returnsok <instance> <version>: the node answering, and what it runs. It is meant for a liveness check (keepalived, a probe), so that such traffic is labelledheartbeatin the statistics instead of being mistaken for a_whoamior for real queries. Any other type on either name answers NOERROR with no record.- AAAA: a backend without
ipv6is not served; if no backend has one, the answer is NOERROR with no record (never SERVFAIL, unless everything is down). - Every query is counted, with an explicit fallback reason.
Environment¶
YAML wins for topology; the environment wins for the process. Values are read at
startup, except GSLB_REQUIRE_TLS, GSLB_ALLOW_PLAINTEXT_AUTH and
GSLB_TRUST_PROXY (per request) and GSLB_RETENTION_DAYS (at the daily purge).
The identity provider is the one block with its own precedence, since 0.13:
a value saved in the console (Settings → Identity) wins over the environment,
which wins over the default. It is resolved at each request, so a save applies
to the next sign-in without a restart, and Back to the environment erases the
overrides. GSLB_OIDC_CLIENT_SECRET and GSLB_SESSION_SECRET are not part of
it: they stay in the environment and are never written to SQLite, which is
backed up and restored. Everything the DNS reads remains YAML; no identity key
reaches the routing configuration.
The shipped compose files declare every variable below, either as a
${NAME:-...} pass-through or, for the credentials that have no safe default,
as ${NAME:?…}. docker compose --env-file only performs that substitution: a
variable missing from the service's environment: block never reaches the
container, whatever the env file says. With these files, adding a line to the
env file is enough — and a variable newly read by the code must be added to the
composes too, which tests/test_compose.py enforces.
| Variable | Default | Role |
|---|---|---|
GSLB_CONFIG |
/config/gslb.yaml |
Configuration file the DNS reads |
GSLB_PORT |
53 |
Listen port, UDP and TCP |
GSLB_ADDR |
0.0.0.0 |
Bind address(es), comma-separated for a VIP |
GSLB_HEALTHCHECK_ADDR |
first bind address | Address the container health check queries; a wildcard means loopback |
GSLB_HC_INTERVAL |
5 |
Probe interval, only when the YAML has no health.interval |
GSLB_HC_TIMEOUT |
2 |
Probe timeout, only when the YAML has no health.timeout |
GSLB_LOG_LEVEL |
INFO |
DEBUG, INFO, WARNING, ERROR |
GSLB_LOG_FORMAT |
text |
json emits one object per line, same fields |
GSLB_WORKERS |
1 |
Processes per node: a number, or auto for one per usable core |
GSLB_WORKER |
0 |
Set by the supervisor; never configure it by hand |
GSLB_REUSEPORT |
unset | 1 lets several processes share the port; GSLB_WORKERS>1 sets it |
GSLB_INSTANCE |
hostname | Node name in the fleet view and in heartbeat; leave it unset on a single node to keep the hostname |
GSLB_STATE |
/state |
Reload token, snapshot and event files (wN/ per worker) |
GSLB_API_URL |
unset | HA mode: the management API this node syncs with |
GSLB_API_TOKEN |
unset | Static bearer token a DNS node uses against that API |
GSLB_API_USER |
unset | HTTP Basic user for the console and the API |
GSLB_API_PASSWORD |
unset | HTTP Basic password |
GSLB_API_RO_TOKEN |
unset | Second token: every read, no write |
GSLB_OIDC_ISSUER |
unset | Turns sign-in on: the provider's issuer URL (discovery is read from it) |
GSLB_OIDC_ENABLED |
true |
0 disables sign-in while keeping the values (console-overridable) |
GSLB_OIDC_PRESET |
generic |
google, microsoft or generic; fills the form, changes no behaviour |
GSLB_OIDC_CLIENT_ID |
unset | Confidential client registered at the provider |
GSLB_OIDC_CLIENT_SECRET |
unset | Its secret; environment only, never written to SQLite or a log |
GSLB_OIDC_REDIRECT_URI |
unset | Public URL of /api/v1/auth/callback; derived from GSLB_PUBLIC_ORIGIN when unset |
GSLB_OIDC_SCOPES |
openid profile email |
Scopes requested; openid is required |
GSLB_OIDC_GROUPS_CLAIM |
groups |
Claim that carries the group list |
GSLB_OIDC_ADMIN_GROUP |
unset | Group (or GUID, or app role) mapped to admin |
GSLB_OIDC_OPERATOR_GROUP |
unset | Group mapped to operator |
GSLB_OIDC_READER_GROUP |
unset | Group mapped to reader |
GSLB_OIDC_DEFAULT_ROLE |
unset | Role for a token with no mapped group; unset means refuse |
GSLB_OIDC_ALLOWED_DOMAINS |
unset | Comma-separated bare domains allowed to sign in (checked before the role) |
GSLB_OIDC_DISPLAY_NAME |
SSO |
Label of the sign-in button ("Continue with …") |
GSLB_OIDC_LOGOUT_URL |
unset | Provider logout page the console sends the operator to |
GSLB_SESSION_SECRET |
unset | Signs the session cookie; mandatory once OIDC is on, or sign-in answers 503 |
GSLB_SESSION_TTL |
28800 |
Session lifetime in seconds (8 h); the role is frozen for that long |
GSLB_PUBLIC_ORIGIN |
unset | Public origin of the console, checked by the CSRF guard; unset means the request's own Host |
GSLB_TRUST_PROXY |
unset | 1 reads X-Real-IP, X-Forwarded-For and X-Forwarded-Proto; without it they are ignored |
GSLB_ALLOW_PLAINTEXT_AUTH |
unset | 1 accepts a credential over plain HTTP (lab only; refused by default) |
GSLB_REQUIRE_TLS |
unset | 1 refuses plaintext whatever else is set; 0 is the deprecated alias that allows it |
GSLB_ENV |
production |
Environment label shown by /about and in the console |
GSLB_VIP |
unset | Floating address shown and checkable on the Instances page |
GSLB_VIP_PORT |
53 |
Port the VIP check queries |
GSLB_DB |
/data/gslb.db |
SQLite file (API only) |
GSLB_RETENTION_DAYS |
7 |
Days of routing and health events kept |
TZ |
host zone | Zone used to display instants in the console |
GSLB_REQUIRE_TLS, GSLB_ALLOW_PLAINTEXT_AUTH, GSLB_TRUST_PROXY,
GSLB_API_USER, GSLB_API_PASSWORD, GSLB_API_TOKEN, GSLB_API_RO_TOKEN,
GSLB_PUBLIC_ORIGIN and every GSLB_OIDC_* / GSLB_SESSION_* variable belong
to the API container; the rest to the DNS. With no credential at all the
API answers 503 on every data route — fail closed. The keepalived example adds
its own GSLB_VRRP_* variables, which the DNS process never reads.
OIDC is entirely optional: without GSLB_OIDC_ISSUER, Basic and the tokens are
the only credentials and nothing else changes. With it, /auth/methods
announces it and the console offers a single sign-on button labelled with
GSLB_OIDC_DISPLAY_NAME. Since 0.13 the provider can also be configured from
Settings → Identity in the console; the environment above stays the floor,
and GSLB_OIDC_CLIENT_SECRET/GSLB_SESSION_SECRET cannot be set there. See
OIDC.