Installation Guide¶

This guide explains how to install and run Pleiades GSLB (gslbd) on Linux using: (a) the automated install script, (b) Docker/Podman, or © manual build from source.

For Kubernetes deployments see docs/user/Kubernetes.md.

Supported platforms¶

Linux x86_64/arm64 (primary)
macOS for development and local testing

Prerequisites¶

Root access (for systemd install) or Docker/Podman.
Go 1.25+ if building from source.
Port 5353 is the default DNS port — no elevated privileges required. To use port 53, see the port 53 note below.

Directory layout¶

Path	Purpose
`/usr/local/bin/gslbd`	Daemon binary
`/usr/local/bin/gslbctl`	Management CLI/TUI
`/etc/gslb/config.yaml`	Main configuration
`/etc/gslb/gslbd.env`	License credentials (env overrides)
`/var/lib/gslbd/gslbd.db`	SQLite state database

Option A: Automated install (systemd)¶

The fastest path for bare-metal Linux. Requires root.

git clone https://your.git/pleiades.git
cd pleiades
sudo bash deploy/install.sh

The script: 1. Builds gslbd and gslbctl if not already present 2. Installs binaries to /usr/local/bin/ 3. Creates a dedicated gslbd system user (no login shell) 4. Creates and permissions /etc/gslb/ and /var/lib/gslbd/ 5. Installs deploy/config.yaml as a starting-point config 6. Installs and enables the hardened systemd unit

After install:

# 1) Edit configuration
sudo nano /etc/gslb/config.yaml

# 2) Set license credentials (optional — free tier works without)
sudo nano /etc/gslb/gslbd.env
# Add: GSLB_LICENSE_KEY=your-key
#      GSLB_LICENSE_SECRET=your-secret

# 3) Start
sudo systemctl start gslbd
sudo systemctl status gslbd
journalctl -u gslbd -f

Upgrade¶

cd pleiades && git pull
go build -trimpath -ldflags="-s -w" -o gslbd ./cmd/gslbd
sudo install -m 755 gslbd /usr/local/bin/gslbd
sudo systemctl restart gslbd

Port 53¶

The default DNS port is 5353 and requires no special privileges. To bind to port 53:

In /etc/gslb/config.yaml set dns.port: 53

In /etc/systemd/system/gslbd.service uncomment:

AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE

sudo systemctl daemon-reload && sudo systemctl restart gslbd

Option B: Docker / Docker Compose¶

git clone https://your.git/pleiades.git
cd pleiades

# Edit the example config
cp deploy/config.yaml deploy/config.local.yaml
nano deploy/config.local.yaml

# Build and run
GSLB_LICENSE_KEY=your-key GSLB_LICENSE_SECRET=your-secret docker compose up -d

The compose stack exposes:

Port	Purpose
5353/udp + 5353/tcp	DNS
8080/tcp	REST API
9090/tcp	Prometheus metrics

The SQLite database is persisted in a named Docker volume (gslbd-data).

Health check: GET http://localhost:8080/api/v1/health (requires api.enabled: true in config).

Run with Podman¶

podman compose up -d
# or without compose:
podman run -d \
  -p 5353:5353/udp -p 5353:5353/tcp \
  -p 8080:8080 -p 9090:9090 \
  -v ./deploy/config.yaml:/etc/gslb/config.yaml:ro \
  -v gslbd-data:/var/lib/gslbd \
  -e GSLB_LICENSE_KEY=your-key \
  pleiades/gslbd:latest

Option C: Build from source (manual)¶

git clone https://your.git/pleiades.git
cd pleiades

# Build both binaries
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o gslbd   ./cmd/gslbd
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o gslbctl ./cmd/gslbctl

# Install
sudo install -m 755 gslbd   /usr/local/bin/gslbd
sudo install -m 755 gslbctl /usr/local/bin/gslbctl

# Create config directory and minimal config
sudo mkdir -p /etc/gslb
sudo tee /etc/gslb/config.yaml >/dev/null <<'YAML'
dns:
  listenAddr: "0.0.0.0"
  port: 5353
  domain: "gslb.example.com"
loadbalancer:
  algorithm: "round-robin"
  endpoints:
    - 203.0.113.10
    - 203.0.113.11
database:
  path: "/var/lib/gslbd/gslbd.db"
api:
  enabled: true
  listenAddr: "127.0.0.1"
  port: 8080
YAML

sudo mkdir -p /var/lib/gslbd
sudo /usr/local/bin/gslbd -config /etc/gslb/config.yaml

Management CLI (`gslbctl`)¶

gslbctl is a terminal UI for managing pools, members, services, health checks, and geo rules without touching the database directly.

# Connect to the local database
gslbctl -db /var/lib/gslbd/gslbd.db

# Also load cluster/NATS config for editing
gslbctl -db /var/lib/gslbd/gslbd.db -config /etc/gslb/config.yaml

Key bindings inside the TUI:

Key	Action
`n`	New item
`e`	Edit selected
`d`	Delete selected
`enter`	Drill into pool (show members)
`H`	Health check screen
`G`	Geo rules screen
`M`	Members screen
`C`	Cluster/NATS config screen
`←` / `→`	Switch tabs (Pools / Services)
`r`	Trigger daemon restart (if restart pending)
`esc`	Back
`q`	Quit

DNSSEC DS record export¶

gslbctl dnssec ds --zone example.com. --ksk-file /etc/gslb/ksk.pem

Outputs the DS record in zone-file format for submission to your registrar.

Uninstall¶

sudo systemctl disable --now gslbd || true
sudo rm -f /etc/systemd/system/gslbd.service
sudo systemctl daemon-reload
sudo rm -f /usr/local/bin/gslbd /usr/local/bin/gslbctl
sudo rm -rf /etc/gslb /var/lib/gslbd

Optional: Enable DNSSEC¶

See docs/Security.md for key generation. Once keys exist:

# /etc/gslb/config.yaml
dnssec:
  enabled: true
  zone: "gslb.example.com."
  ksk:
    pemFile: "/etc/gslb/ksk.pem"
  zsk:
    pemFile: "/etc/gslb/zsk.pem"
  signatureValidityDays: 7

Optional: Enable Configuration Sync (JetStream)¶

state:
  enableConfigSync: true
  nats:
    servers: ["nats://n1.example.com:4222"]
  config:
    mode: "jetstream"
    stream: "PLEIADES.cfg"
    subjectPrefix: "pleiades.cfg"
    kvBucket: "PLEIADES_CFG"
    applyTimeout: "5s"

See docs/user/StateSyncSetup.md for full topology and verification steps.