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 |