network/docs/NAMESERVER_SETUP.md

Nameserver Setup Guide

This guide explains how to configure your domain registrar to use Orama Network nodes as authoritative nameservers.

Overview

When you install Orama with the --nameserver flag, the node runs CoreDNS to serve DNS records for your domain. This enables:

• Dynamic DNS for deployments (e.g., myapp.node-abc123.dbrs.space)
• Wildcard DNS support for all subdomains
• ACME DNS-01 challenges for automatic SSL certificates

Prerequisites

Before setting up nameservers, you need:

1. Domain ownership - A domain you control (e.g., dbrs.space)
2. 3+ VPS nodes - Recommended for redundancy
3. Static IP addresses - Each VPS must have a static public IP
4. Access to registrar DNS settings - Admin access to your domain registrar

Understanding DNS Records

NS Records (Nameserver Records)

NS records tell the internet which servers are authoritative for your domain:

dbrs.space.  IN  NS  ns1.dbrs.space.
dbrs.space.  IN  NS  ns2.dbrs.space.
dbrs.space.  IN  NS  ns3.dbrs.space.

Glue Records

Glue records are A records that provide IP addresses for nameservers that are under the same domain. They're required because:

• ns1.dbrs.space is under dbrs.space
• To resolve ns1.dbrs.space, you need to query dbrs.space nameservers
• But those nameservers ARE ns1.dbrs.space - circular dependency!
• Glue records break this cycle by providing IPs at the registry level

ns1.dbrs.space.  IN  A  141.227.165.168
ns2.dbrs.space.  IN  A  141.227.165.154
ns3.dbrs.space.  IN  A  141.227.156.51

Installation

Step 1: Install Orama on Each VPS

Install Orama with the --nameserver flag on each VPS that will serve as a nameserver:

# On VPS 1 (ns1)
sudo orama install \
  --nameserver \
  --domain dbrs.space \
  --vps-ip 141.227.165.168

# On VPS 2 (ns2)
sudo orama install \
  --nameserver \
  --domain dbrs.space \
  --vps-ip 141.227.165.154

# On VPS 3 (ns3)
sudo orama install \
  --nameserver \
  --domain dbrs.space \
  --vps-ip 141.227.156.51

Step 2: Configure Your Registrar

For Namecheap

1. Log into Namecheap Dashboard

   • Go to https://www.namecheap.com
   • Navigate to Domain List → Manage (next to your domain)

2. Add Glue Records (Personal DNS Servers)

   • Go to Advanced DNS tab
   • Scroll down to Personal DNS Servers section
   • Click Add Nameserver
   • Add each nameserver with its IP:

     Nameserver	IP Address
     ns1.yourdomain.com	141.227.165.168
     ns2.yourdomain.com	141.227.165.154
     ns3.yourdomain.com	141.227.156.51

3. Set Custom Nameservers

   • Go back to the Domain tab
   • Under Nameservers, select Custom DNS
   • Add your nameserver hostnames:
     • ns1.yourdomain.com
     • ns2.yourdomain.com
     • ns3.yourdomain.com
   • Click the green checkmark to save

4. Wait for Propagation

   • DNS changes can take 24-48 hours to propagate globally
   • Most changes are visible within 1-4 hours

For GoDaddy

1. Log into GoDaddy account
2. Go to My Products → DNS for your domain
3. Under Nameservers, click Change
4. Select Enter my own nameservers
5. Add your nameserver hostnames
6. For glue records, go to DNS Management → Host Names
7. Add A records for ns1, ns2, ns3

For Cloudflare (as Registrar)

1. Log into Cloudflare Dashboard
2. Go to Domain Registration → your domain
3. Under Nameservers, change to custom
4. Note: Cloudflare Registrar may require contacting support for glue records

For Google Domains

1. Log into Google Domains
2. Select your domain → DNS
3. Under Name servers, select Use custom name servers
4. Add your nameserver hostnames
5. For glue records, click Add under Glue records

Verification

Step 1: Verify NS Records

After propagation, check that NS records are visible:

# Check NS records from Google DNS
dig NS yourdomain.com @8.8.8.8

# Expected output should show:
# yourdomain.com.    IN  NS  ns1.yourdomain.com.
# yourdomain.com.    IN  NS  ns2.yourdomain.com.
# yourdomain.com.    IN  NS  ns3.yourdomain.com.

Step 2: Verify Glue Records

Check that glue records resolve:

# Check glue records
dig A ns1.yourdomain.com @8.8.8.8
dig A ns2.yourdomain.com @8.8.8.8
dig A ns3.yourdomain.com @8.8.8.8

# Each should return the correct IP address

Step 3: Test CoreDNS

Query your nameservers directly:

# Test a query against ns1
dig @ns1.yourdomain.com test.yourdomain.com

# Test wildcard resolution
dig @ns1.yourdomain.com myapp.node-abc123.yourdomain.com

Step 4: Verify from Multiple Locations

Use online tools to verify global propagation:

• https://dnschecker.org
• https://www.whatsmydns.net

Troubleshooting

DNS Not Resolving

1. Check CoreDNS is running:

   sudo systemctl status coredns
   

2. Check CoreDNS logs:

   sudo journalctl -u coredns -f
   

3. Verify port 53 is open:

   sudo ufw status
   # Port 53 (TCP/UDP) should be allowed
   

4. Test locally:

   dig @localhost yourdomain.com
   

Glue Records Not Propagating

• Glue records are stored at the registry level, not DNS level
• They can take longer to propagate (up to 48 hours)
• Verify at your registrar that they were saved correctly
• Some registrars require the domain to be using their nameservers first

SERVFAIL Errors

Usually indicates CoreDNS configuration issues:

1. Check Corefile syntax
2. Verify RQLite connectivity
3. Check firewall rules

Security Considerations

Firewall Rules

Only expose necessary ports:

# Allow DNS from anywhere
sudo ufw allow 53/tcp
sudo ufw allow 53/udp

# Restrict admin ports to internal network
sudo ufw allow from 10.0.0.0/8 to any port 8080  # Health
sudo ufw allow from 10.0.0.0/8 to any port 9153  # Metrics

Rate Limiting

Consider adding rate limiting to prevent DNS amplification attacks. This can be configured in the CoreDNS Corefile.

Multi-Node Coordination

When running multiple nameservers:

1. All nodes share the same RQLite cluster - DNS records are automatically synchronized
2. Install in order - First node bootstraps, others join
3. Same domain configuration - All nodes must use the same --domain value

Related Documentation

• CoreDNS RQLite Plugin - Technical details
• Deployment Guide - Full deployment instructions
• Architecture - System architecture overview