Appliance image¶
Two artifacts contain the same thing: a Debian 13 system with Docker installed, the three pygslb containers preloaded, and a systemd unit that starts them at boot. No Internet access is needed at first boot.
| File | Use |
|---|---|
gslb-<version>-amd64.qcow2 |
KVM, Proxmox, libvirt, OpenStack |
gslb-<version>.ova |
VMware (vSphere, Workstation, Fusion), VirtualBox |
Measured on the build host (2026-11-16, version 0.7.0): qcow2 1.82 GiB, OVA
691 MiB, virtual disk 8 GiB. The 0.4.1 artifact booted to a serving stack in
about 3 minutes on 2 vCPU / 4 GiB; the 0.7.0 image was verified structurally
(checksums, qemu-img info, OVF manifest, tar layout) and its first boot was
not validated in the lab — the build host was running three other virtual
machines and the guest never obtained an IPv4 address under QEMU user
networking, so GSLB_ADDR=auto had nothing to resolve. Boot it on the target
hypervisor before publishing it.
What is inside¶
/opt/gslb/compose.yml the three containers, single-host layout
/opt/gslb/images/*.tar gslb, gslb-api, gslb-web, preloaded
/opt/gslb/LICENSE, NOTICE AGPL-3.0-or-later and the copyright notice
/opt/gslb/THIRD-PARTY.md every Debian package installed, and the
licences of the embedded components
/opt/gslb/SOURCE-OFFER.txt how to get the corresponding source
/etc/gslb/gslb.env the only file an operator edits
/etc/systemd/system/gslb-appliance.service
/usr/local/sbin/gslb-up loads the images once, then docker compose up
The containers keep the hardening of the compose files shipped with the
project: non-root UID 1000, cap_drop: ALL, read-only root filesystem,
no-new-privileges, no Docker socket, and the DNS on host networking so it sees
the real client address.
First boot¶
- Import the image (or convert the qcow2 into your platform's format).
- Give it 2 vCPU, 4 GiB of RAM and one network interface on the network your DNS clients use.
- Boot. The console prints either the password you set in
/etc/gslb/gslb.envor a generated one:
gslb: GSLB_ADDR=auto resolved to 192.0.2.10
gslb: generated an API password: see /etc/gslb/initial-credentials (mode 600)
- Open
http://<appliance>:8080. The first-start wizard asks for the zone, one pool, its backends and the operator password. It applies the configuration through the same validate → write → acknowledge → rollback path as every later save. - Point a client at it:
dig @<appliance> app.example.com A +short.
GSLB_ADDR=auto binds the address of the default route. That is deliberate: the
image runs systemd-resolved, which holds 127.0.0.53:53, so a DNS bound to
0.0.0.0:53 would fail. Set GSLB_ADDR to an explicit address when the
appliance has several interfaces and you want to choose.
Ports¶
| Port | Service | Exposure |
|---|---|---|
| 53/udp, 53/tcp | DNS | the client networks only |
| 8080/tcp | web console (nginx → API) | the management network only |
| 22/tcp | SSH, when a cloud-init seed installs a key | management only |
The API itself publishes no port: it is reachable only through nginx. DNSSEC, DoT/DoH and anycast are not offered — see the security page for what is and is not protected.
Configuration¶
Everything an operator changes is in /etc/gslb/gslb.env (mode 600):
GSLB_ADDR=auto # or a fixed address
GSLB_WORKERS=1 # or auto: one process per core
GSLB_WEB_PORT=8080
GSLB_API_USER=admin
GSLB_API_PASSWORD=... # generated on first boot when empty
GSLB_API_TOKEN= # for HA nodes
GSLB_LOG_LEVEL=INFO
GSLB_LOG_FORMAT=text # or json
GSLB_RETENTION_DAYS=7
After a change: systemctl restart gslb-appliance. The zone itself is managed in
the console, not in this file.
Any variable the API or the DNS reads can be added to this file: the compose
file baked into the image already declares them all as pass-throughs, so no
/opt/gslb/compose.yml edit is needed. OIDC is off by default; the commented
block at the end of gslb.env.example lists what to fill, and
GSLB_SESSION_SECRET is then mandatory.
Driving the first boot from cloud-init¶
The image answers the NoCloud datasource, so a hypervisor template or a
provisioning tool can set the hostname, the SSH key and the credentials without
touching the console. An example seed is in packaging/appliance/cloud-init/:
cloud-localds seed.iso user-data meta-data
qemu-system-x86_64 -enable-kvm -m 4096 \
-drive file=gslb-0.7.0-amd64.qcow2,if=virtio \
-drive file=seed.iso,media=cdrom \
-netdev user,id=n0 -device virtio-net-pci,netdev=n0
Without a seed the appliance still boots and generates its own password.
A node in a fleet¶
The default is a single host: DNS, API and console. To use the appliance as a DNS node behind a central management host, keep the same image and change the environment:
GSLB_API_URL=http://<management-host>:8088
GSLB_API_TOKEN=<token>
GSLB_INSTANCE=dns-a
GSLB_ADDR=192.0.2.10 # the node address, never the VIP
GSLB_HEALTHCHECK_ADDR=192.0.2.10
Then stop the local API and console on that node and let it pull its configuration from the management host — see High availability. The node keeps answering when the management host is down.
Updating¶
docker load --input /opt/gslb/images/gslb-<new>.tar # from the new release
sed -i 's/0.7.0/0.8.0/' /opt/gslb/compose.yml
systemctl restart gslb-appliance
The configuration volume and the database are Docker named volumes
(config, state, data); replacing the image keeps them. Export them before
an upgrade:
docker run --rm -v config:/c -v /root:/backup alpine tar czf /backup/gslb-config.tgz -C /c .
docker run --rm -v data:/d -v /root:/backup alpine tar czf /backup/gslb-data.tgz -C /d .
Rollback¶
Keep the previous image tarballs. Revert the tag in /opt/gslb/compose.yml,
systemctl restart gslb-appliance, done. The database schema is migrated
forward only: a rollback across a schema change needs the backup taken above.
Verify what you downloaded¶
sha256sum -c SHA256SUMS
cosign verify-blob --bundle gslb-0.7.0-amd64.qcow2.bundle \
--certificate-identity-regexp 'https://gitlab.com/claw-prj/pygslb' \
--certificate-oidc-issuer https://gitlab.com \
gslb-0.7.0-amd64.qcow2
The release page carries the SBOM (SPDX) of the container images: it lists every package and every library the appliance runs.
Licence and source¶
The image is a distribution of AGPL-3.0-or-later software, so it ships
LICENSE, NOTICE, THIRD-PARTY.md and SOURCE-OFFER.txt in /opt/gslb. The
corresponding source of the exact version is the Git repository at the matching
tag, or the source archive attached to the same release. A commercial licence is
available — see LICENSING.md in the repository, or the contact page.
Known limits¶
- The OVA was not booted on VMware. It is validated structurally only
(checksums,
qemu-img check, manifest, tar layout) because no vSphere or Workstation instance was available. The qcow2 boots and serves; the OVA is the same disk converted tostreamOptimizedVMDK with a hand-written OVF. - amd64 only for now. The build script refuses cross-architecture builds; an arm64 appliance is built on an arm64 host with the same script.
- No update channel. The appliance does not phone home, check for updates or
refresh itself: upgrading is the
docker loadabove.