Skip to content

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 returns ok <instance> <version>: the node answering, and what it runs. It is meant for a liveness check (keepalived, a probe), so that such traffic is labelled heartbeat in the statistics instead of being mistaken for a _whoami or for real queries. Any other type on either name answers NOERROR with no record.
  • AAAA: a backend without ipv6 is 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.