Skip to content

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

  1. Import the image (or convert the qcow2 into your platform's format).
  2. Give it 2 vCPU, 4 GiB of RAM and one network interface on the network your DNS clients use.
  3. Boot. The console prints either the password you set in /etc/gslb/gslb.env or 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)

  1. 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.
  2. 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 to streamOptimized VMDK 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 load above.