Getting Started | Starstorm

This guide gets you from zero to a working DNS server in under 10 minutes. You will install the daemon, start it with a minimal config, and verify DNS responses using dig.

Who is this for?

Operators / SREs evaluating Nexus GSLB
Developers wanting to try the DNS and health-checking behaviour locally

Prerequisites

Linux or macOS host
curl and dig (from bind-utils / dnsutils)
Root access (for port binding and systemd install)

Step 1 — Install

Linux (auto-install):

curl -fsSL https://gslb.nexus/install.sh | sudo bash

This detects your architecture, downloads the latest release from gslb.nexus, verifies the checksum, installs gslbd and gslbctl, and sets up a systemd unit.

macOS (manual):

VERSION=0.1.0
curl -fsSLO "https://gslb.nexus/releases/v${VERSION}/nexus-gslb-${VERSION}-darwin-arm64.tar.gz"
tar -xzf "nexus-gslb-${VERSION}-darwin-arm64.tar.gz"
sudo install -m 755 "nexus-gslb-${VERSION}-darwin-arm64/gslbd" /usr/local/bin/gslbd
sudo install -m 755 "nexus-gslb-${VERSION}-darwin-arm64/gslbctl" /usr/local/bin/gslbctl

Use darwin-amd64 for Intel Macs.

Step 2 — Minimal configuration

Create /etc/gslb/config.yaml:

sudo mkdir -p /etc/gslb
sudo tee /etc/gslb/config.yaml > /dev/null <<'YAML'
dns:
  listenAddr: "0.0.0.0"
  port: 5353                     # 5353 requires no root; change to 53 for production
  domain: "gslb.example.com"    # authoritative zone (trailing dot optional)
rqlite:
  httpAddr: localhost:4001       # local rqlited datastore (see reference/Datastore.md)
api:
  enabled: true
  listenAddr: "127.0.0.1"
  port: 8080
loadBalancer:
  algorithm: round-robin
  endpoints:
    - 203.0.113.10
    - 203.0.113.11
health:
  enabled: true
  type: http
  port: 80
  checkInterval: 10s
  timeout: 2s
YAML
sudo mkdir -p /var/lib/gslbd

Tip: Replace 203.0.113.10 and 203.0.113.11 with real servers you control. For a quick smoke-test without real backends, set health.enabled: false.

Step 3 — Start

sudo systemctl start gslbdsudo systemctl status gslbdjournalctl -u gslbd -f

Or run directly (foreground):

sudo gslbd -config /etc/gslb/config.yaml

Step 4 — Verify with dig

# A record — should return one of your endpointsdig @127.0.0.1 -p 5353 A gslb.example.com.# Repeat to see round-robin cyclingdig @127.0.0.1 -p 5353 A gslb.example.com.dig @127.0.0.1 -p 5353 A gslb.example.com.# AAAA (if you have IPv6 endpoints)dig @127.0.0.1 -p 5353 AAAA gslb.example.com.

If a health check marks an endpoint unhealthy it will be skipped in responses.

Step 5 — Create the first admin user

The API requires authentication. Call the one-time setup endpoint:

curl -X POST http://localhost:8080/api/v1/auth/setup \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"your-secure-password"}'

Disable the setup endpoint in config.yaml after use:

auth:
  setupEndpoint: false

Then open the WebUI at http://localhost:8080/ (or your domain if running behind Caddy).

What's next

Installation guide — Docker Compose, DEB/RPM packages, port 53 setup
Configuration reference — all config fields explained
Three-node cluster — multi-region HA with NATS
Metrics & Grafana — Prometheus dashboards
Troubleshooting