Skip to content

Command line

python -m gslb is both the DNS process and its command line. Run with no command, it serves — this is the container ENTRYPOINT, unchanged:

python -m gslb                          # serve with the environment
python -m gslb --port 5353              # a `run` option, `run` implied

Every other command is read-only: it loads the file through the runtime's own validator and never binds a socket.

Command What it does
run Serve DNS. The default when no command is named.
init Write a minimal, valid configuration file.
check Validate a file and print its topology.
routes Which pool would answer a given client address.
probe Run one, several or all backend probes once.
version Print the release.

Configuration precedence

--config PATH wins over GSLB_CONFIG, which wins over /config/gslb.yaml. run writes the chosen path back into the environment, so a reload (SIGHUP), the worker supervisor and the probes all read the same file.

Writing a first file

python -m gslb init --zone app.example.com. \
  --backend web-1=192.0.2.10 --backend web-2=192.0.2.11

It writes gslb.yaml — one zone, one default pool, the backends, no routing rule — then reloads it with the runtime's validator, so a file that init accepted is a file run will serve. --output chooses the path, --force overwrites, --health-url changes the probe template ({ip} is the backend address, default http://{ip}/health).

Checking before a restart

python -m gslb check --config /config/gslb.yaml
app.example.com.  ttl 30  default pool default
  pool paris        2 backends: paris-1, paris-2
  pool default      2 backends: central-1, central-2
  rule 10.10.0.0/16       -> paris
  rule 10.20.0.0/16       -> lyon
health  interval 5.0s  timeout 2.0s

Rules are listed longest prefix first, the order the resolver applies. Exit code 0 means the file would load; 1 means it would refuse, with the reason on stderr and no traceback. --json prints the same report for a deployment script:

{"valid": true,
 "health": {"interval": 5.0, "timeout": 2.0},
 "zones": {"app.example.com.": {"ttl": 30, "default_pool": "default",
           "pools": {"default": ["central-1"]},
           "rules": [{"cidr": "10.0.0.0/8", "pool": "default"}]}}}

Understanding a routing decision

python -m gslb routes --ip 10.10.1.5
10.10.1.5  app.example.com.  -> paris (rule 10.10.0.0/16)
  candidates: 192.0.2.10, 192.0.2.11

A client matching no rule reports no rule matched and the default pool. With several zones the command answers for all of them; --zone narrows it. --json wraps the decision in {"ip": ..., "routes": [...]}, with "rule": null and "fallback": true for the default.

The candidates are the configured addresses; whether they are healthy is what the API and the console answer.

Testing a probe

python -m gslb probe --pool paris
python -m gslb probe --backend paris-1 --timeout 2
app.example.com./paris/paris-1   up       status:200
app.example.com./paris/paris-2   unknown  timeout

Each selected probe is executed once, for five seconds at most, and nothing is stored: no health state changes. up and down are conclusions; unknown means the probe could not conclude (timeout, supervision 5xx, unreadable answer, a missing *_env variable) — see Probes and health. The exit code is 0 only when every selected probe answered up.

Inside a container

The DNS image ships no dig — the CLI is the tool that is always there:

docker exec gslb python -m gslb check
docker exec gslb python -m gslb routes --ip 10.10.1.5 --json
docker exec gslb python -m gslb probe --backend paris-1

Exit codes

Code Meaning
0 Success; for probe, every selected probe is up
1 Refusal: invalid file, unknown zone, no backend selected, a probe not up, or a failed init
2 Usage error: argparse rejected the arguments