Skip to content

Corefile Reference

This document provides a comprehensive reference of all Corefile configuration parameters available inside the gslb block.

CoreDNS-GSLB automatically watches its configuration files and reloads them at runtime when changes are detected. This allows most configuration updates to be applied without restarting CoreDNS.

Syntax Overview

gslb {
    # Zone-to-file mappings
    zone example.org.   /etc/coredns/db.example.org.yml

    # GeoIP MaxMind databases
    geoip_maxmind country_db /coredns/GeoLite2-Country.mmdb
    geoip_maxmind city_db    /coredns/GeoLite2-City.mmdb
    geoip_maxmind asn_db     /coredns/GeoLite2-ASN.mmdb
    geoip_custom             /coredns/location_map.yml

    # DNS Features
    use_edns_csubnet
    disable_txt

    # Scrapers and Healthchecks Startup Settings
    max_stagger_start "120s"
    batch_size_start 100

    # Scraper Idle optimization
    resolution_idle_timeout "3600s"
    healthcheck_idle_multiplier 10

    # REST API Configuration
    api_enable true
    api_tls_cert ""
    api_tls_key ""
    api_listen_addr 0.0.0.0
    api_listen_port 8080
    api_basic_user admin
    api_basic_pass secret

    # Global Healthcheck Profiles Reference File
    healthcheck_profiles /etc/coredns/healthcheck_profiles.yml

    # Redis Shared Health Checks Options
    redis_enable true
    redis_addr 127.0.0.1:6379
    redis_password securepass
    redis_db 0
    redis_key_prefix gslb:
    redis_sync_mode lock

    # Standalone Local Disk State Persistence (ignored if redis_enable is true)
    state_persist_enable true
    state_persist_path /var/lib/coredns-gslb/state.json
    state_persist_interval 30s
    state_max_age 60s
}

Configuration Parameters

Zone Definitions

  • zone <fqdn> <path> (Required, repeatable): Maps an authoritative DNS zone (must end with a trailing dot) to its corresponding YAML configuration file containing records.

GeoIP Settings

  • geoip_maxmind <type> <path>: Loads a MaxMind GeoIP2 database.
  • <type> can be:
    • country_db: Used for matching by country (two-letter ISO code) and continent.
    • city_db: Used for matching by coordinates (latitude and longitude), city, subdivision, country, and continent.
    • asn_db: Used for matching by Autonomous System Number (asn).
  • Block Syntax Support: You can also use a block format: 
    geoip_maxmind {
    country_db /coredns/GeoLite2-Country.mmdb
    city_db    /coredns/GeoLite2-City.mmdb
    asn_db     /coredns/GeoLite2-ASN.mmdb
}
  • geoip_custom <path>: Path to a YAML file mapping subnets to custom locations for custom-scoped geographical routing. Subnets are pre-parsed on load and configuration reloads to avoid runtime overhead.

DNS & Protocol Flags

  • use_edns_csubnet: Enables EDNS Client Subnet (ECS, RFC 7871) support. When active, GSLB uses the client's subnet instead of the DNS resolver IP to perform geo-routing. See the ECS and Caching Guide for details.
  • disable_txt: Disables automatic TXT record generation for GSLB-managed domains. If set, TXT queries are passed to the next plugin or return empty.

Startup & Timing Tuning

  • max_stagger_start <duration>: The maximum duration to randomize/stagger the start of background healthchecks (default: "120s").
  • batch_size_start <number>: The number of backend healthcheck scrapers to boot up concurrently during startup (default: 100).
  • resolution_idle_timeout <duration>: The duration after which a record is considered idle if it receives no DNS queries (default: "3600s").
  • healthcheck_idle_multiplier <multiplier>: The factor by which a backend's health check scrape interval is multiplied when the record becomes idle (default: 10).

REST API Options

  • api_enable <bool>: Enables or disables the REST API server (default: true).
  • api_listen_addr <ip>: The bind IP address for the REST API server (default: 0.0.0.0).
  • api_listen_port <port>: The bind port for the REST API server (default: 8080).
  • api_tls_cert <path>: Path to the TLS certificate file (enables HTTPS if set with api_tls_key).
  • api_tls_key <path>: Path to the TLS private key file (enables HTTPS if set with api_tls_cert).
  • api_basic_user <username>: Username to enforce HTTP Basic Auth on API requests (optional).
  • api_basic_pass <password>: Password to enforce HTTP Basic Auth on API requests (optional).

Reusable Profiles File

  • healthcheck_profiles <path>: Path to a YAML file containing global health check profiles shared across all zone files. See the Health Checks Guide for structure.

Redis Cluster Mode Options

  • redis_enable <bool>: Enables or disables Redis shared health checks synchronization (default: false).
  • redis_addr <ip:port>: The address and port of the Redis server (default: "127.0.0.1:6379").
  • redis_password <password>: Authentication password for the Redis server (default: "").
  • redis_db <number>: Database number to use inside the Redis server (default: 0).
  • redis_key_prefix <prefix>: Prefix prepended to all Redis keys used by GSLB (default: "gslb:").
  • redis_sync_mode <mode>: The synchronization mode to coordinate health checks (default: "lock").
  • lock (Distributed Lock Mode): Before executing a check, GSLB instances try to acquire a short-lived SETNX distributed lock on the backend. Only the instance that acquires the lock runs the physical health check, writes the result to Redis, and broadcasts a real-time update via Pub/Sub. The other instances skip the check and rely on Redis. This mode is highly recommended to minimize duplicate probing load on backends.
  • none (No Lock Mode): All GSLB instances run their health checks independently on their own local schedules. However, they still write their results to Redis and publish changes to the pub/sub channel. Use this mode if you want independent probing from each instance, but still wish to maintain a unified fallback cache of check history in Redis.

Standalone State Persistence Options (Standalone Mode Only)

[!NOTE] These options are only active when redis_enable is set to false (standalone mode). If Redis cluster mode is enabled, local disk persistence is ignored as Redis acts as the centralized state manager.

  • state_persist_enable <bool>: Enables or disables local state persistence on disk (default: false).
  • state_persist_path <path>: File path where the serialized health state JSON file is written to and read from (default: "/var/lib/coredns-gslb/state.json").
  • state_persist_interval <duration>: How often the local state is periodically flushed to disk (default: "30s").
  • state_max_age <duration>: The maximum allowed age for a state file to be loaded at startup. If the file on disk is older than this value, it is ignored as stale and a fresh cold start is performed (default: "60s").